02 Core – Overview

6 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.

Summary

Scylla Core is the module every other Scylla module depends on. It gives you the framework infrastructure that turns a Unity scene into a coherent, deterministic system, 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.

Core exists because most Unity projects never settle on a shared opinion about how their 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 answers those questions differently, and the result is 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 (Persistence, Input, Graphics, Audio, TextMode, Data, UI, Console, Stats, Camera, YM2612, CharacterController, AI) declares Core as a dependency, and Core depends on nothing. That asymmetry is enforced, and it 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 worth the install, and so is the framework infrastructure on its own; most projects end up using both.

Features

Scylla Core provides the following, ordered from the framework pieces everything else depends on 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. It enforces deterministic order, fail-fast validation, and 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. A dual-layer design: ScriptableObject assets for design-time defaults plus optional JSON files for runtime overrides, resolved through a four-tier layered fallback (User Documents, Application, Unity Asset, Defaults) handled by ConfigFileManager. The Inspector integrates an “Export Config File” button. In the Editor, Play mode works on runtime copies of the configuration assets, so runtime changes and JSON overrides never end up in the assets. See Configuration.
  • Logging System. Centralized log calls with module categories, pluggable receivers (Unity console, file system), and filtering, all through one call site with multiple sinks and a 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. See Time.
  • 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.
  • Persistence Contracts. IScyllaPersistable and ScyllaPersistenceRegistry let any system make its state saveable by implementing a small interface and registering itself. The Persistence module reads the registry, so a module can take part in saves without referencing it. See Persistence Contracts.
  • 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, all of it stable, allocation-aware, and 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; color analysis tools for WCAG contrast checks, color blindness simulation, harmony schemes, and tint and shade ramps; 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 serialization engine that writes JSON or a compact binary format, with attribute-driven configuration, reference tracking, schema migrations, and type serializers, plus compression providers for GZip, Deflate, BZip2, and Zip. File writes can be atomic, so a crash leaves either the old file or the new one. Authenticated encryption covers AES-CBC-HMAC, AES-GCM, and ChaCha20-Poly1305 with PBKDF2 key derivation, and checksums span 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, RectTransform, and UI Toolkit VisualElements.
  • 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, plus 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 among those four pieces. 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 October 7, 2026