@zylem/game-lib 0.5.1 → 0.6.0

package/dist/main.js

@@ -40,10 +40,64 @@ 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 createGlobal(path, defaultValue) {
   const existing = getByPath(state.globals, path);
@@ -58,17 +112,22 @@ function getGlobal(path) {
 }
 function onGlobalChange(path, callback) {
   let previous = getByPath(state.globals, path);
-  return subscribe(state.globals, () => {
+  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));
-  return subscribe(state.globals, () => {
+  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) {
@@ -76,6 +135,11 @@ function onGlobalChanges(paths, callback) {
       callback(currentValues);
     }
   });
+  activeSubscriptions.add(unsub);
+  return () => {
+    unsub();
+    activeSubscriptions.delete(unsub);
+  };
 }
 function getGlobals() {
   return state.globals;
@@ -88,16 +152,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();
   }
 });
 
@@ -112,6 +184,9 @@ function setPaused(paused) {
 function getDebugTool() {
   return debugState.tool;
 }
+function setDebugTool(tool) {
+  debugState.tool = tool;
+}
 function setSelectedEntity(entity) {
   debugState.selectedEntity = entity;
 }
@@ -163,21 +238,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;
       }
@@ -201,6 +331,9 @@ var init_base_node = __esm({
       isComposite() {
         return this.children.length > 0;
       }
+      // ─────────────────────────────────────────────────────────────────────────────
+      // Node lifecycle execution - runs internal + callback arrays
+      // ─────────────────────────────────────────────────────────────────────────────
       nodeSetup(params) {
         if (DEBUG_FLAG) {
         }
@@ -208,8 +341,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));
       }
@@ -220,21 +353,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;
       }
@@ -250,57 +402,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 destroy2 = (world) => {
+    removeQuery(world, transformQuery);
+  };
+  return { system, destroy: destroy2 };
 }
-var position, rotation, scale;
+var position, rotation, scale, _tempQuaternion;
 var init_transformable_system = __esm({
   "src/lib/systems/transformable.system.ts"() {
     "use strict";
@@ -320,6 +469,7 @@ var init_transformable_system = __esm({
       y: Types.f32,
       z: Types.f32
     });
+    _tempQuaternion = new Quaternion();
   }
 });
 
@@ -343,11 +493,6 @@ var init_entity = __esm({
       custom = {};
       debugInfo = {};
       debugMaterial;
-      lifeCycleDelegate = {
-        setup: [],
-        update: [],
-        destroy: []
-      };
       collisionDelegate = {
         collision: []
       };
@@ -372,67 +517,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 });
         });
@@ -722,6 +840,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;
       }
@@ -1220,7 +1355,7 @@ var init_actor = __esm({
         return new ZylemActor(options);
       }
     };
-    ACTOR_TYPE = Symbol("Actor");
+    ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
     ZylemActor = class extends GameEntity {
       static type = ACTOR_TYPE;
       _object = null;
@@ -1231,9 +1366,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() {
@@ -1253,6 +1386,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));
@@ -1312,25 +1473,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;
@@ -1536,7 +1689,11 @@ var init_zylem_scene = __esm({
        * Setup camera with the scene
        */
       setupCamera(scene, camera2) {
-        scene.add(camera2.cameraRig);
+        if (camera2.cameraRig) {
+          scene.add(camera2.cameraRig);
+        } else {
+          scene.add(camera2.camera);
+        }
         camera2.setup(scene);
       }
       /**
@@ -1597,7 +1754,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 getOrCreateVariableProxy(target) {
   let store = variableProxyStore.get(target);
   if (!store) {
@@ -1627,7 +1784,7 @@ function getVariable(target, path) {
 function onVariableChange(target, path, callback) {
   const store = getOrCreateVariableProxy(target);
   let previous = getByPath(store, path);
-  return subscribe2(store, () => {
+  return subscribe3(store, () => {
     const current = getByPath(store, path);
     if (current !== previous) {
       previous = current;
@@ -1638,7 +1795,7 @@ function onVariableChange(target, path, callback) {
 function onVariableChanges(target, paths, callback) {
   const store = getOrCreateVariableProxy(target);
   let previousValues = paths.map((p) => getByPath(store, p));
-  return subscribe2(store, () => {
+  return subscribe3(store, () => {
     const currentValues = paths.map((p) => getByPath(store, p));
     const hasChange = currentValues.some((val, i) => val !== previousValues[i]);
     if (hasChange) {
@@ -1735,68 +1892,355 @@ 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 Mesh4,
+  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: camera2 } = 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 = camera2;
+        const initialGeometry = new BoxGeometry(1, 1, 1);
+        this.fillMesh = new Mesh4(
+          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
-       */
-      resize(width, height) {
-        if (this.screenResolution) {
-          this.screenResolution.set(width, height);
+        this.bbox.setFromObject(object);
+        if (!isFinite(this.bbox.min.x) || !isFinite(this.bbox.max.x)) {
+          this.hide();
+          return;
         }
-      }
-      /**
-       * Set the distance from the target
-       */
+        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 BufferGeometry4, 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 BufferGeometry4(),
+            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 rect2 = canvas.getBoundingClientRect();
+          const x = (e.clientX - rect2.left) / rect2.width * 2 - 1;
+          const y = -((e.clientY - rect2.top) / rect2.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: camera2 } = params;
+        this.screenResolution = screenResolution;
+        this.renderer = renderer;
+        this.scene = scene;
+        this.cameraRef = camera2;
+      }
+      /**
+       * 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) {
+          this.screenResolution.set(width, height);
+        }
+      }
+      /**
+       * Set the distance from the target
+       */
       setDistance(distance) {
         this.distance = distance;
       }
@@ -1901,41 +2345,217 @@ var init_render_pass = __esm({
         } else {
           renderer.setRenderTarget(writeBuffer);
         }
-        this.fsQuad.render(renderer);
+        this.fsQuad.render(renderer);
+      }
+      material() {
+        return new THREE.ShaderMaterial({
+          uniforms: {
+            iTime: { value: 0 },
+            tDiffuse: { value: null },
+            tDepth: { value: null },
+            tNormal: { value: null },
+            resolution: {
+              value: new THREE.Vector4(
+                this.resolution.x,
+                this.resolution.y,
+                1 / this.resolution.x,
+                1 / this.resolution.y
+              )
+            }
+          },
+          vertexShader: standard_default2,
+          fragmentShader: standard_default
+        });
+      }
+      dispose() {
+        try {
+          this.fsQuad?.dispose?.();
+        } catch {
+        }
+        try {
+          this.rgbRenderTarget?.dispose?.();
+          this.normalRenderTarget?.dispose?.();
+        } catch {
+        }
+        try {
+          this.normalMaterial?.dispose?.();
+        } catch {
+        }
+      }
+    };
+  }
+});
+
+// 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(camera2, domElement) {
+        this.camera = camera2;
+        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;
       }
-      material() {
-        return new THREE.ShaderMaterial({
-          uniforms: {
-            iTime: { value: 0 },
-            tDiffuse: { value: null },
-            tDepth: { value: null },
-            tNormal: { value: null },
-            resolution: {
-              value: new THREE.Vector4(
-                this.resolution.x,
-                this.resolution.y,
-                1 / this.resolution.x,
-                1 / this.resolution.y
-              )
-            }
-          },
-          vertexShader: standard_default2,
-          fragmentShader: standard_default
-        });
+      detachDebugDelegate() {
+        if (this.debugUnsubscribe) {
+          try {
+            this.debugUnsubscribe();
+          } catch {
+          }
+        }
+        this.debugUnsubscribe = null;
+        this.debugDelegate = null;
       }
-      dispose() {
-        try {
-          this.fsQuad?.dispose?.();
-        } catch {
+      /**
+       * 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;
         }
-        try {
-          this.rgbRenderTarget?.dispose?.();
-          this.normalRenderTarget?.dispose?.();
-        } catch {
+      }
+      /**
+       * Restore camera position, rotation, and zoom when exiting debug mode.
+       */
+      restoreCameraState() {
+        if (this.savedCameraPosition) {
+          this.camera.position.copy(this.savedCameraPosition);
+          this.savedCameraPosition = null;
         }
-        try {
-          this.normalMaterial?.dispose?.();
-        } catch {
+        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;
         }
       }
     };
@@ -1943,8 +2563,7 @@ 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";
-import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+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({
@@ -1954,24 +2573,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;
@@ -1982,26 +2598,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;
@@ -2023,16 +2636,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
        */
@@ -2042,7 +2657,7 @@ var init_zylem_camera = __esm({
         } catch {
         }
         try {
-          this.disableOrbitControls();
+          this.orbitController?.dispose();
         } catch {
         }
         try {
@@ -2054,28 +2669,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
@@ -2167,15 +2767,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
@@ -2183,348 +2799,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;
-      }
-      disableOrbitControls() {
-        if (!this.orbitControls) {
-          return;
-        }
-        this.orbitControls.dispose();
-        this.orbitControls = null;
-      }
-      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;
-          }
-        }
-        this.orbitTarget = null;
-      }
-      detachDebugDelegate() {
-        if (this.debugUnsubscribe) {
-          try {
-            this.debugUnsubscribe();
-          } catch {
-          }
-        }
-        this.debugUnsubscribe = null;
-        this.debugDelegate = null;
-      }
     };
   }
 });
 
-// src/lib/camera/camera.ts
-import { Vector2 as Vector24, Vector3 as Vector39 } from "three";
-function camera(options) {
-  const screenResolution = options.screenResolution || new Vector24(window.innerWidth, window.innerHeight);
-  let frustumSize = 10;
-  if (options.perspective === "fixed-2d") {
-    frustumSize = options.zoom || 10;
-  }
-  const zylemCamera = new ZylemCamera(options.perspective || "third-person", screenResolution, frustumSize);
-  zylemCamera.move(options.position || new Vector39(0, 0, 0));
-  zylemCamera.camera.lookAt(options.target || new Vector39(0, 0, 0));
-  return new CameraWrapper(zylemCamera);
-}
-var CameraWrapper;
-var init_camera = __esm({
-  "src/lib/camera/camera.ts"() {
+// 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();
-    CameraWrapper = class {
-      cameraRef;
-      constructor(camera2) {
-        this.cameraRef = camera2;
-      }
-    };
-  }
-});
-
-// src/lib/stage/debug-entity-cursor.ts
-import {
-  Box3,
-  BoxGeometry,
-  Color as Color7,
-  EdgesGeometry,
-  Group as Group4,
-  LineBasicMaterial,
-  LineSegments,
-  Mesh as Mesh4,
-  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 Mesh4(
-          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);
+    init_perspective();
+    StageCameraDelegate = class {
+      stage;
+      constructor(stage) {
+        this.stage = stage;
       }
       /**
-       * Update the cursor to enclose the provided Object3D using a world-space AABB.
+       * Create a default third-person camera based on window size.
        */
-      updateFromObject(object) {
-        if (!object) {
-          this.hide();
-          return;
-        }
-        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;
+      createDefaultCamera() {
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+        const screenResolution = new Vector25(width, height);
+        return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
       }
-      dispose() {
-        this.scene.remove(this.container);
-        this.fillMesh.geometry.dispose();
-        this.fillMesh.material.dispose();
-        this.edgeLines.geometry.dispose();
-        this.edgeLines.material.dispose();
+      /**
+       * 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;
+        }
+        if (cameraWrapper) {
+          return cameraWrapper.cameraRef;
+        }
+        return this.createDefaultCamera();
       }
     };
   }
 });
 
-// src/lib/stage/stage-debug-delegate.ts
-import { Ray } from "@dimforge/rapier3d-compat";
-import { BufferAttribute, BufferGeometry as BufferGeometry4, 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/stage/stage-loading-delegate.ts
+var StageLoadingDelegate;
+var init_stage_loading_delegate = __esm({
+  "src/lib/stage/stage-loading-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 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
+    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;
+      }
+      /**
+       * 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);
         };
-        if (this.stage.scene) {
-          this.debugLines = new LineSegments2(
-            new BufferGeometry4(),
-            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);
+      /**
+       * Emit a loading event to all subscribers and to the game event bus.
+       * 
+       * @param event The loading event to broadcast
+       */
+      emit(event) {
+        for (const handler of this.loadingHandlers) {
+          try {
+            handler(event);
+          } catch (e) {
+            console.error("Loading handler failed", e);
           }
         }
-        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;
+        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.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;
-        }
+      /**
+       * Emit a start loading event.
+       */
+      emitStart(message = "Loading stage...") {
+        this.emit({ type: "start", message, progress: 0 });
       }
-      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;
-        }
+      /**
+       * Emit a progress loading event.
+       */
+      emitProgress(message, current, total) {
+        const progress = total > 0 ? current / total : 0;
+        this.emit({ type: "progress", message, progress, current, total });
       }
-      attachDomListeners() {
-        const canvas = this.stage.cameraRef?.renderer.domElement ?? this.stage.scene?.zylemCamera.renderer.domElement;
-        if (!canvas) return;
-        const onMouseMove = (e) => {
-          const rect2 = canvas.getBoundingClientRect();
-          const x = (e.clientX - rect2.left) / rect2.width * 2 - 1;
-          const y = -((e.clientY - rect2.top) / rect2.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));
+      /**
+       * Emit a complete loading event.
+       */
+      emitComplete(message = "Stage loaded") {
+        this.emit({ type: "complete", message, progress: 1 });
+      }
+      /**
+       * Clear all loading handlers.
+       */
+      dispose() {
+        this.loadingHandlers = [];
+      }
+    };
+  }
+});
+
+// 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";
+  }
+});
+
+// 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 camera2;
+  for (const item of options) {
+    if (isCameraWrapper(item)) {
+      camera2 = 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: camera2 };
+}
+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;
       }
     };
   }
@@ -2532,7 +3021,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({
@@ -2546,12 +3036,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;
@@ -2562,7 +3053,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: []
       };
@@ -2577,16 +3068,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
@@ -2596,49 +3090,22 @@ var init_zylem_stage = __esm({
         this.world = null;
         this.scene = null;
         this.uuid = nanoid2();
-        const { config, entities, asyncEntities, camera: camera2 } = this.parseOptions(options);
-        this.camera = camera2;
-        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 camera2;
-        for (const item of options) {
-          if (this.isCameraWrapper(item)) {
-            camera2 = 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: camera2 };
-      }
-      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) {
@@ -2659,42 +3126,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, camera2) {
         this.setState();
-        const zylemCamera = camera2 || (this.camera ? this.camera.cameraRef : this.createDefaultCamera());
+        const zylemCamera = this.cameraDelegate.resolveCamera(camera2, 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) {
@@ -2704,24 +3176,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) {
@@ -2731,7 +3223,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,
@@ -2765,13 +3257,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);
       }
@@ -2852,13 +3351,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.
@@ -2915,16 +3408,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) {
@@ -2932,7 +3425,7 @@ var init_zylem_stage = __esm({
             }
             continue;
           }
-          if (this.isThenable(item)) {
+          if (isThenable(item)) {
             this.handlePromiseWithSpawnOnResolve(item);
           }
         }
@@ -2941,9 +3434,36 @@ var init_zylem_stage = __esm({
   }
 });
 
+// src/lib/camera/camera.ts
+import { Vector2 as Vector27, Vector3 as Vector314 } from "three";
+function camera(options) {
+  const screenResolution = options.screenResolution || new Vector27(window.innerWidth, window.innerHeight);
+  let frustumSize = 10;
+  if (options.perspective === "fixed-2d") {
+    frustumSize = options.zoom || 10;
+  }
+  const zylemCamera = new ZylemCamera(options.perspective || "third-person", screenResolution, frustumSize);
+  zylemCamera.move(options.position || new Vector314(0, 0, 0));
+  zylemCamera.camera.lookAt(options.target || new Vector314(0, 0, 0));
+  return new CameraWrapper(zylemCamera);
+}
+var CameraWrapper;
+var init_camera = __esm({
+  "src/lib/camera/camera.ts"() {
+    "use strict";
+    init_zylem_camera();
+    CameraWrapper = class {
+      cameraRef;
+      constructor(camera2) {
+        this.cameraRef = camera2;
+      }
+    };
+  }
+});
+
 // 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 = {};
@@ -2974,7 +3494,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({
@@ -2999,30 +3519,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, camera2) {
         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 = camera2 instanceof CameraWrapper ? camera2.cameraRef : camera2;
         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;
         }
@@ -3047,28 +3595,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;
+      }
     };
   }
 });
@@ -3909,8 +4486,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(camera2) {
+    this.camera = camera2;
+    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 = {};
@@ -3925,7 +4696,6 @@ var ZylemGame = class _ZylemGame {
   timer;
   inputManager;
   wrapperRef;
-  statsRef = null;
   defaultCamera = null;
   container = null;
   canvas = null;
@@ -3934,6 +4704,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;
@@ -3965,42 +4739,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;
@@ -4015,8 +4780,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 };
@@ -4051,7 +4820,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();
@@ -4061,14 +4830,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));
@@ -4081,9 +4850,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({
@@ -4104,6 +4877,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
@@ -4234,7 +5053,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";
@@ -4341,7 +5160,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 {
@@ -4349,7 +5168,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;
@@ -4362,12 +5181,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");
@@ -4445,7 +5272,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) {
@@ -4505,7 +5332,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     if (!this._sprite || !this._cameraRef) return;
     const camera2 = 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(camera2, zDist);
@@ -4533,6 +5360,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({
@@ -4550,20 +5395,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: [],
@@ -4571,7 +5416,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;
@@ -4582,7 +5427,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 = [];
@@ -4596,12 +5441,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();
@@ -4671,7 +5525,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;
         }
@@ -4755,12 +5609,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;
@@ -4772,10 +5629,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;
   }
@@ -4786,6 +5662,9 @@ var Game = class {
       ...options,
       ...resolved
     }, this);
+    for (const callback of this.pendingLoadingCallbacks) {
+      game.onLoading(callback);
+    }
     await game.loadStage(options.stages[0]);
     return game;
   }
@@ -4794,9 +5673,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);
@@ -4815,19 +5744,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) {
@@ -4843,39 +5772,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) {
@@ -4886,7 +5837,7 @@ function createGame(...options) {
 init_stage();
 
 // src/lib/stage/entity-spawner.ts
-import { Euler as Euler2, Quaternion as Quaternion3, Vector2 as Vector28 } from "three";
+import { Euler as Euler2, Quaternion as Quaternion4, Vector2 as Vector29 } from "three";
 function entitySpawner(factory) {
   return {
     spawn: async (stage, x, y) => {
@@ -4894,7 +5845,7 @@ function entitySpawner(factory) {
       stage.add(instance);
       return instance;
     },
-    spawnRelative: async (source, stage, offset = new Vector28(0, 1)) => {
+    spawnRelative: async (source, stage, offset = new Vector29(0, 1)) => {
       if (!source.body) {
         console.warn("body missing for entity during spawnRelative");
         return void 0;
@@ -4903,7 +5854,7 @@ function entitySpawner(factory) {
       let rz = source._rotation2DAngle ?? 0;
       try {
         const r = source.body.rotation();
-        const q = new Quaternion3(r.x, r.y, r.z, r.w);
+        const q = new Quaternion4(r.x, r.y, r.z, r.w);
         const e = new Euler2().setFromQuaternion(q, "XYZ");
         rz = e.z;
       } catch {
@@ -4919,7 +5870,7 @@ function entitySpawner(factory) {
 
 // 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) {
@@ -4952,23 +5903,23 @@ init_builder();
 init_builder();
 init_builder();
 import { ColliderDesc as ColliderDesc4 } from "@dimforge/rapier3d-compat";
-import { BoxGeometry as BoxGeometry2, Color as Color11 } from "three";
-import { Vector3 as Vector315 } from "three";
+import { BoxGeometry as BoxGeometry2, Color as Color12 } from "three";
+import { Vector3 as Vector317 } from "three";
 init_create();
 var boxDefaults = {
-  size: new Vector315(1, 1, 1),
-  position: new Vector315(0, 0, 0),
+  size: new Vector317(1, 1, 1),
+  position: new Vector317(0, 0, 0),
   collision: {
     static: false
   },
   material: {
-    color: new Color11("#ffffff"),
+    color: new Color12("#ffffff"),
     shader: "standard"
   }
 };
 var BoxCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const size = options.size || new Vector315(1, 1, 1);
+    const size = options.size || new Vector317(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
     let colliderDesc = ColliderDesc4.cuboid(half.x, half.y, half.z);
     return colliderDesc;
@@ -4976,7 +5927,7 @@ var BoxCollisionBuilder = class extends EntityCollisionBuilder {
 };
 var BoxMeshBuilder = class extends EntityMeshBuilder {
   build(options) {
-    const size = options.size ?? new Vector315(1, 1, 1);
+    const size = options.size ?? new Vector317(1, 1, 1);
     return new BoxGeometry2(size.x, size.y, size.z);
   }
 };
@@ -4985,7 +5936,7 @@ var BoxBuilder = class extends EntityBuilder {
     return new ZylemBox(options);
   }
 };
-var BOX_TYPE = Symbol("Box");
+var BOX_TYPE = /* @__PURE__ */ Symbol("Box");
 var ZylemBox = class _ZylemBox extends GameEntity {
   static type = BOX_TYPE;
   constructor(options) {
@@ -5021,17 +5972,17 @@ init_builder();
 init_builder();
 init_builder();
 import { ColliderDesc as ColliderDesc5 } from "@dimforge/rapier3d-compat";
-import { Color as Color12, SphereGeometry } from "three";
-import { Vector3 as Vector316 } from "three";
+import { Color as Color13, SphereGeometry } from "three";
+import { Vector3 as Vector318 } from "three";
 init_create();
 var sphereDefaults = {
   radius: 1,
-  position: new Vector316(0, 0, 0),
+  position: new Vector318(0, 0, 0),
   collision: {
     static: false
   },
   material: {
-    color: new Color12("#ffffff"),
+    color: new Color13("#ffffff"),
     shader: "standard"
   }
 };
@@ -5053,7 +6004,7 @@ var SphereBuilder = class extends EntityBuilder {
     return new ZylemSphere(options);
   }
 };
-var SPHERE_TYPE = Symbol("Sphere");
+var SPHERE_TYPE = /* @__PURE__ */ Symbol("Sphere");
 var ZylemSphere = class _ZylemSphere extends GameEntity {
   static type = SPHERE_TYPE;
   constructor(options) {
@@ -5089,7 +6040,7 @@ init_builder();
 init_builder();
 init_builder();
 import { ColliderDesc as ColliderDesc6 } from "@dimforge/rapier3d-compat";
-import { Color as Color13, PlaneGeometry, Vector2 as Vector29, Vector3 as Vector317 } from "three";
+import { Color as Color14, PlaneGeometry, Vector2 as Vector210, Vector3 as Vector319 } from "three";
 
 // src/lib/graphics/geometries/XZPlaneGeometry.ts
 import { BufferGeometry as BufferGeometry5, Float32BufferAttribute } from "three";
@@ -5154,25 +6105,25 @@ var XZPlaneGeometry = class _XZPlaneGeometry extends BufferGeometry5 {
 init_create();
 var DEFAULT_SUBDIVISIONS = 4;
 var planeDefaults = {
-  tile: new Vector29(10, 10),
-  repeat: new Vector29(1, 1),
-  position: new Vector317(0, 0, 0),
+  tile: new Vector210(10, 10),
+  repeat: new Vector210(1, 1),
+  position: new Vector319(0, 0, 0),
   collision: {
     static: true
   },
   material: {
-    color: new Color13("#ffffff"),
+    color: new Color14("#ffffff"),
     shader: "standard"
   },
   subdivisions: DEFAULT_SUBDIVISIONS
 };
 var PlaneCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const tile = options.tile ?? new Vector29(1, 1);
+    const tile = options.tile ?? new Vector210(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
-    const size = new Vector317(tile.x, 1, tile.y);
+    const size = new Vector319(tile.x, 1, tile.y);
     const heightData = options._builders?.meshBuilder?.heightData;
-    const scale2 = new Vector317(size.x, 1, size.z);
+    const scale2 = new Vector319(size.x, 1, size.z);
     let colliderDesc = ColliderDesc6.heightfield(
       subdivisions,
       subdivisions,
@@ -5186,9 +6137,9 @@ var PlaneMeshBuilder = class extends EntityMeshBuilder {
   heightData = new Float32Array();
   columnsRows = /* @__PURE__ */ new Map();
   build(options) {
-    const tile = options.tile ?? new Vector29(1, 1);
+    const tile = options.tile ?? new Vector210(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
-    const size = new Vector317(tile.x, 1, tile.y);
+    const size = new Vector319(tile.x, 1, tile.y);
     const geometry = new XZPlaneGeometry(size.x, size.z, subdivisions, subdivisions);
     const vertexGeometry = new PlaneGeometry(size.x, size.z, subdivisions, subdivisions);
     const dx = size.x / subdivisions;
@@ -5230,7 +6181,7 @@ var PlaneBuilder = class extends EntityBuilder {
     return new ZylemPlane(options);
   }
 };
-var PLANE_TYPE = Symbol("Plane");
+var PLANE_TYPE = /* @__PURE__ */ Symbol("Plane");
 var ZylemPlane = class extends GameEntity {
   static type = PLANE_TYPE;
   constructor(options) {
@@ -5257,10 +6208,10 @@ init_builder();
 init_create();
 init_game_state();
 import { ActiveCollisionTypes as ActiveCollisionTypes3, ColliderDesc as ColliderDesc7 } from "@dimforge/rapier3d-compat";
-import { Vector3 as Vector318 } from "three";
+import { Vector3 as Vector320 } from "three";
 var zoneDefaults = {
-  size: new Vector318(1, 1, 1),
-  position: new Vector318(0, 0, 0),
+  size: new Vector320(1, 1, 1),
+  position: new Vector320(0, 0, 0),
   collision: {
     static: true
   },
@@ -5270,7 +6221,7 @@ var zoneDefaults = {
 };
 var ZoneCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const size = options.size || new Vector318(1, 1, 1);
+    const size = options.size || new Vector320(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
     let colliderDesc = ColliderDesc7.cuboid(half.x, half.y, half.z);
     colliderDesc.setSensor(true);
@@ -5283,7 +6234,7 @@ var ZoneBuilder = class extends EntityBuilder {
     return new ZylemZone(options);
   }
 };
-var ZONE_TYPE = Symbol("Zone");
+var ZONE_TYPE = /* @__PURE__ */ Symbol("Zone");
 var ZylemZone = class extends GameEntity {
   static type = ZONE_TYPE;
   _enteredZone = /* @__PURE__ */ new Map();
@@ -5380,7 +6331,7 @@ init_actor();
 init_entity();
 init_builder();
 init_create();
-import { Color as Color14, Group as Group7, Sprite as ThreeSprite3, SpriteMaterial as SpriteMaterial3, CanvasTexture as CanvasTexture2, LinearFilter as LinearFilter2, Vector2 as Vector210, ClampToEdgeWrapping as ClampToEdgeWrapping2, ShaderMaterial as ShaderMaterial4, Mesh as Mesh5, PlaneGeometry as PlaneGeometry2, Vector3 as Vector319 } from "three";
+import { Color as Color15, Group as Group7, Sprite as ThreeSprite3, SpriteMaterial as SpriteMaterial3, CanvasTexture as CanvasTexture2, LinearFilter as LinearFilter2, Vector2 as Vector211, ClampToEdgeWrapping as ClampToEdgeWrapping2, ShaderMaterial as ShaderMaterial4, Mesh as Mesh5, PlaneGeometry as PlaneGeometry2, Vector3 as Vector321 } from "three";
 var rectDefaults = {
   position: void 0,
   width: 120,
@@ -5391,16 +6342,16 @@ var rectDefaults = {
   radius: 0,
   padding: 0,
   stickToViewport: true,
-  screenPosition: new Vector210(24, 24),
+  screenPosition: new Vector211(24, 24),
   zDistance: 1,
-  anchor: new Vector210(0, 0)
+  anchor: new Vector211(0, 0)
 };
 var RectBuilder = class extends EntityBuilder {
   createEntity(options) {
     return new ZylemRect(options);
   }
 };
-var RECT_TYPE = Symbol("Rect");
+var RECT_TYPE = /* @__PURE__ */ Symbol("Rect");
 var ZylemRect = class _ZylemRect extends GameEntity {
   static type = RECT_TYPE;
   _sprite = null;
@@ -5416,10 +6367,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     this.options = { ...rectDefaults, ...options };
     this.group = new Group7();
     this.createSprite();
-    this.lifeCycleDelegate = {
-      setup: [this.rectSetup.bind(this)],
-      update: [this.rectUpdate.bind(this)]
-    };
+    this.prependSetup(this.rectSetup.bind(this));
+    this.prependUpdate(this.rectUpdate.bind(this));
   }
   createSprite() {
     this._canvas = document.createElement("canvas");
@@ -5510,7 +6459,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color14 ? color : new Color14(color);
+    const c = color instanceof Color15 ? color : new Color15(color);
     return `#${c.getHexString()}`;
   }
   rectSetup(params) {
@@ -5544,10 +6493,10 @@ var ZylemRect = class _ZylemRect extends GameEntity {
         const desiredW = Math.max(2, Math.floor(width));
         const desiredH = Math.max(2, Math.floor(height));
         const changed = desiredW !== (this.options.width ?? 0) || desiredH !== (this.options.height ?? 0);
-        this.options.screenPosition = new Vector210(Math.floor(x), Math.floor(y));
+        this.options.screenPosition = new Vector211(Math.floor(x), Math.floor(y));
         this.options.width = desiredW;
         this.options.height = desiredH;
-        this.options.anchor = new Vector210(0, 0);
+        this.options.anchor = new Vector211(0, 0);
         if (changed) {
           this.redrawRect();
         }
@@ -5563,8 +6512,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     const dom = this._cameraRef.renderer.domElement;
     const width = dom.clientWidth;
     const height = dom.clientHeight;
-    const px = (this.options.screenPosition ?? new Vector210(24, 24)).x;
-    const py = (this.options.screenPosition ?? new Vector210(24, 24)).y;
+    const px = (this.options.screenPosition ?? new Vector211(24, 24)).x;
+    const py = (this.options.screenPosition ?? new Vector211(24, 24)).y;
     const zDist = Math.max(1e-3, this.options.zDistance ?? 1);
     let worldHalfW = 1;
     let worldHalfH = 1;
@@ -5595,7 +6544,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
       this._sprite.scale.set(scaleX, scaleY, 1);
       if (this._mesh) this._mesh.scale.set(scaleX, scaleY, 1);
     }
-    const anchor = this.options.anchor ?? new Vector210(0, 0);
+    const anchor = this.options.anchor ?? new Vector211(0, 0);
     const ax = Math.min(100, Math.max(0, anchor.x)) / 100;
     const ay = Math.min(100, Math.max(0, anchor.y)) / 100;
     const offsetX = (0.5 - ax) * scaleX;
@@ -5619,8 +6568,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     }
     if (bounds.world) {
       const { left, right, top, bottom, z = 0 } = bounds.world;
-      const tl = this.worldToScreen(new Vector319(left, top, z));
-      const br = this.worldToScreen(new Vector319(right, bottom, z));
+      const tl = this.worldToScreen(new Vector321(left, top, z));
+      const br = this.worldToScreen(new Vector321(right, bottom, z));
       const x = Math.min(tl.x, br.x);
       const y = Math.min(tl.y, br.y);
       const width = Math.abs(br.x - tl.x);
@@ -6089,41 +7038,41 @@ function movementSequence2D(opts, onStep) {
 }
 
 // src/lib/actions/capabilities/moveable.ts
-import { Vector3 as Vector320 } from "three";
+import { Vector3 as Vector322 } from "three";
 function moveX(entity, delta) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(delta, currentVelocity.y, currentVelocity.z);
+  const newVelocity = new Vector322(delta, currentVelocity.y, currentVelocity.z);
   entity.body.setLinvel(newVelocity, true);
 }
 function moveY(entity, delta) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(currentVelocity.x, delta, currentVelocity.z);
+  const newVelocity = new Vector322(currentVelocity.x, delta, currentVelocity.z);
   entity.body.setLinvel(newVelocity, true);
 }
 function moveZ(entity, delta) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(currentVelocity.x, currentVelocity.y, delta);
+  const newVelocity = new Vector322(currentVelocity.x, currentVelocity.y, delta);
   entity.body.setLinvel(newVelocity, true);
 }
 function moveXY(entity, deltaX, deltaY) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(deltaX, deltaY, currentVelocity.z);
+  const newVelocity = new Vector322(deltaX, deltaY, currentVelocity.z);
   entity.body.setLinvel(newVelocity, true);
 }
 function moveXZ(entity, deltaX, deltaZ) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(deltaX, currentVelocity.y, deltaZ);
+  const newVelocity = new Vector322(deltaX, currentVelocity.y, deltaZ);
   entity.body.setLinvel(newVelocity, true);
 }
 function move(entity, vector) {
   if (!entity.body) return;
   const currentVelocity = entity.body.linvel();
-  const newVelocity = new Vector320(
+  const newVelocity = new Vector322(
     currentVelocity.x + vector.x,
     currentVelocity.y + vector.y,
     currentVelocity.z + vector.z
@@ -6132,7 +7081,7 @@ function move(entity, vector) {
 }
 function resetVelocity(entity) {
   if (!entity.body) return;
-  entity.body.setLinvel(new Vector320(0, 0, 0), true);
+  entity.body.setLinvel(new Vector322(0, 0, 0), true);
   entity.body.setLinearDamping(5);
 }
 function moveForwardXY(entity, delta, rotation2DAngle) {
@@ -6262,14 +7211,14 @@ function makeMoveable(entity) {
 }
 
 // src/lib/actions/capabilities/rotatable.ts
-import { Euler as Euler3, Vector3 as Vector321, MathUtils, Quaternion as Quaternion4 } from "three";
+import { Euler as Euler3, Vector3 as Vector323, MathUtils, Quaternion as Quaternion5 } from "three";
 function rotateInDirection(entity, moveVector) {
   if (!entity.body) return;
   const rotate = Math.atan2(-moveVector.x, moveVector.z);
   rotateYEuler(entity, rotate);
 }
 function rotateYEuler(entity, amount) {
-  rotateEuler(entity, new Vector321(0, -amount, 0));
+  rotateEuler(entity, new Vector323(0, -amount, 0));
 }
 function rotateEuler(entity, rotation2) {
   if (!entity.group) return;
@@ -6317,7 +7266,7 @@ function setRotationDegreesZ(entity, z) {
 }
 function setRotation(entity, x, y, z) {
   if (!entity.body) return;
-  const quat = new Quaternion4().setFromEuler(new Euler3(x, y, z));
+  const quat = new Quaternion5().setFromEuler(new Euler3(x, y, z));
   entity.body.setRotation({ w: quat.w, x: quat.x, y: quat.y, z: quat.z }, true);
 }
 function setRotationDegrees(entity, x, y, z) {
@@ -6515,10 +7464,13 @@ function variableChanges(keys, callback) {
 // src/api/main.ts
 init_game_state();
 init_stage_state();
+init_debug_state();
 
 // src/web-components/zylem-game.ts
+init_debug_state();
 var ZylemGameElement = class extends HTMLElement {
   _game = null;
+  _state = {};
   container;
   constructor() {
     super();
@@ -6530,6 +7482,9 @@ var ZylemGameElement = class extends HTMLElement {
     this.shadowRoot.appendChild(this.container);
   }
   set game(game) {
+    if (this._game) {
+      this._game.dispose();
+    }
     this._game = game;
     game.options.push({ container: this.container });
     game.start();
@@ -6537,6 +7492,35 @@ var ZylemGameElement = class extends HTMLElement {
   get game() {
     return this._game;
   }
+  set state(value) {
+    this._state = value;
+    this.syncDebugState();
+    this.syncToolbarState();
+  }
+  get state() {
+    return this._state;
+  }
+  /**
+   * Sync the web component's state with the game-lib's internal debug state
+   */
+  syncDebugState() {
+    const debugFlag = this._state.gameState?.debugFlag;
+    if (debugFlag !== void 0) {
+      debugState.enabled = debugFlag;
+    }
+  }
+  /**
+   * Sync toolbar state with game-lib's debug state
+   */
+  syncToolbarState() {
+    const { tool, paused } = this._state.toolbarState ?? {};
+    if (tool !== void 0) {
+      setDebugTool(tool);
+    }
+    if (paused !== void 0) {
+      setPaused(paused);
+    }
+  }
   disconnectedCallback() {
     if (this._game) {
       this._game.dispose();
@@ -6545,22 +7529,36 @@ var ZylemGameElement = class extends HTMLElement {
   }
 };
 customElements.define("zylem-game", ZylemGameElement);
+
+// src/lib/types/entity-type-map.ts
+init_actor();
 export {
+  ACTOR_TYPE,
+  BOX_TYPE,
   Game,
   Howl,
+  PLANE_TYPE,
   Perspectives,
   RAPIER2 as RAPIER,
+  RECT_TYPE,
+  SPHERE_TYPE,
+  SPRITE_TYPE,
+  StageManager,
+  TEXT_TYPE,
   THREE2 as THREE,
+  ZONE_TYPE,
   ZylemBox,
   ZylemGameElement,
   actor,
   boundary2d,
   box,
   camera,
+  clearGlobalSubscriptions,
   createGame,
   createGlobal,
   createStage,
   createVariable,
+  debugState,
   destroy,
   entitySpawner,
   gameConfig,
@@ -6588,10 +7586,13 @@ export {
   ricochetSound,
   rotatable,
   rotateInDirection,
+  setDebugTool,
   setGlobal,
+  setPaused,
   setVariable,
   sphere,
   sprite,
+  stageState2 as stageState,
   text,
   variableChange,
   variableChanges,