@skewedaspect/sage 0.10.0-beta.2 → 0.10.0-rc.2

package/dist/classes/level.d.ts

@@ -1,32 +1,30 @@
 import { Color3, Scene, TransformNode } from '@babylonjs/core';
 import { ClusteredLightContainer } from '@babylonjs/core/Lights/Clustered/clusteredLightContainer';
-import { NodeSimulation } from "../entities/nodeSimulation.d.ts";
-import { LoggerInterface } from "../interfaces/logger.d.ts";
-import { ColorConfig, LevelConfig, LevelContext, LevelInstance, LevelLoadOptions, PropertyHandler } from "../interfaces/level.d.ts";
-import { GameEngine } from "./gameEngine.d.ts";
-import { OutlineManager } from "../managers/outline.d.ts";
+import { NodeEntityRegistry, NodeSimulation } from "../entities/nodeSimulation.js";
+import { MeshLoader } from "../entities/nodeSimulationContext.js";
+import { LoggerInterface } from "../interfaces/logger.js";
+import { ColorConfig, LevelConfig, LevelContext, LevelInstance, LevelLoadOptions, PropertyHandler } from "../interfaces/level.js";
+import { OutlineManager } from "../managers/outline.js";
 /**
- * Abstract base class for game levels.
+ * The base a game subclasses when it builds a level's scene in code. A subclass writes one method,
+ * `buildScene`, and reaches every dependency it has through `this.context`; the base drives the load,
+ * publishes the level's own events, and owns the scene, the simulation built against it, and the teardown
+ * (design/levels.md#the-base-class).
  *
- * Levels are responsible for creating and configuring their own scenes via the
- * `buildScene()` method. All runtime dependencies (eventBus, sceneEngine, simulation)
- * are injected via the constructor and are immediately available.
- *
- * Users should not instantiate Level subclasses directly. Instead, use LevelManager
- * which acts as a factory and injects the required dependencies:
+ * The level manager is the factory: it constructs a subclass with the configuration and the context, so a
+ * game registers a class and loads a level rather than constructing one itself.
  *
  * ```typescript
- * // Register a custom level class
  * levelManager.registerLevelClass('my-level', MyCustomLevel);
  *
- * // Load the level - manager creates instance with deps injected
  * const level = await levelManager.loadLevel({ name: 'Level1', class: 'my-level' });
  * ```
  */
-export declare abstract class Level implements LevelInstance {
+export declare abstract class Level<Registry extends NodeEntityRegistry = NodeEntityRegistry> implements LevelInstance {
+    #private;
     readonly name: string;
     protected readonly _log: LoggerInterface;
-    protected readonly _context: LevelContext;
+    protected readonly _context: LevelContext<Registry>;
     protected _scene: Scene | null;
     protected _forRestore: boolean;
     /**
@@ -34,45 +32,42 @@ export declare abstract class Level implements LevelInstance {
      * disposing this one, so by the time this level despawns what it spawned, the engine already holds the
      * next level's simulation, minting the same IDs.
      */
-    protected _simulation: NodeSimulation | null;
+    protected _simulation: NodeSimulation<Registry> | null;
     clusteredLights: ClusteredLightContainer | null;
     outlines: OutlineManager | null;
-    /**
-     * Creates a new Level instance.
-     *
-     * @param config
-     * @param context
-     */
-    constructor(config: LevelConfig, context: LevelContext);
+    constructor(config: LevelConfig, context: LevelContext<Registry>);
     get scene(): Scene | null;
     get isLoaded(): boolean;
-    get gameEngine(): GameEngine;
+    protected get context(): LevelContext<Registry>;
     get propertyHandlers(): Map<string, PropertyHandler>;
-    /**
-     * Emit a progress event during loading
-     *
-     * @param progress - Percentage (0-100)
-     * @param message
-     */
     /**
      * The simulation this level owns, or nothing for a level that never built one. The level manager binds
      * the engine to the current level's simulation (design/simulation.md#which-simulation-the-engine-holds).
      */
-    get $simulation(): NodeSimulation | null;
+    get $simulation(): NodeSimulation<Registry> | null;
+    /**
+     * Takes over a simulation built to replace this level's own, as a save load does once it has restored
+     * into a fresh one (design/simulation.md#saved-games).
+     */
+    $adoptSimulation(simulation: NodeSimulation<Registry>): void;
+    /**
+     * Builds this level's simulation for the scene it just created, named after the level, and keeps it. A
+     * subclass calls this from `buildScene` before it spawns anything, since a NodeEntity constructs its node
+     * in its simulation's scene (design/levels.md#the-scene-and-its-simulation).
+     */
+    protected rebuildSimulation(scene: Scene, meshSource?: MeshLoader): NodeSimulation<Registry>;
     /**
-     * Take over a simulation built to replace this level's own, as a save load does once it has restored
-     * into a fresh one.
-     *
-     * @param simulation
+     * Publishes one more `level:progress` at the number and the message a subclass names, which is how a
+     * level reports its own progress between the 0 and the 100 the base publishes
+     * (design/levels.md#the-base-class).
      */
-    $adoptSimulation(simulation: NodeSimulation): void;
     protected $emitProgress(progress: number, message: string): void;
     protected _toColor3(color: ColorConfig): Color3;
     /**
-     * Get normalized metadata from a node, handling glTF extras.
-     *
-     * Babylon.js stores glTF custom properties in node.metadata.gltf.extras,
-     * so we need to extract them for easier access.
+     * A node's metadata as one flat record: its own top-level keys with its glTF extras merged onto them, extras
+     * winning where both name one. The `gltf` container itself is left out, since it is the loader's record and
+     * never an authored property, so a node whose extras are empty and whose own keys are too normalizes to an
+     * empty record and the walk skips it (design/authoring.md#the-walk).
      */
     protected _getNormalizedMetadata(node: TransformNode): Record<string, unknown> | null;
     /**
@@ -80,16 +75,14 @@ export declare abstract class Level implements LevelInstance {
      */
     protected _runPropertyHandlers(node: TransformNode): Promise<void>;
     /**
-     * Load and create the scene for this level.
-     * Progress events will be emitted during loading.
+     * Builds the scene through `buildScene`, publishing `level:progress` at 0 and at 100 around it and
+     * `level:complete` after, or `level:error` before rethrowing when building fails. A level already holding a
+     * scene warns and answers with the one it has.
      */
     load(options?: LevelLoadOptions): Promise<Scene>;
     /**
-     * Abstract method for building the scene content.
-     * Concrete levels must implement this to create their specific content.
-     *
-     * All dependencies are available via `this.gameEngine`.
-     *
+     * Builds the scene: a subclass answers with the scene it built, reaching what it needs through `this.context`
+     * (design/levels.md#the-base-class).
      */
     protected abstract buildScene(): Promise<Scene>;
     /**
@@ -105,10 +98,8 @@ export declare abstract class Level implements LevelInstance {
      */
     onDeactivate?(): Promise<void> | void;
     /**
-     * Dispose of this level's resources and scene.
-     *
-     * The `$` prefix indicates this is an internal lifecycle method, consistent with
-     * other engine lifecycle methods like `$teardown()`.
+     * Releases what the base owns: the outline manager, the clustered light container, and the scene. Nothing for
+     * a level that never loaded one, and nothing the second time (design/architecture.md#teardown).
      */
-    $dispose(): Promise<void>;
+    dispose(): Promise<void>;
 }

package/dist/classes/loggers/consoleBackend.d.ts

@@ -1,4 +1,4 @@
-import { LoggingBackend } from "../../interfaces/logger.d.ts";
+import { LoggingBackend } from "../../interfaces/logger.js";
 /**
  * A logging backend that logs to the console.
  */

package/dist/classes/loggers/nullBackend.d.ts

@@ -1,4 +1,4 @@
-import { LoggingBackend } from "../../interfaces/logger.d.ts";
+import { LoggingBackend } from "../../interfaces/logger.js";
 /**
  * A logging backend that does nothing (discards all logs).
  * Useful for production environments or when you want to completely disable logging.

package/dist/debug/builtins.d.ts

@@ -1,6 +1,4 @@
-import { DebugConsole } from "../classes/debugConsole.d.ts";
-import { GameEngine } from "../classes/gameEngine.d.ts";
-/**
- * Registers all default references and commands onto the debug console namespace.
- */
-export declare function registerBuiltins(dc: DebugConsole, ge: GameEngine): void;
+import { DebugConsole } from "../classes/debugConsole.js";
+import { GameEngine } from "../classes/gameEngine.js";
+import { NodeEntityRegistry } from "../entities/nodeSimulation.js";
+export declare function registerBuiltins<Registry extends NodeEntityRegistry>(dc: DebugConsole, ge: GameEngine<Registry>): void;

package/dist/engines/audio.d.ts

@@ -1,14 +1,11 @@
 import { AudioBus, IStaticSoundOptions, StaticSound } from '@babylonjs/core';
-import { Disposable } from "../interfaces/lifecycle.d.ts";
-import { LoggingUtility } from "../utils/logger.d.ts";
+import { Disposable } from "../interfaces/lifecycle.js";
+import { LoggingUtility } from "../utils/logger.js";
 export declare class AudioEngine implements Disposable {
-    private _engine;
-    private _mainBus;
-    private _buses;
-    private _log;
+    #private;
     constructor(logger: LoggingUtility);
     initialize(): Promise<void>;
-    $teardown(): Promise<void>;
+    dispose(): Promise<void>;
     createBus(name: string): Promise<AudioBus>;
     getBus(name: string): AudioBus | undefined;
     createSound(name: string, url: string, bus?: AudioBus, options?: Partial<IStaticSoundOptions>): Promise<StaticSound>;

package/dist/engines/scene.d.ts

@@ -1,78 +1,43 @@
-import { AbstractEngine, AbstractMesh, AssetContainer, DirectionalLight, FreeCamera, HemisphericLight, Light, Mesh, PhysicsAggregate, PhysicsShapeType, PointLight, RectAreaLight, Scene, SpotLight, Vector3 } from '@babylonjs/core';
+import { AbstractEngine, AbstractMesh, AssetContainer, DirectionalLight, HemisphericLight, Light, Mesh, PointLight, RectAreaLight, Scene, SpotLight, Vector3 } from '@babylonjs/core';
 import { HavokPhysicsWithBindings } from '@babylonjs/havok';
-import { GameCanvas } from "../interfaces/game.d.ts";
-import { Disposable } from "../interfaces/lifecycle.d.ts";
-import { LoggingUtility } from "../utils/logger.d.ts";
+import { Disposable } from "../interfaces/lifecycle.js";
+import { LoggingUtility } from "../utils/logger.js";
 export declare class SceneEngine implements Disposable {
-    private _canvas;
-    private _engine;
-    private _havok;
-    private _log;
-    constructor(canvas: GameCanvas, engine: AbstractEngine, havok: HavokPhysicsWithBindings, logger: LoggingUtility);
+    #private;
+    constructor(engine: AbstractEngine, logger: LoggingUtility, havokBinary?: BufferSource);
+    /** Whether the Havok module has been loaded, which nothing does until a scene asks for physics. */
+    get $havokLoaded(): boolean;
+    /** The one loaded module, for a test asserting every scene's plugin was built over the same one. */
+    get $havokModule(): HavokPhysicsWithBindings | undefined;
     /**
-     * Creates a new scene with physics enabled
+     * Creates an empty scene on the render engine. It belongs to whoever asked for it.
      */
     createScene(): Scene;
-    enablePhysics(scene: Scene, gravityVector?: Vector3, floatingOriginWorldRadius?: number): void;
-    /**
-     * Creates a free camera at the specified position, targeting the origin. Attaches controls to the provided
-     * canvas, or falls back to the engine's default canvas.
-     * @param name
-     * @param position
-     * @param scene
-     * @param canvas - Overrides the default canvas for input controls
-     */
-    createFreeCamera(name: string, position: Vector3, scene: Scene, canvas?: GameCanvas): FreeCamera;
+    enablePhysics(scene: Scene, gravityVector?: Vector3, floatingOriginWorldRadius?: number): Promise<void>;
     /**
      * Creates a hemispheric light (ambient lighting)
-     * @param name
-     * @param direction
-     * @param scene
-     * @param intensity - Default: 0.7
      */
     createHemisphericLight(name: string, direction: Vector3, scene: Scene, intensity?: number): HemisphericLight;
     /**
      * Creates a directional light (sun-like lighting)
-     * @param name
-     * @param direction
-     * @param scene
-     * @param intensity - Default: 1.0
      */
     createDirectionalLight(name: string, direction: Vector3, scene: Scene, intensity?: number): DirectionalLight;
     /**
      * Creates a point light (bulb-like lighting)
-     * @param name
-     * @param position
-     * @param scene
-     * @param intensity - Default: 1.0
      */
     createPointLight(name: string, position: Vector3, scene: Scene, intensity?: number): PointLight;
     /**
      * Creates a spotlight (flashlight-like lighting)
-     * @param name
-     * @param position
-     * @param direction
      * @param angle - Cone angle in radians
      * @param exponent - Controls light falloff from center to edge of cone
-     * @param scene
-     * @param intensity - Default: 1.0
      */
     createSpotLight(name: string, position: Vector3, direction: Vector3, angle: number, exponent: number, scene: Scene, intensity?: number): SpotLight;
     /**
      * Creates a rectangular area light (emits from a flat rectangle in the -Z direction)
-     * @param name
-     * @param position
-     * @param width
-     * @param height
-     * @param scene
-     * @param intensity - Default: 1.0
      */
     createRectAreaLight(name: string, position: Vector3, width: number, height: number, scene: Scene, intensity?: number): RectAreaLight;
     /**
      * Creates a sphere mesh. Defaults: diameter 1, 32 segments.
-     * @param name
-     * @param options
-     * @param scene
      */
     createSphere(name: string, options: {
         diameter?: number;
@@ -80,9 +45,6 @@ export declare class SceneEngine implements Disposable {
     } | undefined, scene: Scene): Mesh;
     /**
      * Creates a box mesh. Default size: 1.
-     * @param name
-     * @param options
-     * @param scene
      */
     createBox(name: string, options: {
         size?: number;
@@ -92,9 +54,6 @@ export declare class SceneEngine implements Disposable {
     } | undefined, scene: Scene): Mesh;
     /**
      * Creates a ground mesh. Defaults: 6x6 with 2 subdivisions.
-     * @param name
-     * @param options
-     * @param scene
      */
     createGround(name: string, options: {
         width?: number;
@@ -103,38 +62,19 @@ export declare class SceneEngine implements Disposable {
     } | undefined, scene: Scene): Mesh;
     /**
      * Creates a cylinder mesh. Defaults: height 2, diameter 1 (top and bottom).
-     * @param name
-     * @param options
-     * @param scene
      */
     createCylinder(name: string, options: {
         height?: number;
         diameterTop?: number;
         diameterBottom?: number;
     } | undefined, scene: Scene): Mesh;
-    /**
-     * Adds physics to a mesh. Defaults: mass 1, restitution 0.75, friction 0.5.
-     * @param mesh
-     * @param shapeType
-     * @param physicsProps
-     * @param scene
-     */
-    addPhysics(mesh: Mesh, shapeType: PhysicsShapeType, physicsProps: {
-        mass?: number;
-        restitution?: number;
-        friction?: number;
-    } | undefined, scene: Scene): PhysicsAggregate;
     /**
      * Loads a 3D model/asset into an AssetContainer without adding it to the scene automatically.
-     * @param sceneFilename
-     * @param scene
      */
     loadModel(sceneFilename: string, scene: Scene): Promise<AssetContainer>;
     /**
      * Imports meshes from a file directly into the scene.
      * @param meshNames - Specific meshes to import; empty array imports all
-     * @param sceneFilename
-     * @param scene
      */
     importMeshes(meshNames: string[], sceneFilename: string, scene: Scene): Promise<{
         meshes: AbstractMesh[];
@@ -146,7 +86,8 @@ export declare class SceneEngine implements Disposable {
         lights: Light[];
     }>;
     /**
-     * Tears down the scene engine and cleans up any resources
+     * Releases the Havok module and forgets a load of it still in flight. The scenes this engine created
+     * belong to their levels and are left alone.
      */
-    $teardown(): Promise<void>;
+    dispose(): Promise<void>;
 }

package/dist/entities/defineEntity.d.ts

@@ -1,6 +1,7 @@
 import { Action, BehaviorClass, StateFor, ValidTuple } from '@skewedaspect/sage-core';
-import { NodeEntity } from "./nodeEntity.d.ts";
-import { MeshConfig } from "./meshConfig.d.ts";
+import { NodeEntity } from "./nodeEntity.js";
+import { MeshConfig } from "./meshConfig.js";
+import { NodeSimulationContext } from "./nodeSimulationContext.js";
 export interface GameEntityDefinition<Behaviors extends readonly BehaviorClass[]> {
     type: string;
     tags?: string[];
@@ -9,9 +10,10 @@ export interface GameEntityDefinition<Behaviors extends readonly BehaviorClass[]
     mesh?: MeshConfig;
     actions?: readonly Action[];
 }
-export type GameEntityDefinitionClass<Behaviors extends readonly BehaviorClass[]> = typeof NodeEntity & {
+export type GameEntityDefinitionClass<Behaviors extends readonly BehaviorClass[]> = Omit<typeof NodeEntity, 'prototype'> & {
     readonly behaviors: Behaviors;
-};
+    readonly prototype: NodeEntity<Behaviors>;
+} & (abstract new (id: string, context: NodeSimulationContext, providedState: object, runCreateHooks: boolean, name?: string) => NodeEntity<Behaviors>);
 export declare function defineEntity<Behaviors extends readonly BehaviorClass[]>(definition: GameEntityDefinition<Behaviors> & {
-    behaviors: ValidTuple<Behaviors>;
+    behaviors: ValidTuple<Behaviors, NodeEntity<Behaviors>>;
 }): GameEntityDefinitionClass<Behaviors>;

package/dist/entities/entityPicking.d.ts

@@ -1,6 +1,6 @@
 import { Vector3, AbstractMesh, PickingInfo } from '@babylonjs/core';
 import { GameEntity } from '@skewedaspect/sage-core';
-import { NodeEntity } from "./nodeEntity.d.ts";
+import { NodeEntity } from "./nodeEntity.js";
 export interface EntityPickFilter {
     tags?: readonly string[];
 }

package/dist/entities/meshConfig.d.ts

@@ -1,11 +1,19 @@
-import { ColorConfig } from "../interfaces/level.d.ts";
-export interface MeshMaterialConfig {
-    type?: 'standard' | 'pbr';
+import { ColorConfig } from "../interfaces/level.js";
+export interface StandardMaterialConfig {
+    type?: 'standard';
+    color?: ColorConfig;
+    emissive?: ColorConfig;
+    metallic?: never;
+    roughness?: never;
+}
+export interface PBRMaterialConfig {
+    type: 'pbr';
     color?: ColorConfig;
     emissive?: ColorConfig;
     metallic?: number;
     roughness?: number;
 }
+export type MeshMaterialConfig = StandardMaterialConfig | PBRMaterialConfig;
 export interface MeshConfig {
     source: string;
     params?: Record<string, unknown>;

package/dist/entities/nodeEntity.d.ts

@@ -1,8 +1,9 @@
 import { TransformNode, AbstractMesh } from '@babylonjs/core';
-import { GameEntity, Action, GameEntityState, GameSimulationContext } from '@skewedaspect/sage-core';
-import { AudioManager } from "../managers/audio.d.ts";
-import { ColliderDebugConfig } from "../managers/colliderDebug.d.ts";
-import { MeshConfig } from "./meshConfig.d.ts";
+import { GameEntity, Action, BehaviorClass, ComposedOf, DeepReadonly, GameEntityState, GameEntityType, GameSimulationContext, OpsFor, StateFor, ValidTuple } from '@skewedaspect/sage-core';
+import { AudioManager } from "../managers/audio.js";
+import { ColliderDebugConfig } from "../managers/colliderDebug.js";
+import { NodeSimulationContext } from "./nodeSimulationContext.js";
+import { MeshConfig } from "./meshConfig.js";
 export interface Vector3State {
     x: number;
     y: number;
@@ -25,19 +26,27 @@ export interface NodeBehaviorHooks {
     onMeshLoaded?(): void;
     onDestroy?(): void;
 }
-export declare abstract class NodeEntity extends GameEntity {
+export declare abstract class NodeEntity<Behaviors extends readonly BehaviorClass[] = readonly BehaviorClass[]> extends GameEntity {
     #private;
     static readonly poolable: boolean;
     static readonly poolSize?: number;
     static readonly meshConfig?: MeshConfig;
     static readonly actions?: readonly Action[];
+    readonly state: DeepReadonly<StateFor<Behaviors>>;
+    readonly ops: OpsFor<Behaviors>;
+    static create<Type extends GameEntityType>(this: Type & {
+        behaviors: ValidTuple<Type['behaviors'], Type['prototype']>;
+    }, id: string, context: NodeSimulationContext, state?: Partial<StateFor<Type['behaviors']>>, name?: string): ComposedOf<Type>;
+    static restore<Type extends GameEntityType>(this: Type & {
+        behaviors: ValidTuple<Type['behaviors'], Type['prototype']>;
+    }, id: string, context: NodeSimulationContext, state: StateFor<Type['behaviors']>, name?: string): ComposedOf<Type>;
     get node(): TransformNode;
     get mesh(): AbstractMesh | undefined;
     set mesh(mesh: AbstractMesh | undefined);
     get audio(): AudioManager | undefined;
     showCollider(config?: ColliderDebugConfig, color?: string): void;
     hideCollider(name?: string): void;
+    protected declareComputedState(suppliedState: object): void;
     protected constructor(id: string, context: GameSimulationContext, providedState: object, runCreateHooks: boolean, name?: string);
-    update(dt: number): void;
     destroy(): void;
 }

package/dist/entities/nodePool.d.ts

@@ -1,4 +1,4 @@
-import { NodeSet } from "./nodeSimulationContext.d.ts";
+import { NodeSet } from "./nodeSimulationContext.js";
 export declare class NodePool {
     #private;
     take(name: string): NodeSet | undefined;

package/dist/entities/nodeSimulation.d.ts

@@ -1,30 +1,42 @@
-import { GameSimulationManager, GameSimulationOptions, StateBag } from '@skewedaspect/sage-core';
+import { GameSimulationManager, GameEntityRegistry, GameSimulationOptions, GameSimulationSnapshot, StateBag, ValidEntityRegistry } from '@skewedaspect/sage-core';
 import { AbstractMesh, Camera, Ray, Scene } from '@babylonjs/core';
-import { EntityPickFilter, EntityPickResult } from "./entityPicking.d.ts";
-import { NodeEntity } from "./nodeEntity.d.ts";
-import { NodePool } from "./nodePool.d.ts";
-import { MeshLoader, NodeSimulationContext } from "./nodeSimulationContext.d.ts";
-import { AudioManager } from "../managers/audio.d.ts";
-import { ColliderDebugManager } from "../managers/colliderDebug.d.ts";
-export interface NodeSimulationOptions extends GameSimulationOptions {
+import { EntityPickFilter, EntityPickResult } from "./entityPicking.js";
+import { NodeEntity } from "./nodeEntity.js";
+import { NodePool } from "./nodePool.js";
+import { MeshLoader, NodeSimulationContext } from "./nodeSimulationContext.js";
+import { AudioManager } from "../managers/audio.js";
+import { ColliderDebugManager } from "../managers/colliderDebug.js";
+export type NodeEntityRegistry = GameEntityRegistry<NodeSimulationContext>;
+export interface NodeSimulationOptions<Registry extends NodeEntityRegistry = NodeEntityRegistry> extends GameSimulationOptions<Registry> {
     scene: Scene;
     loadMesh: MeshLoader;
     pool: NodePool;
     audio?: AudioManager;
     colliders: ColliderDebugManager;
 }
-export declare class NodeSimulation extends GameSimulationManager implements NodeSimulationContext {
+export declare class NodeSimulation<Registry extends NodeEntityRegistry = NodeEntityRegistry> extends GameSimulationManager<Registry, NodeSimulationContext> implements NodeSimulationContext {
     #private;
     readonly scene: Scene;
     readonly pool: NodePool;
     readonly loadMesh: MeshLoader;
     readonly audio: AudioManager | undefined;
     readonly colliders: ColliderDebugManager;
-    constructor(options: NodeSimulationOptions);
+    constructor(options: NodeSimulationOptions<Registry> & {
+        entityClasses: ValidEntityRegistry<Registry>;
+    });
+    /**
+     * Advances the scene's physics engine by one fixed step.
+     *
+     * A scene with no physics engine has nothing to advance and does nothing, which is what a game that
+     * never asked for physics gets (design/physics.md#physics-is-optional).
+     */
+    protected advanceFixedStep(duration: number): void;
     prewarm(name: string, count: number, state?: StateBag): Promise<void>;
     pickEntityWithRay(ray: Ray, filter?: EntityPickFilter): EntityPickResult | undefined;
     pickEntity(x: number, y: number, filter?: EntityPickFilter): EntityPickResult | undefined;
     pickEntityForward(camera: Camera, range: number, filter?: EntityPickFilter): EntityPickResult | undefined;
     getEntityForMesh(mesh: AbstractMesh): NodeEntity | undefined;
-    protected buildReplacementSimulation(options: GameSimulationOptions): NodeSimulation;
+    spawnByName(name: string, state?: StateBag, id?: string): NodeEntity;
+    buildFromSnapshot(snapshot: GameSimulationSnapshot): NodeSimulation<Registry>;
+    protected buildReplacementSimulation(options: GameSimulationOptions<Registry>): NodeSimulation<Registry>;
 }

package/dist/entities/nodeSimulationContext.d.ts

@@ -1,13 +1,13 @@
 import { AbstractMesh, Scene, TransformNode } from '@babylonjs/core';
 import { GameSimulationContext, StateBag } from '@skewedaspect/sage-core';
-import { AudioManager } from "../managers/audio.d.ts";
-import { ColliderDebugManager } from "../managers/colliderDebug.d.ts";
-import { NodePool } from "./nodePool.d.ts";
+import { AudioManager } from "../managers/audio.js";
+import { ColliderDebugManager } from "../managers/colliderDebug.js";
+import { NodePool } from "./nodePool.js";
 export interface NodeSet {
     node: TransformNode;
     mesh: AbstractMesh | undefined;
 }
-export type MeshLoader = (name: string, state: Readonly<StateBag>) => Promise<AbstractMesh | undefined>;
+export type MeshLoader = (scene: Scene, name: string, state: Readonly<StateBag>) => Promise<AbstractMesh | undefined>;
 export interface NodeSimulationContext extends GameSimulationContext {
     readonly scene: Scene;
     readonly pool: NodePool;

package/dist/entities/standardMeshSource.d.ts

@@ -1,8 +1,8 @@
 import { AbstractMesh, AssetContainer, Mesh } from '@babylonjs/core';
 import { GameEntityType } from '@skewedaspect/sage-core';
-import { EntityMeshLoader } from "../interfaces/game.d.ts";
+import { MeshLoader } from "./nodeSimulationContext.js";
 export interface MeshAssetSource {
     load(path: string): Promise<AssetContainer | AbstractMesh>;
     clone(path: string): Mesh;
 }
-export declare function buildStandardMeshSource(entityClasses: Readonly<Record<string, GameEntityType>>, assets: MeshAssetSource): EntityMeshLoader;
+export declare function buildStandardMeshSource(entityClasses: Readonly<Record<string, GameEntityType>>, assets: MeshAssetSource): MeshLoader;

package/dist/events/payloads.d.ts

@@ -1,4 +1,5 @@
 import { AbstractMesh } from '@babylonjs/core';
+import { LevelInstance } from "../interfaces/level.js";
 /** Payload for level:progress events */
 export interface LevelProgressPayload {
     levelName: string;
@@ -10,7 +11,7 @@ export interface LevelCompletePayload {
     levelName: string;
     message?: string;
     /** The loaded level instance (available for accessing scene, entities, etc.) */
-    level: import('../interfaces/level.ts').LevelInstance;
+    level: LevelInstance;
 }
 /** Payload for level:error events */
 export interface LevelErrorPayload {
@@ -68,26 +69,20 @@ export interface GameResumedPayload {
     /** Optional reason for resuming */
     reason?: string;
 }
-/**
- * Maps library event type strings to their payload types.
- * This is the source of truth for type safety of library-emitted events.
- *
- * The index signature allows this interface to satisfy Record<string, unknown>
- * while still providing type safety for known event types.
- */
-export interface LibraryEventPayloadMap {
-    'level:progress': LevelProgressPayload;
-    'level:complete': LevelCompletePayload;
-    'level:error': LevelErrorPayload;
-    'level:transition:start': LevelTransitionStartPayload;
-    'level:transition:progress': LevelTransitionProgressPayload;
-    'level:transition:complete': LevelTransitionCompletePayload;
-    'level:transition:error': LevelTransitionErrorPayload;
-    'asset:progress': AssetProgressPayload;
-    'asset:complete': AssetCompletePayload;
-    'trigger:enter': TriggerEnterPayload;
-    'trigger:exit': TriggerExitPayload;
-    'game:paused': GamePausedPayload;
-    'game:resumed': GameResumedPayload;
-    [key: string]: unknown;
+declare module '@skewedaspect/sage-core' {
+    interface EventMap {
+        'level:progress': LevelProgressPayload;
+        'level:complete': LevelCompletePayload;
+        'level:error': LevelErrorPayload;
+        'level:transition:start': LevelTransitionStartPayload;
+        'level:transition:progress': LevelTransitionProgressPayload;
+        'level:transition:complete': LevelTransitionCompletePayload;
+        'level:transition:error': LevelTransitionErrorPayload;
+        'asset:progress': AssetProgressPayload;
+        'asset:complete': AssetCompletePayload;
+        'trigger:enter': TriggerEnterPayload;
+        'trigger:exit': TriggerExitPayload;
+        'game:paused': GamePausedPayload;
+        'game:resumed': GameResumedPayload;
+    }
 }

package/dist/handlers/collider.d.ts

@@ -1,17 +1,12 @@
-import { LevelManager } from "../managers/level.d.ts";
+import { LevelManager } from "../managers/level.js";
 /**
  * Register the collider property handler.
  *
  * Supports the following properties on scene nodes:
- * - `collider` (string): Collider type - "box", "sphere", "mesh", or "none"
- * - `collider_mesh` (boolean): On a child node, marks it as the collision source for parent's "mesh" collider
- * - `collider_mass` (number): Mass for the physics body. Defaults to 0 (static). Set > 0 for dynamic bodies.
- * - `collider_kinematic` (boolean): When true, sets `disablePreStep = false` so the physics body
- *   tracks mesh transform each frame. Required for animated colliders (doors, elevators, platforms).
- *
- * For "mesh" colliders, if a child node has `collider_mesh: true`, that child's geometry
- * is used for collision and the child is made invisible.
- *
- * @param levelManager
+ * - `collider` (string): the shape, one of "box", "sphere", "mesh", or "none"
+ * - `collider_mesh` (boolean): on a child node, marks it as the collision source for a parent's "mesh" collider
+ * - `collider_motion` (string): "static", "dynamic", or "kinematic". Defaults to "static".
+ * - `collider_mass` (number): mass in kilograms, defaulting to 1. It sets the mass and nothing else; it does
+ *   not decide whether the body moves.
  */
-export declare function registerColliderHandler(levelManager: LevelManager): void;
+export declare function registerColliderHandler(levelManager: Pick<LevelManager, 'registerPropertyHandler'>): void;