@zylem/game-lib 0.6.2 → 0.6.4

package/dist/stage-types-C19IhuzA.d.ts

@@ -0,0 +1,731 @@
+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-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 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?: MouseConfig;
+    includeDefaults?: boolean;
+}
+interface GameInputConfig {
+    p1?: GameInputPlayerConfig;
+    p2?: GameInputPlayerConfig;
+    p3?: GameInputPlayerConfig;
+    p4?: GameInputPlayerConfig;
+    p5?: GameInputPlayerConfig;
+    p6?: GameInputPlayerConfig;
+    p7?: GameInputPlayerConfig;
+    p8?: GameInputPlayerConfig;
+}
+interface ZylemGameConfig<StageInterface, GameInterface, TGlobals extends BaseGlobals> {
+    id: string;
+    globals?: TGlobals;
+    stages?: StageInterface[];
+    update?: UpdateFunction<GameInterface>;
+    debug?: boolean;
+    time?: number;
+    input?: GameInputConfig;
+}
+
+interface SceneState {
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    backgroundShader?: ZylemShader | null;
+}
+declare class ZylemScene implements Entity<ZylemScene> {
+    type: string;
+    _setup?: SetupFunction<ZylemScene>;
+    scene: Scene;
+    /** @deprecated Use cameraManager instead */
+    zylemCamera: ZylemCamera;
+    cameraManager: CameraManager | null;
+    containerElement: HTMLElement | null;
+    update: LifecycleFunction<ZylemScene>;
+    _collision?: ((entity: any, other: any, globals?: any) => void) | undefined;
+    _destroy?: ((globals?: any) => void) | undefined;
+    name?: string | undefined;
+    tag?: Set<string> | undefined;
+    private skyboxMaterial;
+    constructor(id: string, camera: ZylemCamera, state: SceneState);
+    /**
+     * Create a large inverted box with the shader for skybox effect
+     * Supports both GLSL (ShaderMaterial) and TSL (MeshBasicNodeMaterial) shaders
+     */
+    private setupBackgroundShader;
+    setup(): void;
+    destroy(): void;
+    /**
+     * Setup camera with the scene.
+     * Supports both legacy single camera and CameraManager modes.
+     */
+    setupCamera(scene: Scene, camera: ZylemCamera, rendererManager?: RendererManager): void;
+    /**
+     * Setup with a CameraManager (multi-camera support).
+     */
+    setupCameraManager(scene: Scene, cameraManager: CameraManager, rendererManager: RendererManager): Promise<void>;
+    /**
+     * Add a camera (rig or direct) to the scene graph.
+     */
+    private addCameraToScene;
+    /**
+     * Setup scene lighting
+     */
+    setupLighting(scene: Scene): void;
+    /**
+     * Update renderer size - delegates to camera manager or camera
+     */
+    updateRenderer(width: number, height: number): void;
+    /**
+     * Add object to scene
+     */
+    add(object: Object3D, position?: Vector3): void;
+    /**
+     * Add game entity to scene
+     */
+    addEntity(entity: GameEntity<any>): void;
+    /**
+     * Add an entity's group or mesh to the scene (for late-loaded models).
+     * Uses entity's current body position if physics is active.
+     */
+    addEntityGroup(entity: GameEntity<any>): void;
+    private isAttachedOutsideScene;
+    /**
+     * Add debug helpers to scene
+     */
+    debugScene(): void;
+    /**
+     * Update skybox shader uniforms (only applies to GLSL ShaderMaterial)
+     * TSL shaders use the time node which auto-updates
+     */
+    updateSkybox(delta: number): void;
+}
+
+/**
+ * Configuration for batch key generation
+ */
+interface BatchKeyConfig {
+    geometryType: string;
+    dimensions: Record<string, number>;
+    materialPath?: string | null;
+    shaderType?: 'standard' | 'custom';
+    colorHex?: number;
+}
+/**
+ * Manages instanced mesh batching for entities
+ */
+declare class InstanceManager {
+    private batches;
+    private entityToBatch;
+    private scene;
+    /** Default initial capacity for new batches */
+    static DEFAULT_CAPACITY: number;
+    /** Factor to grow batch when full */
+    static GROWTH_FACTOR: number;
+    /**
+     * Set the scene to add instanced meshes to
+     */
+    setScene(scene: Object3D): void;
+    /**
+     * Generate a batch key from configuration
+     */
+    static generateBatchKey(config: BatchKeyConfig): string;
+    /**
+     * Register an entity with the instance manager
+     * @returns The instance index, or -1 if registration failed
+     */
+    register(entity: GameEntity<any>, geometry: BufferGeometry, material: Material, batchKey: string): number;
+    /**
+     * Unregister an entity from the instance manager
+     */
+    unregister(entity: GameEntity<any>): void;
+    /**
+     * Mark an entity's transform as dirty (needs syncing)
+     */
+    markDirty(entity: GameEntity<any>): void;
+    /**
+     * Update all dirty instance transforms
+     * Call this once per frame
+     */
+    /**
+     * Update all active instance transforms
+     * Call this once per frame
+     */
+    update(): void;
+    private updateInstanceMatrix;
+    /**
+     * Get batch info for an entity
+     */
+    getBatchInfo(entity: GameEntity<any>): {
+        batchKey: string;
+        instanceId: number;
+    } | null;
+    /**
+     * Get statistics about current batching
+     */
+    getStats(): {
+        batchCount: number;
+        totalInstances: number;
+        batches: {
+            key: string;
+            count: number;
+            capacity: number;
+        }[];
+    };
+    /**
+     * Dispose all batches and release resources
+     */
+    dispose(): void;
+    /**
+     * Create a new batch group
+     */
+    private createBatch;
+    /**
+     * Grow a batch's capacity
+     */
+    private growBatch;
+}
+
+/**
+ * Provides BaseNode-like lifecycle without ECS/children. Consumers implement
+ * the protected hooks and may assign public setup/update/destroy callbacks.
+ */
+declare abstract class LifeCycleBase<TSelf> {
+    update: UpdateFunction<TSelf>;
+    setup: SetupFunction<TSelf>;
+    destroy: DestroyFunction<TSelf>;
+    protected abstract _setup(context: SetupContext<TSelf>): void;
+    protected abstract _update(context: UpdateContext<TSelf>): void;
+    protected abstract _destroy(context: DestroyContext<TSelf>): void;
+    nodeSetup(context: SetupContext<TSelf>): void;
+    nodeUpdate(context: UpdateContext<TSelf>): void;
+    nodeDestroy(context: DestroyContext<TSelf>): void;
+}
+
+type StageSystem = {
+    _childrenMap: Map<number, StageEntity & {
+        body: PhysicsPoseReadable | null;
+    }>;
+    _world: {
+        interpolationAlpha: number;
+    } | null;
+};
+type TransformSystemResult = {
+    system: ReturnType<typeof defineSystem>;
+    destroy: (world: IWorld) => void;
+};
+declare function createTransformSystem(stage: StageSystem): TransformSystemResult;
+
+type AddEntityFactory = (params: {
+    position: Vector3;
+    normal?: Vector3;
+}) => Promise<any> | any;
+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 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;
+}
+
+/**
+ * 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 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 {
+    inputs: Record<string, string[]>;
+    backgroundColor: Color | string;
+    backgroundImage: string | null;
+    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 StageOptionItem = Partial<ZylemStageConfig> | CameraWrapper | StageEntityInput;
+type StageOptions = [] | [Partial<ZylemStageConfig>, ...StageOptionItem[]];
+type StageState = ZylemStageConfig & {
+    entities: GameEntityInterface[];
+};
+/**
+ * ZylemStage orchestrates scene, physics world, entities, and lifecycle.
+ *
+ * Responsibilities:
+ * - Manage stage configuration (background, inputs, gravity, variables)
+ * - Initialize and own `ZylemScene` and `ZylemWorld`
+ * - Coordinate delegates for entities, camera, loading, debug, and models
+ * - Drive per-frame updates and transform system
+ */
+declare class ZylemStage extends LifeCycleBase<ZylemStage> {
+    type: string;
+    state: StageState;
+    gravity: Vector3;
+    world: ZylemWorld | null;
+    scene: ZylemScene | null;
+    instanceManager: InstanceManager | null;
+    ecs: bitecs.IWorld;
+    transformSystem: ReturnType<typeof createTransformSystem> | null;
+    debugDelegate: StageDebugDelegate | null;
+    uuid: string;
+    wrapperRef: Stage | null;
+    camera?: CameraWrapper;
+    cameras: CameraWrapper[];
+    cameraRef?: ZylemCamera | null;
+    /** Camera manager for multi-camera support */
+    cameraManagerRef: CameraManager | null;
+    /** Shared renderer manager (injected by the game) */
+    rendererManager: RendererManager | null;
+    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 setState;
+    /**
+     * Load and initialize the stage's scene and world.
+     * Uses generator pattern to yield control to event loop for real-time progress.
+     * @param id DOM element id for the renderer container
+     * @param camera Optional camera override
+     */
+    load(id: string, camera?: ZylemCamera | null, rendererManager?: RendererManager | null): Promise<void>;
+    protected _setup(params: SetupContext<ZylemStage>): void;
+    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;
+    /** Forward to entity delegate. */
+    spawnEntity(child: BaseNode): Promise<void>;
+    /** Forward to entity delegate. */
+    buildEntityState(child: BaseNode): Partial<BaseEntityInterface>;
+    /** Forward to entity delegate. */
+    onEntityAdded(callback: (entity: BaseNode) => void, options?: {
+        replayExisting?: boolean;
+    }): () => void;
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Register an ECS behavior system to run each frame.
+     * @param systemOrFactory A BehaviorSystem instance or factory function
+     * @returns this for chaining
+     */
+    registerSystem(systemOrFactory: BehaviorSystem | BehaviorSystemFactory): this;
+    /** Forward to entity delegate. */
+    removeEntityByUuid(uuid: string): boolean;
+    /** 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. */
+    addCamera(camera: ZylemCamera, name?: string): string | null;
+    /** Remove a camera from this stage's camera manager. */
+    removeCamera(nameOrRef: string | ZylemCamera): boolean;
+    /** Set the active camera by name or reference. */
+    setActiveCamera(nameOrRef: string | ZylemCamera): boolean;
+    /** Get a camera by name from the camera manager. */
+    getCamera(name: string): ZylemCamera | null;
+    /** Resize renderer viewport. */
+    resize(width: number, height: number): void;
+}
+
+type ZylemDiskOptions = GameEntityOptions & {
+    innerRadius?: number;
+    outerRadius?: number;
+    thetaSegments?: number;
+};
+declare const DISK_TYPE: unique symbol;
+declare class ZylemDisk extends GameEntity<ZylemDiskOptions> {
+    static type: symbol;
+    constructor(options?: ZylemDiskOptions);
+    buildInfo(): Record<string, any>;
+}
+type DiskOptions = BaseNode | Partial<ZylemDiskOptions>;
+declare function createDisk(...args: Array<DiskOptions>): ZylemDisk;
+
+/**
+ * Maps entity type symbols to their class types.
+ * Used by getEntityByName to infer return types.
+ */
+interface EntityTypeMap {
+    [SPRITE_TYPE]: ZylemSprite;
+    [SPHERE_TYPE]: ZylemSphere;
+    [RECT_TYPE]: ZylemRect;
+    [TEXT_TYPE]: ZylemText;
+    [BOX_TYPE]: ZylemBox;
+    [PLANE_TYPE]: ZylemPlane;
+    [ZONE_TYPE]: ZylemZone;
+    [ACTOR_TYPE]: ZylemActor;
+    [DISK_TYPE]: ZylemDisk;
+    [CONE_TYPE]: ZylemCone;
+    [PYRAMID_TYPE]: ZylemPyramid;
+    [CYLINDER_TYPE]: ZylemCylinder;
+    [PILL_TYPE]: ZylemPill;
+}
+
+type NodeLike = {
+    create: Function;
+};
+type AnyNode = NodeLike | Promise<NodeLike>;
+type EntityInput = AnyNode | (() => AnyNode) | (() => Promise<any>);
+declare class Stage {
+    wrappedStage: ZylemStage | null;
+    options: StageOptionItem[];
+    private _pendingEntities;
+    private setupCallbacks;
+    private updateCallbacks;
+    private destroyCallbacks;
+    private pendingLoadingCallbacks;
+    private eventDelegate;
+    /** Per-stage input configuration overrides. Merged with game-level defaults on stage load. */
+    inputConfig: GameInputConfig | null;
+    /**
+     * Callback set by the game to trigger input reconfiguration
+     * when this stage's input config changes at runtime.
+     * @internal
+     */
+    onInputConfigChanged: (() => void) | null;
+    constructor(options: StageOptions);
+    /**
+     * Set composable input configuration for this stage.
+     * Multiple configs are deep-merged (later configs win on key conflicts).
+     * If this stage is currently active, the change takes effect immediately.
+     * @example stage.setInputConfiguration(useArrowsForAxes('p1'), useWASDForDirections('p2'));
+     */
+    setInputConfiguration(...configs: GameInputConfig[]): this;
+    load(id: string, camera?: ZylemCamera | CameraWrapper | null, rendererManager?: RendererManager | null): Promise<void>;
+    private applyLifecycleCallbacks;
+    addEntities(entities: BaseNode[]): Promise<void>;
+    add(...inputs: Array<EntityInput>): void;
+    private addToBlueprints;
+    private addToStage;
+    start(params: SetupContext<ZylemStage>): void;
+    onUpdate(...callbacks: UpdateFunction<ZylemStage>[]): this;
+    onSetup(...callbacks: SetupFunction<ZylemStage>[]): this;
+    onDestroy(...callbacks: DestroyFunction<ZylemStage>[]): this;
+    onLoading(callback: (event: LoadingEvent) => void): () => void;
+    /**
+     * Find an entity by name on the current stage.
+     * @param name The name of the entity to find
+     * @param type Optional type symbol for type inference (e.g., TEXT_TYPE, SPRITE_TYPE)
+     * @returns The entity if found, or undefined
+     * @example stage.getEntityByName('scoreText', TEXT_TYPE)
+     */
+    getEntityByName<T extends symbol | void = void>(name: string, type?: T): T extends keyof EntityTypeMap ? EntityTypeMap[T] | undefined : BaseNode | undefined;
+    /**
+     * Add a camera to this stage.
+     * @param camera The ZylemCamera or CameraWrapper to add
+     * @param name Optional name for lookup
+     */
+    addCamera(camera: ZylemCamera | CameraWrapper, name?: string): string | null;
+    /**
+     * Remove a camera from this stage by name or reference.
+     */
+    removeCamera(nameOrRef: string | ZylemCamera | CameraWrapper): boolean;
+    /**
+     * Set the active camera by name or reference.
+     */
+    setActiveCamera(nameOrRef: string | ZylemCamera | CameraWrapper): boolean;
+    /**
+     * Get a camera by name from the camera manager.
+     */
+    getCamera(name: string): ZylemCamera | null;
+    /**
+     * Dispatch an event from the stage.
+     * Events are emitted both locally and to the global event bus.
+     */
+    dispatch<K extends keyof StageEvents>(event: K, payload: StageEvents[K]): void;
+    /**
+     * Listen for events on this stage instance.
+     * @returns Unsubscribe function
+     */
+    listen<K extends keyof StageEvents>(event: K, handler: (payload: StageEvents[K]) => void): () => void;
+    /**
+     * Clean up stage resources including event subscriptions.
+     */
+    dispose(): void;
+}
+/**
+ * Create a stage with optional camera
+ */
+declare function createStage(...options: StageOptions): Stage;
+
+/**
+ * Stage state interface - minimal to prevent circular dependencies
+ */
+interface StageStateInterface {
+    backgroundColor: Color;
+    backgroundImage: string | null;
+    inputs: {
+        p1: string[];
+        p2: string[];
+    };
+    variables: Record<string, any>;
+    gravity: Vector3;
+    entities: Partial<BaseEntityInterface>[];
+    stageRef?: any;
+}
+/**
+ * Minimal stage interface to break circular dependencies
+ */
+interface StageInterface {
+    uuid: string;
+    children: any[];
+    state: StageStateInterface;
+}
+
+export { type BaseGlobals as B, type GameInputConfig as G, type StageStateInterface as S, type ZylemGameConfig as Z, type StageOptions as a, Stage as b, createStage as c, createDisk as d, type StageInterface as e };