@zylem/game-lib 0.5.1 → 0.6.0

package/dist/core.js

@@ -9,6 +9,18 @@ var __export = (target, all) => {
 };
 
 // src/lib/core/utility/path-utils.ts
+function getByPath(obj, path) {
+  if (!path) return void 0;
+  const keys = path.split(".");
+  let current = obj;
+  for (const key of keys) {
+    if (current == null || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[key];
+  }
+  return current;
+}
 function setByPath(obj, path, value) {
   if (!path) return;
   const keys = path.split(".");
@@ -28,10 +40,95 @@ var init_path_utils = __esm({
   }
 });
 
+// src/lib/game/game-event-bus.ts
+var GameEventBus, gameEventBus;
+var init_game_event_bus = __esm({
+  "src/lib/game/game-event-bus.ts"() {
+    "use strict";
+    GameEventBus = class {
+      listeners = /* @__PURE__ */ new Map();
+      /**
+       * Subscribe to an event type.
+       */
+      on(event, callback) {
+        if (!this.listeners.has(event)) {
+          this.listeners.set(event, /* @__PURE__ */ new Set());
+        }
+        this.listeners.get(event).add(callback);
+        return () => this.off(event, callback);
+      }
+      /**
+       * Unsubscribe from an event type.
+       */
+      off(event, callback) {
+        this.listeners.get(event)?.delete(callback);
+      }
+      /**
+       * Emit an event to all subscribers.
+       */
+      emit(event, payload) {
+        const callbacks = this.listeners.get(event);
+        if (!callbacks) return;
+        for (const cb of callbacks) {
+          try {
+            cb(payload);
+          } catch (e) {
+            console.error(`Error in event handler for ${event}`, e);
+          }
+        }
+      }
+      /**
+       * Clear all listeners.
+       */
+      dispose() {
+        this.listeners.clear();
+      }
+    };
+    gameEventBus = new GameEventBus();
+  }
+});
+
 // src/lib/game/game-state.ts
 import { proxy, subscribe } from "valtio/vanilla";
 function setGlobal(path, value) {
+  const previousValue = getByPath(state.globals, path);
   setByPath(state.globals, path, value);
+  gameEventBus.emit("game:state:updated", {
+    path,
+    value,
+    previousValue
+  });
+}
+function onGlobalChange(path, callback) {
+  let previous = getByPath(state.globals, path);
+  const unsub = subscribe(state.globals, () => {
+    const current = getByPath(state.globals, path);
+    if (current !== previous) {
+      previous = current;
+      callback(current);
+    }
+  });
+  activeSubscriptions.add(unsub);
+  return () => {
+    unsub();
+    activeSubscriptions.delete(unsub);
+  };
+}
+function onGlobalChanges(paths, callback) {
+  let previousValues = paths.map((p) => getByPath(state.globals, p));
+  const unsub = subscribe(state.globals, () => {
+    const currentValues = paths.map((p) => getByPath(state.globals, p));
+    const hasChange = currentValues.some((val, i) => val !== previousValues[i]);
+    if (hasChange) {
+      previousValues = currentValues;
+      callback(currentValues);
+    }
+  });
+  activeSubscriptions.add(unsub);
+  return () => {
+    unsub();
+    activeSubscriptions.delete(unsub);
+  };
 }
 function getGlobals() {
   return state.globals;
@@ -44,16 +141,24 @@ function initGlobals(globals) {
 function resetGlobals() {
   state.globals = {};
 }
-var state;
+function clearGlobalSubscriptions() {
+  for (const unsub of activeSubscriptions) {
+    unsub();
+  }
+  activeSubscriptions.clear();
+}
+var state, activeSubscriptions;
 var init_game_state = __esm({
   "src/lib/game/game-state.ts"() {
     "use strict";
     init_path_utils();
+    init_game_event_bus();
     state = proxy({
       id: "",
       globals: {},
       time: 0
     });
+    activeSubscriptions = /* @__PURE__ */ new Set();
   }
 });
 
@@ -119,21 +224,76 @@ var init_base_node = __esm({
       uuid = "";
       name = "";
       markedForRemoval = false;
-      setup = () => {
-      };
-      loaded = () => {
-      };
-      update = () => {
-      };
-      destroy = () => {
-      };
-      cleanup = () => {
+      /**
+       * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+       */
+      lifecycleCallbacks = {
+        setup: [],
+        loaded: [],
+        update: [],
+        destroy: [],
+        cleanup: []
       };
       constructor(args = []) {
         const options = args.filter((arg) => !(arg instanceof _BaseNode)).reduce((acc, opt) => ({ ...acc, ...opt }), {});
         this.options = options;
         this.uuid = nanoid();
       }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Fluent API for adding lifecycle callbacks
+      // ─────────────────────────────────────────────────────────────────────────────
+      /**
+       * Add setup callbacks to be executed in order during nodeSetup
+       */
+      onSetup(...callbacks) {
+        this.lifecycleCallbacks.setup.push(...callbacks);
+        return this;
+      }
+      /**
+       * Add loaded callbacks to be executed in order during nodeLoaded
+       */
+      onLoaded(...callbacks) {
+        this.lifecycleCallbacks.loaded.push(...callbacks);
+        return this;
+      }
+      /**
+       * Add update callbacks to be executed in order during nodeUpdate
+       */
+      onUpdate(...callbacks) {
+        this.lifecycleCallbacks.update.push(...callbacks);
+        return this;
+      }
+      /**
+       * Add destroy callbacks to be executed in order during nodeDestroy
+       */
+      onDestroy(...callbacks) {
+        this.lifecycleCallbacks.destroy.push(...callbacks);
+        return this;
+      }
+      /**
+       * Add cleanup callbacks to be executed in order during nodeCleanup
+       */
+      onCleanup(...callbacks) {
+        this.lifecycleCallbacks.cleanup.push(...callbacks);
+        return this;
+      }
+      /**
+       * Prepend setup callbacks (run before existing ones)
+       */
+      prependSetup(...callbacks) {
+        this.lifecycleCallbacks.setup.unshift(...callbacks);
+        return this;
+      }
+      /**
+       * Prepend update callbacks (run before existing ones)
+       */
+      prependUpdate(...callbacks) {
+        this.lifecycleCallbacks.update.unshift(...callbacks);
+        return this;
+      }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Tree structure
+      // ─────────────────────────────────────────────────────────────────────────────
       setParent(parent) {
         this.parent = parent;
       }
@@ -157,6 +317,9 @@ var init_base_node = __esm({
       isComposite() {
         return this.children.length > 0;
       }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Node lifecycle execution - runs internal + callback arrays
+      // ─────────────────────────────────────────────────────────────────────────────
       nodeSetup(params) {
         if (DEBUG_FLAG) {
         }
@@ -164,8 +327,8 @@ var init_base_node = __esm({
         if (typeof this._setup === "function") {
           this._setup(params);
         }
-        if (this.setup) {
-          this.setup(params);
+        for (const callback of this.lifecycleCallbacks.setup) {
+          callback(params);
         }
         this.children.forEach((child) => child.nodeSetup(params));
       }
@@ -176,21 +339,40 @@ var init_base_node = __esm({
         if (typeof this._update === "function") {
           this._update(params);
         }
-        if (this.update) {
-          this.update(params);
+        for (const callback of this.lifecycleCallbacks.update) {
+          callback(params);
         }
         this.children.forEach((child) => child.nodeUpdate(params));
       }
       nodeDestroy(params) {
         this.children.forEach((child) => child.nodeDestroy(params));
-        if (this.destroy) {
-          this.destroy(params);
+        for (const callback of this.lifecycleCallbacks.destroy) {
+          callback(params);
         }
         if (typeof this._destroy === "function") {
           this._destroy(params);
         }
         this.markedForRemoval = true;
       }
+      async nodeLoaded(params) {
+        if (typeof this._loaded === "function") {
+          await this._loaded(params);
+        }
+        for (const callback of this.lifecycleCallbacks.loaded) {
+          callback(params);
+        }
+      }
+      async nodeCleanup(params) {
+        for (const callback of this.lifecycleCallbacks.cleanup) {
+          callback(params);
+        }
+        if (typeof this._cleanup === "function") {
+          await this._cleanup(params);
+        }
+      }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Options
+      // ─────────────────────────────────────────────────────────────────────────────
       getOptions() {
         return this.options;
       }
@@ -206,57 +388,54 @@ import {
   defineSystem,
   defineQuery,
   defineComponent,
-  Types
+  Types,
+  removeQuery
 } from "bitecs";
 import { Quaternion } from "three";
 function createTransformSystem(stage) {
-  const transformQuery = defineQuery([position, rotation]);
+  const queryTerms = [position, rotation];
+  const transformQuery = defineQuery(queryTerms);
   const stageEntities = stage._childrenMap;
-  return defineSystem((world) => {
+  const system = defineSystem((world) => {
     const entities = transformQuery(world);
     if (stageEntities === void 0) {
       return world;
     }
-    ;
-    for (const [key, value] of stageEntities) {
-      const id = entities[key];
-      const stageEntity = value;
-      if (stageEntity === void 0 || !stageEntity?.body || stageEntity.markedForRemoval) {
+    for (const [key, stageEntity] of stageEntities) {
+      if (!stageEntity?.body || stageEntity.markedForRemoval) {
         continue;
       }
-      const { x, y, z } = stageEntity.body.translation();
-      position.x[id] = x;
-      position.y[id] = y;
-      position.z[id] = z;
-      if (stageEntity.group) {
-        stageEntity.group.position.set(position.x[id], position.y[id], position.z[id]);
-      } else if (stageEntity.mesh) {
-        stageEntity.mesh.position.set(position.x[id], position.y[id], position.z[id]);
+      const id = entities[key];
+      const body = stageEntity.body;
+      const target = stageEntity.group ?? stageEntity.mesh;
+      const translation = body.translation();
+      position.x[id] = translation.x;
+      position.y[id] = translation.y;
+      position.z[id] = translation.z;
+      if (target) {
+        target.position.set(translation.x, translation.y, translation.z);
       }
       if (stageEntity.controlledRotation) {
         continue;
       }
-      const { x: rx, y: ry, z: rz, w: rw } = stageEntity.body.rotation();
-      rotation.x[id] = rx;
-      rotation.y[id] = ry;
-      rotation.z[id] = rz;
-      rotation.w[id] = rw;
-      const newRotation = new Quaternion(
-        rotation.x[id],
-        rotation.y[id],
-        rotation.z[id],
-        rotation.w[id]
-      );
-      if (stageEntity.group) {
-        stageEntity.group.setRotationFromQuaternion(newRotation);
-      } else if (stageEntity.mesh) {
-        stageEntity.mesh.setRotationFromQuaternion(newRotation);
+      const rot = body.rotation();
+      rotation.x[id] = rot.x;
+      rotation.y[id] = rot.y;
+      rotation.z[id] = rot.z;
+      rotation.w[id] = rot.w;
+      if (target) {
+        _tempQuaternion.set(rot.x, rot.y, rot.z, rot.w);
+        target.setRotationFromQuaternion(_tempQuaternion);
       }
     }
     return world;
   });
+  const destroy = (world) => {
+    removeQuery(world, transformQuery);
+  };
+  return { system, destroy };
 }
-var position, rotation, scale;
+var position, rotation, scale, _tempQuaternion;
 var init_transformable_system = __esm({
   "src/lib/systems/transformable.system.ts"() {
     "use strict";
@@ -276,6 +455,7 @@ var init_transformable_system = __esm({
       y: Types.f32,
       z: Types.f32
     });
+    _tempQuaternion = new Quaternion();
   }
 });
 
@@ -299,11 +479,6 @@ var init_entity = __esm({
       custom = {};
       debugInfo = {};
       debugMaterial;
-      lifeCycleDelegate = {
-        setup: [],
-        update: [],
-        destroy: []
-      };
       collisionDelegate = {
         collision: []
       };
@@ -328,67 +503,40 @@ var init_entity = __esm({
         this.name = this.options.name || "";
         return this;
       }
-      onSetup(...callbacks) {
-        const combineCallbacks = [...this.lifeCycleDelegate.setup ?? [], ...callbacks];
-        this.lifeCycleDelegate = {
-          ...this.lifeCycleDelegate,
-          setup: combineCallbacks
-        };
-        return this;
-      }
-      onUpdate(...callbacks) {
-        const combineCallbacks = [...this.lifeCycleDelegate.update ?? [], ...callbacks];
-        this.lifeCycleDelegate = {
-          ...this.lifeCycleDelegate,
-          update: combineCallbacks
-        };
-        return this;
-      }
-      onDestroy(...callbacks) {
-        this.lifeCycleDelegate = {
-          ...this.lifeCycleDelegate,
-          destroy: callbacks.length > 0 ? callbacks : void 0
-        };
-        return this;
-      }
+      /**
+       * Add collision callbacks
+       */
       onCollision(...callbacks) {
-        this.collisionDelegate = {
-          collision: callbacks.length > 0 ? callbacks : void 0
-        };
+        const existing = this.collisionDelegate.collision ?? [];
+        this.collisionDelegate.collision = [...existing, ...callbacks];
         return this;
       }
+      /**
+       * Entity-specific setup - runs behavior callbacks
+       * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+       */
       _setup(params) {
         this.behaviorCallbackMap.setup.forEach((callback) => {
           callback({ ...params, me: this });
         });
-        if (this.lifeCycleDelegate.setup?.length) {
-          const callbacks = this.lifeCycleDelegate.setup;
-          callbacks.forEach((callback) => {
-            callback({ ...params, me: this });
-          });
-        }
       }
       async _loaded(_params) {
       }
+      /**
+       * Entity-specific update - updates materials and runs behavior callbacks
+       * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+       */
       _update(params) {
         this.updateMaterials(params);
-        if (this.lifeCycleDelegate.update?.length) {
-          const callbacks = this.lifeCycleDelegate.update;
-          callbacks.forEach((callback) => {
-            callback({ ...params, me: this });
-          });
-        }
         this.behaviorCallbackMap.update.forEach((callback) => {
           callback({ ...params, me: this });
         });
       }
+      /**
+       * Entity-specific destroy - runs behavior callbacks
+       * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+       */
       _destroy(params) {
-        if (this.lifeCycleDelegate.destroy?.length) {
-          const callbacks = this.lifeCycleDelegate.destroy;
-          callbacks.forEach((callback) => {
-            callback({ ...params, me: this });
-          });
-        }
         this.behaviorCallbackMap.destroy.forEach((callback) => {
           callback({ ...params, me: this });
         });
@@ -678,6 +826,23 @@ var init_animation = __esm({
         this._currentAction = action;
         this._currentKey = key;
       }
+      /**
+       * Dispose of all animation resources
+       */
+      dispose() {
+        Object.values(this._actions).forEach((action) => {
+          action.stop();
+        });
+        if (this._mixer) {
+          this._mixer.stopAllAction();
+          this._mixer.uncacheRoot(this.target);
+          this._mixer = null;
+        }
+        this._actions = {};
+        this._animations = [];
+        this._currentAction = null;
+        this._currentKey = "";
+      }
       get currentAnimationKey() {
         return this._currentKey;
       }
@@ -1093,7 +1258,7 @@ var init_actor = __esm({
       animations: [],
       models: []
     };
-    ACTOR_TYPE = Symbol("Actor");
+    ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
     ZylemActor = class extends GameEntity {
       static type = ACTOR_TYPE;
       _object = null;
@@ -1104,9 +1269,7 @@ var init_actor = __esm({
       constructor(options) {
         super();
         this.options = { ...actorDefaults, ...options };
-        this.lifeCycleDelegate = {
-          update: [this.actorUpdate.bind(this)]
-        };
+        this.prependUpdate(this.actorUpdate.bind(this));
         this.controlledRotation = true;
       }
       async load() {
@@ -1126,6 +1289,34 @@ var init_actor = __esm({
       async actorUpdate(params) {
         this._animationDelegate?.update(params.delta);
       }
+      /**
+       * Clean up actor resources including animations, models, and groups
+       */
+      actorDestroy() {
+        if (this._animationDelegate) {
+          this._animationDelegate.dispose();
+          this._animationDelegate = null;
+        }
+        if (this._object) {
+          this._object.traverse((child) => {
+            if (child.isMesh) {
+              const mesh = child;
+              mesh.geometry?.dispose();
+              if (Array.isArray(mesh.material)) {
+                mesh.material.forEach((m) => m.dispose());
+              } else if (mesh.material) {
+                mesh.material.dispose();
+              }
+            }
+          });
+          this._object = null;
+        }
+        if (this.group) {
+          this.group.clear();
+          this.group = null;
+        }
+        this._modelFileNames = [];
+      }
       async loadModels() {
         if (this._modelFileNames.length === 0) return;
         const promises = this._modelFileNames.map((file) => this._assetLoader.loadFile(file));
@@ -1185,25 +1376,17 @@ var init_actor = __esm({
   }
 });
 
-// src/lib/collision/collision-delegate.ts
+// src/lib/collision/world.ts
+import RAPIER from "@dimforge/rapier3d-compat";
 function isCollisionHandlerDelegate(obj) {
   return typeof obj?.handlePostCollision === "function" && typeof obj?.handleIntersectionEvent === "function";
 }
-var init_collision_delegate = __esm({
-  "src/lib/collision/collision-delegate.ts"() {
-    "use strict";
-  }
-});
-
-// src/lib/collision/world.ts
-import RAPIER from "@dimforge/rapier3d-compat";
 var ZylemWorld;
 var init_world = __esm({
   "src/lib/collision/world.ts"() {
     "use strict";
     init_game_state();
     init_actor();
-    init_collision_delegate();
     ZylemWorld = class {
       type = "World";
       world;
@@ -1409,7 +1592,11 @@ var init_zylem_scene = __esm({
        * Setup camera with the scene
        */
       setupCamera(scene, camera) {
-        scene.add(camera.cameraRig);
+        if (camera.cameraRig) {
+          scene.add(camera.cameraRig);
+        } else {
+          scene.add(camera.camera);
+        }
         camera.setup(scene);
       }
       /**
@@ -1470,7 +1657,7 @@ var init_zylem_scene = __esm({
 
 // src/lib/stage/stage-state.ts
 import { Color as Color5, Vector3 as Vector35 } from "three";
-import { proxy as proxy3, subscribe as subscribe2 } from "valtio/vanilla";
+import { proxy as proxy3, subscribe as subscribe3 } from "valtio/vanilla";
 function clearVariables(target) {
   variableProxyStore.delete(target);
 }
@@ -1558,59 +1745,346 @@ var init_lifecycle_base = __esm({
   }
 });
 
-// src/lib/camera/perspective.ts
-var Perspectives;
-var init_perspective = __esm({
-  "src/lib/camera/perspective.ts"() {
-    "use strict";
-    Perspectives = {
-      FirstPerson: "first-person",
-      ThirdPerson: "third-person",
-      Isometric: "isometric",
-      Flat2D: "flat-2d",
-      Fixed2D: "fixed-2d"
-    };
-  }
-});
-
-// src/lib/camera/third-person.ts
-import { Vector3 as Vector37 } from "three";
-var ThirdPersonCamera;
-var init_third_person = __esm({
-  "src/lib/camera/third-person.ts"() {
+// src/lib/stage/debug-entity-cursor.ts
+import {
+  Box3,
+  BoxGeometry,
+  Color as Color7,
+  EdgesGeometry,
+  Group as Group4,
+  LineBasicMaterial,
+  LineSegments,
+  Mesh as Mesh3,
+  MeshBasicMaterial,
+  Vector3 as Vector37
+} from "three";
+var DebugEntityCursor;
+var init_debug_entity_cursor = __esm({
+  "src/lib/stage/debug-entity-cursor.ts"() {
     "use strict";
-    ThirdPersonCamera = class {
-      distance;
-      screenResolution = null;
-      renderer = null;
-      scene = null;
-      cameraRef = null;
-      constructor() {
-        this.distance = new Vector37(0, 5, 8);
-      }
-      /**
-       * Setup the third person camera controller
-       */
-      setup(params) {
-        const { screenResolution, renderer, scene, camera } = params;
-        this.screenResolution = screenResolution;
-        this.renderer = renderer;
+    DebugEntityCursor = class {
+      scene;
+      container;
+      fillMesh;
+      edgeLines;
+      currentColor = new Color7(65280);
+      bbox = new Box3();
+      size = new Vector37();
+      center = new Vector37();
+      constructor(scene) {
         this.scene = scene;
-        this.cameraRef = camera;
+        const initialGeometry = new BoxGeometry(1, 1, 1);
+        this.fillMesh = new Mesh3(
+          initialGeometry,
+          new MeshBasicMaterial({
+            color: this.currentColor,
+            transparent: true,
+            opacity: 0.12,
+            depthWrite: false
+          })
+        );
+        const edges = new EdgesGeometry(initialGeometry);
+        this.edgeLines = new LineSegments(
+          edges,
+          new LineBasicMaterial({ color: this.currentColor, linewidth: 1 })
+        );
+        this.container = new Group4();
+        this.container.name = "DebugEntityCursor";
+        this.container.add(this.fillMesh);
+        this.container.add(this.edgeLines);
+        this.container.visible = false;
+        this.scene.add(this.container);
+      }
+      setColor(color) {
+        this.currentColor.set(color);
+        this.fillMesh.material.color.set(this.currentColor);
+        this.edgeLines.material.color.set(this.currentColor);
       }
       /**
-       * Update the third person camera
+       * Update the cursor to enclose the provided Object3D using a world-space AABB.
        */
-      update(delta) {
-        if (!this.cameraRef.target) {
+      updateFromObject(object) {
+        if (!object) {
+          this.hide();
           return;
         }
-        const desiredCameraPosition = this.cameraRef.target.group.position.clone().add(this.distance);
-        this.cameraRef.camera.position.lerp(desiredCameraPosition, 0.1);
-        this.cameraRef.camera.lookAt(this.cameraRef.target.group.position);
-      }
-      /**
-       * Handle resize events
+        this.bbox.setFromObject(object);
+        if (!isFinite(this.bbox.min.x) || !isFinite(this.bbox.max.x)) {
+          this.hide();
+          return;
+        }
+        this.bbox.getSize(this.size);
+        this.bbox.getCenter(this.center);
+        const newGeom = new BoxGeometry(
+          Math.max(this.size.x, 1e-6),
+          Math.max(this.size.y, 1e-6),
+          Math.max(this.size.z, 1e-6)
+        );
+        this.fillMesh.geometry.dispose();
+        this.fillMesh.geometry = newGeom;
+        const newEdges = new EdgesGeometry(newGeom);
+        this.edgeLines.geometry.dispose();
+        this.edgeLines.geometry = newEdges;
+        this.container.position.copy(this.center);
+        this.container.visible = true;
+      }
+      hide() {
+        this.container.visible = false;
+      }
+      dispose() {
+        this.scene.remove(this.container);
+        this.fillMesh.geometry.dispose();
+        this.fillMesh.material.dispose();
+        this.edgeLines.geometry.dispose();
+        this.edgeLines.material.dispose();
+      }
+    };
+  }
+});
+
+// src/lib/stage/stage-debug-delegate.ts
+import { Ray } from "@dimforge/rapier3d-compat";
+import { BufferAttribute, BufferGeometry as BufferGeometry3, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 as Vector22 } from "three";
+var SELECT_TOOL_COLOR, DELETE_TOOL_COLOR, StageDebugDelegate;
+var init_stage_debug_delegate = __esm({
+  "src/lib/stage/stage-debug-delegate.ts"() {
+    "use strict";
+    init_debug_state();
+    init_debug_entity_cursor();
+    SELECT_TOOL_COLOR = 2293538;
+    DELETE_TOOL_COLOR = 16724787;
+    StageDebugDelegate = class {
+      stage;
+      options;
+      mouseNdc = new Vector22(-2, -2);
+      raycaster = new Raycaster();
+      isMouseDown = false;
+      disposeFns = [];
+      debugCursor = null;
+      debugLines = null;
+      constructor(stage, options) {
+        this.stage = stage;
+        this.options = {
+          maxRayDistance: options?.maxRayDistance ?? 5e3,
+          addEntityFactory: options?.addEntityFactory ?? null
+        };
+        if (this.stage.scene) {
+          this.debugLines = new LineSegments2(
+            new BufferGeometry3(),
+            new LineBasicMaterial2({ vertexColors: true })
+          );
+          this.stage.scene.scene.add(this.debugLines);
+          this.debugLines.visible = true;
+          this.debugCursor = new DebugEntityCursor(this.stage.scene.scene);
+        }
+        this.attachDomListeners();
+      }
+      update() {
+        if (!debugState.enabled) return;
+        if (!this.stage.scene || !this.stage.world || !this.stage.cameraRef) return;
+        const { world, cameraRef } = this.stage;
+        if (this.debugLines) {
+          const { vertices, colors } = world.world.debugRender();
+          this.debugLines.geometry.setAttribute("position", new BufferAttribute(vertices, 3));
+          this.debugLines.geometry.setAttribute("color", new BufferAttribute(colors, 4));
+        }
+        const tool = getDebugTool();
+        const isCursorTool = tool === "select" || tool === "delete";
+        this.raycaster.setFromCamera(this.mouseNdc, cameraRef.camera);
+        const origin = this.raycaster.ray.origin.clone();
+        const direction = this.raycaster.ray.direction.clone().normalize();
+        const rapierRay = new Ray(
+          { x: origin.x, y: origin.y, z: origin.z },
+          { x: direction.x, y: direction.y, z: direction.z }
+        );
+        const hit = world.world.castRay(rapierRay, this.options.maxRayDistance, true);
+        if (hit && isCursorTool) {
+          const rigidBody = hit.collider?._parent;
+          const hoveredUuid2 = rigidBody?.userData?.uuid;
+          if (hoveredUuid2) {
+            const entity = this.stage._debugMap.get(hoveredUuid2);
+            if (entity) setHoveredEntity(entity);
+          } else {
+            resetHoveredEntity();
+          }
+          if (this.isMouseDown) {
+            this.handleActionOnHit(hoveredUuid2 ?? null, origin, direction, hit.toi);
+          }
+        }
+        this.isMouseDown = false;
+        const hoveredUuid = getHoveredEntity();
+        if (!hoveredUuid) {
+          this.debugCursor?.hide();
+          return;
+        }
+        const hoveredEntity = this.stage._debugMap.get(`${hoveredUuid}`);
+        const targetObject = hoveredEntity?.group ?? hoveredEntity?.mesh ?? null;
+        if (!targetObject) {
+          this.debugCursor?.hide();
+          return;
+        }
+        switch (tool) {
+          case "select":
+            this.debugCursor?.setColor(SELECT_TOOL_COLOR);
+            break;
+          case "delete":
+            this.debugCursor?.setColor(DELETE_TOOL_COLOR);
+            break;
+          default:
+            this.debugCursor?.setColor(16777215);
+            break;
+        }
+        this.debugCursor?.updateFromObject(targetObject);
+      }
+      dispose() {
+        this.disposeFns.forEach((fn) => fn());
+        this.disposeFns = [];
+        this.debugCursor?.dispose();
+        if (this.debugLines && this.stage.scene) {
+          this.stage.scene.scene.remove(this.debugLines);
+          this.debugLines.geometry.dispose();
+          this.debugLines.material.dispose();
+          this.debugLines = null;
+        }
+      }
+      handleActionOnHit(hoveredUuid, origin, direction, toi) {
+        const tool = getDebugTool();
+        switch (tool) {
+          case "select": {
+            if (hoveredUuid) {
+              const entity = this.stage._debugMap.get(hoveredUuid);
+              if (entity) setSelectedEntity(entity);
+            }
+            break;
+          }
+          case "delete": {
+            if (hoveredUuid) {
+              this.stage.removeEntityByUuid(hoveredUuid);
+            }
+            break;
+          }
+          case "scale": {
+            if (!this.options.addEntityFactory) break;
+            const hitPosition = origin.clone().add(direction.clone().multiplyScalar(toi));
+            const newNode = this.options.addEntityFactory({ position: hitPosition });
+            if (newNode) {
+              Promise.resolve(newNode).then((node) => {
+                if (node) this.stage.spawnEntity(node);
+              }).catch(() => {
+              });
+            }
+            break;
+          }
+          default:
+            break;
+        }
+      }
+      attachDomListeners() {
+        const canvas = this.stage.cameraRef?.renderer.domElement ?? this.stage.scene?.zylemCamera.renderer.domElement;
+        if (!canvas) return;
+        const onMouseMove = (e) => {
+          const rect = canvas.getBoundingClientRect();
+          const x = (e.clientX - rect.left) / rect.width * 2 - 1;
+          const y = -((e.clientY - rect.top) / rect.height * 2 - 1);
+          this.mouseNdc.set(x, y);
+        };
+        const onMouseDown = (e) => {
+          this.isMouseDown = true;
+        };
+        canvas.addEventListener("mousemove", onMouseMove);
+        canvas.addEventListener("mousedown", onMouseDown);
+        this.disposeFns.push(() => canvas.removeEventListener("mousemove", onMouseMove));
+        this.disposeFns.push(() => canvas.removeEventListener("mousedown", onMouseDown));
+      }
+    };
+  }
+});
+
+// src/lib/stage/stage-camera-debug-delegate.ts
+import { subscribe as subscribe4 } from "valtio/vanilla";
+var StageCameraDebugDelegate;
+var init_stage_camera_debug_delegate = __esm({
+  "src/lib/stage/stage-camera-debug-delegate.ts"() {
+    "use strict";
+    init_debug_state();
+    StageCameraDebugDelegate = class {
+      stage;
+      constructor(stage) {
+        this.stage = stage;
+      }
+      subscribe(listener) {
+        const notify = () => listener(this.snapshot());
+        notify();
+        return subscribe4(debugState, notify);
+      }
+      resolveTarget(uuid) {
+        const entity = this.stage._debugMap.get(uuid) || this.stage.world?.collisionMap.get(uuid) || null;
+        const target = entity?.group ?? entity?.mesh ?? null;
+        return target ?? null;
+      }
+      snapshot() {
+        return {
+          enabled: debugState.enabled,
+          selected: debugState.selectedEntity ? [debugState.selectedEntity.uuid] : []
+        };
+      }
+    };
+  }
+});
+
+// src/lib/camera/perspective.ts
+var Perspectives;
+var init_perspective = __esm({
+  "src/lib/camera/perspective.ts"() {
+    "use strict";
+    Perspectives = {
+      FirstPerson: "first-person",
+      ThirdPerson: "third-person",
+      Isometric: "isometric",
+      Flat2D: "flat-2d",
+      Fixed2D: "fixed-2d"
+    };
+  }
+});
+
+// src/lib/camera/third-person.ts
+import { Vector3 as Vector39 } from "three";
+var ThirdPersonCamera;
+var init_third_person = __esm({
+  "src/lib/camera/third-person.ts"() {
+    "use strict";
+    ThirdPersonCamera = class {
+      distance;
+      screenResolution = null;
+      renderer = null;
+      scene = null;
+      cameraRef = null;
+      constructor() {
+        this.distance = new Vector39(0, 5, 8);
+      }
+      /**
+       * Setup the third person camera controller
+       */
+      setup(params) {
+        const { screenResolution, renderer, scene, camera } = params;
+        this.screenResolution = screenResolution;
+        this.renderer = renderer;
+        this.scene = scene;
+        this.cameraRef = camera;
+      }
+      /**
+       * Update the third person camera
+       */
+      update(delta) {
+        if (!this.cameraRef.target) {
+          return;
+        }
+        const desiredCameraPosition = this.cameraRef.target.group.position.clone().add(this.distance);
+        this.cameraRef.camera.position.lerp(desiredCameraPosition, 0.1);
+        this.cameraRef.camera.lookAt(this.cameraRef.target.group.position);
+      }
+      /**
+       * Handle resize events
        */
       resize(width, height) {
         if (this.screenResolution) {
@@ -1765,9 +2239,184 @@ var init_render_pass = __esm({
   }
 });
 
-// src/lib/camera/zylem-camera.ts
-import { PerspectiveCamera, Vector3 as Vector38, Object3D as Object3D4, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
+// src/lib/camera/camera-debug-delegate.ts
+import { Vector3 as Vector310 } from "three";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+var CameraOrbitController;
+var init_camera_debug_delegate = __esm({
+  "src/lib/camera/camera-debug-delegate.ts"() {
+    "use strict";
+    CameraOrbitController = class {
+      camera;
+      domElement;
+      orbitControls = null;
+      orbitTarget = null;
+      orbitTargetWorldPos = new Vector310();
+      debugDelegate = null;
+      debugUnsubscribe = null;
+      debugStateSnapshot = { enabled: false, selected: [] };
+      // Saved camera state for restoration when exiting debug mode
+      savedCameraPosition = null;
+      savedCameraQuaternion = null;
+      savedCameraZoom = null;
+      constructor(camera, domElement) {
+        this.camera = camera;
+        this.domElement = domElement;
+      }
+      /**
+       * Check if debug mode is currently active (orbit controls enabled).
+       */
+      get isActive() {
+        return this.debugStateSnapshot.enabled;
+      }
+      /**
+       * Update orbit controls each frame.
+       * Should be called from the camera's update loop.
+       */
+      update() {
+        if (this.orbitControls && this.orbitTarget) {
+          this.orbitTarget.getWorldPosition(this.orbitTargetWorldPos);
+          this.orbitControls.target.copy(this.orbitTargetWorldPos);
+        }
+        this.orbitControls?.update();
+      }
+      /**
+       * Attach a delegate to react to debug state changes.
+       */
+      setDebugDelegate(delegate) {
+        if (this.debugDelegate === delegate) {
+          return;
+        }
+        this.detachDebugDelegate();
+        this.debugDelegate = delegate;
+        if (!delegate) {
+          this.applyDebugState({ enabled: false, selected: [] });
+          return;
+        }
+        const unsubscribe = delegate.subscribe((state2) => {
+          this.applyDebugState(state2);
+        });
+        this.debugUnsubscribe = () => {
+          unsubscribe?.();
+        };
+      }
+      /**
+       * Clean up resources.
+       */
+      dispose() {
+        this.disableOrbitControls();
+        this.detachDebugDelegate();
+      }
+      /**
+       * Get the current debug state snapshot.
+       */
+      get debugState() {
+        return this.debugStateSnapshot;
+      }
+      applyDebugState(state2) {
+        const wasEnabled = this.debugStateSnapshot.enabled;
+        this.debugStateSnapshot = {
+          enabled: state2.enabled,
+          selected: [...state2.selected]
+        };
+        if (state2.enabled && !wasEnabled) {
+          this.saveCameraState();
+          this.enableOrbitControls();
+          this.updateOrbitTargetFromSelection(state2.selected);
+        } else if (!state2.enabled && wasEnabled) {
+          this.orbitTarget = null;
+          this.disableOrbitControls();
+          this.restoreCameraState();
+        } else if (state2.enabled) {
+          this.updateOrbitTargetFromSelection(state2.selected);
+        }
+      }
+      enableOrbitControls() {
+        if (this.orbitControls) {
+          return;
+        }
+        this.orbitControls = new OrbitControls(this.camera, this.domElement);
+        this.orbitControls.enableDamping = true;
+        this.orbitControls.dampingFactor = 0.05;
+        this.orbitControls.screenSpacePanning = false;
+        this.orbitControls.minDistance = 1;
+        this.orbitControls.maxDistance = 500;
+        this.orbitControls.maxPolarAngle = Math.PI / 2;
+        this.orbitControls.target.set(0, 0, 0);
+      }
+      disableOrbitControls() {
+        if (!this.orbitControls) {
+          return;
+        }
+        this.orbitControls.dispose();
+        this.orbitControls = null;
+      }
+      updateOrbitTargetFromSelection(selected) {
+        if (!this.debugDelegate || selected.length === 0) {
+          this.orbitTarget = null;
+          if (this.orbitControls) {
+            this.orbitControls.target.set(0, 0, 0);
+          }
+          return;
+        }
+        for (let i = selected.length - 1; i >= 0; i -= 1) {
+          const uuid = selected[i];
+          const targetObject = this.debugDelegate.resolveTarget(uuid);
+          if (targetObject) {
+            this.orbitTarget = targetObject;
+            if (this.orbitControls) {
+              targetObject.getWorldPosition(this.orbitTargetWorldPos);
+              this.orbitControls.target.copy(this.orbitTargetWorldPos);
+            }
+            return;
+          }
+        }
+        this.orbitTarget = null;
+      }
+      detachDebugDelegate() {
+        if (this.debugUnsubscribe) {
+          try {
+            this.debugUnsubscribe();
+          } catch {
+          }
+        }
+        this.debugUnsubscribe = null;
+        this.debugDelegate = null;
+      }
+      /**
+       * Save camera position, rotation, and zoom before entering debug mode.
+       */
+      saveCameraState() {
+        this.savedCameraPosition = this.camera.position.clone();
+        this.savedCameraQuaternion = this.camera.quaternion.clone();
+        if ("zoom" in this.camera) {
+          this.savedCameraZoom = this.camera.zoom;
+        }
+      }
+      /**
+       * Restore camera position, rotation, and zoom when exiting debug mode.
+       */
+      restoreCameraState() {
+        if (this.savedCameraPosition) {
+          this.camera.position.copy(this.savedCameraPosition);
+          this.savedCameraPosition = null;
+        }
+        if (this.savedCameraQuaternion) {
+          this.camera.quaternion.copy(this.savedCameraQuaternion);
+          this.savedCameraQuaternion = null;
+        }
+        if (this.savedCameraZoom !== null && "zoom" in this.camera) {
+          this.camera.zoom = this.savedCameraZoom;
+          this.camera.updateProjectionMatrix?.();
+          this.savedCameraZoom = null;
+        }
+      }
+    };
+  }
+});
+
+// src/lib/camera/zylem-camera.ts
+import { PerspectiveCamera, Vector3 as Vector311, Object3D as Object3D6, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
 import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
 var ZylemCamera;
 var init_zylem_camera = __esm({
@@ -1777,24 +2426,21 @@ var init_zylem_camera = __esm({
     init_third_person();
     init_fixed_2d();
     init_render_pass();
+    init_camera_debug_delegate();
     ZylemCamera = class {
-      cameraRig;
+      cameraRig = null;
       camera;
       screenResolution;
       renderer;
       composer;
       _perspective;
-      orbitControls = null;
       target = null;
       sceneRef = null;
       frustumSize = 10;
       // Perspective controller delegation
       perspectiveController = null;
-      debugDelegate = null;
-      debugUnsubscribe = null;
-      debugStateSnapshot = { enabled: false, selected: [] };
-      orbitTarget = null;
-      orbitTargetWorldPos = new Vector38();
+      // Debug/orbit controls delegation
+      orbitController = null;
       constructor(perspective, screenResolution, frustumSize = 10) {
         this._perspective = perspective;
         this.screenResolution = screenResolution;
@@ -1805,26 +2451,23 @@ var init_zylem_camera = __esm({
         this.composer = new EffectComposer(this.renderer);
         const aspectRatio = screenResolution.x / screenResolution.y;
         this.camera = this.createCameraForPerspective(aspectRatio);
-        this.cameraRig = new Object3D4();
-        this.cameraRig.position.set(0, 3, 10);
-        this.cameraRig.add(this.camera);
-        this.camera.lookAt(new Vector38(0, 2, 0));
+        if (this.needsRig()) {
+          this.cameraRig = new Object3D6();
+          this.cameraRig.position.set(0, 3, 10);
+          this.cameraRig.add(this.camera);
+          this.camera.lookAt(new Vector311(0, 2, 0));
+        } else {
+          this.camera.position.set(0, 0, 10);
+          this.camera.lookAt(new Vector311(0, 0, 0));
+        }
         this.initializePerspectiveController();
+        this.orbitController = new CameraOrbitController(this.camera, this.renderer.domElement);
       }
       /**
        * Setup the camera with a scene
        */
       async setup(scene) {
         this.sceneRef = scene;
-        if (this.orbitControls === null) {
-          this.orbitControls = new OrbitControls(this.camera, this.renderer.domElement);
-          this.orbitControls.enableDamping = true;
-          this.orbitControls.dampingFactor = 0.05;
-          this.orbitControls.screenSpacePanning = false;
-          this.orbitControls.minDistance = 1;
-          this.orbitControls.maxDistance = 500;
-          this.orbitControls.maxPolarAngle = Math.PI / 2;
-        }
         let renderResolution = this.screenResolution.clone().divideScalar(2);
         renderResolution.x |= 0;
         renderResolution.y |= 0;
@@ -1846,16 +2489,18 @@ var init_zylem_camera = __esm({
        * Update camera and render
        */
       update(delta) {
-        if (this.orbitControls && this.orbitTarget) {
-          this.orbitTarget.getWorldPosition(this.orbitTargetWorldPos);
-          this.orbitControls.target.copy(this.orbitTargetWorldPos);
-        }
-        this.orbitControls?.update();
-        if (this.perspectiveController) {
+        this.orbitController?.update();
+        if (this.perspectiveController && !this.isDebugModeActive()) {
           this.perspectiveController.update(delta);
         }
         this.composer.render(delta);
       }
+      /**
+       * Check if debug mode is active (orbit controls taking over camera)
+       */
+      isDebugModeActive() {
+        return this.orbitController?.isActive ?? false;
+      }
       /**
        * Dispose renderer, composer, controls, and detach from scene
        */
@@ -1865,7 +2510,7 @@ var init_zylem_camera = __esm({
         } catch {
         }
         try {
-          this.disableOrbitControls();
+          this.orbitController?.dispose();
         } catch {
         }
         try {
@@ -1877,28 +2522,13 @@ var init_zylem_camera = __esm({
           this.renderer.dispose();
         } catch {
         }
-        this.detachDebugDelegate();
         this.sceneRef = null;
       }
       /**
        * Attach a delegate to react to debug state changes.
        */
       setDebugDelegate(delegate) {
-        if (this.debugDelegate === delegate) {
-          return;
-        }
-        this.detachDebugDelegate();
-        this.debugDelegate = delegate;
-        if (!delegate) {
-          this.applyDebugState({ enabled: false, selected: [] });
-          return;
-        }
-        const unsubscribe = delegate.subscribe((state2) => {
-          this.applyDebugState(state2);
-        });
-        this.debugUnsubscribe = () => {
-          unsubscribe?.();
-        };
+        this.orbitController?.setDebugDelegate(delegate);
       }
       /**
        * Resize camera and renderer
@@ -1990,15 +2620,31 @@ var init_zylem_camera = __esm({
         if (this._perspective === Perspectives.Flat2D || this._perspective === Perspectives.Fixed2D) {
           this.frustumSize = position2.z;
         }
-        this.cameraRig.position.set(position2.x, position2.y, position2.z);
+        if (this.cameraRig) {
+          this.cameraRig.position.set(position2.x, position2.y, position2.z);
+        } else {
+          this.camera.position.set(position2.x, position2.y, position2.z);
+        }
       }
       move(position2) {
         this.moveCamera(position2);
       }
       rotate(pitch, yaw, roll) {
-        this.cameraRig.rotateX(pitch);
-        this.cameraRig.rotateY(yaw);
-        this.cameraRig.rotateZ(roll);
+        if (this.cameraRig) {
+          this.cameraRig.rotateX(pitch);
+          this.cameraRig.rotateY(yaw);
+          this.cameraRig.rotateZ(roll);
+        } else {
+          this.camera.rotateX(pitch);
+          this.camera.rotateY(yaw);
+          this.camera.rotateZ(roll);
+        }
+      }
+      /**
+       * Check if this perspective type needs a camera rig
+       */
+      needsRig() {
+        return this._perspective === Perspectives.ThirdPerson;
       }
       /**
        * Get the DOM element for the renderer
@@ -2006,336 +2652,221 @@ var init_zylem_camera = __esm({
       getDomElement() {
         return this.renderer.domElement;
       }
-      applyDebugState(state2) {
-        this.debugStateSnapshot = {
-          enabled: state2.enabled,
-          selected: [...state2.selected]
-        };
-        if (state2.enabled) {
-          this.enableOrbitControls();
-          this.updateOrbitTargetFromSelection(state2.selected);
-        } else {
-          this.orbitTarget = null;
-          this.disableOrbitControls();
-        }
-      }
-      enableOrbitControls() {
-        if (this.orbitControls) {
-          return;
-        }
-        this.orbitControls = new OrbitControls(this.camera, this.renderer.domElement);
-        this.orbitControls.enableDamping = true;
-        this.orbitControls.dampingFactor = 0.05;
-        this.orbitControls.screenSpacePanning = false;
-        this.orbitControls.minDistance = 1;
-        this.orbitControls.maxDistance = 500;
-        this.orbitControls.maxPolarAngle = Math.PI / 2;
+    };
+  }
+});
+
+// src/lib/stage/stage-camera-delegate.ts
+import { Vector2 as Vector25 } from "three";
+var StageCameraDelegate;
+var init_stage_camera_delegate = __esm({
+  "src/lib/stage/stage-camera-delegate.ts"() {
+    "use strict";
+    init_zylem_camera();
+    init_perspective();
+    StageCameraDelegate = class {
+      stage;
+      constructor(stage) {
+        this.stage = stage;
       }
-      disableOrbitControls() {
-        if (!this.orbitControls) {
-          return;
-        }
-        this.orbitControls.dispose();
-        this.orbitControls = null;
+      /**
+       * Create a default third-person camera based on window size.
+       */
+      createDefaultCamera() {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        const screenResolution = new Vector25(width, height);
+        return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
       }
-      updateOrbitTargetFromSelection(selected) {
-        if (!this.debugDelegate || selected.length === 0) {
-          this.orbitTarget = null;
-          return;
-        }
-        for (let i = selected.length - 1; i >= 0; i -= 1) {
-          const uuid = selected[i];
-          const targetObject = this.debugDelegate.resolveTarget(uuid);
-          if (targetObject) {
-            this.orbitTarget = targetObject;
-            if (this.orbitControls) {
-              targetObject.getWorldPosition(this.orbitTargetWorldPos);
-              this.orbitControls.target.copy(this.orbitTargetWorldPos);
-            }
-            return;
-          }
+      /**
+       * Resolve the camera to use for the stage.
+       * Uses the provided camera, stage camera wrapper, or creates a default.
+       * 
+       * @param cameraOverride Optional camera override
+       * @param cameraWrapper Optional camera wrapper from stage options
+       * @returns The resolved ZylemCamera instance
+       */
+      resolveCamera(cameraOverride, cameraWrapper) {
+        if (cameraOverride) {
+          return cameraOverride;
         }
-        this.orbitTarget = null;
-      }
-      detachDebugDelegate() {
-        if (this.debugUnsubscribe) {
-          try {
-            this.debugUnsubscribe();
-          } catch {
-          }
+        if (cameraWrapper) {
+          return cameraWrapper.cameraRef;
         }
-        this.debugUnsubscribe = null;
-        this.debugDelegate = null;
+        return this.createDefaultCamera();
       }
     };
   }
 });
 
-// src/lib/camera/camera.ts
-import { Vector2 as Vector24, Vector3 as Vector39 } from "three";
-var CameraWrapper;
-var init_camera = __esm({
-  "src/lib/camera/camera.ts"() {
+// src/lib/stage/stage-loading-delegate.ts
+var StageLoadingDelegate;
+var init_stage_loading_delegate = __esm({
+  "src/lib/stage/stage-loading-delegate.ts"() {
     "use strict";
-    CameraWrapper = class {
-      cameraRef;
-      constructor(camera) {
-        this.cameraRef = camera;
+    init_game_event_bus();
+    StageLoadingDelegate = class {
+      loadingHandlers = [];
+      stageName;
+      stageIndex;
+      /**
+       * Set stage context for event bus emissions.
+       */
+      setStageContext(stageName, stageIndex) {
+        this.stageName = stageName;
+        this.stageIndex = stageIndex;
       }
-    };
-  }
-});
-
-// src/lib/stage/debug-entity-cursor.ts
-import {
-  Box3,
-  BoxGeometry,
-  Color as Color7,
-  EdgesGeometry,
-  Group as Group4,
-  LineBasicMaterial,
-  LineSegments,
-  Mesh as Mesh3,
-  MeshBasicMaterial,
-  Vector3 as Vector310
-} from "three";
-var DebugEntityCursor;
-var init_debug_entity_cursor = __esm({
-  "src/lib/stage/debug-entity-cursor.ts"() {
-    "use strict";
-    DebugEntityCursor = class {
-      scene;
-      container;
-      fillMesh;
-      edgeLines;
-      currentColor = new Color7(65280);
-      bbox = new Box3();
-      size = new Vector310();
-      center = new Vector310();
-      constructor(scene) {
-        this.scene = scene;
-        const initialGeometry = new BoxGeometry(1, 1, 1);
-        this.fillMesh = new Mesh3(
-          initialGeometry,
-          new MeshBasicMaterial({
-            color: this.currentColor,
-            transparent: true,
-            opacity: 0.12,
-            depthWrite: false
-          })
-        );
-        const edges = new EdgesGeometry(initialGeometry);
-        this.edgeLines = new LineSegments(
-          edges,
-          new LineBasicMaterial({ color: this.currentColor, linewidth: 1 })
-        );
-        this.container = new Group4();
-        this.container.name = "DebugEntityCursor";
-        this.container.add(this.fillMesh);
-        this.container.add(this.edgeLines);
-        this.container.visible = false;
-        this.scene.add(this.container);
-      }
-      setColor(color) {
-        this.currentColor.set(color);
-        this.fillMesh.material.color.set(this.currentColor);
-        this.edgeLines.material.color.set(this.currentColor);
+      /**
+       * Subscribe to loading events.
+       * 
+       * @param callback Invoked for each loading event (start, progress, complete)
+       * @returns Unsubscribe function
+       */
+      onLoading(callback) {
+        this.loadingHandlers.push(callback);
+        return () => {
+          this.loadingHandlers = this.loadingHandlers.filter((h) => h !== callback);
+        };
       }
       /**
-       * Update the cursor to enclose the provided Object3D using a world-space AABB.
+       * Emit a loading event to all subscribers and to the game event bus.
+       * 
+       * @param event The loading event to broadcast
        */
-      updateFromObject(object) {
-        if (!object) {
-          this.hide();
-          return;
+      emit(event) {
+        for (const handler of this.loadingHandlers) {
+          try {
+            handler(event);
+          } catch (e) {
+            console.error("Loading handler failed", e);
+          }
         }
-        this.bbox.setFromObject(object);
-        if (!isFinite(this.bbox.min.x) || !isFinite(this.bbox.max.x)) {
-          this.hide();
-          return;
+        const payload = {
+          ...event,
+          stageName: this.stageName,
+          stageIndex: this.stageIndex
+        };
+        if (event.type === "start") {
+          gameEventBus.emit("stage:loading:start", payload);
+        } else if (event.type === "progress") {
+          gameEventBus.emit("stage:loading:progress", payload);
+        } else if (event.type === "complete") {
+          gameEventBus.emit("stage:loading:complete", payload);
         }
-        this.bbox.getSize(this.size);
-        this.bbox.getCenter(this.center);
-        const newGeom = new BoxGeometry(
-          Math.max(this.size.x, 1e-6),
-          Math.max(this.size.y, 1e-6),
-          Math.max(this.size.z, 1e-6)
-        );
-        this.fillMesh.geometry.dispose();
-        this.fillMesh.geometry = newGeom;
-        const newEdges = new EdgesGeometry(newGeom);
-        this.edgeLines.geometry.dispose();
-        this.edgeLines.geometry = newEdges;
-        this.container.position.copy(this.center);
-        this.container.visible = true;
       }
-      hide() {
-        this.container.visible = false;
+      /**
+       * Emit a start loading event.
+       */
+      emitStart(message = "Loading stage...") {
+        this.emit({ type: "start", message, progress: 0 });
       }
+      /**
+       * Emit a progress loading event.
+       */
+      emitProgress(message, current, total) {
+        const progress = total > 0 ? current / total : 0;
+        this.emit({ type: "progress", message, progress, current, total });
+      }
+      /**
+       * Emit a complete loading event.
+       */
+      emitComplete(message = "Stage loaded") {
+        this.emit({ type: "complete", message, progress: 1 });
+      }
+      /**
+       * Clear all loading handlers.
+       */
       dispose() {
-        this.scene.remove(this.container);
-        this.fillMesh.geometry.dispose();
-        this.fillMesh.material.dispose();
-        this.edgeLines.geometry.dispose();
-        this.edgeLines.material.dispose();
+        this.loadingHandlers = [];
       }
     };
   }
 });
 
-// src/lib/stage/stage-debug-delegate.ts
-import { Ray } from "@dimforge/rapier3d-compat";
-import { BufferAttribute, BufferGeometry as BufferGeometry3, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 as Vector25 } from "three";
-var SELECT_TOOL_COLOR, DELETE_TOOL_COLOR, StageDebugDelegate;
-var init_stage_debug_delegate = __esm({
-  "src/lib/stage/stage-debug-delegate.ts"() {
+// src/lib/core/utility/options-parser.ts
+function isBaseNode(item) {
+  return !!item && typeof item === "object" && typeof item.create === "function";
+}
+function isThenable(item) {
+  return !!item && typeof item.then === "function";
+}
+function isCameraWrapper(item) {
+  return !!item && typeof item === "object" && item.constructor?.name === "CameraWrapper";
+}
+function isConfigObject(item) {
+  if (!item || typeof item !== "object") return false;
+  if (isBaseNode(item)) return false;
+  if (isCameraWrapper(item)) return false;
+  if (isThenable(item)) return false;
+  if (typeof item.then === "function") return false;
+  return item.constructor === Object || item.constructor?.name === "Object";
+}
+function isEntityInput(item) {
+  if (!item) return false;
+  if (isBaseNode(item)) return true;
+  if (typeof item === "function") return true;
+  if (isThenable(item)) return true;
+  return false;
+}
+var init_options_parser = __esm({
+  "src/lib/core/utility/options-parser.ts"() {
     "use strict";
-    init_debug_state();
-    init_debug_entity_cursor();
-    SELECT_TOOL_COLOR = 2293538;
-    DELETE_TOOL_COLOR = 16724787;
-    StageDebugDelegate = class {
-      stage;
-      options;
-      mouseNdc = new Vector25(-2, -2);
-      raycaster = new Raycaster();
-      isMouseDown = false;
-      disposeFns = [];
-      debugCursor = null;
-      debugLines = null;
-      constructor(stage, options) {
-        this.stage = stage;
-        this.options = {
-          maxRayDistance: options?.maxRayDistance ?? 5e3,
-          addEntityFactory: options?.addEntityFactory ?? null
-        };
-        if (this.stage.scene) {
-          this.debugLines = new LineSegments2(
-            new BufferGeometry3(),
-            new LineBasicMaterial2({ vertexColors: true })
-          );
-          this.stage.scene.scene.add(this.debugLines);
-          this.debugLines.visible = true;
-          this.debugCursor = new DebugEntityCursor(this.stage.scene.scene);
-        }
-        this.attachDomListeners();
-      }
-      update() {
-        if (!debugState.enabled) return;
-        if (!this.stage.scene || !this.stage.world || !this.stage.cameraRef) return;
-        const { world, cameraRef } = this.stage;
-        if (this.debugLines) {
-          const { vertices, colors } = world.world.debugRender();
-          this.debugLines.geometry.setAttribute("position", new BufferAttribute(vertices, 3));
-          this.debugLines.geometry.setAttribute("color", new BufferAttribute(colors, 4));
-        }
-        const tool = getDebugTool();
-        const isCursorTool = tool === "select" || tool === "delete";
-        this.raycaster.setFromCamera(this.mouseNdc, cameraRef.camera);
-        const origin = this.raycaster.ray.origin.clone();
-        const direction = this.raycaster.ray.direction.clone().normalize();
-        const rapierRay = new Ray(
-          { x: origin.x, y: origin.y, z: origin.z },
-          { x: direction.x, y: direction.y, z: direction.z }
-        );
-        const hit = world.world.castRay(rapierRay, this.options.maxRayDistance, true);
-        if (hit && isCursorTool) {
-          const rigidBody = hit.collider?._parent;
-          const hoveredUuid2 = rigidBody?.userData?.uuid;
-          if (hoveredUuid2) {
-            const entity = this.stage._debugMap.get(hoveredUuid2);
-            if (entity) setHoveredEntity(entity);
-          } else {
-            resetHoveredEntity();
-          }
-          if (this.isMouseDown) {
-            this.handleActionOnHit(hoveredUuid2 ?? null, origin, direction, hit.toi);
-          }
-        }
-        this.isMouseDown = false;
-        const hoveredUuid = getHoveredEntity();
-        if (!hoveredUuid) {
-          this.debugCursor?.hide();
-          return;
-        }
-        const hoveredEntity = this.stage._debugMap.get(`${hoveredUuid}`);
-        const targetObject = hoveredEntity?.group ?? hoveredEntity?.mesh ?? null;
-        if (!targetObject) {
-          this.debugCursor?.hide();
-          return;
-        }
-        switch (tool) {
-          case "select":
-            this.debugCursor?.setColor(SELECT_TOOL_COLOR);
-            break;
-          case "delete":
-            this.debugCursor?.setColor(DELETE_TOOL_COLOR);
-            break;
-          default:
-            this.debugCursor?.setColor(16777215);
-            break;
-        }
-        this.debugCursor?.updateFromObject(targetObject);
-      }
-      dispose() {
-        this.disposeFns.forEach((fn) => fn());
-        this.disposeFns = [];
-        this.debugCursor?.dispose();
-        if (this.debugLines && this.stage.scene) {
-          this.stage.scene.scene.remove(this.debugLines);
-          this.debugLines.geometry.dispose();
-          this.debugLines.material.dispose();
-          this.debugLines = null;
-        }
-      }
-      handleActionOnHit(hoveredUuid, origin, direction, toi) {
-        const tool = getDebugTool();
-        switch (tool) {
-          case "select": {
-            if (hoveredUuid) {
-              const entity = this.stage._debugMap.get(hoveredUuid);
-              if (entity) setSelectedEntity(entity);
-            }
-            break;
-          }
-          case "delete": {
-            if (hoveredUuid) {
-              this.stage.removeEntityByUuid(hoveredUuid);
-            }
-            break;
-          }
-          case "scale": {
-            if (!this.options.addEntityFactory) break;
-            const hitPosition = origin.clone().add(direction.clone().multiplyScalar(toi));
-            const newNode = this.options.addEntityFactory({ position: hitPosition });
-            if (newNode) {
-              Promise.resolve(newNode).then((node) => {
-                if (node) this.stage.spawnEntity(node);
-              }).catch(() => {
-              });
-            }
-            break;
-          }
-          default:
-            break;
-        }
-      }
-      attachDomListeners() {
-        const canvas = this.stage.cameraRef?.renderer.domElement ?? this.stage.scene?.zylemCamera.renderer.domElement;
-        if (!canvas) return;
-        const onMouseMove = (e) => {
-          const rect = canvas.getBoundingClientRect();
-          const x = (e.clientX - rect.left) / rect.width * 2 - 1;
-          const y = -((e.clientY - rect.top) / rect.height * 2 - 1);
-          this.mouseNdc.set(x, y);
-        };
-        const onMouseDown = (e) => {
-          this.isMouseDown = true;
-        };
-        canvas.addEventListener("mousemove", onMouseMove);
-        canvas.addEventListener("mousedown", onMouseDown);
-        this.disposeFns.push(() => canvas.removeEventListener("mousemove", onMouseMove));
-        this.disposeFns.push(() => canvas.removeEventListener("mousedown", onMouseDown));
+  }
+});
+
+// src/lib/stage/stage-config.ts
+import { Vector3 as Vector312 } from "three";
+function createDefaultStageConfig() {
+  return new StageConfig(
+    {
+      p1: ["gamepad-1", "keyboard-1"],
+      p2: ["gamepad-2", "keyboard-2"]
+    },
+    ZylemBlueColor,
+    null,
+    new Vector312(0, 0, 0),
+    {}
+  );
+}
+function parseStageOptions(options = []) {
+  const defaults = createDefaultStageConfig();
+  let config = {};
+  const entities = [];
+  const asyncEntities = [];
+  let camera;
+  for (const item of options) {
+    if (isCameraWrapper(item)) {
+      camera = item;
+    } else if (isBaseNode(item)) {
+      entities.push(item);
+    } else if (isEntityInput(item) && !isBaseNode(item)) {
+      asyncEntities.push(item);
+    } else if (isConfigObject(item)) {
+      config = { ...config, ...item };
+    }
+  }
+  const resolvedConfig = new StageConfig(
+    config.inputs ?? defaults.inputs,
+    config.backgroundColor ?? defaults.backgroundColor,
+    config.backgroundImage ?? defaults.backgroundImage,
+    config.gravity ?? defaults.gravity,
+    config.variables ?? defaults.variables
+  );
+  return { config: resolvedConfig, entities, asyncEntities, camera };
+}
+var StageConfig;
+var init_stage_config = __esm({
+  "src/lib/stage/stage-config.ts"() {
+    "use strict";
+    init_options_parser();
+    init_vector();
+    StageConfig = class {
+      constructor(inputs, backgroundColor, backgroundImage, gravity, variables) {
+        this.inputs = inputs;
+        this.backgroundColor = backgroundColor;
+        this.backgroundImage = backgroundImage;
+        this.gravity = gravity;
+        this.variables = variables;
       }
     };
   }
@@ -2343,7 +2874,8 @@ var init_stage_debug_delegate = __esm({
 
 // src/lib/stage/zylem-stage.ts
 import { addComponent, addEntity, createWorld as createECS, removeEntity } from "bitecs";
-import { Color as Color8, Vector3 as Vector312, Vector2 as Vector26 } from "three";
+import { Color as Color9, Vector3 as Vector313 } from "three";
+import { subscribe as subscribe5 } from "valtio/vanilla";
 import { nanoid as nanoid2 } from "nanoid";
 var STAGE_TYPE, ZylemStage;
 var init_zylem_stage = __esm({
@@ -2357,12 +2889,13 @@ var init_zylem_stage = __esm({
     init_game_state();
     init_lifecycle_base();
     init_transformable_system();
-    init_base_node();
-    init_perspective();
-    init_camera();
     init_stage_debug_delegate();
+    init_stage_camera_debug_delegate();
+    init_stage_camera_delegate();
+    init_stage_loading_delegate();
     init_entity();
-    init_zylem_camera();
+    init_stage_config();
+    init_options_parser();
     STAGE_TYPE = "Stage";
     ZylemStage = class extends LifeCycleBase {
       type = STAGE_TYPE;
@@ -2373,7 +2906,7 @@ var init_zylem_stage = __esm({
           p1: ["gamepad-1", "keyboard"],
           p2: ["gamepad-2", "keyboard"]
         },
-        gravity: new Vector312(0, 0, 0),
+        gravity: new Vector313(0, 0, 0),
         variables: {},
         entities: []
       };
@@ -2388,16 +2921,19 @@ var init_zylem_stage = __esm({
       isLoaded = false;
       _debugMap = /* @__PURE__ */ new Map();
       entityAddedHandlers = [];
-      loadingHandlers = [];
       ecs = createECS();
       testSystem = null;
       transformSystem = null;
       debugDelegate = null;
       cameraDebugDelegate = null;
+      debugStateUnsubscribe = null;
       uuid;
       wrapperRef = null;
       camera;
       cameraRef = null;
+      // Delegates
+      cameraDelegate;
+      loadingDelegate;
       /**
        * Create a new stage.
        * @param options Stage options: partial config, camera, and initial entities or factories
@@ -2407,49 +2943,22 @@ var init_zylem_stage = __esm({
         this.world = null;
         this.scene = null;
         this.uuid = nanoid2();
-        const { config, entities, asyncEntities, camera } = this.parseOptions(options);
-        this.camera = camera;
-        this.children = entities;
-        this.pendingEntities = asyncEntities;
-        this.saveState({ ...this.state, ...config, entities: [] });
-        this.gravity = config.gravity ?? new Vector312(0, 0, 0);
-      }
-      parseOptions(options) {
-        let config = {};
-        const entities = [];
-        const asyncEntities = [];
-        let camera;
-        for (const item of options) {
-          if (this.isCameraWrapper(item)) {
-            camera = item;
-          } else if (this.isBaseNode(item)) {
-            entities.push(item);
-          } else if (this.isEntityInput(item)) {
-            asyncEntities.push(item);
-          } else if (this.isZylemStageConfig(item)) {
-            config = { ...config, ...item };
-          }
-        }
-        return { config, entities, asyncEntities, camera };
-      }
-      isZylemStageConfig(item) {
-        return item && typeof item === "object" && !(item instanceof BaseNode) && !(item instanceof CameraWrapper);
-      }
-      isBaseNode(item) {
-        return item && typeof item === "object" && typeof item.create === "function";
-      }
-      isCameraWrapper(item) {
-        return item && typeof item === "object" && item.constructor.name === "CameraWrapper";
-      }
-      isEntityInput(item) {
-        if (!item) return false;
-        if (this.isBaseNode(item)) return true;
-        if (typeof item === "function") return true;
-        if (typeof item === "object" && typeof item.then === "function") return true;
-        return false;
-      }
-      isThenable(value) {
-        return !!value && typeof value.then === "function";
+        this.cameraDelegate = new StageCameraDelegate(this);
+        this.loadingDelegate = new StageLoadingDelegate();
+        const parsed = parseStageOptions(options);
+        this.camera = parsed.camera;
+        this.children = parsed.entities;
+        this.pendingEntities = parsed.asyncEntities;
+        this.saveState({
+          ...this.state,
+          inputs: parsed.config.inputs,
+          backgroundColor: parsed.config.backgroundColor,
+          backgroundImage: parsed.config.backgroundImage,
+          gravity: parsed.config.gravity,
+          variables: parsed.config.variables,
+          entities: []
+        });
+        this.gravity = parsed.config.gravity ?? new Vector313(0, 0, 0);
       }
       handleEntityImmediatelyOrQueue(entity) {
         if (this.isLoaded) {
@@ -2470,42 +2979,47 @@ var init_zylem_stage = __esm({
       }
       setState() {
         const { backgroundColor, backgroundImage } = this.state;
-        const color = backgroundColor instanceof Color8 ? backgroundColor : new Color8(backgroundColor);
+        const color = backgroundColor instanceof Color9 ? backgroundColor : new Color9(backgroundColor);
         setStageBackgroundColor(color);
         setStageBackgroundImage(backgroundImage);
         setStageVariables(this.state.variables ?? {});
       }
       /**
        * 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
        */
       async load(id, camera) {
         this.setState();
-        const zylemCamera = camera || (this.camera ? this.camera.cameraRef : this.createDefaultCamera());
+        const zylemCamera = this.cameraDelegate.resolveCamera(camera, this.camera);
         this.cameraRef = zylemCamera;
         this.scene = new ZylemScene(id, zylemCamera, this.state);
-        const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector312(0, 0, 0));
+        const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector313(0, 0, 0));
         this.world = new ZylemWorld(physicsWorld);
         this.scene.setup();
-        this.emitLoading({ type: "start", message: "Loading stage...", progress: 0 });
+        this.loadingDelegate.emitStart();
+        await this.runEntityLoadGenerator();
+        this.transformSystem = createTransformSystem(this);
+        this.isLoaded = true;
+        this.loadingDelegate.emitComplete();
+      }
+      /**
+       * Generator that yields between entity loads for real-time progress updates.
+       */
+      *entityLoadGenerator() {
         const total = this.children.length + this.pendingEntities.length + this.pendingPromises.length;
         let current = 0;
-        for (let child of this.children) {
+        for (const child of this.children) {
           this.spawnEntity(child);
           current++;
-          this.emitLoading({
-            type: "progress",
-            message: `Loaded entity ${child.name || "unknown"}`,
-            progress: current / total,
-            current,
-            total
-          });
+          yield { current, total, name: child.name || "unknown" };
         }
         if (this.pendingEntities.length) {
           this.enqueue(...this.pendingEntities);
           current += this.pendingEntities.length;
           this.pendingEntities = [];
+          yield { current, total, name: "pending entities" };
         }
         if (this.pendingPromises.length) {
           for (const promise of this.pendingPromises) {
@@ -2515,24 +3029,44 @@ var init_zylem_stage = __esm({
           }
           current += this.pendingPromises.length;
           this.pendingPromises = [];
+          yield { current, total, name: "async entities" };
         }
-        this.transformSystem = createTransformSystem(this);
-        this.isLoaded = true;
-        this.emitLoading({ type: "complete", message: "Stage loaded", progress: 1 });
       }
-      createDefaultCamera() {
-        const width = window.innerWidth;
-        const height = window.innerHeight;
-        const screenResolution = new Vector26(width, height);
-        return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
+      /**
+       * 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.
+       */
+      async runEntityLoadGenerator() {
+        const gen = this.entityLoadGenerator();
+        for (const progress of gen) {
+          this.loadingDelegate.emitProgress(`Loaded ${progress.name}`, progress.current, progress.total);
+          await new Promise((resolve) => setTimeout(resolve, 0));
+        }
       }
       _setup(params) {
         if (!this.scene || !this.world) {
           this.logMissingEntities();
           return;
         }
-        if (debugState.enabled) {
+        this.updateDebugDelegate();
+        this.debugStateUnsubscribe = subscribe5(debugState, () => {
+          this.updateDebugDelegate();
+        });
+      }
+      updateDebugDelegate() {
+        if (debugState.enabled && !this.debugDelegate && this.scene && this.world) {
           this.debugDelegate = new StageDebugDelegate(this);
+          if (this.cameraRef && !this.cameraDebugDelegate) {
+            this.cameraDebugDelegate = new StageCameraDebugDelegate(this);
+            this.cameraRef.setDebugDelegate(this.cameraDebugDelegate);
+          }
+        } else if (!debugState.enabled && this.debugDelegate) {
+          this.debugDelegate.dispose();
+          this.debugDelegate = null;
+          if (this.cameraRef) {
+            this.cameraRef.setDebugDelegate(null);
+          }
+          this.cameraDebugDelegate = null;
         }
       }
       _update(params) {
@@ -2542,7 +3076,7 @@ var init_zylem_stage = __esm({
           return;
         }
         this.world.update(params);
-        this.transformSystem(this.ecs);
+        this.transformSystem?.system(this.ecs);
         this._childrenMap.forEach((child, eid) => {
           child.nodeUpdate({
             ...params,
@@ -2576,13 +3110,20 @@ var init_zylem_stage = __esm({
         this._debugMap.clear();
         this.world?.destroy();
         this.scene?.destroy();
+        if (this.debugStateUnsubscribe) {
+          this.debugStateUnsubscribe();
+          this.debugStateUnsubscribe = null;
+        }
         this.debugDelegate?.dispose();
+        this.debugDelegate = null;
         this.cameraRef?.setDebugDelegate(null);
         this.cameraDebugDelegate = null;
         this.isLoaded = false;
         this.world = null;
         this.scene = null;
         this.cameraRef = null;
+        this.transformSystem?.destroy(this.ecs);
+        this.transformSystem = null;
         resetStageVariables();
         clearVariables(this);
       }
@@ -2663,13 +3204,7 @@ var init_zylem_stage = __esm({
         };
       }
       onLoading(callback) {
-        this.loadingHandlers.push(callback);
-        return () => {
-          this.loadingHandlers = this.loadingHandlers.filter((h) => h !== callback);
-        };
-      }
-      emitLoading(event) {
-        this.loadingHandlers.forEach((h) => h(event));
+        return this.loadingDelegate.onLoading(callback);
       }
       /**
        * Remove an entity and its resources by its UUID.
@@ -2726,16 +3261,16 @@ var init_zylem_stage = __esm({
       enqueue(...items) {
         for (const item of items) {
           if (!item) continue;
-          if (this.isBaseNode(item)) {
+          if (isBaseNode(item)) {
             this.handleEntityImmediatelyOrQueue(item);
             continue;
           }
           if (typeof item === "function") {
             try {
               const result = item();
-              if (this.isBaseNode(result)) {
+              if (isBaseNode(result)) {
                 this.handleEntityImmediatelyOrQueue(result);
-              } else if (this.isThenable(result)) {
+              } else if (isThenable(result)) {
                 this.handlePromiseWithSpawnOnResolve(result);
               }
             } catch (error) {
@@ -2743,7 +3278,7 @@ var init_zylem_stage = __esm({
             }
             continue;
           }
-          if (this.isThenable(item)) {
+          if (isThenable(item)) {
             this.handlePromiseWithSpawnOnResolve(item);
           }
         }
@@ -2752,9 +3287,24 @@ var init_zylem_stage = __esm({
   }
 });
 
+// src/lib/camera/camera.ts
+import { Vector2 as Vector27, Vector3 as Vector314 } from "three";
+var CameraWrapper;
+var init_camera = __esm({
+  "src/lib/camera/camera.ts"() {
+    "use strict";
+    CameraWrapper = class {
+      cameraRef;
+      constructor(camera) {
+        this.cameraRef = camera;
+      }
+    };
+  }
+});
+
 // src/lib/stage/stage-default.ts
 import { proxy as proxy4 } from "valtio/vanilla";
-import { Vector3 as Vector313 } from "three";
+import { Vector3 as Vector315 } from "three";
 function getStageOptions(options) {
   const defaults = getStageDefaultConfig();
   let originalConfig = {};
@@ -2785,7 +3335,7 @@ var init_stage_default = __esm({
         p1: ["gamepad-1", "keyboard"],
         p2: ["gamepad-2", "keyboard"]
       },
-      gravity: new Vector313(0, 0, 0),
+      gravity: new Vector315(0, 0, 0),
       variables: {}
     };
     stageDefaultsState = proxy4({
@@ -2810,30 +3360,58 @@ var init_stage = __esm({
     Stage = class {
       wrappedStage;
       options = [];
-      // TODO: these shouldn't be here maybe more like nextFrame(stageInstance, () => {})
-      update = () => {
-      };
-      setup = () => {
-      };
-      destroy = () => {
-      };
+      // Entities added after construction, consumed on each load
+      _pendingEntities = [];
+      // Lifecycle callback arrays
+      setupCallbacks = [];
+      updateCallbacks = [];
+      destroyCallbacks = [];
+      pendingLoadingCallbacks = [];
       constructor(options) {
         this.options = options;
         this.wrappedStage = null;
       }
       async load(id, camera) {
         stageState.entities = [];
-        this.wrappedStage = new ZylemStage(this.options);
+        const loadOptions = [...this.options, ...this._pendingEntities];
+        this._pendingEntities = [];
+        this.wrappedStage = new ZylemStage(loadOptions);
         this.wrappedStage.wrapperRef = this;
+        this.pendingLoadingCallbacks.forEach((cb) => {
+          this.wrappedStage.onLoading(cb);
+        });
+        this.pendingLoadingCallbacks = [];
         const zylemCamera = camera instanceof CameraWrapper ? camera.cameraRef : camera;
         await this.wrappedStage.load(id, zylemCamera);
         this.wrappedStage.onEntityAdded((child) => {
           const next = this.wrappedStage.buildEntityState(child);
           stageState.entities = [...stageState.entities, next];
         }, { replayExisting: true });
+        this.applyLifecycleCallbacks();
+      }
+      applyLifecycleCallbacks() {
+        if (!this.wrappedStage) return;
+        if (this.setupCallbacks.length > 0) {
+          this.wrappedStage.setup = (params) => {
+            const extended = { ...params, stage: this };
+            this.setupCallbacks.forEach((cb) => cb(extended));
+          };
+        }
+        if (this.updateCallbacks.length > 0) {
+          this.wrappedStage.update = (params) => {
+            const extended = { ...params, stage: this };
+            this.updateCallbacks.forEach((cb) => cb(extended));
+          };
+        }
+        if (this.destroyCallbacks.length > 0) {
+          this.wrappedStage.destroy = (params) => {
+            const extended = { ...params, stage: this };
+            this.destroyCallbacks.forEach((cb) => cb(extended));
+          };
+        }
       }
       async addEntities(entities) {
-        this.options.push(...entities);
+        this._pendingEntities.push(...entities);
         if (!this.wrappedStage) {
           return;
         }
@@ -2858,28 +3436,57 @@ var init_stage = __esm({
       start(params) {
         this.wrappedStage?.nodeSetup(params);
       }
+      // Fluent API for adding lifecycle callbacks
       onUpdate(...callbacks) {
-        if (!this.wrappedStage) {
-          return;
+        this.updateCallbacks.push(...callbacks);
+        if (this.wrappedStage) {
+          this.wrappedStage.update = (params) => {
+            const extended = { ...params, stage: this };
+            this.updateCallbacks.forEach((cb) => cb(extended));
+          };
         }
-        this.wrappedStage.update = (params) => {
-          const extended = { ...params, stage: this };
-          callbacks.forEach((cb) => cb(extended));
-        };
+        return this;
       }
-      onSetup(callback) {
-        this.wrappedStage.setup = callback;
+      onSetup(...callbacks) {
+        this.setupCallbacks.push(...callbacks);
+        if (this.wrappedStage) {
+          this.wrappedStage.setup = (params) => {
+            const extended = { ...params, stage: this };
+            this.setupCallbacks.forEach((cb) => cb(extended));
+          };
+        }
+        return this;
       }
-      onDestroy(callback) {
-        this.wrappedStage.destroy = callback;
+      onDestroy(...callbacks) {
+        this.destroyCallbacks.push(...callbacks);
+        if (this.wrappedStage) {
+          this.wrappedStage.destroy = (params) => {
+            const extended = { ...params, stage: this };
+            this.destroyCallbacks.forEach((cb) => cb(extended));
+          };
+        }
+        return this;
       }
       onLoading(callback) {
         if (!this.wrappedStage) {
+          this.pendingLoadingCallbacks.push(callback);
           return () => {
+            this.pendingLoadingCallbacks = this.pendingLoadingCallbacks.filter((c) => c !== callback);
           };
         }
         return this.wrappedStage.onLoading(callback);
       }
+      /**
+       * 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(name, type) {
+        const entity = this.wrappedStage?.children.find((c) => c.name === name);
+        return entity;
+      }
     };
   }
 });
@@ -3717,8 +4324,202 @@ var GameCanvas = class {
   }
 };
 
-// src/lib/game/zylem-game.ts
+// src/lib/game/game-debug-delegate.ts
+init_debug_state();
 import Stats from "stats.js";
+import { subscribe as subscribe2 } from "valtio/vanilla";
+var GameDebugDelegate = class {
+  statsRef = null;
+  unsubscribe = null;
+  constructor() {
+    this.updateDebugUI();
+    this.unsubscribe = subscribe2(debugState, () => {
+      this.updateDebugUI();
+    });
+  }
+  /**
+   * Called every frame - wraps stats.begin()
+   */
+  begin() {
+    this.statsRef?.begin();
+  }
+  /**
+   * Called every frame - wraps stats.end()
+   */
+  end() {
+    this.statsRef?.end();
+  }
+  updateDebugUI() {
+    if (debugState.enabled && !this.statsRef) {
+      this.statsRef = new Stats();
+      this.statsRef.showPanel(0);
+      this.statsRef.dom.style.position = "absolute";
+      this.statsRef.dom.style.bottom = "0";
+      this.statsRef.dom.style.right = "0";
+      this.statsRef.dom.style.top = "auto";
+      this.statsRef.dom.style.left = "auto";
+      document.body.appendChild(this.statsRef.dom);
+    } else if (!debugState.enabled && this.statsRef) {
+      if (this.statsRef.dom.parentNode) {
+        this.statsRef.dom.parentNode.removeChild(this.statsRef.dom);
+      }
+      this.statsRef = null;
+    }
+  }
+  dispose() {
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+    if (this.statsRef?.dom?.parentNode) {
+      this.statsRef.dom.parentNode.removeChild(this.statsRef.dom);
+    }
+    this.statsRef = null;
+  }
+};
+
+// src/lib/game/game-loading-delegate.ts
+var GAME_LOADING_EVENT = "GAME_LOADING_EVENT";
+var GameLoadingDelegate = class {
+  loadingHandlers = [];
+  stageLoadingUnsubscribes = [];
+  /**
+   * Subscribe to loading events from the game.
+   * Events include stage context (stageName, stageIndex).
+   * 
+   * @param callback Invoked for each loading event
+   * @returns Unsubscribe function
+   */
+  onLoading(callback) {
+    this.loadingHandlers.push(callback);
+    return () => {
+      this.loadingHandlers = this.loadingHandlers.filter((h) => h !== callback);
+    };
+  }
+  /**
+   * Emit a loading event to all subscribers and dispatch to window.
+   */
+  emit(event) {
+    for (const handler of this.loadingHandlers) {
+      console.log("Game loading event", event);
+      try {
+        handler(event);
+      } catch (e) {
+        console.error("Game loading handler failed", e);
+      }
+    }
+    if (typeof window !== "undefined") {
+      window.dispatchEvent(new CustomEvent(GAME_LOADING_EVENT, { detail: event }));
+    }
+  }
+  /**
+   * Wire up a stage's loading events to this delegate.
+   * 
+   * @param stage The stage to wire up
+   * @param stageIndex The index of the stage
+   */
+  wireStageLoading(stage, stageIndex) {
+    const unsub = stage.onLoading((event) => {
+      this.emit({
+        type: event.type,
+        message: event.message ?? "",
+        progress: event.progress ?? 0,
+        current: event.current,
+        total: event.total,
+        stageName: stage.uuid ?? `Stage ${stageIndex}`,
+        stageIndex
+      });
+    });
+    if (typeof unsub === "function") {
+      this.stageLoadingUnsubscribes.push(unsub);
+    }
+  }
+  /**
+   * Unsubscribe from all stage loading events.
+   */
+  unwireAllStages() {
+    for (const unsub of this.stageLoadingUnsubscribes) {
+      try {
+        unsub();
+      } catch {
+      }
+    }
+    this.stageLoadingUnsubscribes = [];
+  }
+  /**
+   * Clean up all handlers.
+   */
+  dispose() {
+    this.unwireAllStages();
+    this.loadingHandlers = [];
+  }
+};
+
+// src/lib/game/zylem-game.ts
+init_game_event_bus();
+
+// src/lib/game/game-renderer-observer.ts
+var GameRendererObserver = class {
+  container = null;
+  camera = null;
+  gameCanvas = null;
+  config = null;
+  mounted = false;
+  setGameCanvas(canvas) {
+    this.gameCanvas = canvas;
+    this.tryMount();
+  }
+  setConfig(config) {
+    this.config = config;
+    this.tryMount();
+  }
+  setContainer(container) {
+    this.container = container;
+    this.tryMount();
+  }
+  setCamera(camera) {
+    this.camera = camera;
+    this.tryMount();
+  }
+  /**
+   * Attempt to mount renderer if all dependencies are available.
+   */
+  tryMount() {
+    if (this.mounted) return;
+    if (!this.container || !this.camera || !this.gameCanvas) return;
+    const dom = this.camera.getDomElement();
+    const internal = this.config?.internalResolution;
+    this.gameCanvas.mountRenderer(dom, (cssW, cssH) => {
+      if (!this.camera) return;
+      if (internal) {
+        this.camera.setPixelRatio(1);
+        this.camera.resize(internal.width, internal.height);
+      } else {
+        const dpr = window.devicePixelRatio || 1;
+        this.camera.setPixelRatio(dpr);
+        this.camera.resize(cssW, cssH);
+      }
+    });
+    this.mounted = true;
+  }
+  /**
+   * Reset state for stage transitions.
+   */
+  reset() {
+    this.camera = null;
+    this.mounted = false;
+  }
+  dispose() {
+    this.container = null;
+    this.camera = null;
+    this.gameCanvas = null;
+    this.config = null;
+    this.mounted = false;
+  }
+};
+
+// src/lib/game/zylem-game.ts
+var ZYLEM_STATE_DISPATCH = "zylem:state:dispatch";
 var ZylemGame = class _ZylemGame {
   id;
   initialGlobals = {};
@@ -3733,7 +4534,6 @@ var ZylemGame = class _ZylemGame {
   timer;
   inputManager;
   wrapperRef;
-  statsRef = null;
   defaultCamera = null;
   container = null;
   canvas = null;
@@ -3742,6 +4542,10 @@ var ZylemGame = class _ZylemGame {
   gameCanvas = null;
   animationFrameId = null;
   isDisposed = false;
+  debugDelegate = null;
+  loadingDelegate = new GameLoadingDelegate();
+  rendererObserver = new GameRendererObserver();
+  eventBusUnsubscribes = [];
   static FRAME_LIMIT = 120;
   static FRAME_DURATION = 1e3 / _ZylemGame.FRAME_LIMIT;
   static MAX_DELTA_SECONDS = 1 / 30;
@@ -3773,42 +4577,33 @@ var ZylemGame = class _ZylemGame {
     this.gameCanvas.applyBodyBackground();
     this.gameCanvas.mountCanvas();
     this.gameCanvas.centerIfFullscreen();
+    this.rendererObserver.setGameCanvas(this.gameCanvas);
+    if (this.resolvedConfig) {
+      this.rendererObserver.setConfig(this.resolvedConfig);
+    }
+    if (this.container) {
+      this.rendererObserver.setContainer(this.container);
+    }
+    this.subscribeToEventBus();
   }
   loadDebugOptions(options) {
-    debugState.enabled = Boolean(options.debug);
-    if (options.debug) {
-      this.statsRef = new Stats();
-      this.statsRef.showPanel(0);
-      this.statsRef.dom.style.position = "absolute";
-      this.statsRef.dom.style.bottom = "0";
-      this.statsRef.dom.style.right = "0";
-      this.statsRef.dom.style.top = "auto";
-      this.statsRef.dom.style.left = "auto";
-      document.body.appendChild(this.statsRef.dom);
+    if (options.debug !== void 0) {
+      debugState.enabled = Boolean(options.debug);
     }
+    this.debugDelegate = new GameDebugDelegate();
   }
-  async loadStage(stage) {
+  loadStage(stage, stageIndex = 0) {
     this.unloadCurrentStage();
     const config = stage.options[0];
-    await stage.load(this.id, config?.camera);
-    this.stageMap.set(stage.wrappedStage.uuid, stage);
-    this.currentStageId = stage.wrappedStage.uuid;
-    this.defaultCamera = stage.wrappedStage.cameraRef;
-    if (this.container && this.defaultCamera) {
-      const dom = this.defaultCamera.getDomElement();
-      const internal = this.resolvedConfig?.internalResolution;
-      this.gameCanvas?.mountRenderer(dom, (cssW, cssH) => {
-        if (!this.defaultCamera) return;
-        if (internal) {
-          this.defaultCamera.setPixelRatio(1);
-          this.defaultCamera.resize(internal.width, internal.height);
-        } else {
-          const dpr = window.devicePixelRatio || 1;
-          this.defaultCamera.setPixelRatio(dpr);
-          this.defaultCamera.resize(cssW, cssH);
-        }
-      });
-    }
+    this.loadingDelegate.wireStageLoading(stage, stageIndex);
+    return stage.load(this.id, config?.camera).then(() => {
+      this.stageMap.set(stage.wrappedStage.uuid, stage);
+      this.currentStageId = stage.wrappedStage.uuid;
+      this.defaultCamera = stage.wrappedStage.cameraRef;
+      if (this.defaultCamera) {
+        this.rendererObserver.setCamera(this.defaultCamera);
+      }
+    });
   }
   unloadCurrentStage() {
     if (!this.currentStageId) return;
@@ -3823,8 +4618,12 @@ var ZylemGame = class _ZylemGame {
       } catch (e) {
         console.error("Failed to destroy previous stage", e);
       }
+      current.wrappedStage = null;
     }
     this.stageMap.delete(this.currentStageId);
+    this.currentStageId = "";
+    this.defaultCamera = null;
+    this.rendererObserver.reset();
   }
   setGlobals(options) {
     this.initialGlobals = { ...options.globals };
@@ -3859,7 +4658,7 @@ var ZylemGame = class _ZylemGame {
     this.loop(0);
   }
   loop(timestamp) {
-    this.statsRef && this.statsRef.begin();
+    this.debugDelegate?.begin();
     if (!isPaused()) {
       this.timer.update(timestamp);
       const stage = this.currentStage();
@@ -3869,14 +4668,14 @@ var ZylemGame = class _ZylemGame {
       if (this.customUpdate) {
         this.customUpdate(clampedParams);
       }
-      if (stage) {
+      if (stage && stage.wrappedStage) {
         stage.wrappedStage.nodeUpdate({ ...clampedParams, me: stage.wrappedStage });
       }
       this.totalTime += clampedParams.delta;
       state.time = this.totalTime;
       this.previousTimeStamp = timestamp;
     }
-    this.statsRef && this.statsRef.end();
+    this.debugDelegate?.end();
     this.outOfLoop();
     if (!this.isDisposed) {
       this.animationFrameId = requestAnimationFrame(this.loop.bind(this));
@@ -3889,9 +4688,13 @@ var ZylemGame = class _ZylemGame {
       this.animationFrameId = null;
     }
     this.unloadCurrentStage();
-    if (this.statsRef && this.statsRef.dom && this.statsRef.dom.parentNode) {
-      this.statsRef.dom.parentNode.removeChild(this.statsRef.dom);
+    if (this.debugDelegate) {
+      this.debugDelegate.dispose();
+      this.debugDelegate = null;
     }
+    this.eventBusUnsubscribes.forEach((unsub) => unsub());
+    this.eventBusUnsubscribes = [];
+    this.rendererObserver.dispose();
     this.timer.dispose();
     if (this.customDestroy) {
       this.customDestroy({
@@ -3912,6 +4715,52 @@ var ZylemGame = class _ZylemGame {
   currentStage() {
     return this.getStage(this.currentStageId);
   }
+  /**
+   * Subscribe to loading events from the game.
+   * Events include stage context (stageName, stageIndex).
+   * @param callback Invoked for each loading event
+   * @returns Unsubscribe function
+   */
+  onLoading(callback) {
+    return this.loadingDelegate.onLoading(callback);
+  }
+  /**
+   * Subscribe to the game event bus for stage loading and state events.
+   * Emits window events for cross-application communication.
+   */
+  subscribeToEventBus() {
+    const emitLoadingWindowEvent = (payload) => {
+      if (typeof window !== "undefined") {
+        const event = {
+          type: payload.type,
+          message: payload.message ?? "",
+          progress: payload.progress ?? 0,
+          current: payload.current,
+          total: payload.total,
+          stageName: payload.stageName,
+          stageIndex: payload.stageIndex
+        };
+        window.dispatchEvent(new CustomEvent(GAME_LOADING_EVENT, { detail: event }));
+      }
+    };
+    const emitStateDispatchEvent = (payload) => {
+      if (typeof window !== "undefined") {
+        const detail = {
+          scope: "game",
+          path: payload.path,
+          value: payload.value,
+          previousValue: payload.previousValue
+        };
+        window.dispatchEvent(new CustomEvent(ZYLEM_STATE_DISPATCH, { detail }));
+      }
+    };
+    this.eventBusUnsubscribes.push(
+      gameEventBus.on("stage:loading:start", emitLoadingWindowEvent),
+      gameEventBus.on("stage:loading:progress", emitLoadingWindowEvent),
+      gameEventBus.on("stage:loading:complete", emitLoadingWindowEvent),
+      gameEventBus.on("game:state:updated", emitStateDispatchEvent)
+    );
+  }
 };
 
 // src/lib/game/game.ts
@@ -4042,7 +4891,7 @@ init_stage();
 init_entity();
 init_builder();
 init_create();
-import { Color as Color9, Group as Group5, Sprite as ThreeSprite, SpriteMaterial, CanvasTexture, LinearFilter, Vector2 as Vector27, ClampToEdgeWrapping } from "three";
+import { Color as Color10, Group as Group5, Sprite as ThreeSprite, SpriteMaterial, CanvasTexture, LinearFilter, Vector2 as Vector28, ClampToEdgeWrapping } from "three";
 
 // src/lib/entities/delegates/debug.ts
 import { MeshStandardMaterial as MeshStandardMaterial2, MeshBasicMaterial as MeshBasicMaterial2, MeshPhongMaterial as MeshPhongMaterial2 } from "three";
@@ -4149,7 +4998,7 @@ var textDefaults = {
   backgroundColor: null,
   padding: 4,
   stickToViewport: true,
-  screenPosition: new Vector27(24, 24),
+  screenPosition: new Vector28(24, 24),
   zDistance: 1
 };
 var TextBuilder = class extends EntityBuilder {
@@ -4157,7 +5006,7 @@ var TextBuilder = class extends EntityBuilder {
     return new ZylemText(options);
   }
 };
-var TEXT_TYPE = Symbol("Text");
+var TEXT_TYPE = /* @__PURE__ */ Symbol("Text");
 var ZylemText = class _ZylemText extends GameEntity {
   static type = TEXT_TYPE;
   _sprite = null;
@@ -4170,12 +5019,20 @@ var ZylemText = class _ZylemText extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...textDefaults, ...options };
+    this.prependSetup(this.textSetup.bind(this));
+    this.prependUpdate(this.textUpdate.bind(this));
+    this.onDestroy(this.textDestroy.bind(this));
+  }
+  create() {
+    this._sprite = null;
+    this._texture = null;
+    this._canvas = null;
+    this._ctx = null;
+    this._lastCanvasW = 0;
+    this._lastCanvasH = 0;
     this.group = new Group5();
     this.createSprite();
-    this.lifeCycleDelegate = {
-      setup: [this.textSetup.bind(this)],
-      update: [this.textUpdate.bind(this)]
-    };
+    return super.create();
   }
   createSprite() {
     this._canvas = document.createElement("canvas");
@@ -4253,7 +5110,7 @@ var ZylemText = class _ZylemText extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color9 ? color : new Color9(color);
+    const c = color instanceof Color10 ? color : new Color10(color);
     return `#${c.getHexString()}`;
   }
   textSetup(params) {
@@ -4313,7 +5170,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     if (!this._sprite || !this._cameraRef) return;
     const camera = this._cameraRef.camera;
     const { width, height } = this.getResolution();
-    const sp = this.options.screenPosition ?? new Vector27(24, 24);
+    const sp = this.options.screenPosition ?? new Vector28(24, 24);
     const { px, py } = this.getScreenPixels(sp, width, height);
     const zDist = Math.max(1e-3, this.options.zDistance ?? 1);
     const { worldHalfW, worldHalfH } = this.computeWorldExtents(camera, zDist);
@@ -4341,6 +5198,24 @@ var ZylemText = class _ZylemText extends GameEntity {
       sticky: this.options.stickToViewport
     };
   }
+  /**
+   * Dispose of Three.js resources when the entity is destroyed.
+   */
+  async textDestroy() {
+    this._texture?.dispose();
+    if (this._sprite?.material) {
+      this._sprite.material.dispose();
+    }
+    if (this._sprite) {
+      this._sprite.removeFromParent();
+    }
+    this.group?.removeFromParent();
+    this._sprite = null;
+    this._texture = null;
+    this._canvas = null;
+    this._ctx = null;
+    this._cameraRef = null;
+  }
 };
 async function text(...args) {
   return createEntity({
@@ -4358,20 +5233,20 @@ init_builder();
 init_builder();
 init_create();
 import { ColliderDesc as ColliderDesc3 } from "@dimforge/rapier3d-compat";
-import { Color as Color10, Euler, Group as Group6, Quaternion as Quaternion2, Vector3 as Vector314 } from "three";
+import { Color as Color11, Euler, Group as Group6, Quaternion as Quaternion3, Vector3 as Vector316 } from "three";
 import {
   TextureLoader as TextureLoader3,
   SpriteMaterial as SpriteMaterial2,
   Sprite as ThreeSprite2
 } from "three";
 var spriteDefaults = {
-  size: new Vector314(1, 1, 1),
-  position: new Vector314(0, 0, 0),
+  size: new Vector316(1, 1, 1),
+  position: new Vector316(0, 0, 0),
   collision: {
     static: false
   },
   material: {
-    color: new Color10("#ffffff"),
+    color: new Color11("#ffffff"),
     shader: "standard"
   },
   images: [],
@@ -4379,7 +5254,7 @@ var spriteDefaults = {
 };
 var SpriteCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const size = options.collisionSize || options.size || new Vector314(1, 1, 1);
+    const size = options.collisionSize || options.size || new Vector316(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
     let colliderDesc = ColliderDesc3.cuboid(half.x, half.y, half.z);
     return colliderDesc;
@@ -4390,7 +5265,7 @@ var SpriteBuilder = class extends EntityBuilder {
     return new ZylemSprite(options);
   }
 };
-var SPRITE_TYPE = Symbol("Sprite");
+var SPRITE_TYPE = /* @__PURE__ */ Symbol("Sprite");
 var ZylemSprite = class _ZylemSprite extends GameEntity {
   static type = SPRITE_TYPE;
   sprites = [];
@@ -4404,12 +5279,21 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...spriteDefaults, ...options };
-    this.createSpritesFromImages(options?.images || []);
-    this.createAnimations(options?.animations || []);
-    this.lifeCycleDelegate = {
-      update: [this.spriteUpdate.bind(this)],
-      destroy: [this.spriteDestroy.bind(this)]
-    };
+    this.prependUpdate(this.spriteUpdate.bind(this));
+    this.onDestroy(this.spriteDestroy.bind(this));
+  }
+  create() {
+    this.sprites = [];
+    this.spriteMap.clear();
+    this.animations.clear();
+    this.currentAnimation = null;
+    this.currentAnimationFrame = "";
+    this.currentAnimationIndex = 0;
+    this.currentAnimationTime = 0;
+    this.group = void 0;
+    this.createSpritesFromImages(this.options?.images || []);
+    this.createAnimations(this.options?.animations || []);
+    return super.create();
   }
   createSpritesFromImages(images) {
     const textureLoader = new TextureLoader3();
@@ -4479,7 +5363,7 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
       if (_sprite.material) {
         const q = this.body?.rotation();
         if (q) {
-          const quat = new Quaternion2(q.x, q.y, q.z, q.w);
+          const quat = new Quaternion3(q.x, q.y, q.z, q.w);
           const euler = new Euler().setFromQuaternion(quat, "XYZ");
           _sprite.material.rotation = euler.z;
         }
@@ -4563,12 +5447,15 @@ init_game_state();
 var Game = class {
   wrappedGame = null;
   options;
-  update = () => {
-  };
-  setup = () => {
-  };
-  destroy = () => {
-  };
+  // Lifecycle callback arrays
+  setupCallbacks = [];
+  updateCallbacks = [];
+  destroyCallbacks = [];
+  pendingLoadingCallbacks = [];
+  // Game-scoped global change subscriptions
+  globalChangeCallbacks = [];
+  globalChangesCallbacks = [];
+  activeGlobalSubscriptions = [];
   refErrorMessage = "lost reference to game";
   constructor(options) {
     this.options = options;
@@ -4580,10 +5467,29 @@ var Game = class {
       initGlobals(globals);
     }
   }
+  // Fluent API for adding lifecycle callbacks
+  onSetup(...callbacks) {
+    this.setupCallbacks.push(...callbacks);
+    return this;
+  }
+  onUpdate(...callbacks) {
+    this.updateCallbacks.push(...callbacks);
+    return this;
+  }
+  onDestroy(...callbacks) {
+    this.destroyCallbacks.push(...callbacks);
+    return this;
+  }
   async start() {
+    resetGlobals();
+    const globals = extractGlobalsFromOptions(this.options);
+    if (globals) {
+      initGlobals(globals);
+    }
     const game = await this.load();
     this.wrappedGame = game;
     this.setOverrides();
+    this.registerGlobalSubscriptions();
     game.start();
     return this;
   }
@@ -4594,6 +5500,9 @@ var Game = class {
       ...options,
       ...resolved
     }, this);
+    for (const callback of this.pendingLoadingCallbacks) {
+      game.onLoading(callback);
+    }
     await game.loadStage(options.stages[0]);
     return game;
   }
@@ -4602,9 +5511,59 @@ var Game = class {
       console.error(this.refErrorMessage);
       return;
     }
-    this.wrappedGame.customSetup = this.setup;
-    this.wrappedGame.customUpdate = this.update;
-    this.wrappedGame.customDestroy = this.destroy;
+    this.wrappedGame.customSetup = (params) => {
+      this.setupCallbacks.forEach((cb) => cb(params));
+    };
+    this.wrappedGame.customUpdate = (params) => {
+      this.updateCallbacks.forEach((cb) => cb(params));
+    };
+    this.wrappedGame.customDestroy = (params) => {
+      this.destroyCallbacks.forEach((cb) => cb(params));
+    };
+  }
+  /**
+   * Subscribe to changes on a global value. Subscriptions are registered
+   * when the game starts and cleaned up when disposed.
+   * The callback receives the value and the current stage.
+   * @example game.onGlobalChange('score', (val, stage) => console.log(val));
+   */
+  onGlobalChange(path, callback) {
+    this.globalChangeCallbacks.push({ path, callback });
+    return this;
+  }
+  /**
+   * Subscribe to changes on multiple global paths. Subscriptions are registered
+   * when the game starts and cleaned up when disposed.
+   * The callback receives the values and the current stage.
+   * @example game.onGlobalChanges(['score', 'lives'], ([score, lives], stage) => console.log(score, lives));
+   */
+  onGlobalChanges(paths, callback) {
+    this.globalChangesCallbacks.push({ paths, callback });
+    return this;
+  }
+  /**
+   * Register all stored global change callbacks.
+   * Called internally during start().
+   */
+  registerGlobalSubscriptions() {
+    for (const { path, callback } of this.globalChangeCallbacks) {
+      const unsub = onGlobalChange(path, (value) => {
+        callback(value, this.getCurrentStage());
+      });
+      this.activeGlobalSubscriptions.push(unsub);
+    }
+    for (const { paths, callback } of this.globalChangesCallbacks) {
+      const unsub = onGlobalChanges(paths, (values) => {
+        callback(values, this.getCurrentStage());
+      });
+      this.activeGlobalSubscriptions.push(unsub);
+    }
+  }
+  /**
+   * Get the current stage wrapper.
+   */
+  getCurrentStage() {
+    return this.wrappedGame?.currentStage() ?? null;
   }
   async pause() {
     setPaused(true);
@@ -4623,19 +5582,19 @@ var Game = class {
     }
     await this.wrappedGame.loadStage(this.wrappedGame.stages[0]);
   }
-  async previousStage() {
+  previousStage() {
     if (!this.wrappedGame) {
       console.error(this.refErrorMessage);
       return;
     }
     const currentStageId = this.wrappedGame.currentStageId;
-    const currentIndex = this.wrappedGame.stages.findIndex((s) => s.wrappedStage.uuid === currentStageId);
+    const currentIndex = this.wrappedGame.stages.findIndex((s) => s.wrappedStage?.uuid === currentStageId);
     const previousStage = this.wrappedGame.stages[currentIndex - 1];
     if (!previousStage) {
       console.error("previous stage called on first stage");
       return;
     }
-    await this.wrappedGame.loadStage(previousStage);
+    this.wrappedGame.loadStage(previousStage);
   }
   async loadStageFromId(stageId) {
     if (!this.wrappedGame) {
@@ -4651,39 +5610,61 @@ var Game = class {
       console.error(`Failed to load stage ${stageId}`, e);
     }
   }
-  async nextStage() {
+  nextStage() {
     if (!this.wrappedGame) {
       console.error(this.refErrorMessage);
       return;
     }
     if (stageState2.next) {
       const nextId = stageState2.next.id;
-      await StageManager.transitionForward(nextId);
+      StageManager.transitionForward(nextId);
       if (stageState2.current) {
-        const stage = await StageFactory.createFromBlueprint(stageState2.current);
-        await this.wrappedGame.loadStage(stage);
+        StageFactory.createFromBlueprint(stageState2.current).then((stage) => {
+          this.wrappedGame?.loadStage(stage);
+        });
         return;
       }
     }
     const currentStageId = this.wrappedGame.currentStageId;
-    const currentIndex = this.wrappedGame.stages.findIndex((s) => s.wrappedStage.uuid === currentStageId);
+    const currentIndex = this.wrappedGame.stages.findIndex((s) => s.wrappedStage?.uuid === currentStageId);
     const nextStage = this.wrappedGame.stages[currentIndex + 1];
     if (!nextStage) {
       console.error("next stage called on last stage");
       return;
     }
-    await this.wrappedGame.loadStage(nextStage);
+    this.wrappedGame.loadStage(nextStage);
   }
   async goToStage() {
   }
   async end() {
   }
   dispose() {
+    for (const unsub of this.activeGlobalSubscriptions) {
+      unsub();
+    }
+    this.activeGlobalSubscriptions = [];
     if (this.wrappedGame) {
       this.wrappedGame.dispose();
     }
+    clearGlobalSubscriptions();
+    resetGlobals();
   }
+  /**
+   * Subscribe to loading events from the game.
+   * Events include stage context (stageName, stageIndex).
+   * @param callback Invoked for each loading event
+   * @returns Unsubscribe function
+   */
   onLoading(callback) {
+    if (this.wrappedGame) {
+      return this.wrappedGame.onLoading(callback);
+    }
+    this.pendingLoadingCallbacks.push(callback);
+    return () => {
+      this.pendingLoadingCallbacks = this.pendingLoadingCallbacks.filter((c) => c !== callback);
+      if (this.wrappedGame) {
+      }
+    };
   }
 };
 function createGame(...options) {
@@ -4692,7 +5673,7 @@ function createGame(...options) {
 
 // src/lib/core/vessel.ts
 init_base_node();
-var VESSEL_TYPE = Symbol("vessel");
+var VESSEL_TYPE = /* @__PURE__ */ Symbol("vessel");
 var Vessel = class extends BaseNode {
   static type = VESSEL_TYPE;
   _setup(_params) {