@zylem/game-lib 0.6.3 → 0.6.4

package/dist/{stage-types-BFsm3qsZ.d.ts → stage-types-C19IhuzA.d.ts}

@@ -1,22 +1,30 @@
-import { J as UpdateFunction, S as SetupFunction, Z as ZylemShader, I as GameEntity, K as DestroyFunction, L as SetupContext, U as UpdateContext, M as DestroyContext, N as BaseNode, O as LoadingEvent, P as GameEntityOptions, Q as StageEvents } from './entity-BpbZqg19.js';
+import { J as UpdateFunction, S as SetupFunction, Z as ZylemShader, I as GameEntity, K as DestroyFunction, L as SetupContext, U as UpdateContext, M as DestroyContext, N as LoadingEvent, O as BaseNode, P as GameEntityOptions, Q as StageEvents } from './entity-vj-HTjzU.js';
 import * as bitecs from 'bitecs';
 import { defineSystem, IWorld } from 'bitecs';
 import { Scene, Color, Object3D, Vector3, BufferGeometry, Material } from 'three';
-import { Z as ZylemWorld } from './world-Be5m1XC1.js';
+import { Z as ZylemWorld } from './world-DfgxoNMt.js';
 import { E as Entity, L as LifecycleFunction, S as StageEntity } from './entity-Bq_eNEDI.js';
-import { Z as ZylemCamera, C as CameraManager, R as RendererManager, a as CameraDebugDelegate, b as CameraDebugState, c as CameraWrapper } from './camera-B5e4c78l.js';
-import { G as GameEntityInterface, B as BaseEntityInterface } from './entity-types-DAu8sGJH.js';
-import RAPIER__default from '@dimforge/rapier3d-compat';
-import { S as SPRITE_TYPE, Z as ZylemSprite, a as SPHERE_TYPE, b as ZylemSphere, R as RECT_TYPE, c as ZylemRect, T as TEXT_TYPE, d as ZylemText, B as BOX_TYPE, e as ZylemBox, P as PLANE_TYPE, f as ZylemPlane, g as ZONE_TYPE, h as ZylemZone, A as ACTOR_TYPE, i as ZylemActor, C as CONE_TYPE, j as ZylemCone, k as PYRAMID_TYPE, l as ZylemPyramid, m as CYLINDER_TYPE, n as ZylemCylinder, o as PILL_TYPE, p as ZylemPill } from './entities-DC9ce_vx.js';
-import { B as BehaviorSystem, a as BehaviorSystemFactory } from './behavior-descriptor-BWNWmIjv.js';
+import { Z as ZylemCamera, C as CameraManager, R as RendererManager, a as CameraWrapper } from './camera-4XO5gbQH.js';
+import { B as BaseEntityInterface, G as GameEntityInterface } from './entity-types-DAu8sGJH.js';
+import { b as PhysicsPoseReadable } from './physics-pose-DCc4oE44.js';
+import { S as SPRITE_TYPE, Z as ZylemSprite, a as SPHERE_TYPE, b as ZylemSphere, R as RECT_TYPE, c as ZylemRect, T as TEXT_TYPE, d as ZylemText, B as BOX_TYPE, e as ZylemBox, P as PLANE_TYPE, f as ZylemPlane, g as ZONE_TYPE, h as ZylemZone, A as ACTOR_TYPE, i as ZylemActor, C as CONE_TYPE, j as ZylemCone, k as PYRAMID_TYPE, l as ZylemPyramid, m as CYLINDER_TYPE, n as ZylemCylinder, o as PILL_TYPE, p as ZylemPill } from './entities-ChFirVL9.js';
+import { B as BehaviorSystem, a as BehaviorEntityLink, b as BehaviorSystemFactory } from './behavior-descriptor-BXnVR8Ki.js';
 
 type BasicTypes = number | string | boolean;
 type BaseGlobals = Record<string, BasicTypes>;
 type KeyboardMapping = Record<string, string[]>;
 type MouseMapping = Record<string, string[]>;
+interface MouseConfig {
+    /** Custom mapping from mouse actions to input properties. */
+    mapping?: MouseMapping;
+    /** Whether to capture the cursor via Pointer Lock API. */
+    pointerLock?: boolean;
+    /** Sensitivity multiplier for mouse movement (default 0.002). */
+    sensitivity?: number;
+}
 interface GameInputPlayerConfig {
     key?: KeyboardMapping;
-    mouse?: MouseMapping;
+    mouse?: MouseConfig;
     includeDefaults?: boolean;
 }
 interface GameInputConfig {
@@ -100,6 +108,7 @@ declare class ZylemScene implements Entity<ZylemScene> {
      * Uses entity's current body position if physics is active.
      */
     addEntityGroup(entity: GameEntity<any>): void;
+    private isAttachedOutsideScene;
     /**
      * Add debug helpers to scene
      */
@@ -214,8 +223,11 @@ declare abstract class LifeCycleBase<TSelf> {
 
 type StageSystem = {
     _childrenMap: Map<number, StageEntity & {
-        body: RAPIER__default.RigidBody;
+        body: PhysicsPoseReadable | null;
     }>;
+    _world: {
+        interpolationAlpha: number;
+    } | null;
 };
 type TransformSystemResult = {
     system: ReturnType<typeof defineSystem>;
@@ -231,33 +243,236 @@ interface StageDebugDelegateOptions {
     maxRayDistance?: number;
     addEntityFactory?: AddEntityFactory | null;
 }
+/**
+ * Self-managing debug delegate that subscribes to `debugState` internally.
+ *
+ * When debug is enabled it lazily initializes visuals and DOM listeners.
+ * When debug is disabled it tears down visuals but stays alive so it can
+ * re-activate without being recreated. Call `dispose()` to fully tear down.
+ */
 declare class StageDebugDelegate {
     private stage;
     private options;
     private mouseNdc;
     private raycaster;
     private isMouseDown;
-    private disposeFns;
+    private domDisposeFns;
+    private domListenersAttached;
     private debugCursor;
     private debugLines;
+    private cameraDebugDelegate;
+    private debugStateUnsubscribe;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    private syncWithDebugState;
+    /** Initialize DOM listeners and camera debug delegate when debug is turned on. */
+    private activate;
+    /** Tear down visuals and camera debug delegate when debug is turned off. */
+    private deactivate;
     private initDebugVisuals;
     private disposeDebugVisuals;
     update(): void;
+    /** Full teardown — unsubscribes from debugState and cleans up all resources. */
     dispose(): void;
     private handleActionOnHit;
     private attachDomListeners;
 }
 
 /**
- * Debug delegate that bridges the stage's entity map and debug state to the camera.
+ * Delegate for managing loading events and progress within a stage.
+ * Handles subscription to loading events and broadcasting progress.
+ * Emits to game event bus for game-level observation.
  */
-declare class StageCameraDebugDelegate implements CameraDebugDelegate {
-    private stage;
-    constructor(stage: ZylemStage);
-    subscribe(listener: (state: CameraDebugState) => void): () => void;
-    resolveTarget(uuid: string): Object3D | null;
-    private snapshot;
+declare class StageLoadingDelegate {
+    private loadingHandlers;
+    private stageName?;
+    private stageIndex?;
+    /**
+     * Set stage context for event bus emissions.
+     */
+    setStageContext(stageName: string, stageIndex: number): void;
+    /**
+     * Subscribe to loading events.
+     *
+     * @param callback Invoked for each loading event (start, progress, complete)
+     * @returns Unsubscribe function
+     */
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Emit a loading event to all subscribers and to the game event bus.
+     *
+     * @param event The loading event to broadcast
+     */
+    emit(event: LoadingEvent): void;
+    /**
+     * Emit a start loading event.
+     */
+    emitStart(message?: string): void;
+    /**
+     * Emit a progress loading event.
+     */
+    emitProgress(message: string, current: number, total: number): void;
+    /**
+     * Emit a complete loading event.
+     */
+    emitComplete(message?: string): void;
+    /**
+     * Clear all loading handlers.
+     */
+    dispose(): void;
+}
+
+/**
+ * Delegate for handling deferred model loading in entities.
+ * Subscribes to model:loaded events and adds entity groups to the scene
+ * when they become available after async loading completes.
+ */
+declare class StageEntityModelDelegate {
+    private scene;
+    private onEntityReady;
+    private pendingEntities;
+    private modelLoadedHandler;
+    /**
+     * Initialize the delegate with the scene reference and start listening.
+     */
+    attach(scene: ZylemScene, onEntityReady?: (entity: GameEntity<any>) => void): void;
+    /**
+     * Register an entity for observation.
+     * When its model loads, the group will be added to the scene.
+     */
+    observe(entity: GameEntity<any>): void;
+    /**
+     * Unregister an entity (e.g., when removed before model loads).
+     */
+    unobserve(entityId: string): void;
+    /**
+     * Handle model loaded event - add group to scene if entity is pending.
+     */
+    private handleModelLoaded;
+    /**
+     * Cleanup all subscriptions and pending entities.
+     */
+    dispose(): void;
+}
+
+type NodeLike$1 = {
+    create: Function;
+};
+type StageEntityInput = NodeLike$1 | Promise<any> | (() => NodeLike$1 | Promise<any>);
+/**
+ * Runtime context provided by ZylemStage after scene and world are initialized.
+ */
+interface EntityDelegateContext {
+    scene: ZylemScene;
+    world: ZylemWorld;
+    ecs: ReturnType<typeof bitecs.createWorld>;
+    instanceManager: InstanceManager | null;
+    /** Resolved camera for entity setup contexts. */
+    camera: ZylemCamera;
+}
+/**
+ * Delegate responsible for entity spawning, tracking, queuing, removal, and lookup.
+ *
+ * Owns all entity-related state and exposes it to ZylemStage for orchestration
+ * and to external consumers (debug delegate, transform system) via public getters.
+ */
+declare class StageEntityDelegate {
+    private static readonly EMPTY_BEHAVIOR_LINKS;
+    /** Entities queued before load completes. */
+    children: BaseNode[];
+    /** EID → BaseNode map of all live entities. */
+    readonly childrenMap: Map<number, BaseNode>;
+    /** UUID → BaseNode map populated when debug mode is active. */
+    readonly debugMap: Map<string, BaseNode>;
+    /** UUID → EID reverse lookup for O(1) removal. */
+    private readonly uuidToEid;
+    private pendingEntities;
+    private pendingPromises;
+    private _isLoaded;
+    private entityAddedHandlers;
+    /** ECS behavior systems auto-registered from entity refs or manually added. */
+    readonly behaviorSystems: BehaviorSystem[];
+    readonly registeredSystemKeys: Set<symbol>;
+    readonly behaviorEntityIndex: Map<symbol, Set<BehaviorEntityLink>>;
+    private readonly behaviorLinksByUuid;
+    private scene;
+    private world;
+    private ecs;
+    private instanceManager;
+    private camera;
+    private loadingDelegate;
+    private entityModelDelegate;
+    constructor(loadingDelegate: StageLoadingDelegate, entityModelDelegate: StageEntityModelDelegate);
+    get isLoaded(): boolean;
+    set isLoaded(value: boolean);
+    /**
+     * Bind runtime context after scene and world are initialized.
+     * Must be called before any spawn/enqueue operations.
+     */
+    attach(context: EntityDelegateContext): void;
+    /**
+     * Create, register, and add an entity to the scene/world.
+     * Safe to call only after `attach` when scene/world exist.
+     */
+    spawnEntity(child: BaseNode): Promise<void>;
+    handleLateModelReady(entity: GameEntity<any>): void;
+    /**
+     * Register an entity for instanced rendering if opted in with `batched: true`.
+     */
+    private tryRegisterInstance;
+    private maybeAttachEntityPhysics;
+    /** Add the entity to internal maps and notify listeners. */
+    addEntityToStage(entity: BaseNode): void;
+    /**
+     * Remove an entity and its resources by its UUID.
+     * Uses a uuid→eid reverse map for O(1) lookup.
+     * @returns true if removed, false if not found or stage not ready
+     */
+    removeEntityByUuid(uuid: string): boolean;
+    /** Get an entity by its name; returns null if not found. */
+    getEntityByName(name: string): BaseNode | null;
+    /** Build a serializable state snapshot for an entity. */
+    buildEntityState(child: BaseNode): Partial<BaseEntityInterface>;
+    /**
+     * Subscribe to entity-added events.
+     * @param callback Invoked for each entity when added
+     * @param options.replayExisting If true and stage already loaded, replays existing entities
+     * @returns Unsubscribe function
+     */
+    onEntityAdded(callback: (entity: BaseNode) => void, options?: {
+        replayExisting?: boolean;
+    }): () => void;
+    /**
+     * Enqueue items to be spawned. Items can be:
+     * - BaseNode instances (immediate or deferred until load)
+     * - Factory functions returning BaseNode or Promise<BaseNode>
+     * - Promises resolving to BaseNode
+     */
+    enqueue(...items: StageEntityInput[]): void;
+    private handleEntityImmediatelyOrQueue;
+    private handlePromiseWithSpawnOnResolve;
+    /**
+     * Generator that yields between entity loads for real-time progress updates.
+     */
+    private entityLoadGenerator;
+    /** Yields to the event loop via MessageChannel (~0.1ms vs ~4ms for setTimeout). */
+    private yieldToEventLoop;
+    /**
+     * Runs the entity load generator, yielding to the event loop in batches.
+     * Emits progress events through the loading delegate.
+     */
+    runEntityLoadGenerator(): Promise<void>;
+    /**
+     * Register an ECS behavior system to run each frame.
+     * @param systemOrFactory A BehaviorSystem instance or factory function
+     */
+    registerSystem(systemOrFactory: BehaviorSystem | BehaviorSystemFactory): void;
+    /**
+     * Destroy all entities and clear internal state.
+     * Called by ZylemStage._destroy().
+     */
+    destroyAll(): void;
+    private registerBehaviorLinks;
+    private unregisterBehaviorLinks;
 }
 
 interface ZylemStageConfig {
@@ -267,12 +482,14 @@ interface ZylemStageConfig {
     backgroundShader: any | null;
     gravity: Vector3;
     variables: Record<string, any>;
+    /** Physics update rate in Hz (default 60). */
+    physicsRate: number;
+    /** Run physics in a Web Worker for true parallelism (default false). */
+    usePhysicsWorker: boolean;
+    /** URL to the physics worker script (required when usePhysicsWorker is true). */
+    physicsWorkerUrl?: URL | string;
     stageRef?: Stage;
 }
-type NodeLike$1 = {
-    create: Function;
-};
-type StageEntityInput = NodeLike$1 | Promise<any> | (() => NodeLike$1 | Promise<any>);
 type StageOptionItem = Partial<ZylemStageConfig> | CameraWrapper | StageEntityInput;
 type StageOptions = [] | [Partial<ZylemStageConfig>, ...StageOptionItem[]];
 type StageState = ZylemStageConfig & {
@@ -284,7 +501,7 @@ type StageState = ZylemStageConfig & {
  * Responsibilities:
  * - Manage stage configuration (background, inputs, gravity, variables)
  * - Initialize and own `ZylemScene` and `ZylemWorld`
- * - Spawn, track, and remove entities; emit entity-added events
+ * - Coordinate delegates for entities, camera, loading, debug, and models
  * - Drive per-frame updates and transform system
  */
 declare class ZylemStage extends LifeCycleBase<ZylemStage> {
@@ -294,22 +511,9 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     world: ZylemWorld | null;
     scene: ZylemScene | null;
     instanceManager: InstanceManager | null;
-    children: Array<BaseNode>;
-    _childrenMap: Map<number, BaseNode>;
-    _removalMap: Map<number, BaseNode>;
-    private pendingEntities;
-    private pendingPromises;
-    private isLoaded;
-    _debugMap: Map<string, BaseNode>;
-    private entityAddedHandlers;
     ecs: bitecs.IWorld;
-    testSystem: any;
     transformSystem: ReturnType<typeof createTransformSystem> | null;
-    private behaviorSystems;
-    private registeredSystemKeys;
     debugDelegate: StageDebugDelegate | null;
-    cameraDebugDelegate: StageCameraDebugDelegate | null;
-    private debugStateUnsubscribe;
     uuid: string;
     wrapperRef: Stage | null;
     camera?: CameraWrapper;
@@ -322,14 +526,14 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     private cameraDelegate;
     private loadingDelegate;
     private entityModelDelegate;
+    private readonly childUpdateParams;
+    /** Entity management delegate — public for external consumers (debug, transform system). */
+    readonly entityDelegate: StageEntityDelegate;
     /**
      * Create a new stage.
      * @param options Stage options: partial config, camera, and initial entities or factories
      */
     constructor(options?: StageOptions);
-    private handleEntityImmediatelyOrQueue;
-    private handlePromiseWithSpawnOnResolve;
-    private saveState;
     private setState;
     /**
      * Load and initialize the stage's scene and world.
@@ -338,42 +542,18 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
      * @param camera Optional camera override
      */
     load(id: string, camera?: ZylemCamera | null, rendererManager?: RendererManager | null): Promise<void>;
-    /**
-     * Generator that yields between entity loads for real-time progress updates.
-     */
-    private entityLoadGenerator;
-    /**
-     * Runs the entity load generator, yielding to the event loop between loads.
-     * This allows the browser to process events and update the UI in real-time.
-     */
-    private runEntityLoadGenerator;
     protected _setup(params: SetupContext<ZylemStage>): void;
-    private updateDebugDelegate;
     protected _update(params: UpdateContext<ZylemStage>): void;
     outOfLoop(): void;
     /** Update debug overlays and helpers if enabled. */
     debugUpdate(): void;
     /** Cleanup owned resources when the stage is destroyed. */
     protected _destroy(params: DestroyContext<ZylemStage>): void;
-    /**
-     * Create, register, and add an entity to the scene/world.
-     * Safe to call only after `load` when scene/world exist.
-     */
+    /** Forward to entity delegate. */
     spawnEntity(child: BaseNode): Promise<void>;
-    /**
-     * Try to register an entity for instanced rendering.
-     * Batching is enabled by default unless explicitly disabled with batched: false.
-     */
-    private tryRegisterInstance;
+    /** Forward to entity delegate. */
     buildEntityState(child: BaseNode): Partial<BaseEntityInterface>;
-    /** Add the entity to internal maps and notify listeners. */
-    addEntityToStage(entity: BaseNode): void;
-    /**
-     * Subscribe to entity-added events.
-     * @param callback Invoked for each entity when added
-     * @param options.replayExisting If true and stage already loaded, replays existing entities
-     * @returns Unsubscribe function
-     */
+    /** Forward to entity delegate. */
     onEntityAdded(callback: (entity: BaseNode) => void, options?: {
         replayExisting?: boolean;
     }): () => void;
@@ -384,39 +564,23 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
      * @returns this for chaining
      */
     registerSystem(systemOrFactory: BehaviorSystem | BehaviorSystemFactory): this;
-    /**
-     * Remove an entity and its resources by its UUID.
-     * @returns true if removed, false if not found or stage not ready
-     */
+    /** Forward to entity delegate. */
     removeEntityByUuid(uuid: string): boolean;
-    /** Get an entity by its name; returns null if not found. */
+    /** Forward to entity delegate. */
     getEntityByName(name: string): BaseNode<any, any> | null;
+    /** Forward to entity delegate. */
+    enqueue(...items: StageEntityInput[]): void;
     logMissingEntities(): void;
-    /**
-     * Add a camera to this stage's camera manager.
-     */
+    /** Add a camera to this stage's camera manager. */
     addCamera(camera: ZylemCamera, name?: string): string | null;
-    /**
-     * Remove a camera from this stage's camera manager.
-     */
+    /** Remove a camera from this stage's camera manager. */
     removeCamera(nameOrRef: string | ZylemCamera): boolean;
-    /**
-     * Set the active camera by name or reference.
-     */
+    /** Set the active camera by name or reference. */
     setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
-    /**
-     * Get a camera by name from the camera manager.
-     */
+    /** Get a camera by name from the camera manager. */
     getCamera(name: string): ZylemCamera | null;
     /** Resize renderer viewport. */
     resize(width: number, height: number): void;
-    /**
-     * Enqueue items to be spawned. Items can be:
-     * - BaseNode instances (immediate or deferred until load)
-     * - Factory functions returning BaseNode or Promise<BaseNode>
-     * - Promises resolving to BaseNode
-     */
-    enqueue(...items: StageEntityInput[]): void;
 }
 
 type ZylemDiskOptions = GameEntityOptions & {

package/dist/stage.d.ts

@@ -1,19 +1,20 @@
-import { S as StageStateInterface } from './stage-types-BFsm3qsZ.js';
-export { a as StageOptions, c as createStage } from './stage-types-BFsm3qsZ.js';
-export { S as StageBlueprint, e as entitySpawner } from './blueprints-BWGz8fII.js';
-import './entity-BpbZqg19.js';
+import { S as StageStateInterface } from './stage-types-C19IhuzA.js';
+export { a as StageOptions, c as createStage } from './stage-types-C19IhuzA.js';
+export { S as StageBlueprint, e as entitySpawner } from './blueprints-DmbK2dki.js';
+import './entity-vj-HTjzU.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import 'bitecs';
 import 'mitt';
-import './behavior-descriptor-BWNWmIjv.js';
-import './world-Be5m1XC1.js';
+import './behavior-descriptor-BXnVR8Ki.js';
+import './world-DfgxoNMt.js';
 import './entity-Bq_eNEDI.js';
-import './camera-B5e4c78l.js';
+import './camera-4XO5gbQH.js';
 import 'three/webgpu';
 import 'three/examples/jsm/postprocessing/EffectComposer.js';
 import './entity-types-DAu8sGJH.js';
-import './entities-DC9ce_vx.js';
+import './physics-pose-DCc4oE44.js';
+import './entities-ChFirVL9.js';
 import '@sinclair/typebox';
 
 /**