Inno.Scene
Section titled “Inno.Scene”
- Scene objects, behaviors, transforms, persistent state and generation recovery.
Inno.Scene owns the runtime Scene model: scenes, objects, components, scene-level systems, transforms, prefab instances and their recoverable state. A host-owned SceneWorld isolates one session. The script-facing SceneManager resolves that world from the current execution context; it does not own another scene collection.
Start with working with scenes. For host integration, read scene ownership and reload and capturing scene state.
Scene ownership contract
Section titled “Scene ownership contract”Use live scenes and elements in their owning runtime session and its serialized execution/lifecycle boundary. SceneWorld.EnterScope binds the world and its identity allocator and returns a caller-owned, strictly nested scope. Entering a scope does not add synchronization or move work to the owner thread. The host supplies the type catalog and identity allocator; world disposal unloads scenes and releases its own type-catalog participant, not those borrowed host services.
A scene owns its objects, attached components and systems. Every object has one required, non-removable Transform. Do not keep old component/system instances, strong query snapshots or type-cache snapshots across generation retirement. Persist stable identities and neutral state; resolve the current live object when needed. Destruction, removal and reload invalidate former runtime identities even when a persistent identity survives.
Mutations during a lifecycle stage may be queued until its boundary. Do not capture a complete scene while structural work is uncommitted. New prefab subtrees can restore their own component order before commitment; this does not permit arbitrary reordering of already committed objects during execution.
Loading one scene replaces the loaded set. Additive loading preserves other scenes. An object move requires both scenes in the same loaded world, preserves the subtree and persistent identities, and makes the moved root a destination root. It is not a serialized clone or a reset. Closing the last scene is valid; no active scene is a supported state.
Lifecycle and recovery contract
Section titled “Lifecycle and recovery contract”GameBehavior is the component base with independent enabling and frame callbacks. GameSystem is scene-level, serializable coordination. Display order, hierarchy order and execution priority are distinct; see choosing a behavior or system.
Missing component/system placeholders preserve logical type identity, original neutral property bytes, asset dependencies and scene-reference aliases. They are restoration results, not ordinary attachable types. Their serialized form remains the original logical element. Restoring a Missing element requires complete property recovery; failure must preserve the placeholder. A still-Missing asset dependency is not silently changed to null.
Reload preparation, provisional replacement, publication and retirement belong to the shared generation transaction. Restore structure before old type/serializer state and previous properties/lifecycle when rolling back. Ordinary retirement failures aggregate; pending retirement retains owners and faults the shared gate. Cleanup after irreversible commit cannot pretend that the old generation was restored.
API surfaces
Section titled “API surfaces”The reference below describes the actual CLR surface, including host state-transfer and serialization APIs. Runtime scripts use the explicitly exported scene types under InnoEngine.Scene; namespace projection does not export the entire assembly. SceneWorld, host serialization helpers and Missing placeholder constructors are not general game-script entry points. Scene asset importers belong to Inno.Scene.Assets.
API reference
Section titled “API reference”Types and exact member contracts include the host and relevant protected extension surface. Member-specific contracts supplement the shared ownership and recovery rules above.
Logical script references
Section titled “Logical script references”The compiler-selected script declarations are separate from this project’s host CLR surface. Read the script calling guide and the associated module contracts before using a projected member.
Source project facts
Section titled “Source project facts”Project: Inno.Scene
Source: src/content/scene/Inno.Scene/Inno.Scene.csproj
| Type | API | Description |
|---|---|---|
| AllowMultipleComponentAttribute | engine | Allows multiple instances of a concrete component type on one game object. |
| AllowMultipleSystemAttribute | engine | Allows multiple instances of a concrete T:Inno.Scene.GameSystem type in one scene. |
| Transform | engine | Stores local transform data and exposes the scene hierarchy relationship. |
| EngineAssetContent | engine | Carries immutable scene or prefab runtime content across the runtime-to-authoring asset boundary. |
| EngineObject | engine | Provides identity and destruction state shared by all managed scene objects. |
| GameBehavior | engine | Base component for independently enabled scene functionality with frame lifecycle callbacks. |
| GameComponent | engine | Base type for data and behavior objects attached to a T:Inno.Scene.GameObject. |
| GameObject | engine | Represents a scene-owned object and exposes its component-oriented API. |
| GameScene | engine | Owns a runtime scene, including its objects, components, hierarchy, and systems. |
| GameSystem | engine | Base type for serializable, ordered scene-level behaviors. |
| GameTagCatalog | engine | Stores the project-wide tag definitions used to author and validate scene object assignments. |
| ISceneReloadStateTransfer | engine | Represents a staged scene object state transfer associated with one assembly reload transaction. |
| GameLayer | engine | Identifies one of the thirty-two runtime layers available to scene objects. |
| GameLayerCatalog | engine | Stores the named layer catalog and symmetric layer-interaction matrix used by a project. |
| GameLayerDefinition | engine | Describes one named layer slot in a T:Inno.Scene.Layers.GameLayerCatalog snapshot. |
| GameLayerId | engine | Identifies one project-scoped game layer independently from its compact runtime slot. |
| GameLayerMask | engine | Stores a compact set of scene layers for rendering, physics, and query filtering. |
| MissingGameComponent | engine | Preserves the identity, order, and serialized state of a component whose managed type is unavailable. |
| MissingGameSystem | engine | Preserves the identity, order, and serialized state of a scene system whose managed type is unavailable. |
| PrefabAsset | engine | Stores a persistent game object subtree that can be instantiated repeatedly. |
| PrefabInstanceInfo | engine | Describes the read-only source connection retained by one prefab instance object. |
| SceneAsset | engine | Stores imported scene source that can create independent runtime scenes. |
| SceneContentSource | engine | Projects loaded scenes into the shared content protocol without depending on a rendering or audio model. |
| SceneElementSerialization | engine | Recreates individual scene components and systems from stable type and object identities. |
| SceneManager | engine | Provides Unity-style scene operations by resolving the world in the current runtime execution context. |
| ScenePropertySerialization | engine | Captures and restores individual scene-object properties while preserving scene reference identities. |
| SceneReloadDiagnostic | engine | Describes a non-fatal issue encountered while migrating scene state to a new assembly generation. |
| SceneReloadService | engine | Creates scene state-transfer transactions for assembly generation changes. |
| SceneSubtreeSerialization | engine | Captures and restores one GameObject subtree with its persistent object and component identities. |
| SceneTypeResolutionException | engine | Reports that a serialized scene element cannot be created because its stable type is not present in the active type catalog. |
| SceneWorld | engine | Owns the loaded scene set and lifecycle state for one isolated runtime session. |
| AllowMultipleComponentAttribute | Runtime | Allows multiple instances of a concrete component type on one game object. |
| AllowMultipleSystemAttribute | Runtime | Allows multiple instances of a concrete T:InnoEngine.Scene.GameSystem type in one scene. |
| EngineObject | Runtime | Provides identity and destruction state shared by all managed scene objects. |
| GameBehavior | Runtime | Base component for independently enabled scene functionality with frame lifecycle callbacks. |
| GameComponent | Runtime | Base type for data and behavior objects attached to a T:InnoEngine.Scene.GameObject. |
| GameLayer | Runtime | Identifies one of the thirty-two runtime layers available to scene objects. |
| GameLayerCatalog | Runtime | Stores the named layer catalog and symmetric layer-interaction matrix used by a project. |
| GameLayerDefinition | Runtime | Describes one named layer slot in a T:InnoEngine.Scene.GameLayerCatalog snapshot. |
| GameLayerId | Runtime | Identifies one project-scoped game layer independently from its compact runtime slot. |
| GameLayerMask | Runtime | Stores a compact set of scene layers for rendering, physics, and query filtering. |
| GameObject | Runtime | Represents a scene-owned object and exposes its component-oriented API. |
| GameScene | Runtime | Owns a runtime scene, including its objects, components, hierarchy, and systems. |
| GameSystem | Runtime | Base type for serializable, ordered scene-level behaviors. |
| GameTagCatalog | Runtime | Stores the project-wide tag definitions used to author and validate scene object assignments. |
| PrefabAsset | Runtime | Stores a persistent game object subtree that can be instantiated repeatedly. |
| PrefabInstanceInfo | Runtime | Describes the read-only source connection retained by one prefab instance object. |
| SceneAsset | Runtime | Stores imported scene source that can create independent runtime scenes. |
| SceneManager | Runtime | Provides Unity-style scene operations by resolving the world in the current runtime execution context. |
| Transform | Runtime | Stores local transform data and exposes the scene hierarchy relationship. |