Skip to content

Generated reference. This page mirrors Code/Core/README.md, this module's source-of-truth documentation (Standards/02_DOCUMENTATION_STANDARDS.md §1). Edit it there, not here -- this file is regenerated on every docs build and any local edit is silently overwritten.

Core

Purpose. The cross-cutting concerns every other module depends on: the module lifecycle itself, service resolution, the event bus, logging, and configuration loading. Core is the one module every other module is allowed to depend on unconditionally — see Documentation/Architecture/00_OVERVIEW.md.

Responsibilities. - Modules/ — the GameModule contract, the topological dependency resolver, and the bootstrap file declaring the fixed module list. See 02_MODULE_MODEL.md. - Services/ — IServiceRegistry / IServiceResolver, singleton-only service resolution. See 03_SERVICE_REGISTRY.md. - Events/ — IEventBus, IEvent, CancellableEvent, with per-handler failure isolation. See 04_EVENT_BUS.md. - Logging/ — IGameLog, the fixed LogCategory set. See 12_LOGGING_AND_DIAGNOSTICS.md. - Configuration/ — IModuleConfigurationContext, resolving operator configuration overrides. See 05_CONFIGURATION.md. - Result.cs — the Result / Result<T> shape every expected-failure path in the project returns. See 13_ERROR_HANDLING.md. - Persistence/ — IPersistenceBackend and both implementations. See its own README and 06_PERSISTENCE.md.

Not responsible for. - Any gameplay state. Core knows nothing about characters, items, or money. If a Core type starts referencing gameplay concepts, that is a layering violation — see 00_CONSTITUTION.md §3.

Dependencies. The S&box engine only. Core is the base of the dependency graph in Documentation/Architecture/00_OVERVIEW.md §1 — nothing in this project may be a dependency of Core.

Public API. - GameModule (abstract) — the type every module derives from. - IServiceRegistry, IServiceResolver — service registration and resolution. - IEventBus, IEvent, CancellableEvent — publish/subscribe with explicit cancellation. - IGameLog, LogCategory — structured, categorised logging. - IModuleConfigurationContext — per-module configuration loading. - Result, Result<T> — the expected-failure result shape. - IPersistenceBackend, SaveDocument<T>, DocumentKey, ISchemaMigration<T> — see Persistence/README.md.

Events published. None directly — Core provides the bus other modules publish on. It does not itself publish gameplay events.

Persistence. Owns the persistence layer itself; see Persistence/README.md.

Future improvements. - IServiceRegistry is intentionally singleton-only with no scoping — see ADR-0002 for why, and the trigger for revisiting it. - ServiceContainer does not yet enforce "registration closes once boot reaches Initialize" (stated as intent in 03_SERVICE_REGISTRY.md's XML doc) — duplicate-registration is enforced, closing the registry after boot is not. Add if a real bug ever comes from a late registration; not worth the design cost speculatively. - ModuleRunner.Shutdown() (not ApplejackBootstrap.Shutdown() — ApplejackBootstrap itself has no Shutdown() method) is now wired to a confirmed engine hook: ApplejackBootstrap overrides Dispose(), calling ModuleRunner.Shutdown() before base.Dispose(). The counterpart to ISceneStartup.OnHostInitialize is Dispose() on GameObjectSystem, the base class ApplejackBootstrap extends — confirmed against the real engine source (GameObjectSystem.cs, Scene.System.cs, Scene.cs under /home/kyle/Projects/sbox-public): Scene.Destroy() calls Scene.DestroyInternal(), which calls Scene.ShutdownSystems(), which calls Dispose() on every registered GameObjectSystem. See Modules/ApplejackBootstrap.cs's header comment and its Dispose() override for the full citation and the reasoning behind running module shutdown before the base class's own cleanup. - PlaceholderAModule / PlaceholderBModule (Milestone 2's "two modules boot in the correct order" exit criterion) are deleted as of Milestone 5 -- ApplejackBootstrap.Modules now boots CoreModule -> PersistenceModule -> CharacterModule -> ItemsModule -> InventoryModule, a real multi-module dependency chain that proves the same guarantee organically. This also fixed a gap found while wiring Milestone 5 in: CharacterModule (Milestone 4) had been built and merged but was never actually added to ApplejackBootstrap.Modules, so it had never booted in any real scene. - Written without a local S&box editor available to compile against — see handoverdaily.md for the specific integration points flagged as needing verification (the .sbproj/UnitTests/ project files, ResourceLibrary.GetAll<T>()'s cross-addon behaviour, and the Log.Error exception-overload assumption in GameLog.cs).