@zylem/game-lib 0.5.1 → 0.6.0

package/dist/entity-Bq_eNEDI.d.ts

@@ -0,0 +1,28 @@
+import { RigidBody, Collider, KinematicCharacterController } from '@dimforge/rapier3d-compat';
+import { Group, Mesh } from 'three';
+
+type LifecycleFunction<T> = (params?: any) => void;
+interface Entity<T = any> {
+    setup: (entity: T) => void;
+    destroy: () => void;
+    update: LifecycleFunction<T>;
+    type: string;
+    _collision?: (entity: any, other: any, globals?: any) => void;
+    _destroy?: (globals?: any) => void;
+    name?: string;
+    tag?: Set<string>;
+}
+interface StageEntity extends Entity {
+    uuid: string;
+    body: RigidBody;
+    group: Group;
+    mesh: Mesh;
+    instanceId: number;
+    collider: Collider;
+    controlledRotation: boolean;
+    characterController: KinematicCharacterController;
+    name: string;
+    markedForRemoval: boolean;
+}
+
+export type { Entity as E, LifecycleFunction as L, StageEntity as S };

package/dist/{entity-bQElAdpo.d.ts → entity-COvRtFNG.d.ts}

@@ -57,8 +57,8 @@ type LoadingEvent = {
 };
 interface IGame<TGlobals extends Record<string, unknown> = any> {
     start: () => Promise<this>;
-    nextStage: () => Promise<void>;
-    previousStage: () => Promise<void>;
+    nextStage: () => void;
+    previousStage: () => void;
     reset: () => Promise<void>;
     pause: () => Promise<void>;
     resume: () => Promise<void>;
@@ -140,6 +140,17 @@ interface NodeInterface {
 }
 
 type BaseNodeOptions<T = any> = BaseNode | Partial<T>;
+/**
+ * Lifecycle callback arrays - each lifecycle event can have multiple callbacks
+ * that execute in order.
+ */
+interface LifecycleCallbacks<T> {
+    setup: Array<SetupFunction<T>>;
+    loaded: Array<LoadedFunction<T>>;
+    update: Array<UpdateFunction<T>>;
+    destroy: Array<DestroyFunction<T>>;
+    cleanup: Array<CleanupFunction<T>>;
+}
 declare abstract class BaseNode<Options = any, T = any> implements NodeInterface {
     protected parent: NodeInterface | null;
     protected children: NodeInterface[];
@@ -148,12 +159,39 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     uuid: string;
     name: string;
     markedForRemoval: boolean;
-    setup: SetupFunction<this>;
-    loaded: LoadedFunction<this>;
-    update: UpdateFunction<this>;
-    destroy: DestroyFunction<this>;
-    cleanup: CleanupFunction<this>;
+    /**
+     * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+     */
+    protected lifecycleCallbacks: LifecycleCallbacks<this>;
     constructor(args?: BaseNodeOptions[]);
+    /**
+     * Add setup callbacks to be executed in order during nodeSetup
+     */
+    onSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Add loaded callbacks to be executed in order during nodeLoaded
+     */
+    onLoaded(...callbacks: Array<LoadedFunction<this>>): this;
+    /**
+     * Add update callbacks to be executed in order during nodeUpdate
+     */
+    onUpdate(...callbacks: Array<UpdateFunction<this>>): this;
+    /**
+     * Add destroy callbacks to be executed in order during nodeDestroy
+     */
+    onDestroy(...callbacks: Array<DestroyFunction<this>>): this;
+    /**
+     * Add cleanup callbacks to be executed in order during nodeCleanup
+     */
+    onCleanup(...callbacks: Array<CleanupFunction<this>>): this;
+    /**
+     * Prepend setup callbacks (run before existing ones)
+     */
+    prependSetup(...callbacks: Array<SetupFunction<this>>): this;
+    /**
+     * Prepend update callbacks (run before existing ones)
+     */
+    prependUpdate(...callbacks: Array<UpdateFunction<this>>): this;
     setParent(parent: NodeInterface | null): void;
     getParent(): NodeInterface | null;
     add(baseNode: NodeInterface): void;
@@ -169,6 +207,8 @@ declare abstract class BaseNode<Options = any, T = any> implements NodeInterface
     nodeSetup(params: SetupContext<this>): void;
     nodeUpdate(params: UpdateContext<this>): void;
     nodeDestroy(params: DestroyContext<this>): void;
+    nodeLoaded(params: LoadedContext<this>): Promise<void>;
+    nodeCleanup(params: CleanupContext<this>): Promise<void>;
     getOptions(): Options;
     setOptions(options: Partial<Options>): void;
 }
@@ -204,15 +244,17 @@ declare class MaterialBuilder {
     setShader(customShader: ZylemShaderType): void;
 }
 
+/**
+ * Options for configuring entity collision behavior.
+ */
 interface CollisionOptions {
     static?: boolean;
     sensor?: boolean;
-    size?: Vector3;
-    position?: Vector3;
+    size?: Vector3$1;
+    position?: Vector3$1;
     collisionType?: string;
     collisionFilter?: string[];
 }
-
 declare class CollisionBuilder {
     static: boolean;
     sensor: boolean;
@@ -255,11 +297,6 @@ interface Behavior {
     values: any;
 }
 
-interface LifeCycleDelegate<U> {
-    setup?: ((params: SetupContext<U>) => void)[];
-    update?: ((params: UpdateContext<U>) => void)[];
-    destroy?: ((params: DestroyContext<U>) => void)[];
-}
 interface CollisionContext<T, O extends GameEntityOptions, TGlobals extends Record<string, unknown> = any> {
     entity: T;
     other: GameEntity<O>;
@@ -316,19 +353,30 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     custom: Record<string, any>;
     debugInfo: Record<string, any>;
     debugMaterial: ShaderMaterial | undefined;
-    lifeCycleDelegate: LifeCycleDelegate<O>;
     collisionDelegate: CollisionDelegate<this, O>;
     collisionType?: string;
     behaviorCallbackMap: Record<BehaviorCallbackType, BehaviorCallback<this, O>[]>;
     constructor();
     create(): this;
-    onSetup(...callbacks: ((params: SetupContext<this>) => void)[]): this;
-    onUpdate(...callbacks: ((params: UpdateContext<this>) => void)[]): this;
-    onDestroy(...callbacks: ((params: DestroyContext<this>) => void)[]): this;
+    /**
+     * Add collision callbacks
+     */
     onCollision(...callbacks: ((params: CollisionContext<this, O>) => void)[]): this;
+    /**
+     * Entity-specific setup - runs behavior callbacks
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+     */
     _setup(params: SetupContext<this>): void;
     protected _loaded(_params: LoadedContext<this>): Promise<void>;
+    /**
+     * Entity-specific update - updates materials and runs behavior callbacks
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+     */
     _update(params: UpdateContext<this>): void;
+    /**
+     * Entity-specific destroy - runs behavior callbacks
+     * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+     */
     _destroy(params: DestroyContext<this>): void;
     protected _cleanup(_params: CleanupContext<this>): Promise<void>;
     _collision(other: GameEntity<O>, globals?: any): void;
@@ -344,4 +392,4 @@ declare class GameEntity<O extends GameEntityOptions> extends BaseNode<O> implem
     buildInfo(): Record<string, string>;
 }
 
-export { type AnalogState as A, type BehaviorCallbackType as B, type CleanupContext as C, type DestroyFunction as D, GameEntity as G, type InputGamepad as I, type LoadingEvent as L, type MaterialOptions as M, type SetupFunction as S, type TexturePath as T, type UpdateContext as U, type Vec3 as V, type Behavior as a, type UpdateFunction as b, type SetupContext as c, type DestroyContext as d, BaseNode as e, type InputPlayerNumber as f, type Inputs as g, type ButtonState as h, GameEntityLifeCycle as i, type IGame as j, type LoadedContext as k, type GameEntityOptions as l, type CollisionContext as m };
+export { type AnalogState as A, type BehaviorCallbackType as B, type CleanupContext as C, type DestroyFunction as D, GameEntity as G, type InputGamepad as I, type LoadingEvent as L, type MaterialOptions as M, type SetupContext as S, type TexturePath as T, type UpdateContext as U, type Vec3 as V, type Behavior as a, type SetupFunction as b, type UpdateFunction as c, type DestroyContext as d, BaseNode as e, type InputPlayerNumber as f, type Inputs as g, type ButtonState as h, GameEntityLifeCycle as i, type IGame as j, type LoadedContext as k, type GameEntityOptions as l, type CollisionContext as m };

package/dist/main.d.ts

@@ -1,11 +1,12 @@
-import { G as Game } from './core-C2mjetAd.js';
-export { V as Vect3, Z as ZylemGameConfig, c as createGame, g as gameConfig, a as globalChange, b as globalChanges, d as variableChange, e as variableChanges, v as vessel } from './core-C2mjetAd.js';
-export { S as StageOptions, c as createStage } from './stage-CrmY7V0i.js';
-export { e as entitySpawner } from './entity-spawner-DNnLYnZq.js';
-export { P as PerspectiveType, a as Perspectives, c as camera } from './camera-Dk-fOVZE.js';
-export { ZylemBox, actor, box, plane, rect, sphere, sprite, text, zone } from './entities.js';
-import { U as UpdateContext, B as BehaviorCallbackType } from './entity-bQElAdpo.js';
-export { a as Behavior, L as LoadingEvent } from './entity-bQElAdpo.js';
+import { G as Game } from './core-CZhozNRH.js';
+export { V as Vect3, Z as ZylemGameConfig, c as createGame, g as gameConfig, a as globalChange, b as globalChanges, d as variableChange, e as variableChanges, v as vessel } from './core-CZhozNRH.js';
+export { a as StageOptions, c as createStage } from './stage-types-CD21XoIU.js';
+import { S as StageBlueprint } from './blueprints-BOCc3Wve.js';
+export { e as entitySpawner } from './blueprints-BOCc3Wve.js';
+export { P as PerspectiveType, a as Perspectives, c as camera } from './camera-CpbDr4-V.js';
+export { A as ACTOR_TYPE, B as BOX_TYPE, P as PLANE_TYPE, R as RECT_TYPE, d as SPHERE_TYPE, S as SPRITE_TYPE, T as TEXT_TYPE, e as ZONE_TYPE, Z as ZylemBox, c as actor, b as box, p as plane, r as rect, s as sphere, a as sprite, t as text, z as zone } from './entities-BAxfJOkk.js';
+import { U as UpdateContext, B as BehaviorCallbackType, G as GameEntity } from './entity-COvRtFNG.js';
+export { a as Behavior, L as LoadingEvent, S as SetupContext } from './entity-COvRtFNG.js';
 export { boundary2d, ricochet2DCollision, ricochet2DInBounds } from './behaviors.js';
 import { M as MoveableEntity } from './moveable-B_vyA6cw.js';
 export { m as makeMoveable, b as move, a as moveable, r as resetVelocity } from './moveable-B_vyA6cw.js';
@@ -15,10 +16,40 @@ import * as three from 'three';
 export { three as THREE };
 import * as RAPIER from '@dimforge/rapier3d-compat';
 export { RAPIER };
+export { S as StageEntity } from './entity-Bq_eNEDI.js';
 import 'bitecs';
-import 'three/addons/controls/OrbitControls.js';
+import '@sinclair/typebox';
 import 'three/examples/jsm/postprocessing/EffectComposer.js';
 
+declare const stageState: {
+    previous: StageBlueprint | null;
+    current: StageBlueprint | null;
+    next: StageBlueprint | null;
+    isLoading: boolean;
+};
+declare const StageManager: {
+    staticRegistry: Map<string, {
+        name?: string | undefined;
+        assets?: string[] | undefined;
+        id: string;
+        entities: {
+            position?: [number, number] | undefined;
+            data?: {
+                [x: string]: any;
+            } | undefined;
+            id: string;
+            type: string;
+        }[];
+    }>;
+    registerStaticStage(id: string, blueprint: StageBlueprint): void;
+    loadStageData(stageId: string): Promise<StageBlueprint>;
+    transitionForward(nextStageId: string, loadStaticStage?: (id: string) => Promise<StageBlueprint>): Promise<void>;
+    /**
+     * Manually set the next stage to pre-load it.
+     */
+    preloadNext(stageId: string, loadStaticStage?: (id: string) => Promise<StageBlueprint>): Promise<void>;
+};
+
 interface MovementSequence2DStep {
     name: string;
     moveX?: number;
@@ -54,6 +85,7 @@ declare function pingPongBeep(frequency?: number, duration?: number): void;
 
 /**
  * Set a global value by path.
+ * Emits a 'game:state:updated' event when the value changes.
  * @example setGlobal('score', 100)
  * @example setGlobal('player.health', 50)
  */
@@ -74,14 +106,15 @@ declare function createGlobal<T>(path: string, defaultValue: T): T;
 declare function getGlobal<T = unknown>(path: string): T | undefined;
 /**
  * Subscribe to changes on a global value at a specific path.
- * Returns an unsubscribe function.
+ * Returns an unsubscribe function. Subscriptions are automatically
+ * cleaned up when the game is disposed.
  * @example const unsub = onGlobalChange('score', (val) => console.log(val));
  */
 declare function onGlobalChange<T = unknown>(path: string, callback: (value: T) => void): () => void;
 /**
  * Subscribe to changes on multiple global paths.
  * Callback fires when any of the paths change, receiving all current values.
- * Returns an unsubscribe function.
+ * Subscriptions are automatically cleaned up when the game is disposed.
  * @example const unsub = onGlobalChanges(['score', 'lives'], ([score, lives]) => console.log(score, lives));
  */
 declare function onGlobalChanges<T extends unknown[] = unknown[]>(paths: string[], callback: (values: T) => void): () => void;
@@ -89,6 +122,11 @@ declare function onGlobalChanges<T extends unknown[] = unknown[]>(paths: string[
  * Get the entire globals object (read-only snapshot).
  */
 declare function getGlobals<T = Record<string, unknown>>(): T;
+/**
+ * Unsubscribe all active global subscriptions.
+ * Used internally on game dispose to prevent old callbacks from firing.
+ */
+declare function clearGlobalSubscriptions(): void;
 
 /**
  * Set a variable on an object by path.
@@ -123,13 +161,51 @@ declare function onVariableChange<T = unknown>(target: object, path: string, cal
  */
 declare function onVariableChanges<T extends unknown[] = unknown[]>(target: object, paths: string[], callback: (values: T) => void): () => void;
 
+type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'none';
+interface DebugState {
+    enabled: boolean;
+    paused: boolean;
+    tool: DebugTools;
+    selectedEntity: GameEntity<any> | null;
+    hoveredEntity: GameEntity<any> | null;
+    flags: Set<string>;
+}
+declare const debugState: DebugState;
+declare function setPaused(paused: boolean): void;
+declare function setDebugTool(tool: DebugTools): void;
+
+/**
+ * State interface for editor-to-game communication
+ */
+interface ZylemGameState {
+    gameState?: {
+        debugFlag?: boolean;
+        [key: string]: unknown;
+    };
+    toolbarState?: {
+        tool?: DebugTools;
+        paused?: boolean;
+    };
+    [key: string]: unknown;
+}
 declare class ZylemGameElement extends HTMLElement {
     private _game;
+    private _state;
     private container;
     constructor();
     set game(game: Game<any>);
     get game(): Game<any> | null;
+    set state(value: ZylemGameState);
+    get state(): ZylemGameState;
+    /**
+     * Sync the web component's state with the game-lib's internal debug state
+     */
+    private syncDebugState;
+    /**
+     * Sync toolbar state with game-lib's debug state
+     */
+    private syncToolbarState;
     disconnectedCallback(): void;
 }
 
-export { Game, ZylemGameElement, createGlobal, createVariable, destroy, getGlobal, getGlobals, getVariable, movementSequence2D, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pingPongBeep, ricochetSound, setGlobal, setVariable };
+export { type DebugTools, Game, StageBlueprint, StageManager, UpdateContext, ZylemGameElement, type ZylemGameState, clearGlobalSubscriptions, createGlobal, createVariable, debugState, destroy, getGlobal, getGlobals, getVariable, movementSequence2D, onGlobalChange, onGlobalChanges, onVariableChange, onVariableChanges, pingPongBeep, ricochetSound, setDebugTool, setGlobal, setPaused, setVariable, stageState };