Overview

7 min read

What Scylla Core is, the problem it solves, and everything it gives you: the bootstrap, module system, event bus, time, configuration, logging, and a broad utility library.

Scylla Core is the foundation of the framework. It owns the bootstrap, the module lifecycle, the event bus, the time subsystem, the configuration system, the logging system, and a broad library of utilities and data structures that every other module is built on. This page is the tour of what you get; when you’re ready to wire it into a scene, head to Getting Started.

Summary

Scylla Core is the module every other Scylla module depends on. It gives you the runtime spine that turns a Unity scene into a coherent, deterministic framework, plus the day-to-day toolbox your game code reaches for constantly: math, noise, random, tweens, collections, serialization, compression, crypto, file IO, debug drawing, and more.

The problem Core solves is the one you rediscover around the third month of every Unity project: there is no shared opinion about how your systems start, how they talk to each other, how they read configuration, how they log, or how they shut down. Every asset on the shelf has its own answer, and you end up with a patchwork that works just well enough to discourage rewriting it and just poorly enough to keep costing you time. Core replaces that patchwork with a single coherent foundation that the rest of Scylla builds on, and that your game code can build on too.

Here is how Core works at a glance. A ScyllaBootstrap component lives in your first scene. On Awake it brings up a C# singleton, ScyllaCore, which in turn owns the module manager. The manager discovers every module in your scene, validates the dependency graph, and initializes modules in strict priority order. Failures abort startup with an actionable error rather than corrupting state. Once initialization completes, your modules run as steady-state Enabled or Disabled, and a disabled module is guaranteed to consume zero per-frame cost. Three subsystems live outside the module hierarchy because they have to be available before any module runs: the time subsystem (ScyllaTime), the event bus (SEX, Scylla Event eXchange), and the scene manager (ScyllaSceneManager), which keeps the framework alive across scene loads and manages the loads themselves.

Core sits at the bottom of the tier graph. Every other Scylla module (Input, Graphics, UI, TextMode, Data, Console, Stats, Camera) declares Core as a dependency, and Core depends on nothing. That asymmetry is enforced, and it is what keeps the framework predictable as it grows: a higher tier may build on a lower one, never the other way around.

You do not need any of the higher-tier modules to get value from Core. The utility and collection libraries alone are reason enough to install it, the framework infrastructure is reason enough on its own too, and most projects use both.

Features

Here is what ships in Scylla Core, ordered from the load-bearing framework pieces to the utility library you reach for day to day.

  • Bootstrap and Module System (Scylla ModUlar Topology). A scene-level ScyllaBootstrap component plus a C# ScyllaCore singleton and a ScyllaModuleManager orchestrate the entire module lifecycle: discovery, validation, initialization, start, enable, disable, shutdown. Deterministic order, fail-fast validation, tiered dependency rules. See Module System.
  • Event System (Scylla Event eXchange). A typed publish-subscribe event bus with priority-ordered listeners, cancellable propagation, lifecycle-safe subscription management, and automatic cleanup when subscribers are destroyed.
  • Configuration System. Dual-layer config: ScriptableObject assets for design-time defaults plus optional JSON files for runtime overrides. Four-tier layered fallback (User Documents, Application, Unity Asset, Defaults) handled by ConfigFileManager. Inspector integration with an “Export Config File” button. See Configuration.
  • Logging System. Centralized log calls with module categories, pluggable receivers (Unity console, file system), and filtering. One call site, multiple sinks, consistent format across the framework. See Logging.
  • Time Subsystem. ScyllaTime gives you framework-aware time, timescale control, and pause handling that is independent of Time.timeScale. Initialized by the Bootstrap before any module runs.
  • Scene Manager. ScyllaSceneManager keeps the framework hierarchy alive across scene changes (with automatic deduplication of per-scene bootstraps) and wraps Unity’s scene loading in a managed pipeline: typed events, progress reporting, an activation gate for loading screens, transition hygiene, and optional Addressables routing. See Scene Manager.
  • Utility Library. A broad set of static helpers: math, interpolation, noise (Perlin, OpenSimplex2, Value, ValueCubic, Cellular), random (PCG32, Xoshiro256, Mersenne Twister, SplitMix64, Xoroshiro128+), strings, files, paths, sprites, fonts, colors, lights, cameras, threading, platform, assemblies, types. Stable, allocation-aware, hot-path friendly.
  • Data Structures. Generic and DOTS-compatible collections: queue, priority queue, deque, stack, map, type-map, ring buffer, object pool, trie, quadtree, octree, BVH, KD-tree, bit array, disjoint set, graphs (adjacency list, CSR, grid adapter, algorithms), and grid utilities for hex, square, and triangle layouts. See the Collections Overview.
  • Palette, Config File, and Unit Utilities. A small, opinionated set of first-class utilities: the ColorAssetRegistry with ColorPalette, ColorGradient, ColorSwatchCollection, the ColorRole semantic vocabulary, and mutable builders for runtime authoring; the ConfigFile family (ConfigFile, ConfigFileGroup, ConfigFileProperty) that backs the JSON configuration tier; and eight strongly-typed unit structs (LengthUnit, MassUnit, TimeUnit, AreaUnit, SpeedUnit, PressureUnit, TemperatureUnit, DataUnit) with conversion properties, validated math, and auto-scaling output.
  • Serialization, Compression, and Crypto. A first-party JSON serialization engine with attribute-driven configuration, reference tracking, and type serializers. Compression providers for GZip, Deflate, BZip2, and Zip. AES-CBC-HMAC, AES-GCM, and ChaCha20-Poly1305 with PBKDF2 key derivation. Checksums covering Adler32, CRC16, CRC32, Fletcher32, XXHash32, and XXHash64.
  • Tween System. A reusable tween engine with easing functions, sequences, object pooling, and extensions for Transform, Material, AudioSource, CanvasGroup, SpriteRenderer, and RectTransform.
  • Procedural Map Generation. Algorithms for BSP, cellular automata, drunkard walk, maze, maze with rooms, room and corridor, Voronoi regions, noise threshold, and winding corridor generation. Pluggable post-processing for connectivity, dead-end removal, room detection, doors, and spawn points.
  • Debug Drawing. A runtime debug-draw subsystem with mesh-based primitives that work in both edit and play mode and across render pipelines.
  • Editor Foundation. A UI Toolkit-based foundation for the rest of the framework’s editor experience: ScyllaEditorBase for custom inspectors, ScyllaToolWindowBase for windows, ScyllaScheduler for safe recurring jobs, USS token system for theming, a setup wizard, and a getting-started wizard.

Architecture

Core’s runtime is small on purpose. Four pieces carry the entire framework, and three extra subsystems sit alongside them because they need to be available before any module runs.

flowchart TB
    subgraph Scene
        BS[ScyllaBootstrap<br/>MonoBehaviour]
        M1[Module 1]
        M2[Module 2]
        Mx[...more modules]
        BS --- M1
        BS --- M2
        BS --- Mx
    end
    subgraph Runtime
        Core[ScyllaCore<br/>C# singleton]
        MM[ScyllaModuleManager]
        Time[ScyllaTime]
        EvBus[SEX EventBus]
        Scenes[ScyllaSceneManager]
        Cfg[ConfigFileManager]
        Logs[Log subsystem]
    end
    BS --> Core
    BS --> Time
    BS --> EvBus
    BS --> Scenes
    Core --> MM
    MM --> M1
    MM --> M2
    MM --> Mx
    Core -.uses.-> Cfg
    Core -.uses.-> Logs
    M1 -.events.-> EvBus
    M2 -.events.-> EvBus

ScyllaBootstrap is the only MonoBehaviour in the spine. It performs the singleton check, brings up time, events, and the scene manager, validates that every module in your scene is a direct child, and then schedules framework initialization after a short configurable delay. ScyllaCore is the framework-wide C# singleton; it owns the ScyllaModuleManager, which is the only component allowed to mutate module state. Your modules are MonoBehaviours that auto-register on Awake, then transition through a strict lifecycle (Discovered, Validated, Initialized, Started, Enabled, Disabled, Shutdown) under the manager’s control. ScyllaTime, the SEX event bus, and ScyllaSceneManager are framework subsystems rather than modules because every module needs them from the first frame.

The single invariant that holds everything together is the tier rule: dependencies flow downward. A Tier 2 module can build on a Tier 1 module and on Core; a Tier 1 module can build on Core. The reverse is impossible by design, and the manager validates it at startup. An #if SCYLLA_HAS_OTHER_MODULE block in a Core source file is a bug. The full picture, including the bootstrap phases and the tier rules, is on the Architecture Overview.

Updated on July 9, 2026