@zylem/game-lib 0.5.1 → 0.6.2

package/dist/{stage-CrmY7V0i.d.ts → stage-types-Bd-KtcYT.d.ts}

@@ -1,30 +1,17 @@
-import { G as GameEntity, U as UpdateContext, S as SetupFunction, b as UpdateFunction, D as DestroyFunction, c as SetupContext, d as DestroyContext, e as BaseNode, L as LoadingEvent } from './entity-bQElAdpo.js';
+import { S as SetupFunction, Z as ZylemShaderObject, G as GameEntity, U as UpdateFunction, D as DestroyFunction, a as SetupContext, b as UpdateContext, c as DestroyContext, d as ZylemWorld, B as BaseNode, L as LoadingEvent, e as BehaviorSystem, f as BehaviorSystemFactory, g as GameEntityOptions, h as StageEvents } from './world-C8tQ7Plj.js';
 import * as bitecs from 'bitecs';
-import { Vector3, Scene, Color, Object3D, Group } from 'three';
-import RAPIER__default, { World, RigidBody, Collider } from '@dimforge/rapier3d-compat';
-import { E as Entity, Z as ZylemCamera, L as LifecycleFunction, C as CameraDebugDelegate, b as CameraDebugState, d as CameraWrapper } from './camera-Dk-fOVZE.js';
-
-declare class ZylemWorld implements Entity<ZylemWorld> {
-    type: string;
-    world: World;
-    collisionMap: Map<string, GameEntity<any>>;
-    collisionBehaviorMap: Map<string, GameEntity<any>>;
-    _removalMap: Map<string, GameEntity<any>>;
-    static loadPhysics(gravity: Vector3): Promise<RAPIER__default.World>;
-    constructor(world: World);
-    addEntity(entity: any): void;
-    setForRemoval(entity: any): void;
-    destroyEntity(entity: GameEntity<any>): void;
-    setup(): void;
-    update(params: UpdateContext<any>): void;
-    updatePostCollisionBehaviors(delta: number): void;
-    updateColliders(delta: number): void;
-    destroy(): void;
-}
+import { defineSystem, IWorld } from 'bitecs';
+import { Scene, Color, Object3D, Vector3 } from 'three';
+import { E as Entity, L as LifecycleFunction, S as StageEntity } from './entity-Bq_eNEDI.js';
+import { Z as ZylemCamera, C as CameraDebugDelegate, a as CameraDebugState, b as CameraWrapper } from './camera-CeJPAgGg.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 } from './entities-DvByhMGU.js';
 
 interface SceneState {
     backgroundColor: Color | string;
     backgroundImage: string | null;
+    backgroundShader?: ZylemShaderObject | null;
 }
 declare class ZylemScene implements Entity<ZylemScene> {
     type: string;
@@ -37,7 +24,13 @@ declare class ZylemScene implements Entity<ZylemScene> {
     _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
+     * Uses the pos.xyww trick to ensure skybox is always at maximum depth
+     */
+    private setupBackgroundShader;
     setup(): void;
     destroy(): void;
     /**
@@ -60,32 +53,19 @@ declare class ZylemScene implements Entity<ZylemScene> {
      * 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;
     /**
      * Add debug helpers to scene
      */
     debugScene(): void;
-}
-
-/**
- * Base entity interface - shared across modules to prevent circular dependencies
- */
-interface BaseEntityInterface {
-    uuid: string;
-    name: string;
-    eid: number;
-    group: Group | null;
-    body: RigidBody | null;
-    collider: Collider | null;
-}
-/**
- * Game entity interface - minimal interface to break circular dependencies
- */
-interface GameEntityInterface extends BaseEntityInterface {
-    type: string;
-    isStatic: boolean;
-    setPosition(x: number, y: number, z: number): void;
-    setRotation(x: number, y: number, z: number): void;
-    setScale(x: number, y: number, z: number): void;
+    /**
+     * Update skybox shader uniforms
+     */
+    updateSkybox(delta: number): void;
 }
 
 /**
@@ -104,6 +84,17 @@ declare abstract class LifeCycleBase<TSelf> {
     nodeDestroy(context: DestroyContext<TSelf>): void;
 }
 
+type StageSystem = {
+    _childrenMap: Map<number, StageEntity & {
+        body: RAPIER__default.RigidBody;
+    }>;
+};
+type TransformSystemResult = {
+    system: ReturnType<typeof defineSystem>;
+    destroy: (world: IWorld) => void;
+};
+declare function createTransformSystem(stage: StageSystem): TransformSystemResult;
+
 type AddEntityFactory = (params: {
     position: Vector3;
     normal?: Vector3;
@@ -122,6 +113,8 @@ declare class StageDebugDelegate {
     private debugCursor;
     private debugLines;
     constructor(stage: ZylemStage, options?: StageDebugDelegateOptions);
+    private initDebugVisuals;
+    private disposeDebugVisuals;
     update(): void;
     dispose(): void;
     private handleActionOnHit;
@@ -143,6 +136,7 @@ interface ZylemStageConfig {
     inputs: Record<string, string[]>;
     backgroundColor: Color | string;
     backgroundImage: string | null;
+    backgroundShader: any | null;
     gravity: Vector3;
     variables: Record<string, any>;
     stageRef?: Stage;
@@ -179,39 +173,48 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     private isLoaded;
     _debugMap: Map<string, BaseNode>;
     private entityAddedHandlers;
-    private loadingHandlers;
     ecs: bitecs.IWorld;
     testSystem: any;
-    transformSystem: 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;
     cameraRef?: ZylemCamera | null;
+    private cameraDelegate;
+    private loadingDelegate;
+    private entityModelDelegate;
     /**
      * Create a new stage.
      * @param options Stage options: partial config, camera, and initial entities or factories
      */
     constructor(options?: StageOptions);
-    private parseOptions;
-    private isZylemStageConfig;
-    private isBaseNode;
-    private isCameraWrapper;
-    private isEntityInput;
-    private isThenable;
     private handleEntityImmediatelyOrQueue;
     private handlePromiseWithSpawnOnResolve;
     private saveState;
     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): Promise<void>;
-    private createDefaultCamera;
+    /**
+     * 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. */
@@ -236,7 +239,12 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
         replayExisting?: boolean;
     }): () => void;
     onLoading(callback: (event: LoadingEvent) => void): () => void;
-    private emitLoading;
+    /**
+     * 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;
     /**
      * Remove an entity and its resources by its UUID.
      * @returns true if removed, false if not found or stage not ready
@@ -256,6 +264,36 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     enqueue(...items: StageEntityInput[]): 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;
+}
+
 type NodeLike = {
     create: Function;
 };
@@ -264,24 +302,74 @@ type EntityInput = AnyNode | (() => AnyNode) | (() => Promise<any>);
 declare class Stage {
     wrappedStage: ZylemStage | null;
     options: StageOptionItem[];
-    update: UpdateFunction<ZylemStage>;
-    setup: SetupFunction<ZylemStage>;
-    destroy: DestroyFunction<ZylemStage>;
+    private _pendingEntities;
+    private setupCallbacks;
+    private updateCallbacks;
+    private destroyCallbacks;
+    private pendingLoadingCallbacks;
+    private eventDelegate;
     constructor(options: StageOptions);
     load(id: string, camera?: ZylemCamera | CameraWrapper | 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>[]): void;
-    onSetup(callback: SetupFunction<ZylemStage>): void;
-    onDestroy(callback: DestroyFunction<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;
+    /**
+     * 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;
 
-export { type BaseEntityInterface as B, type StageOptions as S, Stage as a, createStage as c };
+/**
+ * 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 StageStateInterface as S, type StageOptions as a, Stage as b, createStage as c, createDisk as d, type StageInterface as e };

package/dist/stage.d.ts

@@ -1,26 +1,48 @@
-export { S as StageOptions, c as createStage } from './stage-CrmY7V0i.js';
-export { e as entitySpawner } from './entity-spawner-DNnLYnZq.js';
-import * as _sinclair_typebox from '@sinclair/typebox';
-import { Static } from '@sinclair/typebox';
-import './entity-bQElAdpo.js';
+import { S as StageStateInterface } from './stage-types-Bd-KtcYT.js';
+export { a as StageOptions, c as createStage } from './stage-types-Bd-KtcYT.js';
+export { S as StageBlueprint, e as entitySpawner } from './blueprints-Cq3Ko6_G.js';
+import './world-C8tQ7Plj.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
+import './entity-Bq_eNEDI.js';
 import 'bitecs';
-import './camera-Dk-fOVZE.js';
-import 'three/addons/controls/OrbitControls.js';
+import 'mitt';
+import './camera-CeJPAgGg.js';
 import 'three/examples/jsm/postprocessing/EffectComposer.js';
+import './entity-types-DAu8sGJH.js';
+import './entities-DvByhMGU.js';
+import '@sinclair/typebox';
 
-declare const StageSchema: _sinclair_typebox.TObject<{
-    id: _sinclair_typebox.TString;
-    name: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
-    entities: _sinclair_typebox.TArray<_sinclair_typebox.TObject<{
-        id: _sinclair_typebox.TString;
-        type: _sinclair_typebox.TString;
-        position: _sinclair_typebox.TOptional<_sinclair_typebox.TTuple<[_sinclair_typebox.TNumber, _sinclair_typebox.TNumber]>>;
-        data: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TAny>>;
-    }>>;
-    assets: _sinclair_typebox.TOptional<_sinclair_typebox.TArray<_sinclair_typebox.TString>>;
-}>;
-type StageBlueprint = Static<typeof StageSchema>;
+/**
+ * Event name for stage state changes.
+ * Dispatched when the stage state proxy is updated.
+ */
+declare const STAGE_STATE_CHANGE = "STAGE_STATE_CHANGE";
+/**
+ * Event detail payload for STAGE_STATE_CHANGE events.
+ */
+interface StageStateChangeEvent {
+    entities: StageStateInterface['entities'];
+    variables: StageStateInterface['variables'];
+}
+/**
+ * Initialize the stage state dispatcher.
+ * Subscribes to stageState changes and dispatches STAGE_STATE_CHANGE events to the window.
+ *
+ * @returns Unsubscribe function to stop dispatching events.
+ *
+ * @example
+ * // Start dispatching stage state changes
+ * const unsubscribe = initStageStateDispatcher();
+ *
+ * // Later, stop dispatching
+ * unsubscribe();
+ */
+declare function initStageStateDispatcher(): () => void;
+/**
+ * Manually dispatch the current stage state.
+ * Useful for initial sync when a listener is added.
+ */
+declare function dispatchStageState(): void;
 
-export type { StageBlueprint };
+export { STAGE_STATE_CHANGE, type StageStateChangeEvent, dispatchStageState, initStageStateDispatcher };