Class ScyllaCore

Central framework manager and primary entry point for the Scylla game framework. Owns the module system lifecycle and provides access to all registered modules. This class is NOT a module itself - it is the authority that MANAGES modules.

Inheritance
object
ScyllaCore
Inherited Members
Namespace: Scylla.Core
Assembly: ScyllaCore.dll
Syntax
public sealed class ScyllaCore
Remarks

Architecture overview

ScyllaCore sits at the very top of the Scylla dependency hierarchy, above all modules. The layered ownership is:

  1. ScyllaBootstrap (MonoBehaviour) The Unity scene component that drives the entire startup sequence. Its Awake() method acquires Instance, configures logging, and validates the scene hierarchy. Its Start() method schedules a call to InitializeFramework() after a short delay to allow all module Awake() registrations to complete.
  2. ScyllaCore (this class, pure C# singleton) Owns the ModuleManager and exposes the top-level framework API (InitializeFramework(), ShutdownFramework(), RegisterModule(IScyllaModule), GetModule<T>(string)). Never inherits from MonoBehaviour and never depends on any module.
  3. IScyllaModuleManager / ScyllaModuleManager Orchestrates the SMUT (Scylla ModUlar Topology) lifecycle: module registration, dependency validation, priority-ordered initialization, starting, and reverse-order shutdown.
  4. IScyllaModule / ScyllaModule (MonoBehaviour) Individual game modules. They call RegisterModule(IScyllaModule) from their Awake() methods via base.Awake() and then progress through the managed lifecycle.

Fail-fast philosophy

If any module's hard dependencies are missing or version-incompatible, InitializeFramework() throws a ScyllaModuleException and the application terminates immediately. Partial initialization is never permitted; the framework is either fully operational or not started at all.

Singleton lifecycle

The singleton is created lazily on the first access to Instance and lives for the entire application session. It is never destroyed at runtime because its constructor is private and no reset mechanism is exposed. The ScyllaBootstrap MonoBehaviour is the sole owner responsible for calling ShutdownFramework() before the application exits.

Fields

Multi-line ASCII art logo for the Scylla framework, suitable for printing to a log or console output at startup. Each line is terminated with a newline character (\n). The final line is a blank separator line.

Declaration
public const string FrameworkLogo = "     ____         ____      \n    / __/_____ __/ / /__ _  \n   _\\ \\/ __/ // / / / _ `/  \n  /___/\\__/\\_, /_/_/\\_,_/   \n       /______/             \n \n"
Field Value
Type Description
string

FrameworkTagline

Short marketing tagline for the Scylla framework, displayed alongside the FrameworkLogo in startup log output.

Declaration
public const string FrameworkTagline = "Universal Game Framework for Unity"
Field Value
Type Description
string

URL_API_DOCS_BASE

Base URL of the generated API reference site, with a trailing slash. Each module's Meta.API_DOCS_URL is composed by appending its lowercase short name and a trailing slash to this base (for example input/), yielding a link such as https://apidocs.scyllaframework.com/input/. Centralised here so the host name only needs to be changed in one place if the API docs site moves.

Declaration
public const string URL_API_DOCS_BASE = "https://apidocs.scyllaframework.com/"
Field Value
Type Description
string

URL_DOCS_BASE

Base URL of the user-facing documentation category index, with a trailing slash. Each module's Meta.DOCS_URL is composed by appending its lowercase short name and a trailing slash to this base (for example core/), yielding a link such as https://scyllaframework.com/docs-category/core/. Centralised here so the host name only needs to be changed in one place if the docs site moves.

Declaration
public const string URL_DOCS_BASE = "https://scyllaframework.com/docs-category/"
Field Value
Type Description
string

Properties

Instance

Gets the globally accessible, thread-safe singleton instance of ScyllaCore. This is the primary entry point for the entire Scylla Framework at runtime.

Declaration
public static ScyllaCore Instance { get; }
Property Value
Type Description
ScyllaCore
Remarks

The instance is created lazily on the first access. In a standard Unity setup, ScyllaBootstrap accesses this property during its Awake() method, which establishes the singleton before any module's Awake() can call RegisterModule(IScyllaModule). This ordering is guaranteed by Unity's MonoBehaviour execution order.

Game code should generally prefer accessing modules through Framework rather than through this property directly, so that the bootstrap acts as the sole manager of the singleton lifecycle.

IsInitialized

Gets a value indicating whether the Scylla Framework has completed its three-phase startup sequence and all registered modules are running.

Declaration
public bool IsInitialized { get; }
Property Value
Type Description
bool

true after InitializeFramework() has successfully completed dependency validation, module initialization, and module startup for all registered modules. Remains true until the application exits; there is no in-process reset.

false before InitializeFramework() is called, or if the method was never called (e.g., the framework was constructed but the ScyllaBootstrap was destroyed before initialization).

ModuleManager

Gets the module manager that orchestrates the full SMUT lifecycle for all registered modules, including dependency resolution, priority-ordered initialization, runtime enable/disable transitions, and reverse-order shutdown.

Declaration
public IScyllaModuleManager ModuleManager { get; }
Property Value
Type Description
IScyllaModuleManager

The active IScyllaModuleManager instance, always non-null after the ScyllaCore singleton is constructed. The concrete type is ScyllaModuleManager, but consumers should program against the IScyllaModuleManager interface to avoid coupling to the implementation.
See Also

Methods

GetModule<T>(string)

Retrieves a registered module by its unique string identifier and casts it to the specified type T.

Declaration
public T GetModule<T>(string moduleID) where T : class, IScyllaModule
Parameters
Type Name Description
string moduleID

The unique string identifier of the module to retrieve. Use the constants defined in ScyllaModuleID for built-in modules to avoid hard-coded strings and benefit from compile-time typo detection.
Returns
Type Description
T

The registered module cast to T, or null if no module with the given moduleID is registered, or if the registered module's runtime type is not assignable to T. The returned module may be in any lifecycle state; callers should check IsEnabled if they require a fully operational module.
Type Parameters
Name Description
T

The type to cast the located module to. Must be a reference type that implements IScyllaModule. Typically this is the concrete module class (e.g., ScyllaInputModule) or a module-specific interface. If the registered module cannot be cast to T, the method returns null rather than throwing an InvalidCastException.
Remarks

This method delegates directly to GetModule<T>(string) and is provided as a convenience shortcut on ScyllaCore so that callers do not need to navigate through ModuleManager. For repeated lookups in performance-sensitive code, cache the result to avoid repeated dictionary lookups on every call.

The preferred pattern for one module to acquire a reference to another is to call this method (or the equivalent on ModuleManager) inside InjectDependencies(IScyllaModuleManager), which is called by the framework during the initialization phase before any module's Initialize() runs.

See Also

InitializeFramework()

Executes the full Scylla Framework startup sequence: validates all module dependencies, initializes all validated modules in priority order, then starts and enables every initialized module. Sets IsInitialized to true upon success.

Declaration
public void InitializeFramework()
Remarks

Three-phase startup sequence

  1. Validate ValidateAllDependencies() checks every registered module's hard dependencies. A single missing or version-incompatible hard dependency causes this phase to fail and throws a ScyllaModuleException (fail-fast philosophy). Soft and event-based dependencies are logged but never fatal.
  2. Initialize InitializeAllModules() injects dependencies and calls Initialize() on each module in topological + priority order (lower InitPriority values first). If any module's initialization fails, all previously initialized modules are rolled back in reverse order before the exception propagates.
  3. Start StartAllModules() calls StartModule() followed by EnableModule() on every successfully initialized module, transitioning them to Enabled.

Idempotency

If IsInitialized is already true when this method is called, it logs a warning via Log.Warning and returns without performing any work. This makes duplicate calls safe but unintentional.

This method is normally invoked by InitializeFramework() after a short delay to ensure all ScyllaModule Awake() registrations have completed. It should not typically be called directly from game code.

Exceptions
Type Condition
ScyllaModuleException

Thrown when dependency validation fails. ScyllaBootstrap catches this exception and terminates the application (or stops play mode in the Editor) so that the game is never run with an invalid module configuration.
Exception

Any unexpected exception thrown during initialization is logged as fatal and then rethrown, halting application startup.
See Also

RegisterModule(IScyllaModule)

Registers a module with the framework so that it participates in the SMUT lifecycle. Transitions the module to Discovered via the underlying ModuleManager.

Declaration
public void RegisterModule(IScyllaModule scyllaModule)
Parameters
Type Name Description
IScyllaModule scyllaModule

The module instance to register. Must not be null. The module's Info must provide a non-empty, unique ID; attempting to register two modules with the same ID may result in a warning or error depending on the ModuleManager implementation. The module must also implement IScyllaModule and declare valid dependencies via Dependencies.
Remarks

In a standard setup, each ScyllaModule MonoBehaviour calls this method automatically from its Awake() via base.Awake(). Game code does not typically need to call it directly. Manual registration is only necessary when hosting non-MonoBehaviour modules or writing tests.

All registrations must be completed before InitializeFramework() is called, since the validation and initialization phases operate on the snapshot of modules present at that point. The ScyllaBootstrap enforces this timing via the short initialization delay introduced in its Start() method.

Passing null logs an error via Log.Error under LogCategory.Module and returns without modifying the registry.

See Also

RunWhenReady(Action, ScyllaEventPriority)

Invokes onReady as soon as the framework has finished its initialisation sequence. If IsInitialized is already true the callback runs synchronously before this method returns; otherwise it is invoked exactly once when ScyllaFrameworkInitializedEvent is published.

Declaration
public void RunWhenReady(Action onReady, ScyllaEventPriority priority = ScyllaEventPriority.Medium)
Parameters
Type Name Description
Action onReady

The callback to execute once the framework is ready. Must not be null; if null is passed a warning is logged and the call is a no-op.
ScyllaEventPriority priority

The ScyllaEventPriority that governs the ordering of the underlying ScyllaFrameworkInitializedEvent subscription relative to other subscribers. Ignored on the fast path when the framework is already initialised (the callback then runs synchronously). Defaults to Medium.
Remarks

This is the recommended way for game code, demos, and late-loaded scenes to wait for framework readiness. It removes the need for coroutine-based polling of IsInitialized and gracefully handles the race where the framework completes initialisation between the caller's first check and the moment the subscription is installed.

The callback is guaranteed to run at most once. If it is invoked via the SEX event path, the internal subscription is disposed immediately after the handler fires, so the caller does not need to manage a subscription token.

Exceptions thrown from onReady are not caught - they propagate to the publisher on the slow path and to the caller on the fast path, mirroring normal SEX dispatch semantics.

Typical usage from a demo or game manager:

private void Start()
{
    ScyllaCore.Instance.RunWhenReady(() =>
    {
        var input = ScyllaCore.Instance.GetModule<ScyllaInput>(ScyllaModuleID.INPUT);
        input.ActionManager.SetActiveMap("Gameplay");
    });
}
See Also

ShutdownFramework()

Shuts down all active modules in strict reverse initialization order and marks the framework as no longer operational. Delegates to ShutdownAllModules(), which calls DisableModule() (if currently enabled) and then Shutdown() on each module.

Declaration
public void ShutdownFramework()
Remarks

Already-uninitialized guard

If IsInitialized is false when this method is called (i.e., InitializeFramework() was never successfully completed), a warning is logged and the method returns immediately without attempting any module teardown. This makes defensive calls from ShutdownFramework() safe regardless of whether the framework started successfully.

This method is automatically invoked by Scylla.Core.ScyllaBootstrap.OnApplicationQuit() and may also be called manually for controlled teardown scenarios such as scene transitions. After this call returns, module references obtained via GetModule<T>(string) should be considered invalid.

See Also

Extension Methods

See Also