Interface IScyllaModule
Core contract for all modules in the Scylla ModUlar Topology (SMUT).
Every concrete module must implement this interface, either directly or - more
commonly - by extending ScyllaModule, the framework-provided
MonoBehaviour base class that fulfils most of this contract automatically.
Namespace: Scylla.Core.Modules
Assembly: ScyllaCore.dll
Syntax
public interface IScyllaModuleRemarks
Modules follow a deterministic lifecycle managed by IScyllaModuleManager. The lifecycle progresses through the states defined in ScyllaModuleState:
- DiscoveredModule is registered with the manager but not yet examined.
- ValidatedAll declared dependencies exist and version constraints are satisfied.
- InitializedInitialize() has run; module resources are ready.
- StartedStartModule() has run; module is active but not yet enabled.
- EnabledModule is fully operational at runtime.
- DisabledModule is suspended but not destroyed; can return to
Enabled. - ShutdownResources released; module cannot be re-enabled.
- ErrorAn unrecoverable failure occurred; the framework will roll back initialization.
Module dependencies are resolved before Initialize() is called. Hard dependencies (Hard) that are missing or version-incompatible will abort the entire startup sequence fail-fast. Soft dependencies (Soft) degrade gracefully. Event-based dependencies (EventBased) are documentation-only and carry no runtime enforcement.
Initialization order is determined first by topological sort of hard/soft dependency edges, then by InitPriority (lower values initialize earlier). Shutdown runs in strict reverse initialization order.
Use the constants in ScyllaModuleID when referencing built-in module IDs in dependency declarations.
Properties
Info
Gets the immutable metadata record for this module, including its unique ID, display name, semantic version, description, declared dependencies, and initialization priority.
Declaration
ScyllaModuleInfo Info { get; }Property Value
| Type | Description |
|---|---|
| ScyllaModuleInfo | A ScyllaModuleInfo instance populated by the concrete module
implementation. This value must not be |
See Also
IsEnabled
Gets a value indicating whether the module is currently enabled and processing runtime logic.
Declaration
bool IsEnabled { get; }Property Value
| Type | Description |
|---|---|
| bool |
|
State
Gets the module's current position in the SMUT lifecycle state machine.
Declaration
ScyllaModuleState State { get; }Property Value
| Type | Description |
|---|---|
| ScyllaModuleState | One of the ScyllaModuleState values representing the lifecycle phase the module is currently in. The state is advanced exclusively by IScyllaModuleManager; modules must not alter it directly. |
See Also
Methods
DisableModule()
Suspends the module's runtime processing without releasing its allocated resources. Transitions the module to Disabled. The module can be returned to an active state by calling EnableModule().
Declaration
void DisableModule()Remarks
Concrete implementations should pause all live behavior here (e.g., unsubscribe from events, pause timers, stop coroutines) to fulfil the framework's zero-cost disabled module guarantee. Resources allocated during Initialize() must not be freed here; reserve that for Shutdown().
Unlike Shutdown(), disabling is reversible. A disabled module retains its internal state and can be re-enabled at any time while the application is running.
See Also
EnableModule()
Declaration
void EnableModule()Remarks
This method is called by the framework automatically after StartModule() succeeds, and also whenever the module is re-enabled after a DisableModule() call. Concrete implementations should resume any paused work here (e.g., re-subscribing to input events, resuming timers).
A module that is disabled consumes zero runtime cost until it is re-enabled, which is the basis of Scylla's zero-cost disabled module guarantee.
See Also
Initialize()
Executes the module's initialization logic. Called by the framework after all hard and soft dependencies have been injected via InjectDependencies(IScyllaModuleManager), and after ValidateDependencies() has confirmed that the dependency graph is satisfied.
Declaration
void Initialize()Remarks
Concrete implementations should allocate and configure all module-owned resources in this method (e.g., data structures, native arrays, subsystem registrations). Avoid starting live runtime behavior here; defer that to StartModule().
On success the framework advances the module's state to Initialized. If initialization throws, the module enters Error and the framework triggers a full rollback of all previously initialized modules in reverse order.
Modules initialize in the order determined by topological dependency sort combined with InitPriority. Lower priority values run first.
Exceptions
| Type | Condition |
|---|---|
| ScyllaModuleException | May be thrown by concrete implementations when initialization encounters an unrecoverable error. The framework catches this and transitions the module to Error. |
See Also
InjectDependencies(IScyllaModuleManager)
Supplies the module with a reference to the IScyllaModuleManager so that it can resolve and cache its declared dependencies before Initialize() is called.
Declaration
void InjectDependencies(IScyllaModuleManager moduleManager)Parameters
| Type | Name | Description |
|---|---|---|
| IScyllaModuleManager | moduleManager | The active IScyllaModuleManager instance. Concrete implementations should call GetModule<T>(string) (or the non-generic overload) on this reference to obtain and store typed references to their dependencies. The reference is safe to retain for the lifetime of the module, but should not be used to call lifecycle management methods (InitializeAllModules(), etc.) directly from within a module. |
Remarks
The framework calls this method for every registered module in priority order after ValidateAllDependencies() succeeds, and before Initialize() is invoked on any module. This guarantees that all modules have a chance to cache their dependency references before any initialization begins.
See Also
Shutdown()
Releases all resources held by the module and transitions it to Shutdown. Called by the framework during application teardown in strict reverse initialization order so that no module shuts down before its dependents.
Declaration
void Shutdown()Remarks
Concrete implementations must free all managed and unmanaged resources here: native arrays, render textures, file handles, network connections, and any other disposable objects. After this method returns the module must not be used again.
The framework guarantees that DisableModule() is called before
Shutdown if the module is currently enabled. Concrete implementations
may therefore assume that runtime subscriptions and callbacks have already
been torn down.
Shutdown is irreversible. A module that has reached Shutdown cannot be re-enabled or re-initialized without creating a new instance.
See Also
StartModule()
Begins the module's runtime behavior after all modules in the dependency graph have been initialized. Called by the framework once InitializeAllModules() completes successfully for every module.
Declaration
void StartModule()Remarks
Use this method to start coroutines, subscribe to events, register update callbacks, and perform any work that requires peer modules to also be in the Initialized state.
On success the framework advances the module's state to Started. The framework subsequently calls EnableModule() to transition the module to Enabled and make it fully operational.
Exceptions
| Type | Condition |
|---|---|
| ScyllaModuleException | May be thrown by concrete implementations when startup encounters an unrecoverable error. |
See Also
ValidateDependencies()
Verifies that every dependency declared in Dependencies is satisfied: required modules must be registered, and version constraints declared via MinVersion must be met.
Declaration
bool ValidateDependencies()Returns
| Type | Description |
|---|---|
| bool |
|
Remarks
This method is called by ValidateAllDependencies()
before any module is initialized. A return value of false causes the
framework to transition the module (and any dependents) to
Error and abort startup.