@zylem/game-lib 0.6.0 → 0.6.3

package/dist/stage.js

@@ -1,6 +1,6 @@
 // src/lib/stage/zylem-stage.ts
-import { addComponent, addEntity, createWorld as createECS, removeEntity } from "bitecs";
-import { Color as Color7, Vector3 as Vector311 } from "three";
+import { addEntity, createWorld as createECS, removeEntity } from "bitecs";
+import { Color as Color9, Vector3 as Vector318 } from "three";
 
 // src/lib/collision/world.ts
 import RAPIER from "@dimforge/rapier3d-compat";
@@ -61,11 +61,11 @@ function getGlobals() {
 }
 
 // src/lib/entities/actor.ts
-import { ActiveCollisionTypes, ColliderDesc } from "@dimforge/rapier3d-compat";
-import { SkinnedMesh, Group as Group2, Vector3 } from "three";
+import { ActiveCollisionTypes as ActiveCollisionTypes2, ColliderDesc as ColliderDesc2 } from "@dimforge/rapier3d-compat";
+import { MeshStandardMaterial as MeshStandardMaterial2, Group as Group2, Vector3 as Vector37 } from "three";
 
 // src/lib/entities/entity.ts
-import { ShaderMaterial } from "three";
+import { Mesh, ShaderMaterial, Group } from "three";
 
 // src/lib/systems/transformable.system.ts
 import {
@@ -152,6 +152,9 @@ var BaseNode = class _BaseNode {
   markedForRemoval = false;
   /**
    * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+   * Uses `any` for the type parameter to avoid invariance issues when subclasses
+   * are assigned to BaseNode references. Type safety is enforced by the public
+   * onSetup/onUpdate/etc. methods which are typed with `this`.
    */
   lifecycleCallbacks = {
     setup: [],
@@ -265,12 +268,16 @@ var BaseNode = class _BaseNode {
     if (typeof this._update === "function") {
       this._update(params);
     }
+    if (typeof this._tickActions === "function") {
+      this._tickActions(params.delta);
+    }
     for (const callback of this.lifecycleCallbacks.update) {
       callback(params);
     }
     this.children.forEach((child) => child.nodeUpdate(params));
   }
   nodeDestroy(params) {
+    if (this.markedForRemoval) return;
     this.children.forEach((child) => child.nodeDestroy(params));
     for (const callback of this.lifecycleCallbacks.destroy) {
       callback(params);
@@ -279,6 +286,12 @@ var BaseNode = class _BaseNode {
       this._destroy(params);
     }
     this.markedForRemoval = true;
+    for (const callback of this.lifecycleCallbacks.cleanup) {
+      callback(params);
+    }
+    if (typeof this._cleanup === "function") {
+      this._cleanup(params);
+    }
   }
   async nodeLoaded(params) {
     if (typeof this._loaded === "function") {
@@ -288,12 +301,13 @@ var BaseNode = class _BaseNode {
       callback(params);
     }
   }
-  async nodeCleanup(params) {
+  nodeCleanup(params) {
+    this.children.forEach((child) => child.nodeCleanup?.(params));
     for (const callback of this.lifecycleCallbacks.cleanup) {
       callback(params);
     }
     if (typeof this._cleanup === "function") {
-      await this._cleanup(params);
+      this._cleanup(params);
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
@@ -307,6 +321,422 @@ var BaseNode = class _BaseNode {
   }
 };
 
+// ../../node_modules/.pnpm/mitt@3.0.1/node_modules/mitt/dist/mitt.mjs
+function mitt_default(n) {
+  return { all: n = n || /* @__PURE__ */ new Map(), on: function(t, e) {
+    var i = n.get(t);
+    i ? i.push(e) : n.set(t, [e]);
+  }, off: function(t, e) {
+    var i = n.get(t);
+    i && (e ? i.splice(i.indexOf(e) >>> 0, 1) : n.set(t, []));
+  }, emit: function(t, e) {
+    var i = n.get(t);
+    i && i.slice().map(function(n2) {
+      n2(e);
+    }), (i = n.get("*")) && i.slice().map(function(n2) {
+      n2(t, e);
+    });
+  } };
+}
+
+// src/lib/events/event-emitter-delegate.ts
+var EventEmitterDelegate = class {
+  emitter;
+  unsubscribes = [];
+  constructor() {
+    this.emitter = mitt_default();
+  }
+  /**
+   * Dispatch an event to all listeners.
+   */
+  dispatch(event, payload) {
+    this.emitter.emit(event, payload);
+  }
+  /**
+   * Subscribe to an event. Returns an unsubscribe function.
+   */
+  listen(event, handler) {
+    this.emitter.on(event, handler);
+    const unsub = () => this.emitter.off(event, handler);
+    this.unsubscribes.push(unsub);
+    return unsub;
+  }
+  /**
+   * Subscribe to all events.
+   */
+  listenAll(handler) {
+    this.emitter.on("*", handler);
+    const unsub = () => this.emitter.off("*", handler);
+    this.unsubscribes.push(unsub);
+    return unsub;
+  }
+  /**
+   * Clean up all subscriptions.
+   */
+  dispose() {
+    this.unsubscribes.forEach((fn) => fn());
+    this.unsubscribes = [];
+    this.emitter.all.clear();
+  }
+};
+
+// src/lib/events/zylem-events.ts
+var zylemEventBus = mitt_default();
+
+// src/lib/actions/capabilities/transform-store.ts
+import { proxy as proxy2 } from "valtio";
+function createTransformStore(initial) {
+  const defaultState = {
+    position: { x: 0, y: 0, z: 0 },
+    rotation: { x: 0, y: 0, z: 0, w: 1 },
+    velocity: { x: 0, y: 0, z: 0 },
+    angularVelocity: { x: 0, y: 0, z: 0 },
+    dirty: {
+      position: false,
+      rotation: false,
+      velocity: false,
+      angularVelocity: false
+    }
+  };
+  return proxy2({
+    ...defaultState,
+    ...initial,
+    // Ensure dirty flags are properly initialized even if partial initial state
+    dirty: {
+      ...defaultState.dirty,
+      ...initial?.dirty
+    }
+  });
+}
+
+// src/lib/actions/capabilities/moveable.ts
+import { Vector3 } from "three";
+function moveX(entity, delta) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.x = delta;
+  entity.transformStore.dirty.velocity = true;
+}
+function moveY(entity, delta) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.y = delta;
+  entity.transformStore.dirty.velocity = true;
+}
+function moveZ(entity, delta) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.z = delta;
+  entity.transformStore.dirty.velocity = true;
+}
+function moveXY(entity, deltaX, deltaY) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.x = deltaX;
+  entity.transformStore.velocity.y = deltaY;
+  entity.transformStore.dirty.velocity = true;
+}
+function moveXZ(entity, deltaX, deltaZ) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.x = deltaX;
+  entity.transformStore.velocity.z = deltaZ;
+  entity.transformStore.dirty.velocity = true;
+}
+function move(entity, vector) {
+  if (!entity.transformStore) return;
+  entity.transformStore.velocity.x += vector.x;
+  entity.transformStore.velocity.y += vector.y;
+  entity.transformStore.velocity.z += vector.z;
+  entity.transformStore.dirty.velocity = true;
+}
+function resetVelocity(entity) {
+  if (!entity.body) return;
+  entity.body.setLinvel(new Vector3(0, 0, 0), true);
+  entity.body.setLinearDamping(5);
+}
+function moveForwardXY(entity, delta, rotation2DAngle) {
+  const deltaX = Math.sin(-rotation2DAngle) * delta;
+  const deltaY = Math.cos(-rotation2DAngle) * delta;
+  moveXY(entity, deltaX, deltaY);
+}
+function getPosition(entity) {
+  if (!entity.body) return null;
+  return entity.body.translation();
+}
+function getVelocity(entity) {
+  if (!entity.body) return null;
+  return entity.body.linvel();
+}
+function setPosition(entity, x, y, z) {
+  if (!entity.body) return;
+  entity.body.setTranslation({ x, y, z }, true);
+}
+function setPositionX(entity, x) {
+  if (!entity.body) return;
+  const { y, z } = entity.body.translation();
+  entity.body.setTranslation({ x, y, z }, true);
+}
+function setPositionY(entity, y) {
+  if (!entity.body) return;
+  const { x, z } = entity.body.translation();
+  entity.body.setTranslation({ x, y, z }, true);
+}
+function setPositionZ(entity, z) {
+  if (!entity.body) return;
+  const { x, y } = entity.body.translation();
+  entity.body.setTranslation({ x, y, z }, true);
+}
+function wrapAroundXY(entity, boundsX, boundsY) {
+  const position2 = getPosition(entity);
+  if (!position2) return;
+  const { x, y } = position2;
+  const newX = x > boundsX ? -boundsX : x < -boundsX ? boundsX : x;
+  const newY = y > boundsY ? -boundsY : y < -boundsY ? boundsY : y;
+  if (newX !== x || newY !== y) {
+    setPosition(entity, newX, newY, 0);
+  }
+}
+function wrapAround3D(entity, boundsX, boundsY, boundsZ) {
+  const position2 = getPosition(entity);
+  if (!position2) return;
+  const { x, y, z } = position2;
+  const newX = x > boundsX ? -boundsX : x < -boundsX ? boundsX : x;
+  const newY = y > boundsY ? -boundsY : y < -boundsY ? boundsY : y;
+  const newZ = z > boundsZ ? -boundsZ : z < -boundsZ ? boundsZ : z;
+  if (newX !== x || newY !== y || newZ !== z) {
+    setPosition(entity, newX, newY, newZ);
+  }
+}
+function makeMoveable(entity) {
+  const moveable = entity;
+  if (!moveable.transformStore) {
+    moveable.transformStore = createTransformStore();
+  }
+  moveable.moveX = (delta) => moveX(entity, delta);
+  moveable.moveY = (delta) => moveY(entity, delta);
+  moveable.moveZ = (delta) => moveZ(entity, delta);
+  moveable.moveXY = (deltaX, deltaY) => moveXY(entity, deltaX, deltaY);
+  moveable.moveXZ = (deltaX, deltaZ) => moveXZ(entity, deltaX, deltaZ);
+  moveable.move = (vector) => move(entity, vector);
+  moveable.resetVelocity = () => resetVelocity(entity);
+  moveable.moveForwardXY = (delta, rotation2DAngle) => moveForwardXY(entity, delta, rotation2DAngle);
+  moveable.getPosition = () => getPosition(entity);
+  moveable.getVelocity = () => getVelocity(entity);
+  moveable.setPosition = (x, y, z) => setPosition(entity, x, y, z);
+  moveable.setPositionX = (x) => setPositionX(entity, x);
+  moveable.setPositionY = (y) => setPositionY(entity, y);
+  moveable.setPositionZ = (z) => setPositionZ(entity, z);
+  moveable.wrapAroundXY = (boundsX, boundsY) => wrapAroundXY(entity, boundsX, boundsY);
+  moveable.wrapAround3D = (boundsX, boundsY, boundsZ) => wrapAround3D(entity, boundsX, boundsY, boundsZ);
+  return moveable;
+}
+
+// src/lib/actions/capabilities/rotatable.ts
+import { Euler, Vector3 as Vector32, MathUtils, Quaternion as Quaternion2 } 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 Vector32(0, -amount, 0));
+}
+function rotateEuler(entity, rotation2) {
+  if (!entity.group) return;
+  const euler = new Euler(rotation2.x, rotation2.y, rotation2.z);
+  entity.group.setRotationFromEuler(euler);
+}
+function rotateY(entity, delta) {
+  if (!entity.transformStore) return;
+  const halfAngle = delta / 2;
+  const deltaW = Math.cos(halfAngle);
+  const deltaY = Math.sin(halfAngle);
+  const q = entity.transformStore.rotation;
+  const newW = q.w * deltaW - q.y * deltaY;
+  const newX = q.x * deltaW + q.z * deltaY;
+  const newY = q.y * deltaW + q.w * deltaY;
+  const newZ = q.z * deltaW - q.x * deltaY;
+  entity.transformStore.rotation.w = newW;
+  entity.transformStore.rotation.x = newX;
+  entity.transformStore.rotation.y = newY;
+  entity.transformStore.rotation.z = newZ;
+  entity.transformStore.dirty.rotation = true;
+}
+function rotateX(entity, delta) {
+  if (!entity.transformStore) return;
+  const halfAngle = delta / 2;
+  const deltaW = Math.cos(halfAngle);
+  const deltaX = Math.sin(halfAngle);
+  const q = entity.transformStore.rotation;
+  const newW = q.w * deltaW - q.x * deltaX;
+  const newX = q.x * deltaW + q.w * deltaX;
+  const newY = q.y * deltaW + q.z * deltaX;
+  const newZ = q.z * deltaW - q.y * deltaX;
+  entity.transformStore.rotation.w = newW;
+  entity.transformStore.rotation.x = newX;
+  entity.transformStore.rotation.y = newY;
+  entity.transformStore.rotation.z = newZ;
+  entity.transformStore.dirty.rotation = true;
+}
+function rotateZ(entity, delta) {
+  if (!entity.transformStore) return;
+  const halfAngle = delta / 2;
+  const deltaW = Math.cos(halfAngle);
+  const deltaZ = Math.sin(halfAngle);
+  const q = entity.transformStore.rotation;
+  const newW = q.w * deltaW - q.z * deltaZ;
+  const newX = q.x * deltaW - q.y * deltaZ;
+  const newY = q.y * deltaW + q.x * deltaZ;
+  const newZ = q.z * deltaW + q.w * deltaZ;
+  entity.transformStore.rotation.w = newW;
+  entity.transformStore.rotation.x = newX;
+  entity.transformStore.rotation.y = newY;
+  entity.transformStore.rotation.z = newZ;
+  entity.transformStore.dirty.rotation = true;
+}
+function setRotationY(entity, y) {
+  if (!entity.transformStore) return;
+  const halfAngle = y / 2;
+  const w = Math.cos(halfAngle);
+  const yComponent = Math.sin(halfAngle);
+  entity.transformStore.rotation.w = w;
+  entity.transformStore.rotation.x = 0;
+  entity.transformStore.rotation.y = yComponent;
+  entity.transformStore.rotation.z = 0;
+  entity.transformStore.dirty.rotation = true;
+}
+function setRotationDegreesY(entity, y) {
+  if (!entity.body) return;
+  setRotationY(entity, MathUtils.degToRad(y));
+}
+function setRotationX(entity, x) {
+  if (!entity.transformStore) return;
+  const halfAngle = x / 2;
+  const w = Math.cos(halfAngle);
+  const xComponent = Math.sin(halfAngle);
+  entity.transformStore.rotation.w = w;
+  entity.transformStore.rotation.x = xComponent;
+  entity.transformStore.rotation.y = 0;
+  entity.transformStore.rotation.z = 0;
+  entity.transformStore.dirty.rotation = true;
+}
+function setRotationDegreesX(entity, x) {
+  if (!entity.body) return;
+  setRotationX(entity, MathUtils.degToRad(x));
+}
+function setRotationZ(entity, z) {
+  if (!entity.transformStore) return;
+  const halfAngle = z / 2;
+  const w = Math.cos(halfAngle);
+  const zComponent = Math.sin(halfAngle);
+  entity.transformStore.rotation.w = w;
+  entity.transformStore.rotation.x = 0;
+  entity.transformStore.rotation.y = 0;
+  entity.transformStore.rotation.z = zComponent;
+  entity.transformStore.dirty.rotation = true;
+}
+function setRotationDegreesZ(entity, z) {
+  if (!entity.body) return;
+  setRotationZ(entity, MathUtils.degToRad(z));
+}
+function setRotation(entity, x, y, z) {
+  if (!entity.transformStore) return;
+  const quat = new Quaternion2().setFromEuler(new Euler(x, y, z));
+  entity.transformStore.rotation.w = quat.w;
+  entity.transformStore.rotation.x = quat.x;
+  entity.transformStore.rotation.y = quat.y;
+  entity.transformStore.rotation.z = quat.z;
+  entity.transformStore.dirty.rotation = true;
+}
+function setRotationDegrees(entity, x, y, z) {
+  if (!entity.body) return;
+  setRotation(entity, MathUtils.degToRad(x), MathUtils.degToRad(y), MathUtils.degToRad(z));
+}
+function getRotation(entity) {
+  if (!entity.body) return null;
+  return entity.body.rotation();
+}
+function makeRotatable(entity) {
+  const rotatableEntity = entity;
+  if (!rotatableEntity.transformStore) {
+    rotatableEntity.transformStore = createTransformStore();
+  }
+  rotatableEntity.rotateInDirection = (moveVector) => rotateInDirection(entity, moveVector);
+  rotatableEntity.rotateYEuler = (amount) => rotateYEuler(entity, amount);
+  rotatableEntity.rotateEuler = (rotation2) => rotateEuler(entity, rotation2);
+  rotatableEntity.rotateX = (delta) => rotateX(entity, delta);
+  rotatableEntity.rotateY = (delta) => rotateY(entity, delta);
+  rotatableEntity.rotateZ = (delta) => rotateZ(entity, delta);
+  rotatableEntity.setRotationY = (y) => setRotationY(entity, y);
+  rotatableEntity.setRotationX = (x) => setRotationX(entity, x);
+  rotatableEntity.setRotationZ = (z) => setRotationZ(entity, z);
+  rotatableEntity.setRotationDegreesY = (y) => setRotationDegreesY(entity, y);
+  rotatableEntity.setRotationDegreesX = (x) => setRotationDegreesX(entity, x);
+  rotatableEntity.setRotationDegreesZ = (z) => setRotationDegreesZ(entity, z);
+  rotatableEntity.setRotationDegrees = (x, y, z) => setRotationDegrees(entity, x, y, z);
+  rotatableEntity.setRotation = (x, y, z) => setRotation(entity, x, y, z);
+  rotatableEntity.getRotation = () => getRotation(entity);
+  return rotatableEntity;
+}
+
+// src/lib/actions/capabilities/transformable.ts
+function makeTransformable(entity) {
+  const withMovement = makeMoveable(entity);
+  const withRotation = makeRotatable(withMovement);
+  return withRotation;
+}
+
+// src/lib/entities/parts/collision-factories.ts
+import {
+  ActiveCollisionTypes,
+  ColliderDesc,
+  RigidBodyDesc,
+  RigidBodyType
+} from "@dimforge/rapier3d-compat";
+import { Vector3 as Vector33 } from "three";
+function isCollisionComponent(obj) {
+  return obj && obj.__kind === "collision";
+}
+
+// src/lib/entities/common.ts
+import { Color, Vector3 as Vector34 } from "three";
+
+// src/lib/graphics/shaders/vertex/object.shader.ts
+var objectVertexShader = `
+uniform vec2 uvScale;
+varying vec2 vUv;
+
+void main() {
+	vUv = uv;
+	vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+	gl_Position = projectionMatrix * mvPosition;
+}
+`;
+
+// src/lib/graphics/shaders/standard.shader.ts
+var fragment = `
+uniform sampler2D tDiffuse;
+varying vec2 vUv;
+
+void main() {
+	vec4 texel = texture2D( tDiffuse, vUv );
+
+	gl_FragColor = texel;
+}
+`;
+var standardShader = {
+  vertex: objectVertexShader,
+  fragment
+};
+
+// src/lib/entities/common.ts
+var commonDefaults = {
+  position: new Vector34(0, 0, 0),
+  material: {
+    color: new Color("#ffffff"),
+    shader: standardShader
+  },
+  collision: {
+    static: false
+  }
+};
+
 // src/lib/entities/entity.ts
 var GameEntity = class extends BaseNode {
   behaviors = [];
@@ -318,20 +748,187 @@ var GameEntity = class extends BaseNode {
   colliderDesc;
   collider;
   custom = {};
+  // Compound entity support: multiple colliders and meshes
+  /** All collider descriptions for this entity (including primary) */
+  colliderDescs = [];
+  /** All colliders attached to this entity's rigid body */
+  colliders = [];
+  /** Additional meshes for compound visual entities (added via add()) */
+  compoundMeshes = [];
   debugInfo = {};
   debugMaterial;
   collisionDelegate = {
     collision: []
   };
   collisionType;
-  behaviorCallbackMap = {
-    setup: [],
-    update: [],
-    destroy: [],
-    collision: []
-  };
+  // Instancing support
+  /** Batch key for instanced rendering (null if not instanced) */
+  batchKey = null;
+  /** Index within the instanced mesh batch */
+  instanceId = -1;
+  /** Whether this entity uses instanced rendering */
+  isInstanced = false;
+  // Event delegate for dispatch/listen API
+  eventDelegate = new EventEmitterDelegate();
+  // Behavior references (new ECS pattern)
+  behaviorRefs = [];
+  // Transform store for batched physics updates (auto-created in create())
+  transformStore;
+  // Movement & rotation methods are assigned at runtime by makeTransformable.
+  // The `implements` clause above ensures the type contract; declarations below
+  // satisfy the compiler while the constructor fills them in.
+  moveX;
+  moveY;
+  moveZ;
+  moveXY;
+  moveXZ;
+  move;
+  resetVelocity;
+  moveForwardXY;
+  getPosition;
+  getVelocity;
+  setPosition;
+  setPositionX;
+  setPositionY;
+  setPositionZ;
+  wrapAroundXY;
+  wrapAround3D;
+  rotateInDirection;
+  rotateYEuler;
+  rotateEuler;
+  rotateX;
+  rotateY;
+  rotateZ;
+  setRotationY;
+  setRotationX;
+  setRotationZ;
+  setRotationDegrees;
+  setRotationDegreesY;
+  setRotationDegreesX;
+  setRotationDegreesZ;
+  setRotation;
+  getRotation;
   constructor() {
     super();
+    this.transformStore = createTransformStore();
+    makeTransformable(this);
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Composable add() - accepts Mesh, CollisionComponent, or child entities
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Add meshes, collision components, or child entities to this entity.
+   * Supports fluent chaining: `entity.add(boxMesh()).add(boxCollision())`.
+   *
+   * - `Mesh`: First mesh becomes the primary mesh; subsequent meshes are
+   *   compound meshes grouped together.
+   * - `CollisionComponent`: First sets bodyDesc + colliderDesc; subsequent
+   *   add extra colliders to the same rigid body.
+   * - `NodeInterface`: Added as a child entity (delegates to BaseNode.add).
+   */
+  add(...components) {
+    for (const component of components) {
+      if (component instanceof Mesh) {
+        this.addMeshComponent(component);
+      } else if (isCollisionComponent(component)) {
+        this.addCollisionComponent(component);
+      } else {
+        super.add(component);
+      }
+    }
+    return this;
+  }
+  addMeshComponent(mesh) {
+    if (!this.mesh) {
+      this.mesh = mesh;
+      if (!this.materials) {
+        this.materials = [];
+      }
+      if (mesh.material) {
+        const mat = mesh.material;
+        if (Array.isArray(mat)) {
+          this.materials.push(...mat);
+        } else {
+          this.materials.push(mat);
+        }
+      }
+    } else {
+      this.compoundMeshes.push(mesh);
+      if (!this.group) {
+        this.group = new Group();
+        this.group.add(this.mesh);
+      }
+      this.group.add(mesh);
+    }
+  }
+  addCollisionComponent(collision) {
+    if (!this.bodyDesc) {
+      this.bodyDesc = collision.bodyDesc;
+      this.colliderDesc = collision.colliderDesc;
+      this.colliderDescs.push(collision.colliderDesc);
+      const pos = this.options?.position ?? { x: 0, y: 0, z: 0 };
+      this.bodyDesc.setTranslation(pos.x, pos.y, pos.z);
+    } else {
+      this.colliderDescs.push(collision.colliderDesc);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Actions API -- entity-scoped, self-contained stateful actions
+  // ─────────────────────────────────────────────────────────────────────────────
+  _actions = [];
+  /**
+   * Run a fire-and-forget action. Auto-removed when done.
+   * @example `me.runAction(moveBy({ x: 10, duration: 0.3 }))`
+   */
+  runAction(action) {
+    this._actions.push(action);
+    return action;
+  }
+  /**
+   * Register a persistent action (throttle, onPress). Not removed when done.
+   * @example `const press = entity.action(onPress())`
+   */
+  action(action) {
+    action.persistent = true;
+    this._actions.push(action);
+    return action;
+  }
+  /**
+   * Tick all registered actions. Called automatically before user onUpdate callbacks.
+   *
+   * Resets velocity/angularVelocity accumulation before ticking so that
+   * actions can compose via `+=` without cross-frame build-up.
+   * (The existing move helpers like `moveXY` use `=` which doesn't accumulate,
+   * but action composition needs additive writes on a clean slate each frame.)
+   */
+  _tickActions(delta) {
+    if (this._actions.length === 0) return;
+    const store = this.transformStore;
+    store.velocity.x = 0;
+    store.velocity.y = 0;
+    store.velocity.z = 0;
+    store.dirty.velocity = false;
+    store.angularVelocity.x = 0;
+    store.angularVelocity.y = 0;
+    store.angularVelocity.z = 0;
+    store.dirty.angularVelocity = false;
+    for (let i = this._actions.length - 1; i >= 0; i--) {
+      const act = this._actions[i];
+      act.tick(this, delta);
+      if (act.done && !act.persistent) {
+        this._actions.splice(i, 1);
+      }
+    }
+    if (this._actions.length === 0) {
+      store.velocity.x = 0;
+      store.velocity.y = 0;
+      store.velocity.z = 0;
+      store.dirty.velocity = false;
+      store.angularVelocity.x = 0;
+      store.angularVelocity.y = 0;
+      store.angularVelocity.z = 0;
+      store.dirty.angularVelocity = false;
+    }
   }
   create() {
     const { position: setupPosition } = this.options;
@@ -353,36 +950,88 @@ var GameEntity = class extends BaseNode {
     return this;
   }
   /**
-   * Entity-specific setup - runs behavior callbacks
+   * Use a behavior on this entity via typed descriptor.
+   * Behaviors will be auto-registered as systems when the entity is spawned.
+   * @param descriptor The behavior descriptor (import from behaviors module)
+   * @param options Optional overrides for the behavior's default options
+   * @returns BehaviorHandle with behavior-specific methods for lazy FSM access
+   */
+  use(descriptor, options) {
+    const behaviorRef = {
+      descriptor,
+      options: { ...descriptor.defaultOptions, ...options }
+    };
+    this.behaviorRefs.push(behaviorRef);
+    const baseHandle = {
+      getFSM: () => behaviorRef.fsm ?? null,
+      getOptions: () => behaviorRef.options,
+      ref: behaviorRef
+    };
+    const customMethods = descriptor.createHandle?.(behaviorRef) ?? {};
+    return {
+      ...baseHandle,
+      ...customMethods
+    };
+  }
+  /**
+   * Get all behavior references attached to this entity.
+   * Used by the stage to auto-register required systems.
+   */
+  getBehaviorRefs() {
+    return this.behaviorRefs;
+  }
+  /**
+   * Entity-specific setup - resets actions for a fresh stage session.
    * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
    */
   _setup(params) {
-    this.behaviorCallbackMap.setup.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
+    for (let i = this._actions.length - 1; i >= 0; i--) {
+      const act = this._actions[i];
+      if (act.done && !act.persistent) {
+        this._actions.splice(i, 1);
+      } else {
+        act.reset();
+      }
+    }
   }
   async _loaded(_params) {
   }
   /**
-   * Entity-specific update - updates materials and runs behavior callbacks
+   * Entity-specific update - updates materials.
+   * Transform changes are applied by the stage after all update callbacks complete.
    * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
    */
   _update(params) {
     this.updateMaterials(params);
-    this.behaviorCallbackMap.update.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
   }
   /**
-   * Entity-specific destroy - runs behavior callbacks
-   * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+   * Entity-specific destroy -- reserved for consumer game logic.
+   * Engine-internal resource disposal runs in _cleanup() instead.
    */
   _destroy(params) {
-    this.behaviorCallbackMap.destroy.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
   }
-  async _cleanup(_params) {
+  /**
+   * Engine-internal resource cleanup -- runs automatically after destroy.
+   * Disposes GPU/DOM resources (meshes, materials, debug material).
+   *
+   * Note: actions, collision callbacks, and behavior refs are intentionally
+   * NOT cleared here -- they are registered by consumer code at module level
+   * and must persist across stage reloads. Actions are reset in _setup().
+   */
+  _cleanup(_params) {
+    this.disposeEvents();
+    for (const m of this.compoundMeshes) {
+      m.geometry?.dispose();
+      if (Array.isArray(m.material)) {
+        m.material.forEach((mat) => mat.dispose());
+      } else {
+        m.material?.dispose();
+      }
+    }
+    this.compoundMeshes.length = 0;
+    this.debugMaterial?.dispose();
+    this.debugMaterial = void 0;
+    this.group?.removeFromParent();
   }
   _collision(other, globals) {
     if (this.collisionDelegate.collision?.length) {
@@ -391,25 +1040,6 @@ var GameEntity = class extends BaseNode {
         callback({ entity: this, other, globals });
       });
     }
-    this.behaviorCallbackMap.collision.forEach((callback) => {
-      callback({ entity: this, other, globals });
-    });
-  }
-  addBehavior(behaviorCallback) {
-    const handler = behaviorCallback.handler;
-    if (handler) {
-      this.behaviorCallbackMap[behaviorCallback.type].push(handler);
-    }
-    return this;
-  }
-  addBehaviors(behaviorCallbacks) {
-    behaviorCallbacks.forEach((callback) => {
-      const handler = callback.handler;
-      if (handler) {
-        this.behaviorCallbackMap[callback.type].push(handler);
-      }
-    });
-    return this;
   }
   updateMaterials(params) {
     if (!this.materials?.length) {
@@ -430,99 +1060,754 @@ var GameEntity = class extends BaseNode {
     info.eid = this.eid.toString();
     return info;
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Events API
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Dispatch an event from this entity.
+   * Events are emitted both locally and to the global event bus.
+   */
+  dispatch(event, payload) {
+    this.eventDelegate.dispatch(event, payload);
+    zylemEventBus.emit(event, payload);
+  }
+  /**
+   * Listen for events on this entity instance.
+   * @returns Unsubscribe function
+   */
+  listen(event, handler) {
+    return this.eventDelegate.listen(event, handler);
+  }
+  /**
+   * Clean up entity event subscriptions.
+   */
+  disposeEvents() {
+    this.eventDelegate.dispose();
+  }
 };
 
-// src/lib/core/entity-asset-loader.ts
-import { FBXLoader } from "three/addons/loaders/FBXLoader.js";
+// src/lib/core/asset-manager.ts
+import { LoadingManager, Cache } from "three";
+
+// src/lib/core/loaders/texture-loader.ts
+import { TextureLoader, RepeatWrapping } from "three";
+var TextureLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new TextureLoader();
+  }
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ["png", "jpg", "jpeg", "gif", "webp", "bmp", "tga"].includes(ext || "");
+  }
+  async load(url, options) {
+    const texture = await this.loader.loadAsync(url, (event) => {
+      if (options?.onProgress && event.lengthComputable) {
+        options.onProgress(event.loaded / event.total);
+      }
+    });
+    if (options?.repeat) {
+      texture.repeat.copy(options.repeat);
+    }
+    texture.wrapS = options?.wrapS ?? RepeatWrapping;
+    texture.wrapT = options?.wrapT ?? RepeatWrapping;
+    return texture;
+  }
+  /**
+   * Clone a texture for independent usage
+   */
+  clone(texture) {
+    const cloned = texture.clone();
+    cloned.needsUpdate = true;
+    return cloned;
+  }
+};
+
+// src/lib/core/loaders/gltf-loader.ts
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
-var FBXAssetLoader = class {
-  loader = new FBXLoader();
-  isSupported(file) {
-    return file.toLowerCase().endsWith("fbx" /* FBX */);
+var GLTFLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new GLTFLoader();
+  }
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ["gltf", "glb"].includes(ext || "");
+  }
+  async load(url, options) {
+    if (options?.useAsyncFetch) {
+      return this.loadWithAsyncFetch(url, options);
+    }
+    return this.loadMainThread(url, options);
+  }
+  /**
+   * Load using native fetch + parseAsync
+   * Both fetch and parsing are async, keeping the main thread responsive
+   */
+  async loadWithAsyncFetch(url, options) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+      }
+      const buffer = await response.arrayBuffer();
+      const gltf = await this.loader.parseAsync(buffer, url);
+      return {
+        object: gltf.scene,
+        animations: gltf.animations,
+        gltf
+      };
+    } catch (error) {
+      console.error(`Async fetch GLTF load failed for ${url}, falling back to loader.load():`, error);
+      return this.loadMainThread(url, options);
+    }
   }
-  async load(file) {
+  async loadMainThread(url, options) {
     return new Promise((resolve, reject) => {
       this.loader.load(
-        file,
-        (object) => {
-          const animation = object.animations[0];
+        url,
+        (gltf) => {
           resolve({
-            object,
-            animation
+            object: gltf.scene,
+            animations: gltf.animations,
+            gltf
           });
         },
-        void 0,
-        reject
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
       );
     });
   }
+  /**
+   * Clone a loaded GLTF scene for reuse
+   */
+  clone(result) {
+    return {
+      object: result.object.clone(),
+      animations: result.animations?.map((anim) => anim.clone()),
+      gltf: result.gltf
+    };
+  }
 };
-var GLTFAssetLoader = class {
-  loader = new GLTFLoader();
-  isSupported(file) {
-    return file.toLowerCase().endsWith("gltf" /* GLTF */);
+
+// src/lib/core/loaders/fbx-loader.ts
+import { FBXLoader } from "three/addons/loaders/FBXLoader.js";
+var FBXLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new FBXLoader();
+  }
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ext === "fbx";
+  }
+  async load(url, options) {
+    if (options?.useAsyncFetch) {
+      return this.loadWithAsyncFetch(url, options);
+    }
+    return this.loadMainThread(url, options);
+  }
+  /**
+   * Load using native fetch + parse
+   */
+  async loadWithAsyncFetch(url, _options) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+      }
+      const buffer = await response.arrayBuffer();
+      const object = this.loader.parse(buffer, url);
+      return {
+        object,
+        animations: object.animations || []
+      };
+    } catch (error) {
+      console.error(`Async fetch FBX load failed for ${url}, falling back to loader.load():`, error);
+      return this.loadMainThread(url, _options);
+    }
   }
-  async load(file) {
+  async loadMainThread(url, options) {
     return new Promise((resolve, reject) => {
       this.loader.load(
-        file,
-        (gltf) => {
+        url,
+        (object) => {
           resolve({
-            object: gltf.scene,
-            gltf
+            object,
+            animations: object.animations || []
           });
         },
-        void 0,
-        reject
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
       );
     });
   }
-};
-var EntityAssetLoader = class {
-  loaders = [
-    new FBXAssetLoader(),
-    new GLTFAssetLoader()
-  ];
-  async loadFile(file) {
-    const loader = this.loaders.find((l) => l.isSupported(file));
-    if (!loader) {
-      throw new Error(`Unsupported file type: ${file}`);
-    }
-    return loader.load(file);
+  /**
+   * Clone a loaded FBX object for reuse
+   */
+  clone(result) {
+    return {
+      object: result.object.clone(),
+      animations: result.animations?.map((anim) => anim.clone())
+    };
   }
 };
 
-// src/lib/entities/delegates/animation.ts
-import {
-  AnimationMixer,
-  LoopOnce,
-  LoopRepeat
-} from "three";
-var AnimationDelegate = class {
-  constructor(target) {
-    this.target = target;
+// src/lib/core/loaders/obj-loader.ts
+import { OBJLoader } from "three/addons/loaders/OBJLoader.js";
+import { MTLLoader } from "three/addons/loaders/MTLLoader.js";
+var OBJLoaderAdapter = class {
+  loader;
+  mtlLoader;
+  constructor() {
+    this.loader = new OBJLoader();
+    this.mtlLoader = new MTLLoader();
   }
-  _mixer = null;
-  _actions = {};
-  _animations = [];
-  _currentAction = null;
-  _pauseAtPercentage = 0;
-  _isPaused = false;
-  _queuedKey = null;
-  _fadeDuration = 0.5;
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ext === "obj";
+  }
+  async load(url, options) {
+    if (options?.mtlPath) {
+      await this.loadMTL(options.mtlPath);
+    }
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (object) => {
+          resolve({
+            object,
+            animations: []
+          });
+        },
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
+      );
+    });
+  }
+  async loadMTL(url) {
+    return new Promise((resolve, reject) => {
+      this.mtlLoader.load(
+        url,
+        (materials) => {
+          materials.preload();
+          this.loader.setMaterials(materials);
+          resolve();
+        },
+        void 0,
+        (error) => reject(error)
+      );
+    });
+  }
+  /**
+   * Clone a loaded OBJ object for reuse
+   */
+  clone(result) {
+    return {
+      object: result.object.clone(),
+      animations: []
+    };
+  }
+};
+
+// src/lib/core/loaders/audio-loader.ts
+import { AudioLoader } from "three";
+var AudioLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new AudioLoader();
+  }
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ["mp3", "ogg", "wav", "flac", "aac", "m4a"].includes(ext || "");
+  }
+  async load(url, options) {
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (buffer) => resolve(buffer),
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
+      );
+    });
+  }
+};
+
+// src/lib/core/loaders/file-loader.ts
+import { FileLoader } from "three";
+var FileLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new FileLoader();
+  }
+  isSupported(_url) {
+    return true;
+  }
+  async load(url, options) {
+    const responseType = options?.responseType ?? "text";
+    this.loader.setResponseType(responseType);
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (data) => resolve(data),
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
+      );
+    });
+  }
+};
+var JsonLoaderAdapter = class {
+  fileLoader;
+  constructor() {
+    this.fileLoader = new FileLoaderAdapter();
+  }
+  isSupported(url) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    return ext === "json";
+  }
+  async load(url, options) {
+    const data = await this.fileLoader.load(url, { ...options, responseType: "json" });
+    return data;
+  }
+};
+
+// src/lib/core/asset-manager.ts
+var AssetManager = class _AssetManager {
+  static instance = null;
+  // Caches for different asset types
+  textureCache = /* @__PURE__ */ new Map();
+  modelCache = /* @__PURE__ */ new Map();
+  audioCache = /* @__PURE__ */ new Map();
+  fileCache = /* @__PURE__ */ new Map();
+  jsonCache = /* @__PURE__ */ new Map();
+  // Loaders
+  textureLoader;
+  gltfLoader;
+  fbxLoader;
+  objLoader;
+  audioLoader;
+  fileLoader;
+  jsonLoader;
+  // Loading manager for progress tracking
+  loadingManager;
+  // Event emitter
+  events;
+  // Stats
+  stats = {
+    texturesLoaded: 0,
+    modelsLoaded: 0,
+    audioLoaded: 0,
+    filesLoaded: 0,
+    cacheHits: 0,
+    cacheMisses: 0
+  };
+  constructor() {
+    this.textureLoader = new TextureLoaderAdapter();
+    this.gltfLoader = new GLTFLoaderAdapter();
+    this.fbxLoader = new FBXLoaderAdapter();
+    this.objLoader = new OBJLoaderAdapter();
+    this.audioLoader = new AudioLoaderAdapter();
+    this.fileLoader = new FileLoaderAdapter();
+    this.jsonLoader = new JsonLoaderAdapter();
+    this.loadingManager = new LoadingManager();
+    this.loadingManager.onProgress = (url, loaded, total) => {
+      this.events.emit("batch:progress", { loaded, total });
+    };
+    this.events = mitt_default();
+    Cache.enabled = true;
+  }
+  /**
+   * Get the singleton instance
+   */
+  static getInstance() {
+    if (!_AssetManager.instance) {
+      _AssetManager.instance = new _AssetManager();
+    }
+    return _AssetManager.instance;
+  }
+  /**
+   * Reset the singleton (useful for testing)
+   */
+  static resetInstance() {
+    if (_AssetManager.instance) {
+      _AssetManager.instance.clearCache();
+      _AssetManager.instance = null;
+    }
+  }
+  // ==================== TEXTURE LOADING ====================
+  /**
+   * Load a texture with caching
+   */
+  async loadTexture(url, options) {
+    return this.loadWithCache(
+      url,
+      "texture" /* TEXTURE */,
+      this.textureCache,
+      () => this.textureLoader.load(url, options),
+      options,
+      (texture) => {
+        if (!options?.clone) return texture;
+        const cloned = this.textureLoader.clone(texture);
+        if (options.repeat) {
+          cloned.repeat.copy(options.repeat);
+        }
+        if (options.wrapS !== void 0) {
+          cloned.wrapS = options.wrapS;
+        }
+        if (options.wrapT !== void 0) {
+          cloned.wrapT = options.wrapT;
+        }
+        return cloned;
+      }
+    );
+  }
+  // ==================== MODEL LOADING ====================
+  /**
+   * Load a GLTF/GLB model with caching
+   */
+  async loadGLTF(url, options) {
+    return this.loadWithCache(
+      url,
+      "gltf" /* GLTF */,
+      this.modelCache,
+      () => this.gltfLoader.load(url, options),
+      options,
+      (result) => options?.clone ? this.gltfLoader.clone(result) : result
+    );
+  }
+  /**
+   * Load an FBX model with caching
+   */
+  async loadFBX(url, options) {
+    return this.loadWithCache(
+      url,
+      "fbx" /* FBX */,
+      this.modelCache,
+      () => this.fbxLoader.load(url, options),
+      options,
+      (result) => options?.clone ? this.fbxLoader.clone(result) : result
+    );
+  }
+  /**
+   * Load an OBJ model with caching
+   */
+  async loadOBJ(url, options) {
+    const cacheKey = options?.mtlPath ? `${url}:${options.mtlPath}` : url;
+    return this.loadWithCache(
+      cacheKey,
+      "obj" /* OBJ */,
+      this.modelCache,
+      () => this.objLoader.load(url, options),
+      options,
+      (result) => options?.clone ? this.objLoader.clone(result) : result
+    );
+  }
+  /**
+   * Auto-detect model type and load
+   */
+  async loadModel(url, options) {
+    const ext = url.split(".").pop()?.toLowerCase();
+    switch (ext) {
+      case "gltf":
+      case "glb":
+        return this.loadGLTF(url, options);
+      case "fbx":
+        return this.loadFBX(url, options);
+      case "obj":
+        return this.loadOBJ(url, options);
+      default:
+        throw new Error(`Unsupported model format: ${ext}`);
+    }
+  }
+  // ==================== AUDIO LOADING ====================
+  /**
+   * Load an audio buffer with caching
+   */
+  async loadAudio(url, options) {
+    return this.loadWithCache(
+      url,
+      "audio" /* AUDIO */,
+      this.audioCache,
+      () => this.audioLoader.load(url, options),
+      options
+    );
+  }
+  // ==================== FILE LOADING ====================
+  /**
+   * Load a raw file with caching
+   */
+  async loadFile(url, options) {
+    const cacheKey = options?.responseType ? `${url}:${options.responseType}` : url;
+    return this.loadWithCache(
+      cacheKey,
+      "file" /* FILE */,
+      this.fileCache,
+      () => this.fileLoader.load(url, options),
+      options
+    );
+  }
+  /**
+   * Load a JSON file with caching
+   */
+  async loadJSON(url, options) {
+    return this.loadWithCache(
+      url,
+      "json" /* JSON */,
+      this.jsonCache,
+      () => this.jsonLoader.load(url, options),
+      options
+    );
+  }
+  // ==================== BATCH LOADING ====================
+  /**
+   * Load multiple assets in parallel
+   */
+  async loadBatch(items) {
+    const results = /* @__PURE__ */ new Map();
+    const promises = items.map(async (item) => {
+      try {
+        let result;
+        switch (item.type) {
+          case "texture" /* TEXTURE */:
+            result = await this.loadTexture(item.url, item.options);
+            break;
+          case "gltf" /* GLTF */:
+            result = await this.loadGLTF(item.url, item.options);
+            break;
+          case "fbx" /* FBX */:
+            result = await this.loadFBX(item.url, item.options);
+            break;
+          case "obj" /* OBJ */:
+            result = await this.loadOBJ(item.url, item.options);
+            break;
+          case "audio" /* AUDIO */:
+            result = await this.loadAudio(item.url, item.options);
+            break;
+          case "file" /* FILE */:
+            result = await this.loadFile(item.url, item.options);
+            break;
+          case "json" /* JSON */:
+            result = await this.loadJSON(item.url, item.options);
+            break;
+          default:
+            throw new Error(`Unknown asset type: ${item.type}`);
+        }
+        results.set(item.url, result);
+      } catch (error) {
+        this.events.emit("asset:error", {
+          url: item.url,
+          type: item.type,
+          error
+        });
+        throw error;
+      }
+    });
+    await Promise.all(promises);
+    this.events.emit("batch:complete", { urls: items.map((i) => i.url) });
+    return results;
+  }
+  /**
+   * Preload assets without returning results
+   */
+  async preload(items) {
+    await this.loadBatch(items);
+  }
+  // ==================== CACHE MANAGEMENT ====================
+  /**
+   * Check if an asset is cached
+   */
+  isCached(url) {
+    return this.textureCache.has(url) || this.modelCache.has(url) || this.audioCache.has(url) || this.fileCache.has(url) || this.jsonCache.has(url);
+  }
+  /**
+   * Clear all caches or a specific URL
+   */
+  clearCache(url) {
+    if (url) {
+      this.textureCache.delete(url);
+      this.modelCache.delete(url);
+      this.audioCache.delete(url);
+      this.fileCache.delete(url);
+      this.jsonCache.delete(url);
+    } else {
+      this.textureCache.clear();
+      this.modelCache.clear();
+      this.audioCache.clear();
+      this.fileCache.clear();
+      this.jsonCache.clear();
+      Cache.clear();
+    }
+  }
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    return { ...this.stats };
+  }
+  // ==================== EVENTS ====================
+  /**
+   * Subscribe to asset manager events
+   */
+  on(event, handler) {
+    this.events.on(event, handler);
+  }
+  /**
+   * Unsubscribe from asset manager events
+   */
+  off(event, handler) {
+    this.events.off(event, handler);
+  }
+  // ==================== PRIVATE HELPERS ====================
+  /**
+   * Generic cache wrapper for loading assets
+   */
+  async loadWithCache(url, type, cache, loader, options, cloner) {
+    if (options?.forceReload) {
+      cache.delete(url);
+    }
+    const cached = cache.get(url);
+    if (cached) {
+      this.stats.cacheHits++;
+      this.events.emit("asset:loaded", { url, type, fromCache: true });
+      const result = await cached.promise;
+      return cloner ? cloner(result) : result;
+    }
+    this.stats.cacheMisses++;
+    this.events.emit("asset:loading", { url, type });
+    const promise = loader();
+    const entry = {
+      promise,
+      loadedAt: Date.now()
+    };
+    cache.set(url, entry);
+    try {
+      const result = await promise;
+      entry.result = result;
+      this.updateStats(type);
+      this.events.emit("asset:loaded", { url, type, fromCache: false });
+      return cloner ? cloner(result) : result;
+    } catch (error) {
+      cache.delete(url);
+      this.events.emit("asset:error", { url, type, error });
+      throw error;
+    }
+  }
+  updateStats(type) {
+    switch (type) {
+      case "texture" /* TEXTURE */:
+        this.stats.texturesLoaded++;
+        break;
+      case "gltf" /* GLTF */:
+      case "fbx" /* FBX */:
+      case "obj" /* OBJ */:
+        this.stats.modelsLoaded++;
+        break;
+      case "audio" /* AUDIO */:
+        this.stats.audioLoaded++;
+        break;
+      case "file" /* FILE */:
+      case "json" /* JSON */:
+        this.stats.filesLoaded++;
+        break;
+    }
+  }
+};
+var assetManager = AssetManager.getInstance();
+
+// src/lib/core/entity-asset-loader.ts
+var EntityAssetLoader = class {
+  /**
+   * Load a model file (FBX, GLTF, GLB, OBJ) using the asset manager
+   */
+  async loadFile(file) {
+    const ext = file.split(".").pop()?.toLowerCase();
+    switch (ext) {
+      case "fbx": {
+        const result = await assetManager.loadFBX(file);
+        return {
+          object: result.object,
+          animation: result.animations?.[0]
+        };
+      }
+      case "gltf":
+      case "glb": {
+        const result = await assetManager.loadGLTF(file);
+        return {
+          object: result.object,
+          gltf: result.gltf
+        };
+      }
+      case "obj": {
+        const result = await assetManager.loadOBJ(file);
+        return {
+          object: result.object
+        };
+      }
+      default:
+        throw new Error(`Unsupported file type: ${file}`);
+    }
+  }
+};
+
+// src/lib/entities/delegates/animation.ts
+import {
+  AnimationMixer,
+  LoopOnce,
+  LoopRepeat
+} from "three";
+var AnimationDelegate = class {
+  constructor(target) {
+    this.target = target;
+  }
+  _mixer = null;
+  _actions = {};
+  _animations = [];
+  _currentAction = null;
+  _pauseAtPercentage = 0;
+  _isPaused = false;
+  _queuedKey = null;
+  _fadeDuration = 0.5;
   _currentKey = "";
   _assetLoader = new EntityAssetLoader();
   async loadAnimations(animations) {
     if (!animations.length) return;
     const results = await Promise.all(animations.map((a) => this._assetLoader.loadFile(a.path)));
-    this._animations = results.filter((r) => !!r.animation).map((r) => r.animation);
-    if (!this._animations.length) return;
+    const loadedAnimations = [];
+    results.forEach((result, i) => {
+      if (result.animation) {
+        loadedAnimations.push({
+          key: animations[i].key || i.toString(),
+          clip: result.animation
+        });
+      }
+    });
+    if (!loadedAnimations.length) return;
+    this._animations = loadedAnimations.map((a) => a.clip);
     this._mixer = new AnimationMixer(this.target);
-    this._animations.forEach((clip, i) => {
-      const key = animations[i].key || i.toString();
+    loadedAnimations.forEach(({ key, clip }) => {
       this._actions[key] = this._mixer.clipAction(clip);
     });
-    this.playAnimation({ key: Object.keys(this._actions)[0] });
+    this.playAnimation({ key: loadedAnimations[0].key });
   }
   update(delta) {
     if (!this._mixer || !this._currentAction) return;
@@ -546,14 +1831,13 @@ var AnimationDelegate = class {
     if (!this._mixer) return;
     const { key, pauseAtPercentage = 0, pauseAtEnd = false, fadeToKey, fadeDuration = 0.5 } = opts;
     if (key === this._currentKey) return;
+    const action = this._actions[key];
+    if (!action) return;
     this._queuedKey = fadeToKey || null;
     this._fadeDuration = fadeDuration;
     this._pauseAtPercentage = pauseAtEnd ? 100 : pauseAtPercentage;
     this._isPaused = false;
     const prev = this._currentAction;
-    if (prev) prev.stop();
-    const action = this._actions[key];
-    if (!action) return;
     if (this._pauseAtPercentage > 0) {
       action.setLoop(LoopOnce, Infinity);
       action.clampWhenFinished = true;
@@ -561,10 +1845,10 @@ var AnimationDelegate = class {
       action.setLoop(LoopRepeat, Infinity);
       action.clampWhenFinished = false;
     }
+    action.reset().play();
     if (prev) {
       prev.crossFadeTo(action, fadeDuration, false);
     }
-    action.reset().play();
     this._currentAction = action;
     this._currentKey = key;
   }
@@ -593,22 +1877,66 @@ var AnimationDelegate = class {
   }
 };
 
-// src/lib/graphics/shaders/fragment/standard.glsl
-var standard_default = "uniform sampler2D tDiffuse;\nvarying vec2 vUv;\n\nvoid main() {\n	vec4 texel = texture2D( tDiffuse, vUv );\n\n	gl_FragColor = texel;\n}";
+// src/lib/graphics/material.ts
+import { Color as Color3, Vector2 as Vector22, Vector3 as Vector36 } from "three";
+import {
+  MeshPhongMaterial,
+  MeshStandardMaterial,
+  RepeatWrapping as RepeatWrapping2,
+  ShaderMaterial as ShaderMaterial2
+} from "three";
+import {
+  MeshBasicNodeMaterial,
+  MeshStandardNodeMaterial
+} from "three/webgpu";
+
+// src/lib/core/utility/strings.ts
+function sortedStringify(obj) {
+  const sortedObj = Object.keys(obj).sort().reduce((acc, key) => {
+    acc[key] = obj[key];
+    return acc;
+  }, {});
+  return JSON.stringify(sortedObj);
+}
+function shortHash(objString) {
+  let hash = 0;
+  for (let i = 0; i < objString.length; i++) {
+    hash = Math.imul(31, hash) + objString.charCodeAt(i) | 0;
+  }
+  return hash.toString(36);
+}
+
+// src/lib/graphics/material.ts
+import {
+  uniform,
+  uv,
+  time,
+  vec3,
+  vec4,
+  float,
+  Fn
+} from "three/tsl";
+function isTSLShader(shader) {
+  return "colorNode" in shader;
+}
+function isGLSLShader(shader) {
+  return "fragment" in shader && "vertex" in shader;
+}
 
 // src/lib/entities/actor.ts
 var actorDefaults = {
-  position: { x: 0, y: 0, z: 0 },
+  ...commonDefaults,
   collision: {
     static: false,
-    size: new Vector3(0.5, 0.5, 0.5),
-    position: new Vector3(0, 0, 0)
+    size: new Vector37(0.5, 0.5, 0.5),
+    position: new Vector37(0, 0, 0)
   },
   material: {
-    shader: "standard"
+    shader: standardShader
   },
   animations: [],
-  models: []
+  models: [],
+  collisionShape: "capsule"
 };
 var ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
 var ZylemActor = class extends GameEntity {
@@ -624,21 +1952,26 @@ var ZylemActor = class extends GameEntity {
     this.prependUpdate(this.actorUpdate.bind(this));
     this.controlledRotation = true;
   }
-  async load() {
+  /**
+   * Initiates model and animation loading in background (deferred).
+   * Call returns immediately; assets will be ready on subsequent updates.
+   */
+  load() {
     this._modelFileNames = this.options.models || [];
-    await this.loadModels();
-    if (this._object) {
-      this._animationDelegate = new AnimationDelegate(this._object);
-      await this._animationDelegate.loadAnimations(this.options.animations || []);
-    }
+    this.loadModelsDeferred();
   }
-  async data() {
+  /**
+   * Returns current data synchronously.
+   * May return null values if loading is still in progress.
+   */
+  data() {
     return {
       animations: this._animationDelegate?.animations,
-      objectModel: this._object
+      objectModel: this._object,
+      collisionShape: this.options.collisionShape
     };
   }
-  async actorUpdate(params) {
+  actorUpdate(params) {
     this._animationDelegate?.update(params.delta);
   }
   /**
@@ -669,26 +2002,79 @@ var ZylemActor = class extends GameEntity {
     }
     this._modelFileNames = [];
   }
-  async loadModels() {
+  /**
+   * Deferred loading - starts async load and updates entity when complete.
+   * Called by synchronous load() method.
+   */
+  loadModelsDeferred() {
     if (this._modelFileNames.length === 0) return;
+    this.dispatch("entity:model:loading", {
+      entityId: this.uuid,
+      files: this._modelFileNames
+    });
     const promises = this._modelFileNames.map((file) => this._assetLoader.loadFile(file));
-    const results = await Promise.all(promises);
-    if (results[0]?.object) {
-      this._object = results[0].object;
-    }
-    if (this._object) {
-      this.group = new Group2();
-      this.group.attach(this._object);
-      this.group.scale.set(
-        this.options.scale?.x || 1,
-        this.options.scale?.y || 1,
-        this.options.scale?.z || 1
-      );
-    }
+    Promise.all(promises).then((results) => {
+      if (results[0]?.object) {
+        this._object = results[0].object;
+      }
+      let meshCount = 0;
+      if (this._object) {
+        this._object.traverse((child) => {
+          if (child.isMesh) meshCount++;
+        });
+        this.group = new Group2();
+        this.group.attach(this._object);
+        this.group.scale.set(
+          this.options.scale?.x || 1,
+          this.options.scale?.y || 1,
+          this.options.scale?.z || 1
+        );
+        this.applyMaterialOverrides();
+        this._animationDelegate = new AnimationDelegate(this._object);
+        this._animationDelegate.loadAnimations(this.options.animations || []).then(() => {
+          this.dispatch("entity:animation:loaded", {
+            entityId: this.uuid,
+            animationCount: this.options.animations?.length || 0
+          });
+        });
+      }
+      this.dispatch("entity:model:loaded", {
+        entityId: this.uuid,
+        success: !!this._object,
+        meshCount
+      });
+    });
   }
   playAnimation(animationOptions) {
     this._animationDelegate?.playAnimation(animationOptions);
   }
+  /**
+   * Apply material overrides from options to all meshes in the loaded model.
+   * Only applies if material options are explicitly specified (not just defaults).
+   */
+  applyMaterialOverrides() {
+    const materialOptions = this.options.material;
+    if (!materialOptions || !materialOptions.color && !materialOptions.path) {
+      return;
+    }
+    if (!this._object) return;
+    this._object.traverse((child) => {
+      if (child.isMesh) {
+        const mesh = child;
+        if (materialOptions.color) {
+          const newMaterial = new MeshStandardMaterial2({
+            color: materialOptions.color,
+            emissiveIntensity: 0.5,
+            lightMapIntensity: 0.5,
+            fog: true
+          });
+          mesh.castShadow = true;
+          mesh.receiveShadow = true;
+          mesh.material = newMaterial;
+        }
+      }
+    });
+  }
   get object() {
     return this._object;
   }
@@ -754,6 +2140,13 @@ var ZylemWorld = class {
     }
     const collider = this.world.createCollider(entity.colliderDesc, entity.body);
     entity.collider = collider;
+    entity.colliders = [collider];
+    if (entity.colliderDescs?.length > 1) {
+      for (let i = 1; i < entity.colliderDescs.length; i++) {
+        const additionalCollider = this.world.createCollider(entity.colliderDescs[i], entity.body);
+        entity.colliders.push(additionalCollider);
+      }
+    }
     if (entity.controlledRotation || entity instanceof ZylemActor) {
       entity.body.lockRotations(true, true);
       entity.characterController = this.world.createCharacterController(0.01);
@@ -772,7 +2165,18 @@ var ZylemWorld = class {
     }
   }
   destroyEntity(entity) {
-    if (entity.collider) {
+    if (entity.characterController) {
+      try {
+        entity.characterController.free();
+      } catch {
+      }
+      entity.characterController = null;
+    }
+    if (entity.colliders?.length) {
+      for (const collider of entity.colliders) {
+        this.world.removeCollider(collider, true);
+      }
+    } else if (entity.collider) {
       this.world.removeCollider(entity.collider, true);
     }
     if (entity.body) {
@@ -817,6 +2221,9 @@ var ZylemWorld = class {
         continue;
       }
       this.world.contactsWith(gameEntity.body.collider(0), (otherCollider) => {
+        if (!otherCollider) {
+          return;
+        }
         const uuid = otherCollider._parent.userData.uuid;
         const entity = dictionaryRef.get(uuid);
         if (!entity) {
@@ -826,7 +2233,13 @@ var ZylemWorld = class {
           gameEntity._collision(entity, state.globals);
         }
       });
+      if (!gameEntity.body || gameEntity.markedForRemoval) {
+        continue;
+      }
       this.world.intersectionsWith(gameEntity.body.collider(0), (otherCollider) => {
+        if (!otherCollider) {
+          return;
+        }
         const uuid = otherCollider._parent.userData.uuid;
         const entity = dictionaryRef.get(uuid);
         if (!entity) {
@@ -853,6 +2266,10 @@ var ZylemWorld = class {
       this.collisionMap.clear();
       this.collisionBehaviorMap.clear();
       this._removalMap.clear();
+      try {
+        this.world?.free();
+      } catch {
+      }
       this.world = void 0;
     } catch {
     }
@@ -862,17 +2279,22 @@ var ZylemWorld = class {
 // src/lib/graphics/zylem-scene.ts
 import {
   Scene,
-  Color as Color2,
+  Color as Color4,
   AmbientLight,
   DirectionalLight,
-  Vector3 as Vector32,
-  TextureLoader,
-  GridHelper
+  Vector3 as Vector38,
+  GridHelper,
+  BoxGeometry,
+  ShaderMaterial as ShaderMaterial3,
+  Mesh as Mesh3,
+  BackSide,
+  Texture as Texture3
 } from "three";
+import { MeshBasicNodeMaterial as MeshBasicNodeMaterial2 } from "three/webgpu";
 
 // src/lib/debug/debug-state.ts
-import { proxy as proxy2 } from "valtio";
-var debugState = proxy2({
+import { proxy as proxy3 } from "valtio";
+var debugState = proxy3({
   enabled: false,
   paused: false,
   tool: "none",
@@ -901,7 +2323,9 @@ var ZylemScene = class {
   type = "Scene";
   _setup;
   scene;
+  /** @deprecated Use cameraManager instead */
   zylemCamera;
+  cameraManager = null;
   containerElement = null;
   update = () => {
   };
@@ -909,61 +2333,159 @@ var ZylemScene = class {
   _destroy;
   name;
   tag;
+  // Skybox for background shaders (supports both GLSL ShaderMaterial and TSL MeshBasicNodeMaterial)
+  skyboxMaterial = null;
   constructor(id, camera, state2) {
     const scene = new Scene();
-    const isColor = state2.backgroundColor instanceof Color2;
-    const backgroundColor = isColor ? state2.backgroundColor : new Color2(state2.backgroundColor);
+    const isColor = state2.backgroundColor instanceof Color4;
+    const backgroundColor = isColor ? state2.backgroundColor : new Color4(state2.backgroundColor);
     scene.background = backgroundColor;
-    if (state2.backgroundImage) {
-      const loader = new TextureLoader();
-      const texture = loader.load(state2.backgroundImage);
-      scene.background = texture;
+    console.log("ZylemScene state.backgroundShader:", state2.backgroundShader);
+    if (state2.backgroundShader) {
+      this.setupBackgroundShader(scene, state2.backgroundShader);
+    } else if (state2.backgroundImage) {
+      assetManager.loadTexture(state2.backgroundImage).then((texture) => {
+        scene.background = texture;
+      });
     }
     this.scene = scene;
     this.zylemCamera = camera;
     this.setupLighting(scene);
-    this.setupCamera(scene, camera);
     if (debugState.enabled) {
       this.debugScene();
     }
   }
+  /**
+   * Create a large inverted box with the shader for skybox effect
+   * Supports both GLSL (ShaderMaterial) and TSL (MeshBasicNodeMaterial) shaders
+   */
+  setupBackgroundShader(scene, shader) {
+    scene.background = null;
+    if (isTSLShader(shader)) {
+      this.skyboxMaterial = new MeshBasicNodeMaterial2();
+      this.skyboxMaterial.colorNode = shader.colorNode;
+      if (shader.transparent) {
+        this.skyboxMaterial.transparent = true;
+      }
+      this.skyboxMaterial.side = BackSide;
+      this.skyboxMaterial.depthWrite = false;
+      console.log("Skybox created with TSL shader");
+    } else if (isGLSLShader(shader)) {
+      const skyboxVertexShader = `
+				varying vec2 vUv;
+				varying vec3 vWorldPosition;
+				
+				void main() {
+					vUv = uv;
+					vec4 worldPosition = modelMatrix * vec4(position, 1.0);
+					vWorldPosition = worldPosition.xyz;
+					vec4 pos = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+					gl_Position = pos.xyww;  // Ensures depth is always 1.0 (farthest)
+				}
+			`;
+      this.skyboxMaterial = new ShaderMaterial3({
+        vertexShader: skyboxVertexShader,
+        fragmentShader: shader.fragment,
+        uniforms: {
+          iTime: { value: 0 }
+        },
+        side: BackSide,
+        // Render on inside of geometry
+        depthWrite: false,
+        // Don't write to depth buffer
+        depthTest: true
+        // But do test depth
+      });
+      console.log("Skybox created with GLSL shader");
+    }
+    const geometry = new BoxGeometry(1, 1, 1);
+    const skybox = new Mesh3(geometry, this.skyboxMaterial);
+    skybox.scale.setScalar(1e5);
+    skybox.frustumCulled = false;
+    scene.add(skybox);
+  }
   setup() {
     if (this._setup) {
       this._setup({ me: this, camera: this.zylemCamera, globals: getGlobals() });
     }
   }
   destroy() {
-    if (this.zylemCamera && this.zylemCamera.destroy) {
+    if (this.cameraManager) {
+      this.cameraManager.dispose();
+      this.cameraManager = null;
+    } else if (this.zylemCamera && this.zylemCamera.destroy) {
       this.zylemCamera.destroy();
     }
+    if (this.skyboxMaterial) {
+      this.skyboxMaterial.dispose();
+    }
     if (this.scene) {
+      if (this.scene.background instanceof Texture3) {
+        this.scene.background.dispose();
+        this.scene.background = null;
+      }
       this.scene.traverse((obj) => {
         if (obj.geometry) {
           obj.geometry.dispose?.();
         }
         if (obj.material) {
-          if (Array.isArray(obj.material)) {
-            obj.material.forEach((m) => m.dispose?.());
-          } else {
-            obj.material.dispose?.();
+          const materials = Array.isArray(obj.material) ? obj.material : [obj.material];
+          for (const mat of materials) {
+            if (mat.map) mat.map.dispose?.();
+            if (mat.normalMap) mat.normalMap.dispose?.();
+            if (mat.aoMap) mat.aoMap.dispose?.();
+            if (mat.emissiveMap) mat.emissiveMap.dispose?.();
+            if (mat.roughnessMap) mat.roughnessMap.dispose?.();
+            if (mat.metalnessMap) mat.metalnessMap.dispose?.();
+            if (mat.envMap) mat.envMap.dispose?.();
+            if (mat.lightMap) mat.lightMap.dispose?.();
+            if (mat.bumpMap) mat.bumpMap.dispose?.();
+            if (mat.displacementMap) mat.displacementMap.dispose?.();
+            if (mat.alphaMap) mat.alphaMap.dispose?.();
+            mat.dispose?.();
           }
         }
+        if (obj.isLight && obj.shadow?.map) {
+          obj.shadow.map.dispose();
+        }
       });
+      this.scene.clear();
     }
   }
   /**
-   * Setup camera with the scene
+   * Setup camera with the scene.
+   * Supports both legacy single camera and CameraManager modes.
    */
-  setupCamera(scene, camera) {
-    if (camera.cameraRig) {
-      scene.add(camera.cameraRig);
+  setupCamera(scene, camera, rendererManager) {
+    this.addCameraToScene(scene, camera);
+    if (rendererManager) {
+      camera.setup(scene, rendererManager);
     } else {
-      scene.add(camera.camera);
+      camera.setupLegacy(scene);
     }
-    camera.setup(scene);
   }
   /**
-   * Setup scene lighting
+   * Setup with a CameraManager (multi-camera support).
+   */
+  async setupCameraManager(scene, cameraManager, rendererManager) {
+    this.cameraManager = cameraManager;
+    for (const camera of cameraManager.activeCameras) {
+      this.addCameraToScene(scene, camera);
+    }
+    await cameraManager.setup(scene, rendererManager);
+  }
+  /**
+   * Add a camera (rig or direct) to the scene graph.
+   */
+  addCameraToScene(scene, camera) {
+    if (camera.cameraRig) {
+      scene.add(camera.cameraRig);
+    } else {
+      scene.add(camera.camera);
+    }
+  }
+  /**
+   * Setup scene lighting
    */
   setupLighting(scene) {
     const ambientLight = new AmbientLight(16777215, 2);
@@ -983,15 +2505,21 @@ var ZylemScene = class {
     scene.add(directionalLight);
   }
   /**
-   * Update renderer size - delegates to camera
+   * Update renderer size - delegates to camera manager or camera
    */
   updateRenderer(width, height) {
-    this.zylemCamera.resize(width, height);
+    if (this.cameraManager) {
+      for (const camera of this.cameraManager.allCameras) {
+        camera.resize(width, height);
+      }
+    } else {
+      this.zylemCamera.resize(width, height);
+    }
   }
   /**
    * Add object to scene
    */
-  add(object, position2 = new Vector32(0, 0, 0)) {
+  add(object, position2 = new Vector38(0, 0, 0)) {
     object.position.set(position2.x, position2.y, position2.z);
     this.scene.add(object);
   }
@@ -1005,6 +2533,22 @@ var ZylemScene = class {
       this.add(entity.mesh, entity.options.position);
     }
   }
+  /**
+   * Add an entity's group or mesh to the scene (for late-loaded models).
+   * Uses entity's current body position if physics is active.
+   */
+  addEntityGroup(entity) {
+    const position2 = entity.body ? new Vector38(
+      entity.body.translation().x,
+      entity.body.translation().y,
+      entity.body.translation().z
+    ) : entity.options.position;
+    if (entity.group) {
+      this.add(entity.group, position2);
+    } else if (entity.mesh) {
+      this.add(entity.mesh, position2);
+    }
+  }
   /**
    * Add debug helpers to scene
    */
@@ -1014,20 +2558,299 @@ var ZylemScene = class {
     const gridHelper = new GridHelper(size, divisions);
     this.scene.add(gridHelper);
   }
+  /**
+   * Update skybox shader uniforms (only applies to GLSL ShaderMaterial)
+   * TSL shaders use the time node which auto-updates
+   */
+  updateSkybox(delta) {
+    if (this.skyboxMaterial && this.skyboxMaterial instanceof ShaderMaterial3) {
+      if (this.skyboxMaterial.uniforms?.iTime) {
+        this.skyboxMaterial.uniforms.iTime.value += delta;
+      }
+    }
+  }
+};
+
+// src/lib/graphics/instance-manager.ts
+import { InstancedMesh, Matrix4, Vector3 as Vector39, Quaternion as Quaternion3 } from "three";
+var InstanceManager = class _InstanceManager {
+  batches = /* @__PURE__ */ new Map();
+  entityToBatch = /* @__PURE__ */ new Map();
+  // entity UUID -> batch key
+  scene = null;
+  /** Default initial capacity for new batches */
+  static DEFAULT_CAPACITY = 128;
+  /** Factor to grow batch when full */
+  static GROWTH_FACTOR = 2;
+  /**
+   * Set the scene to add instanced meshes to
+   */
+  setScene(scene) {
+    this.scene = scene;
+  }
+  /**
+   * Generate a batch key from configuration
+   */
+  static generateBatchKey(config) {
+    const keyData = {
+      geo: `${config.geometryType}:${sortedStringify(config.dimensions)}`,
+      mat: config.materialPath || "none",
+      shader: config.shaderType || "standard",
+      color: config.colorHex ?? 16777215
+    };
+    return shortHash(sortedStringify(keyData));
+  }
+  /**
+   * Register an entity with the instance manager
+   * @returns The instance index, or -1 if registration failed
+   */
+  register(entity, geometry, material, batchKey) {
+    let batch = this.batches.get(batchKey);
+    if (!batch) {
+      batch = this.createBatch(batchKey, geometry, material);
+    }
+    let index;
+    if (batch.freeIndices.length > 0) {
+      index = batch.freeIndices.pop();
+    } else {
+      index = batch.entities.length;
+      if (index >= batch.capacity) {
+        this.growBatch(batch);
+      }
+      batch.entities.push(null);
+    }
+    batch.entities[index] = entity;
+    batch.entityMap.set(entity.uuid, index);
+    this.entityToBatch.set(entity.uuid, batchKey);
+    batch.instancedMesh.count = Math.max(batch.instancedMesh.count, index + 1);
+    batch.activeIndices.push(index);
+    batch.dirtyIndices.add(index);
+    return index;
+  }
+  /**
+   * Unregister an entity from the instance manager
+   */
+  unregister(entity) {
+    const batchKey = this.entityToBatch.get(entity.uuid);
+    if (!batchKey) return;
+    const batch = this.batches.get(batchKey);
+    if (!batch) return;
+    const index = batch.entityMap.get(entity.uuid);
+    if (index === void 0) return;
+    batch.entities[index] = null;
+    batch.entityMap.delete(entity.uuid);
+    this.entityToBatch.delete(entity.uuid);
+    batch.freeIndices.push(index);
+    const idxInActive = batch.activeIndices.indexOf(index);
+    if (idxInActive !== -1) {
+      const last = batch.activeIndices.pop();
+      if (idxInActive < batch.activeIndices.length) {
+        batch.activeIndices[idxInActive] = last;
+      }
+    }
+    batch.dirtyIndices.delete(index);
+    const matrix = new Matrix4();
+    matrix.makeScale(0, 0, 0);
+    batch.instancedMesh.setMatrixAt(index, matrix);
+    batch.instancedMesh.instanceMatrix.needsUpdate = true;
+  }
+  /**
+   * Mark an entity's transform as dirty (needs syncing)
+   */
+  markDirty(entity) {
+    const batchKey = this.entityToBatch.get(entity.uuid);
+    if (!batchKey) return;
+    const batch = this.batches.get(batchKey);
+    if (!batch) return;
+    const index = batch.entityMap.get(entity.uuid);
+    if (index !== void 0) {
+      batch.dirtyIndices.add(index);
+    }
+  }
+  /**
+   * Update all dirty instance transforms
+   * Call this once per frame
+   */
+  /**
+   * Update all active instance transforms
+   * Call this once per frame
+   */
+  update() {
+    const matrix = new Matrix4();
+    const pos = new Vector39();
+    const quat = new Quaternion3();
+    const scale2 = new Vector39(1, 1, 1);
+    for (const batch of this.batches.values()) {
+      if (batch.activeIndices.length === 0) continue;
+      let needsUpdate = false;
+      if (batch.dirtyIndices.size > 0) {
+        for (const index of batch.dirtyIndices) {
+          this.updateInstanceMatrix(batch, index, matrix, pos, quat, scale2);
+        }
+        batch.dirtyIndices.clear();
+        needsUpdate = true;
+      }
+      for (const index of batch.activeIndices) {
+        const entity = batch.entities[index];
+        if (entity && entity.body) {
+          this.updateInstanceMatrix(batch, index, matrix, pos, quat, scale2);
+          needsUpdate = true;
+        }
+      }
+      if (needsUpdate) {
+        batch.instancedMesh.instanceMatrix.needsUpdate = true;
+      }
+    }
+  }
+  updateInstanceMatrix(batch, index, matrix, pos, quat, scale2) {
+    const entity = batch.entities[index];
+    if (!entity) return;
+    if (entity.body) {
+      const translation = entity.body.translation();
+      const rotation2 = entity.body.rotation();
+      pos.set(translation.x, translation.y, translation.z);
+      quat.set(rotation2.x, rotation2.y, rotation2.z, rotation2.w);
+      matrix.compose(pos, quat, scale2);
+    } else if (entity.mesh) {
+      entity.mesh.updateMatrix();
+      matrix.copy(entity.mesh.matrix);
+    } else if (entity.group) {
+      entity.group.updateMatrix();
+      matrix.copy(entity.group.matrix);
+    }
+    batch.instancedMesh.setMatrixAt(index, matrix);
+  }
+  /**
+   * Get batch info for an entity
+   */
+  getBatchInfo(entity) {
+    const batchKey = this.entityToBatch.get(entity.uuid);
+    if (!batchKey) return null;
+    const batch = this.batches.get(batchKey);
+    if (!batch) return null;
+    const instanceId = batch.entityMap.get(entity.uuid);
+    if (instanceId === void 0) return null;
+    return { batchKey, instanceId };
+  }
+  /**
+   * Get statistics about current batching
+   */
+  getStats() {
+    let totalInstances = 0;
+    const batches = [];
+    for (const [key, batch] of this.batches) {
+      const count = batch.entityMap.size;
+      totalInstances += count;
+      batches.push({ key, count, capacity: batch.capacity });
+    }
+    return { batchCount: this.batches.size, totalInstances, batches };
+  }
+  /**
+   * Dispose all batches and release resources
+   */
+  dispose() {
+    for (const batch of this.batches.values()) {
+      if (this.scene) {
+        this.scene.remove(batch.instancedMesh);
+      }
+      batch.instancedMesh.dispose();
+      batch.geometry.dispose();
+    }
+    this.batches.clear();
+    this.entityToBatch.clear();
+  }
+  /**
+   * Create a new batch group
+   */
+  createBatch(key, geometry, material) {
+    const capacity = _InstanceManager.DEFAULT_CAPACITY;
+    const instancedMesh = new InstancedMesh(geometry, material, capacity);
+    instancedMesh.count = 0;
+    instancedMesh.frustumCulled = false;
+    const hiddenMatrix = new Matrix4().makeScale(0, 0, 0);
+    for (let i = 0; i < capacity; i++) {
+      instancedMesh.setMatrixAt(i, hiddenMatrix);
+    }
+    instancedMesh.instanceMatrix.needsUpdate = true;
+    const batch = {
+      key,
+      instancedMesh,
+      geometry,
+      material,
+      entityMap: /* @__PURE__ */ new Map(),
+      entities: [],
+      freeIndices: [],
+      activeIndices: [],
+      dirtyIndices: /* @__PURE__ */ new Set(),
+      capacity
+    };
+    this.batches.set(key, batch);
+    if (this.scene) {
+      this.scene.add(instancedMesh);
+    }
+    return batch;
+  }
+  /**
+   * Grow a batch's capacity
+   */
+  growBatch(batch) {
+    const newCapacity = batch.capacity * _InstanceManager.GROWTH_FACTOR;
+    const newInstancedMesh = new InstancedMesh(batch.geometry, batch.material, newCapacity);
+    newInstancedMesh.count = batch.instancedMesh.count;
+    newInstancedMesh.frustumCulled = false;
+    const matrix = new Matrix4();
+    for (let i = 0; i < batch.capacity; i++) {
+      batch.instancedMesh.getMatrixAt(i, matrix);
+      newInstancedMesh.setMatrixAt(i, matrix);
+    }
+    const hiddenMatrix = new Matrix4().makeScale(0, 0, 0);
+    for (let i = batch.capacity; i < newCapacity; i++) {
+      newInstancedMesh.setMatrixAt(i, hiddenMatrix);
+    }
+    newInstancedMesh.instanceMatrix.needsUpdate = true;
+    if (this.scene) {
+      this.scene.remove(batch.instancedMesh);
+      this.scene.add(newInstancedMesh);
+    }
+    batch.instancedMesh.dispose();
+    batch.instancedMesh = newInstancedMesh;
+    batch.capacity = newCapacity;
+  }
 };
 
 // src/lib/stage/stage-state.ts
-import { Color as Color3, Vector3 as Vector33 } from "three";
-import { proxy as proxy3, subscribe as subscribe2 } from "valtio/vanilla";
-var stageState = proxy3({
-  backgroundColor: new Color3(Color3.NAMES.cornflowerblue),
+import { Color as Color6, Vector3 as Vector311 } from "three";
+import { proxy as proxy4, subscribe as subscribe2 } from "valtio/vanilla";
+
+// src/lib/core/utility/vector.ts
+import { Color as Color5 } from "three";
+import { Vector3 as Vector310 } from "@dimforge/rapier3d-compat";
+var ZylemBlueColor = new Color5("#0333EC");
+var Vec0 = new Vector310(0, 0, 0);
+var Vec1 = new Vector310(1, 1, 1);
+
+// src/lib/stage/stage-state.ts
+var initialStageState = {
+  backgroundColor: ZylemBlueColor,
+  backgroundImage: null,
+  backgroundShader: null,
+  inputs: {
+    p1: ["gamepad-1", "keyboard"],
+    p2: ["gamepad-2", "keyboard"]
+  },
+  gravity: new Vector311(0, 0, 0),
+  variables: {},
+  entities: []
+};
+var stageState = proxy4({
+  backgroundColor: new Color6(Color6.NAMES.cornflowerblue),
   backgroundImage: null,
   inputs: {
     p1: ["gamepad-1", "keyboard-1"],
     p2: ["gamepad-2", "keyboard-2"]
   },
   variables: {},
-  gravity: new Vector33(0, 0, 0),
+  gravity: new Vector311(0, 0, 0),
   entities: []
 });
 var setStageBackgroundColor = (value) => {
@@ -1047,13 +2870,6 @@ function clearVariables(target) {
   variableProxyStore.delete(target);
 }
 
-// src/lib/core/utility/vector.ts
-import { Color as Color4 } from "three";
-import { Vector3 as Vector34 } from "@dimforge/rapier3d-compat";
-var ZylemBlueColor = new Color4("#0333EC");
-var Vec0 = new Vector34(0, 0, 0);
-var Vec1 = new Vector34(1, 1, 1);
-
 // src/lib/stage/zylem-stage.ts
 import { subscribe as subscribe4 } from "valtio/vanilla";
 
@@ -1096,34 +2912,34 @@ import { nanoid as nanoid2 } from "nanoid";
 
 // src/lib/stage/stage-debug-delegate.ts
 import { Ray } from "@dimforge/rapier3d-compat";
-import { BufferAttribute, BufferGeometry as BufferGeometry2, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 } from "three";
+import { BufferAttribute, BufferGeometry as BufferGeometry3, LineBasicMaterial as LineBasicMaterial2, LineSegments as LineSegments2, Raycaster, Vector2 as Vector23 } from "three";
 
 // src/lib/stage/debug-entity-cursor.ts
 import {
   Box3,
-  BoxGeometry,
-  Color as Color5,
+  BoxGeometry as BoxGeometry2,
+  Color as Color7,
   EdgesGeometry,
   Group as Group3,
   LineBasicMaterial,
   LineSegments,
-  Mesh as Mesh2,
+  Mesh as Mesh4,
   MeshBasicMaterial,
-  Vector3 as Vector35
+  Vector3 as Vector312
 } from "three";
 var DebugEntityCursor = class {
   scene;
   container;
   fillMesh;
   edgeLines;
-  currentColor = new Color5(65280);
+  currentColor = new Color7(65280);
   bbox = new Box3();
-  size = new Vector35();
-  center = new Vector35();
+  size = new Vector312();
+  center = new Vector312();
   constructor(scene) {
     this.scene = scene;
-    const initialGeometry = new BoxGeometry(1, 1, 1);
-    this.fillMesh = new Mesh2(
+    const initialGeometry = new BoxGeometry2(1, 1, 1);
+    this.fillMesh = new Mesh4(
       initialGeometry,
       new MeshBasicMaterial({
         color: this.currentColor,
@@ -1164,7 +2980,7 @@ var DebugEntityCursor = class {
     }
     this.bbox.getSize(this.size);
     this.bbox.getCenter(this.center);
-    const newGeom = new BoxGeometry(
+    const newGeom = new BoxGeometry2(
       Math.max(this.size.x, 1e-6),
       Math.max(this.size.y, 1e-6),
       Math.max(this.size.z, 1e-6)
@@ -1195,7 +3011,7 @@ var DELETE_TOOL_COLOR = 16724787;
 var StageDebugDelegate = class {
   stage;
   options;
-  mouseNdc = new Vector2(-2, -2);
+  mouseNdc = new Vector23(-2, -2);
   raycaster = new Raycaster();
   isMouseDown = false;
   disposeFns = [];
@@ -1207,20 +3023,39 @@ var StageDebugDelegate = class {
       maxRayDistance: options?.maxRayDistance ?? 5e3,
       addEntityFactory: options?.addEntityFactory ?? null
     };
-    if (this.stage.scene) {
-      this.debugLines = new LineSegments2(
-        new BufferGeometry2(),
-        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();
   }
+  initDebugVisuals() {
+    if (this.debugLines || !this.stage.scene) return;
+    this.debugLines = new LineSegments2(
+      new BufferGeometry3(),
+      new LineBasicMaterial2({ vertexColors: true })
+    );
+    this.stage.scene.scene.add(this.debugLines);
+    this.debugLines.visible = true;
+    this.debugCursor = new DebugEntityCursor(this.stage.scene.scene);
+  }
+  disposeDebugVisuals() {
+    if (this.debugLines && this.stage.scene) {
+      this.stage.scene.scene.remove(this.debugLines);
+      this.debugLines.geometry.dispose();
+      this.debugLines.material.dispose();
+      this.debugLines = null;
+    }
+    this.debugCursor?.dispose();
+    this.debugCursor = null;
+  }
   update() {
-    if (!debugState.enabled) return;
+    if (!debugState.enabled) {
+      if (this.debugLines) {
+        this.disposeDebugVisuals();
+      }
+      return;
+    }
     if (!this.stage.scene || !this.stage.world || !this.stage.cameraRef) return;
+    if (!this.debugLines) {
+      this.initDebugVisuals();
+    }
     const { world, cameraRef } = this.stage;
     if (this.debugLines) {
       const { vertices, colors } = world.world.debugRender();
@@ -1278,13 +3113,7 @@ var StageDebugDelegate = class {
   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;
-    }
+    this.disposeDebugVisuals();
   }
   handleActionOnHit(hoveredUuid, origin, direction, toi) {
     const tool = getDebugTool();
@@ -1363,10 +3192,10 @@ var StageCameraDebugDelegate = class {
 };
 
 // src/lib/stage/stage-camera-delegate.ts
-import { Vector2 as Vector24 } from "three";
+import { Vector2 as Vector28 } from "three";
 
 // src/lib/camera/zylem-camera.ts
-import { PerspectiveCamera, Vector3 as Vector39, Object3D as Object3D6, OrthographicCamera, WebGLRenderer as WebGLRenderer3 } from "three";
+import { PerspectiveCamera as PerspectiveCamera2, Vector3 as Vector316, Object3D as Object3D8, OrthographicCamera } from "three";
 
 // src/lib/camera/perspective.ts
 var Perspectives = {
@@ -1378,15 +3207,21 @@ var Perspectives = {
 };
 
 // src/lib/camera/third-person.ts
-import { Vector3 as Vector37 } from "three";
+import { Vector3 as Vector314 } from "three";
 var ThirdPersonCamera = class {
   distance;
   screenResolution = null;
   renderer = null;
   scene = null;
   cameraRef = null;
+  /** Padding multiplier when framing multiple targets. Higher = more zoom out. */
+  paddingFactor = 1.5;
+  /** Minimum camera distance when multi-framing (prevents extreme zoom-in). */
+  minDistance = 5;
+  /** Lerp factor for camera position smoothing. */
+  lerpFactor = 0.1;
   constructor() {
-    this.distance = new Vector37(0, 5, 8);
+    this.distance = new Vector314(0, 5, 8);
   }
   /**
    * Setup the third person camera controller
@@ -1399,15 +3234,59 @@ var ThirdPersonCamera = class {
     this.cameraRef = camera;
   }
   /**
-   * Update the third person camera
+   * Update the third person camera.
+   * Handles 0, 1, and multi-target scenarios.
    */
   update(delta) {
-    if (!this.cameraRef.target) {
+    if (!this.cameraRef) return;
+    const targets = this.cameraRef.targets;
+    if (targets.length === 0) {
+      this.cameraRef.camera.lookAt(new Vector314(0, 0, 0));
       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);
+    if (targets.length === 1) {
+      this.updateSingleTarget(targets[0]);
+      return;
+    }
+    this.updateMultiTarget(targets);
+  }
+  /**
+   * Classic single-target follow: lerp to target position + offset, lookAt target.
+   */
+  updateSingleTarget(target) {
+    const useTarget = target.group?.position || new Vector314(0, 0, 0);
+    const desiredCameraPosition = useTarget.clone().add(this.distance);
+    this.cameraRef.camera.position.lerp(desiredCameraPosition, this.lerpFactor);
+    this.cameraRef.camera.lookAt(useTarget);
+  }
+  /**
+   * Multi-target framing: compute centroid, measure spread, zoom out to fit all.
+   */
+  updateMultiTarget(targets) {
+    const centroid = new Vector314();
+    for (const t of targets) {
+      centroid.add(t.group.position);
+    }
+    centroid.divideScalar(targets.length);
+    let maxDistFromCentroid = 0;
+    for (const t of targets) {
+      const dist = centroid.distanceTo(t.group.position);
+      if (dist > maxDistFromCentroid) {
+        maxDistFromCentroid = dist;
+      }
+    }
+    const dynamicDistance = Math.max(maxDistFromCentroid * this.paddingFactor, this.minDistance);
+    const offsetDirection = this.distance.clone().normalize();
+    const desiredCameraPosition = centroid.clone().add(
+      offsetDirection.multiplyScalar(dynamicDistance)
+    );
+    const baseLen = this.distance.length();
+    if (baseLen > 0) {
+      const heightRatio = this.distance.y / baseLen;
+      desiredCameraPosition.y = centroid.y + dynamicDistance * heightRatio;
+    }
+    this.cameraRef.camera.position.lerp(desiredCameraPosition, this.lerpFactor);
+    this.cameraRef.camera.lookAt(centroid);
   }
   /**
    * Handle resize events
@@ -1418,7 +3297,7 @@ var ThirdPersonCamera = class {
     }
   }
   /**
-   * Set the distance from the target
+   * Set the distance offset from the target
    */
   setDistance(distance) {
     this.distance = distance;
@@ -1461,102 +3340,17 @@ var Fixed2DCamera = class {
   }
 };
 
-// src/lib/camera/zylem-camera.ts
-import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
-
-// src/lib/graphics/render-pass.ts
-import * as THREE from "three";
-
-// src/lib/graphics/shaders/vertex/standard.glsl
-var standard_default2 = "varying vec2 vUv;\n\nvoid main() {\n	vUv = uv;\n	gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );\n}";
-
-// src/lib/graphics/render-pass.ts
-import { WebGLRenderTarget } from "three";
-import { Pass, FullScreenQuad } from "three/addons/postprocessing/Pass.js";
-var RenderPass = class extends Pass {
-  fsQuad;
-  resolution;
-  scene;
-  camera;
-  rgbRenderTarget;
-  normalRenderTarget;
-  normalMaterial;
-  constructor(resolution, scene, camera) {
-    super();
-    this.resolution = resolution;
-    this.fsQuad = new FullScreenQuad(this.material());
-    this.scene = scene;
-    this.camera = camera;
-    this.rgbRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
-    this.normalRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
-    this.normalMaterial = new THREE.MeshNormalMaterial();
-  }
-  render(renderer, writeBuffer) {
-    renderer.setRenderTarget(this.rgbRenderTarget);
-    renderer.render(this.scene, this.camera);
-    const overrideMaterial_old = this.scene.overrideMaterial;
-    renderer.setRenderTarget(this.normalRenderTarget);
-    this.scene.overrideMaterial = this.normalMaterial;
-    renderer.render(this.scene, this.camera);
-    this.scene.overrideMaterial = overrideMaterial_old;
-    const uniforms = this.fsQuad.material.uniforms;
-    uniforms.tDiffuse.value = this.rgbRenderTarget.texture;
-    uniforms.tDepth.value = this.rgbRenderTarget.depthTexture;
-    uniforms.tNormal.value = this.normalRenderTarget.texture;
-    uniforms.iTime.value += 0.01;
-    if (this.renderToScreen) {
-      renderer.setRenderTarget(null);
-    } else {
-      renderer.setRenderTarget(writeBuffer);
-    }
-    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 Vector38 } from "three";
+import { Vector3 as Vector315 } from "three";
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
 var CameraOrbitController = class {
   camera;
   domElement;
+  cameraRig = null;
+  sceneRef = null;
   orbitControls = null;
   orbitTarget = null;
-  orbitTargetWorldPos = new Vector38();
+  orbitTargetWorldPos = new Vector315();
   debugDelegate = null;
   debugUnsubscribe = null;
   debugStateSnapshot = { enabled: false, selected: [] };
@@ -1564,16 +3358,37 @@ var CameraOrbitController = class {
   savedCameraPosition = null;
   savedCameraQuaternion = null;
   savedCameraZoom = null;
-  constructor(camera, domElement) {
+  savedCameraLocalPosition = null;
+  // Saved debug camera state for restoration when re-entering debug mode
+  savedDebugCameraPosition = null;
+  savedDebugCameraQuaternion = null;
+  savedDebugCameraZoom = null;
+  savedDebugOrbitTarget = null;
+  /** Whether user-configured orbital controls are enabled (independent of debug) */
+  _userOrbitEnabled = false;
+  constructor(camera, domElement, cameraRig) {
     this.camera = camera;
     this.domElement = domElement;
+    this.cameraRig = cameraRig ?? null;
+  }
+  /**
+   * Set the scene reference for adding/removing camera when detaching from rig.
+   */
+  setScene(scene) {
+    this.sceneRef = scene;
   }
   /**
-   * Check if debug mode is currently active (orbit controls enabled).
+   * Check if debug mode is currently active (orbit controls enabled via debug system).
    */
   get isActive() {
     return this.debugStateSnapshot.enabled;
   }
+  /**
+   * Check if any orbit controls are currently active (debug or user).
+   */
+  get isOrbitActive() {
+    return this.debugStateSnapshot.enabled || this._userOrbitEnabled;
+  }
   /**
    * Update orbit controls each frame.
    * Should be called from the camera's update loop.
@@ -1585,6 +3400,26 @@ var CameraOrbitController = class {
     }
     this.orbitControls?.update();
   }
+  /**
+   * Enable user-configured orbital controls (not debug mode).
+   * These orbit controls persist until explicitly disabled.
+   */
+  enableUserOrbitControls() {
+    this._userOrbitEnabled = true;
+    if (!this.orbitControls) {
+      this.enableOrbitControls();
+    }
+  }
+  /**
+   * Disable user-configured orbital controls.
+   * Will not disable orbit controls if debug mode is active.
+   */
+  disableUserOrbitControls() {
+    this._userOrbitEnabled = false;
+    if (!this.debugStateSnapshot.enabled) {
+      this.disableOrbitControls();
+    }
+  }
   /**
    * Attach a delegate to react to debug state changes.
    */
@@ -1626,11 +3461,17 @@ var CameraOrbitController = class {
     };
     if (state2.enabled && !wasEnabled) {
       this.saveCameraState();
+      this.detachCameraFromRig();
       this.enableOrbitControls();
+      this.restoreDebugCameraState();
       this.updateOrbitTargetFromSelection(state2.selected);
     } else if (!state2.enabled && wasEnabled) {
+      this.saveDebugCameraState();
       this.orbitTarget = null;
-      this.disableOrbitControls();
+      if (!this._userOrbitEnabled) {
+        this.disableOrbitControls();
+      }
+      this.reattachCameraToRig();
       this.restoreCameraState();
     } else if (state2.enabled) {
       this.updateOrbitTargetFromSelection(state2.selected);
@@ -1716,76 +3557,488 @@ var CameraOrbitController = class {
       this.savedCameraZoom = null;
     }
   }
-};
-
-// src/lib/camera/zylem-camera.ts
-var ZylemCamera = class {
-  cameraRig = null;
-  camera;
-  screenResolution;
+  /**
+   * Save debug camera state when exiting debug mode.
+   */
+  saveDebugCameraState() {
+    this.savedDebugCameraPosition = this.camera.position.clone();
+    this.savedDebugCameraQuaternion = this.camera.quaternion.clone();
+    if ("zoom" in this.camera) {
+      this.savedDebugCameraZoom = this.camera.zoom;
+    }
+    if (this.orbitControls) {
+      this.savedDebugOrbitTarget = this.orbitControls.target.clone();
+    }
+  }
+  /**
+   * Restore debug camera state when re-entering debug mode.
+   */
+  restoreDebugCameraState() {
+    if (this.savedDebugCameraPosition) {
+      this.camera.position.copy(this.savedDebugCameraPosition);
+    }
+    if (this.savedDebugCameraQuaternion) {
+      this.camera.quaternion.copy(this.savedDebugCameraQuaternion);
+    }
+    if (this.savedDebugCameraZoom !== null && "zoom" in this.camera) {
+      this.camera.zoom = this.savedDebugCameraZoom;
+      this.camera.updateProjectionMatrix?.();
+    }
+    if (this.savedDebugOrbitTarget && this.orbitControls) {
+      this.orbitControls.target.copy(this.savedDebugOrbitTarget);
+    }
+  }
+  /**
+   * Detach camera from its rig to allow free orbit movement in debug mode.
+   * Preserves the camera's world position.
+   */
+  detachCameraFromRig() {
+    if (!this.cameraRig || this.camera.parent !== this.cameraRig) {
+      return;
+    }
+    this.savedCameraLocalPosition = this.camera.position.clone();
+    const worldPos = new Vector315();
+    this.camera.getWorldPosition(worldPos);
+    this.cameraRig.remove(this.camera);
+    if (this.sceneRef) {
+      this.sceneRef.add(this.camera);
+    }
+    this.camera.position.copy(worldPos);
+  }
+  /**
+   * Reattach camera to its rig when exiting debug mode.
+   * Restores the camera's local position relative to the rig.
+   */
+  reattachCameraToRig() {
+    if (!this.cameraRig || this.camera.parent === this.cameraRig) {
+      return;
+    }
+    if (this.sceneRef && this.camera.parent === this.sceneRef) {
+      this.sceneRef.remove(this.camera);
+    }
+    this.cameraRig.add(this.camera);
+    if (this.savedCameraLocalPosition) {
+      this.camera.position.copy(this.savedCameraLocalPosition);
+      this.savedCameraLocalPosition = null;
+    }
+  }
+};
+
+// src/lib/camera/renderer-manager.ts
+import { Vector2 as Vector25, WebGLRenderer as WebGLRenderer2 } from "three";
+import { WebGPURenderer } from "three/webgpu";
+import { EffectComposer } from "three/examples/jsm/postprocessing/EffectComposer.js";
+
+// src/lib/graphics/render-pass.ts
+import * as THREE from "three";
+import { WebGLRenderTarget } from "three";
+import { Pass, FullScreenQuad } from "three/addons/postprocessing/Pass.js";
+var RenderPass = class extends Pass {
+  fsQuad;
+  resolution;
+  scene;
+  camera;
+  rgbRenderTarget;
+  normalRenderTarget;
+  normalMaterial;
+  constructor(resolution, scene, camera) {
+    super();
+    this.resolution = resolution;
+    this.fsQuad = new FullScreenQuad(this.material());
+    this.scene = scene;
+    this.camera = camera;
+    this.rgbRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
+    this.normalRenderTarget = new WebGLRenderTarget(resolution.x * 4, resolution.y * 4);
+    this.normalMaterial = new THREE.MeshNormalMaterial();
+  }
+  render(renderer, writeBuffer) {
+    renderer.setRenderTarget(this.rgbRenderTarget);
+    renderer.render(this.scene, this.camera);
+    const overrideMaterial_old = this.scene.overrideMaterial;
+    renderer.setRenderTarget(this.normalRenderTarget);
+    this.scene.overrideMaterial = this.normalMaterial;
+    renderer.render(this.scene, this.camera);
+    this.scene.overrideMaterial = overrideMaterial_old;
+    const uniforms = this.fsQuad.material.uniforms;
+    uniforms.tDiffuse.value = this.rgbRenderTarget.texture;
+    uniforms.tDepth.value = this.rgbRenderTarget.depthTexture;
+    uniforms.tNormal.value = this.normalRenderTarget.texture;
+    uniforms.iTime.value += 0.01;
+    if (this.renderToScreen) {
+      renderer.setRenderTarget(null);
+    } else {
+      renderer.setRenderTarget(writeBuffer);
+    }
+    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: standardShader.vertex,
+      fragmentShader: standardShader.fragment
+    });
+  }
+  dispose() {
+    try {
+      this.fsQuad?.dispose?.();
+    } catch {
+    }
+    try {
+      this.rgbRenderTarget?.dispose?.();
+      this.normalRenderTarget?.dispose?.();
+    } catch {
+    }
+    try {
+      this.normalMaterial?.dispose?.();
+    } catch {
+    }
+  }
+};
+
+// src/lib/camera/renderer-manager.ts
+var DEFAULT_VIEWPORT = { x: 0, y: 0, width: 1, height: 1 };
+async function isWebGPUSupported() {
+  if (!("gpu" in navigator)) return false;
+  try {
+    const adapter = await navigator.gpu.requestAdapter();
+    return adapter !== null;
+  } catch {
+    return false;
+  }
+}
+var RendererManager = class {
   renderer;
   composer;
+  screenResolution;
+  rendererType;
+  _isWebGPU = false;
+  _initialized = false;
+  _sceneRef = null;
+  constructor(screenResolution, rendererType = "webgl") {
+    this.screenResolution = screenResolution || new Vector25(window.innerWidth, window.innerHeight);
+    this.rendererType = rendererType;
+  }
+  /**
+   * Check if the renderer has been initialized
+   */
+  get initialized() {
+    return this._initialized;
+  }
+  /**
+   * Check if using WebGPU renderer
+   */
+  get isWebGPU() {
+    return this._isWebGPU;
+  }
+  /**
+   * Initialize the renderer (must be called before rendering).
+   * Async because WebGPU requires async initialization.
+   */
+  async initRenderer() {
+    if (this._initialized) return;
+    let useWebGPU = false;
+    if (this.rendererType === "webgpu") {
+      useWebGPU = true;
+    } else if (this.rendererType === "auto") {
+      useWebGPU = await isWebGPUSupported();
+    }
+    if (useWebGPU) {
+      try {
+        this.renderer = new WebGPURenderer({ antialias: true });
+        await this.renderer.init();
+        this._isWebGPU = true;
+        console.log("RendererManager: Using WebGPU renderer");
+      } catch (e) {
+        console.warn("RendererManager: WebGPU init failed, falling back to WebGL", e);
+        this.renderer = new WebGLRenderer2({ antialias: false, alpha: true });
+        this._isWebGPU = false;
+      }
+    } else {
+      this.renderer = new WebGLRenderer2({ antialias: false, alpha: true });
+      this._isWebGPU = false;
+      console.log("RendererManager: Using WebGL renderer");
+    }
+    this.renderer.setSize(this.screenResolution.x, this.screenResolution.y);
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.shadowMap.enabled = true;
+    }
+    if (!this._isWebGPU) {
+      this.composer = new EffectComposer(this.renderer);
+    }
+    this._initialized = true;
+  }
+  /**
+   * Set the current scene reference for rendering.
+   */
+  setScene(scene) {
+    this._sceneRef = scene;
+  }
+  /**
+   * Setup post-processing render pass for a camera (WebGL only).
+   */
+  setupRenderPass(scene, camera) {
+    if (this._isWebGPU || !this.composer) return;
+    if (this.composer.passes.length > 0) {
+      this.composer.passes.forEach((p) => {
+        try {
+          p.dispose?.();
+        } catch {
+        }
+      });
+      this.composer.passes.length = 0;
+    }
+    const renderResolution = this.screenResolution.clone().divideScalar(2);
+    renderResolution.x |= 0;
+    renderResolution.y |= 0;
+    const pass = new RenderPass(renderResolution, scene, camera);
+    this.composer.addPass(pass);
+  }
+  /**
+   * Start the render loop. Calls the provided callback each frame.
+   */
+  startRenderLoop(onFrame) {
+    this.renderer.setAnimationLoop((delta) => {
+      onFrame(delta || 0);
+    });
+  }
+  /**
+   * Stop the render loop.
+   */
+  stopRenderLoop() {
+    try {
+      this.renderer.setAnimationLoop(null);
+    } catch {
+    }
+  }
+  /**
+   * Render a scene from a single camera's perspective.
+   * Sets the viewport based on the camera's viewport config.
+   */
+  renderCamera(scene, camera) {
+    const vp = camera.viewport;
+    const w = this.screenResolution.x;
+    const h = this.screenResolution.y;
+    const pixelX = Math.floor(vp.x * w);
+    const pixelY = Math.floor(vp.y * h);
+    const pixelW = Math.floor(vp.width * w);
+    const pixelH = Math.floor(vp.height * h);
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setViewport(pixelX, pixelY, pixelW, pixelH);
+      this.renderer.setScissor(pixelX, pixelY, pixelW, pixelH);
+      this.renderer.setScissorTest(true);
+    }
+    if (this._isWebGPU) {
+      this.renderer.render(scene, camera.camera);
+    } else if (this.composer) {
+      this.composer.render(0);
+    }
+  }
+  /**
+   * Render a scene from multiple cameras, each with their own viewport.
+   * Cameras are rendered in order (first = bottom layer, last = top layer).
+   */
+  renderCameras(scene, cameras) {
+    if (!scene || cameras.length === 0) return;
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setScissorTest(false);
+      this.renderer.clear();
+    }
+    for (const cam of cameras) {
+      this.renderCamera(scene, cam);
+    }
+    if (this.renderer instanceof WebGLRenderer2) {
+      this.renderer.setScissorTest(false);
+    }
+  }
+  /**
+   * Simple single-camera render (backwards compatible).
+   * Uses the full viewport for a single camera.
+   */
+  render(scene, camera) {
+    if (this._isWebGPU) {
+      this.renderer.render(scene, camera);
+    } else if (this.composer) {
+      this.composer.render(0);
+    }
+  }
+  /**
+   * Resize the renderer and update resolution.
+   */
+  resize(width, height) {
+    this.screenResolution.set(width, height);
+    this.renderer.setSize(width, height, false);
+    if (this.composer) {
+      this.composer.setSize(width, height);
+    }
+  }
+  /**
+   * Update renderer pixel ratio (DPR).
+   */
+  setPixelRatio(dpr) {
+    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
+    this.renderer.setPixelRatio(safe);
+  }
+  /**
+   * Get the DOM element for the renderer.
+   */
+  getDomElement() {
+    return this.renderer.domElement;
+  }
+  /**
+   * Dispose renderer, composer, and related resources.
+   */
+  dispose() {
+    this.stopRenderLoop();
+    try {
+      this.composer?.passes?.forEach((p) => p.dispose?.());
+      this.composer?.dispose?.();
+    } catch {
+    }
+    try {
+      this.renderer.dispose();
+    } catch {
+    }
+    this._sceneRef = null;
+    this._initialized = false;
+  }
+};
+
+// src/lib/camera/zylem-camera.ts
+var ZylemCamera = class {
+  cameraRig = null;
+  camera;
+  screenResolution;
   _perspective;
-  target = null;
-  sceneRef = null;
   frustumSize = 10;
+  rendererType;
+  sceneRef = null;
+  /** Name for camera manager lookup */
+  name = "";
+  /**
+   * Viewport in normalized coordinates (0-1).
+   * Default is fullscreen: { x: 0, y: 0, width: 1, height: 1 }
+   */
+  viewport = { ...DEFAULT_VIEWPORT };
+  /**
+   * Multiple targets for the camera to follow/frame.
+   * Replaces the old single `target` property.
+   */
+  targets = [];
+  /**
+   * @deprecated Use `targets` array instead. This getter/setter is kept for backward compatibility.
+   */
+  get target() {
+    return this.targets.length > 0 ? this.targets[0] : null;
+  }
+  set target(entity) {
+    if (entity) {
+      if (this.targets.length === 0) {
+        this.targets.push(entity);
+      } else {
+        this.targets[0] = entity;
+      }
+    } else {
+      this.targets = [];
+    }
+  }
   // Perspective controller delegation
   perspectiveController = null;
-  // Debug/orbit controls delegation
+  // Orbit controls
   orbitController = null;
-  constructor(perspective, screenResolution, frustumSize = 10) {
+  _useOrbitalControls = false;
+  /** Reference to the shared renderer manager (set during setup) */
+  _rendererManager = null;
+  constructor(perspective, screenResolution, frustumSize = 10, rendererType = "webgl") {
     this._perspective = perspective;
     this.screenResolution = screenResolution;
     this.frustumSize = frustumSize;
-    this.renderer = new WebGLRenderer3({ antialias: false, alpha: true });
-    this.renderer.setSize(screenResolution.x, screenResolution.y);
-    this.renderer.shadowMap.enabled = true;
-    this.composer = new EffectComposer(this.renderer);
+    this.rendererType = rendererType;
     const aspectRatio = screenResolution.x / screenResolution.y;
     this.camera = this.createCameraForPerspective(aspectRatio);
     if (this.needsRig()) {
-      this.cameraRig = new Object3D6();
+      this.cameraRig = new Object3D8();
       this.cameraRig.position.set(0, 3, 10);
       this.cameraRig.add(this.camera);
-      this.camera.lookAt(new Vector39(0, 2, 0));
+      this.camera.lookAt(new Vector316(0, 2, 0));
     } else {
       this.camera.position.set(0, 0, 10);
-      this.camera.lookAt(new Vector39(0, 0, 0));
+      this.camera.lookAt(new Vector316(0, 0, 0));
     }
     this.initializePerspectiveController();
-    this.orbitController = new CameraOrbitController(this.camera, this.renderer.domElement);
   }
   /**
-   * Setup the camera with a scene
+   * Setup the camera with a scene and renderer manager.
+   * The renderer manager provides shared rendering infrastructure.
    */
-  async setup(scene) {
+  async setup(scene, rendererManager) {
     this.sceneRef = scene;
-    let renderResolution = this.screenResolution.clone().divideScalar(2);
-    renderResolution.x |= 0;
-    renderResolution.y |= 0;
-    const pass = new RenderPass(renderResolution, scene, this.camera);
-    this.composer.addPass(pass);
-    if (this.perspectiveController) {
+    if (rendererManager) {
+      this._rendererManager = rendererManager;
+    }
+    if (this._rendererManager && !this._rendererManager.initialized) {
+      await this._rendererManager.initRenderer();
+    }
+    if (this.perspectiveController && this._rendererManager) {
       this.perspectiveController.setup({
         screenResolution: this.screenResolution,
-        renderer: this.renderer,
+        renderer: this._rendererManager.renderer,
         scene,
         camera: this
       });
     }
-    this.renderer.setAnimationLoop((delta) => {
-      this.update(delta || 0);
-    });
+    if (this._rendererManager) {
+      this.orbitController = new CameraOrbitController(
+        this.camera,
+        this._rendererManager.renderer.domElement,
+        this.cameraRig
+      );
+      this.orbitController.setScene(scene);
+      if (this._useOrbitalControls) {
+        this.orbitController.enableUserOrbitControls();
+      }
+    }
   }
   /**
-   * Update camera and render
+   * Legacy setup method for backward compatibility.
+   * Creates a temporary RendererManager internally.
+   * @deprecated Use setup(scene, rendererManager) instead.
+   */
+  async setupLegacy(scene) {
+    if (!this._rendererManager) {
+      this._rendererManager = new RendererManager(this.screenResolution, this.rendererType);
+      await this._rendererManager.initRenderer();
+      this._rendererManager.setupRenderPass(scene, this.camera);
+      this._rendererManager.startRenderLoop((delta) => {
+        this.update(delta);
+        if (this._rendererManager && this.sceneRef) {
+          this._rendererManager.render(this.sceneRef, this.camera);
+        }
+      });
+    }
+    await this.setup(scene, this._rendererManager);
+  }
+  /**
+   * Update camera controllers (called each frame).
+   * Does NOT render -- rendering is handled by RendererManager.
    */
   update(delta) {
     this.orbitController?.update();
-    if (this.perspectiveController && !this.isDebugModeActive()) {
+    if (this.perspectiveController && !this.isDebugModeActive() && !this._useOrbitalControls) {
       this.perspectiveController.update(delta);
     }
-    this.composer.render(delta);
   }
   /**
    * Check if debug mode is active (orbit controls taking over camera)
@@ -1794,27 +4047,59 @@ var ZylemCamera = class {
     return this.orbitController?.isActive ?? false;
   }
   /**
-   * Dispose renderer, composer, controls, and detach from scene
+   * Enable user-configured orbital controls (not debug mode).
    */
-  destroy() {
-    try {
-      this.renderer.setAnimationLoop(null);
-    } catch {
-    }
-    try {
-      this.orbitController?.dispose();
-    } catch {
+  enableOrbitalControls() {
+    this._useOrbitalControls = true;
+    this.orbitController?.enableUserOrbitControls();
+  }
+  /**
+   * Disable user-configured orbital controls.
+   */
+  disableOrbitalControls() {
+    this._useOrbitalControls = false;
+    this.orbitController?.disableUserOrbitControls();
+  }
+  /**
+   * Whether user orbital controls are enabled.
+   */
+  get useOrbitalControls() {
+    return this._useOrbitalControls;
+  }
+  /**
+   * Add a target entity for the camera to follow/frame.
+   */
+  addTarget(entity) {
+    if (!this.targets.includes(entity)) {
+      this.targets.push(entity);
     }
-    try {
-      this.composer?.passes?.forEach((p) => p.dispose?.());
-      this.composer?.dispose?.();
-    } catch {
+  }
+  /**
+   * Remove a target entity.
+   */
+  removeTarget(entity) {
+    const index = this.targets.indexOf(entity);
+    if (index !== -1) {
+      this.targets.splice(index, 1);
     }
+  }
+  /**
+   * Clear all targets.
+   */
+  clearTargets() {
+    this.targets = [];
+  }
+  /**
+   * Dispose camera resources (not the renderer -- that's managed by RendererManager).
+   */
+  destroy() {
     try {
-      this.renderer.dispose();
+      this.orbitController?.dispose();
     } catch {
     }
     this.sceneRef = null;
+    this.targets = [];
+    this._rendererManager = null;
   }
   /**
    * Attach a delegate to react to debug state changes.
@@ -1823,13 +4108,11 @@ var ZylemCamera = class {
     this.orbitController?.setDebugDelegate(delegate);
   }
   /**
-   * Resize camera and renderer
+   * Resize camera projection.
    */
   resize(width, height) {
     this.screenResolution.set(width, height);
-    this.renderer.setSize(width, height, false);
-    this.composer.setSize(width, height);
-    if (this.camera instanceof PerspectiveCamera) {
+    if (this.camera instanceof PerspectiveCamera2) {
       this.camera.aspect = width / height;
       this.camera.updateProjectionMatrix();
     }
@@ -1838,111 +4121,362 @@ var ZylemCamera = class {
     }
   }
   /**
-   * Update renderer pixel ratio (DPR)
+   * Set the viewport for this camera (normalized 0-1 coordinates).
+   */
+  setViewport(x, y, width, height) {
+    this.viewport = { x, y, width, height };
+  }
+  /**
+   * Create camera based on perspective type
+   */
+  createCameraForPerspective(aspectRatio) {
+    switch (this._perspective) {
+      case Perspectives.ThirdPerson:
+        return this.createThirdPersonCamera(aspectRatio);
+      case Perspectives.FirstPerson:
+        return this.createFirstPersonCamera(aspectRatio);
+      case Perspectives.Isometric:
+        return this.createIsometricCamera(aspectRatio);
+      case Perspectives.Flat2D:
+        return this.createFlat2DCamera(aspectRatio);
+      case Perspectives.Fixed2D:
+        return this.createFixed2DCamera(aspectRatio);
+      default:
+        return this.createThirdPersonCamera(aspectRatio);
+    }
+  }
+  /**
+   * Initialize perspective-specific controller
+   */
+  initializePerspectiveController() {
+    switch (this._perspective) {
+      case Perspectives.ThirdPerson:
+        this.perspectiveController = new ThirdPersonCamera();
+        break;
+      case Perspectives.Fixed2D:
+        this.perspectiveController = new Fixed2DCamera();
+        break;
+      default:
+        this.perspectiveController = new ThirdPersonCamera();
+    }
+  }
+  createThirdPersonCamera(aspectRatio) {
+    return new PerspectiveCamera2(75, aspectRatio, 0.1, 1e3);
+  }
+  createFirstPersonCamera(aspectRatio) {
+    return new PerspectiveCamera2(75, aspectRatio, 0.1, 1e3);
+  }
+  createIsometricCamera(aspectRatio) {
+    return new OrthographicCamera(
+      this.frustumSize * aspectRatio / -2,
+      this.frustumSize * aspectRatio / 2,
+      this.frustumSize / 2,
+      this.frustumSize / -2,
+      1,
+      1e3
+    );
+  }
+  createFlat2DCamera(aspectRatio) {
+    return new OrthographicCamera(
+      this.frustumSize * aspectRatio / -2,
+      this.frustumSize * aspectRatio / 2,
+      this.frustumSize / 2,
+      this.frustumSize / -2,
+      1,
+      1e3
+    );
+  }
+  createFixed2DCamera(aspectRatio) {
+    return this.createFlat2DCamera(aspectRatio);
+  }
+  // Movement methods
+  moveCamera(position2) {
+    if (this._perspective === Perspectives.Flat2D || this._perspective === Perspectives.Fixed2D) {
+      this.frustumSize = 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) {
+    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.
+   * @deprecated Access via RendererManager instead.
+   */
+  getDomElement() {
+    if (this._rendererManager) {
+      return this._rendererManager.getDomElement();
+    }
+    throw new Error("ZylemCamera: No renderer manager available. Call setup() first.");
+  }
+  /**
+   * Get the renderer manager reference.
+   */
+  getRendererManager() {
+    return this._rendererManager;
+  }
+  /**
+   * Set the renderer manager reference (used by CameraManager during setup).
+   */
+  setRendererManager(manager) {
+    this._rendererManager = manager;
+  }
+  // ─── Legacy compatibility methods ────────────────────────────────────────
+  /**
+   * @deprecated Renderer is now owned by RendererManager
+   */
+  get renderer() {
+    return this._rendererManager?.renderer;
+  }
+  /**
+   * @deprecated Composer is now owned by RendererManager
+   */
+  get composer() {
+    return this._rendererManager?.composer;
+  }
+  /**
+   * @deprecated Use RendererManager.setPixelRatio() instead
+   */
+  setPixelRatio(dpr) {
+    this._rendererManager?.setPixelRatio(dpr);
+  }
+};
+
+// src/lib/camera/camera-manager.ts
+import { Vector2 as Vector27 } from "three";
+var CameraManager = class {
+  /** Named camera registry */
+  cameras = /* @__PURE__ */ new Map();
+  /** Currently active cameras, ordered by render layer (first = bottom) */
+  _activeCameras = [];
+  /** Auto-created debug camera with orbit controls */
+  _debugCamera = null;
+  /** Reference to the shared renderer manager */
+  _rendererManager = null;
+  /** Scene reference */
+  _sceneRef = null;
+  /** Counter for auto-generated camera names */
+  _autoNameCounter = 0;
+  constructor() {
+  }
+  /**
+   * Get the list of currently active cameras.
+   */
+  get activeCameras() {
+    return this._activeCameras;
+  }
+  /**
+   * Get the primary active camera (first in the active list).
+   */
+  get primaryCamera() {
+    return this._activeCameras.length > 0 ? this._activeCameras[0] : null;
+  }
+  /**
+   * Get the debug camera.
+   */
+  get debugCamera() {
+    return this._debugCamera;
+  }
+  /**
+   * Get all registered cameras.
+   */
+  get allCameras() {
+    return Array.from(this.cameras.values());
+  }
+  /**
+   * Add a camera to the manager.
+   * If no name is provided, one is auto-generated.
+   * The first camera added becomes the active camera.
+   *
+   * @param camera The ZylemCamera instance to add
+   * @param name Optional name for lookup
+   * @returns The assigned name
+   */
+  addCamera(camera, name) {
+    const resolvedName = name || camera.name || `camera_${this._autoNameCounter++}`;
+    camera.name = resolvedName;
+    this.cameras.set(resolvedName, camera);
+    if (this._activeCameras.length === 0) {
+      this._activeCameras.push(camera);
+    }
+    return resolvedName;
+  }
+  /**
+   * Remove a camera by name or reference.
+   * Cannot remove the debug camera via this method.
+   */
+  removeCamera(nameOrRef) {
+    let name;
+    if (typeof nameOrRef === "string") {
+      name = nameOrRef;
+    } else {
+      for (const [key, cam] of this.cameras.entries()) {
+        if (cam === nameOrRef) {
+          name = key;
+          break;
+        }
+      }
+    }
+    if (!name) return false;
+    const camera = this.cameras.get(name);
+    if (!camera) return false;
+    if (camera === this._debugCamera) {
+      console.warn("CameraManager: Cannot remove the debug camera");
+      return false;
+    }
+    this.cameras.delete(name);
+    const activeIndex = this._activeCameras.indexOf(camera);
+    if (activeIndex !== -1) {
+      this._activeCameras.splice(activeIndex, 1);
+    }
+    return true;
+  }
+  /**
+   * Set a camera as the primary active camera (replaces all active cameras
+   * except additional viewport cameras).
+   *
+   * @param nameOrRef Camera name or reference to activate
+   */
+  setActiveCamera(nameOrRef) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) {
+      console.warn(`CameraManager: Camera not found: ${nameOrRef}`);
+      return false;
+    }
+    const pipCameras = this._activeCameras.filter((c) => {
+      return c !== this._activeCameras[0] && c.viewport.width < 1;
+    });
+    this._activeCameras = [camera, ...pipCameras];
+    return true;
+  }
+  /**
+   * Add a camera as an additional active camera (for split-screen or PiP).
+   */
+  addActiveCamera(nameOrRef) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) return false;
+    if (!this._activeCameras.includes(camera)) {
+      this._activeCameras.push(camera);
+    }
+    return true;
+  }
+  /**
+   * Remove a camera from the active render list (does not remove from registry).
+   */
+  deactivateCamera(nameOrRef) {
+    const camera = this.resolveCamera(nameOrRef);
+    if (!camera) return false;
+    const index = this._activeCameras.indexOf(camera);
+    if (index !== -1) {
+      this._activeCameras.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Get a camera by name.
    */
-  setPixelRatio(dpr) {
-    const safe = Math.max(1, Number.isFinite(dpr) ? dpr : 1);
-    this.renderer.setPixelRatio(safe);
+  getCamera(name) {
+    return this.cameras.get(name) ?? null;
   }
   /**
-   * Create camera based on perspective type
+   * Setup all cameras with the given scene and renderer manager.
+   * Also creates the debug camera.
    */
-  createCameraForPerspective(aspectRatio) {
-    switch (this._perspective) {
-      case Perspectives.ThirdPerson:
-        return this.createThirdPersonCamera(aspectRatio);
-      case Perspectives.FirstPerson:
-        return this.createFirstPersonCamera(aspectRatio);
-      case Perspectives.Isometric:
-        return this.createIsometricCamera(aspectRatio);
-      case Perspectives.Flat2D:
-        return this.createFlat2DCamera(aspectRatio);
-      case Perspectives.Fixed2D:
-        return this.createFixed2DCamera(aspectRatio);
-      default:
-        return this.createThirdPersonCamera(aspectRatio);
+  async setup(scene, rendererManager) {
+    this._sceneRef = scene;
+    this._rendererManager = rendererManager;
+    this.createDebugCamera(rendererManager.screenResolution);
+    for (const camera of this.cameras.values()) {
+      camera.setRendererManager(rendererManager);
+      await camera.setup(scene, rendererManager);
+    }
+    if (this._debugCamera) {
+      this._debugCamera.setRendererManager(rendererManager);
+      await this._debugCamera.setup(scene, rendererManager);
     }
   }
   /**
-   * Initialize perspective-specific controller
+   * Update all active cameras' controllers.
    */
-  initializePerspectiveController() {
-    switch (this._perspective) {
-      case Perspectives.ThirdPerson:
-        this.perspectiveController = new ThirdPersonCamera();
-        break;
-      case Perspectives.Fixed2D:
-        this.perspectiveController = new Fixed2DCamera();
-        break;
-      default:
-        this.perspectiveController = new ThirdPersonCamera();
+  update(delta) {
+    for (const camera of this._activeCameras) {
+      camera.update(delta);
     }
   }
-  createThirdPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
-  }
-  createFirstPersonCamera(aspectRatio) {
-    return new PerspectiveCamera(75, aspectRatio, 0.1, 1e3);
-  }
-  createIsometricCamera(aspectRatio) {
-    return new OrthographicCamera(
-      this.frustumSize * aspectRatio / -2,
-      this.frustumSize * aspectRatio / 2,
-      this.frustumSize / 2,
-      this.frustumSize / -2,
-      1,
-      1e3
-    );
-  }
-  createFlat2DCamera(aspectRatio) {
-    return new OrthographicCamera(
-      this.frustumSize * aspectRatio / -2,
-      this.frustumSize * aspectRatio / 2,
-      this.frustumSize / 2,
-      this.frustumSize / -2,
-      1,
-      1e3
-    );
-  }
-  createFixed2DCamera(aspectRatio) {
-    return this.createFlat2DCamera(aspectRatio);
+  /**
+   * Render all active cameras through the renderer manager.
+   */
+  render(scene) {
+    if (!this._rendererManager || this._activeCameras.length === 0) return;
+    this._rendererManager.renderCameras(scene, this._activeCameras);
   }
-  // Movement methods
-  moveCamera(position2) {
-    if (this._perspective === Perspectives.Flat2D || this._perspective === Perspectives.Fixed2D) {
-      this.frustumSize = 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);
+  /**
+   * Create a default third-person camera if no cameras have been added.
+   */
+  ensureDefaultCamera() {
+    if (this.cameras.size === 0 || this._activeCameras.length === 0) {
+      const screenRes = this._rendererManager?.screenResolution || new Vector27(window.innerWidth, window.innerHeight);
+      const defaultCam = new ZylemCamera(Perspectives.ThirdPerson, screenRes);
+      this.addCamera(defaultCam, "default");
+      return defaultCam;
     }
+    return this._activeCameras[0];
   }
-  move(position2) {
-    this.moveCamera(position2);
-  }
-  rotate(pitch, yaw, 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);
+  /**
+   * Dispose all cameras and cleanup.
+   */
+  dispose() {
+    for (const camera of this.cameras.values()) {
+      camera.destroy();
     }
+    this._debugCamera?.destroy();
+    this.cameras.clear();
+    this._activeCameras = [];
+    this._debugCamera = null;
+    this._rendererManager = null;
+    this._sceneRef = null;
   }
   /**
-   * Check if this perspective type needs a camera rig
+   * Create the always-available debug camera with orbit controls.
    */
-  needsRig() {
-    return this._perspective === Perspectives.ThirdPerson;
+  createDebugCamera(screenResolution) {
+    this._debugCamera = new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
+    this._debugCamera.name = "__debug__";
+    this._debugCamera.enableOrbitalControls();
   }
   /**
-   * Get the DOM element for the renderer
+   * Resolve a camera from a name or reference.
    */
-  getDomElement() {
-    return this.renderer.domElement;
+  resolveCamera(nameOrRef) {
+    if (typeof nameOrRef === "string") {
+      return this.cameras.get(nameOrRef) ?? null;
+    }
+    for (const cam of this.cameras.values()) {
+      if (cam === nameOrRef) return cam;
+    }
+    return null;
   }
 };
 
@@ -1958,7 +4492,7 @@ var StageCameraDelegate = class {
   createDefaultCamera() {
     const width = window.innerWidth;
     const height = window.innerHeight;
-    const screenResolution = new Vector24(width, height);
+    const screenResolution = new Vector28(width, height);
     return new ZylemCamera(Perspectives.ThirdPerson, screenResolution);
   }
   /**
@@ -1978,6 +4512,32 @@ var StageCameraDelegate = class {
     }
     return this.createDefaultCamera();
   }
+  /**
+   * Build a CameraManager from stage options.
+   * Supports single camera (backward compatible) and multiple cameras.
+   * 
+   * @param cameraOverride Optional camera override from game-level config
+   * @param cameraWrappers Camera wrappers from stage options (can be single or array)
+   * @returns A CameraManager populated with the resolved cameras
+   */
+  buildCameraManager(cameraOverride, ...cameraWrappers) {
+    const manager = new CameraManager();
+    if (cameraOverride) {
+      manager.addCamera(cameraOverride, cameraOverride.name || "main");
+      return manager;
+    }
+    const validWrappers = cameraWrappers.filter((w) => w !== void 0);
+    if (validWrappers.length > 0) {
+      for (const wrapper of validWrappers) {
+        const cam = wrapper.cameraRef;
+        manager.addCamera(cam, cam.name || void 0);
+      }
+    } else {
+      const defaultCam = this.createDefaultCamera();
+      manager.addCamera(defaultCam, "default");
+    }
+    return manager;
+  }
 };
 
 // src/lib/stage/stage-loading-delegate.ts
@@ -2057,8 +4617,61 @@ var StageLoadingDelegate = class {
   }
 };
 
+// src/lib/stage/stage-entity-model-delegate.ts
+var StageEntityModelDelegate = class {
+  scene = null;
+  pendingEntities = /* @__PURE__ */ new Map();
+  modelLoadedHandler = null;
+  /**
+   * Initialize the delegate with the scene reference and start listening.
+   */
+  attach(scene) {
+    this.scene = scene;
+    this.modelLoadedHandler = (payload) => {
+      this.handleModelLoaded(payload.entityId, payload.success);
+    };
+    zylemEventBus.on("entity:model:loaded", this.modelLoadedHandler);
+  }
+  /**
+   * Register an entity for observation.
+   * When its model loads, the group will be added to the scene.
+   */
+  observe(entity) {
+    this.pendingEntities.set(entity.uuid, entity);
+  }
+  /**
+   * Unregister an entity (e.g., when removed before model loads).
+   */
+  unobserve(entityId) {
+    this.pendingEntities.delete(entityId);
+  }
+  /**
+   * Handle model loaded event - add group to scene if entity is pending.
+   */
+  handleModelLoaded(entityId, success) {
+    const entity = this.pendingEntities.get(entityId);
+    if (!entity || !success) {
+      this.pendingEntities.delete(entityId);
+      return;
+    }
+    this.scene?.addEntityGroup(entity);
+    this.pendingEntities.delete(entityId);
+  }
+  /**
+   * Cleanup all subscriptions and pending entities.
+   */
+  dispose() {
+    if (this.modelLoadedHandler) {
+      zylemEventBus.off("entity:model:loaded", this.modelLoadedHandler);
+      this.modelLoadedHandler = null;
+    }
+    this.pendingEntities.clear();
+    this.scene = null;
+  }
+};
+
 // src/lib/stage/stage-config.ts
-import { Vector3 as Vector310 } from "three";
+import { Vector3 as Vector317 } from "three";
 
 // src/lib/core/utility/options-parser.ts
 function isBaseNode(item) {
@@ -2088,10 +4701,11 @@ function isEntityInput(item) {
 
 // src/lib/stage/stage-config.ts
 var StageConfig = class {
-  constructor(inputs, backgroundColor, backgroundImage, gravity, variables) {
+  constructor(inputs, backgroundColor, backgroundImage, backgroundShader, gravity, variables) {
     this.inputs = inputs;
     this.backgroundColor = backgroundColor;
     this.backgroundImage = backgroundImage;
+    this.backgroundShader = backgroundShader;
     this.gravity = gravity;
     this.variables = variables;
   }
@@ -2104,7 +4718,8 @@ function createDefaultStageConfig() {
     },
     ZylemBlueColor,
     null,
-    new Vector310(0, 0, 0),
+    null,
+    new Vector317(0, 0, 0),
     {}
   );
 }
@@ -2113,10 +4728,10 @@ function parseStageOptions(options = []) {
   let config = {};
   const entities = [];
   const asyncEntities = [];
-  let camera;
+  const cameras = [];
   for (const item of options) {
     if (isCameraWrapper(item)) {
-      camera = item;
+      cameras.push(item);
     } else if (isBaseNode(item)) {
       entities.push(item);
     } else if (isEntityInput(item) && !isBaseNode(item)) {
@@ -2129,30 +4744,78 @@ function parseStageOptions(options = []) {
     config.inputs ?? defaults.inputs,
     config.backgroundColor ?? defaults.backgroundColor,
     config.backgroundImage ?? defaults.backgroundImage,
+    config.backgroundShader ?? defaults.backgroundShader,
     config.gravity ?? defaults.gravity,
     config.variables ?? defaults.variables
   );
-  return { config: resolvedConfig, entities, asyncEntities, camera };
+  const camera = cameras.length > 0 ? cameras[0] : void 0;
+  return { config: resolvedConfig, entities, asyncEntities, camera, cameras };
 }
 
+// src/lib/actions/capabilities/apply-transform.ts
+function applyTransformChanges(entity, store) {
+  if (!entity.body) return;
+  if (store.dirty.velocity) {
+    entity.body.setLinvel(store.velocity, true);
+  }
+  if (store.dirty.rotation) {
+    entity.body.setRotation(store.rotation, true);
+  }
+  if (store.dirty.angularVelocity) {
+    entity.body.setAngvel(store.angularVelocity, true);
+  }
+  if (store.dirty.position) {
+    const current = entity.body.translation();
+    entity.body.setTranslation(
+      {
+        x: current.x + store.position.x,
+        y: current.y + store.position.y,
+        z: current.z + store.position.z
+      },
+      true
+    );
+  }
+}
+
+// src/lib/core/vessel.ts
+var VESSEL_TYPE = /* @__PURE__ */ Symbol("vessel");
+var Vessel = class extends BaseNode {
+  static type = VESSEL_TYPE;
+  _setup(_params) {
+  }
+  async _loaded(_params) {
+  }
+  _update(_params) {
+  }
+  _destroy(_params) {
+  }
+  _cleanup(_params) {
+  }
+  create() {
+    return this;
+  }
+  /**
+   * Add one or more child entities to this vessel.
+   * Overrides parent to support multiple arguments.
+   * @returns this for chaining
+   */
+  add(...nodes) {
+    for (const node of nodes) {
+      super.add(node);
+    }
+    return this;
+  }
+};
+
 // src/lib/stage/zylem-stage.ts
 var STAGE_TYPE = "Stage";
 var ZylemStage = class extends LifeCycleBase {
   type = STAGE_TYPE;
-  state = {
-    backgroundColor: ZylemBlueColor,
-    backgroundImage: null,
-    inputs: {
-      p1: ["gamepad-1", "keyboard"],
-      p2: ["gamepad-2", "keyboard"]
-    },
-    gravity: new Vector311(0, 0, 0),
-    variables: {},
-    entities: []
-  };
+  state = { ...initialStageState };
   gravity;
   world;
   scene;
+  instanceManager = null;
   children = [];
   _childrenMap = /* @__PURE__ */ new Map();
   _removalMap = /* @__PURE__ */ new Map();
@@ -2164,16 +4827,24 @@ var ZylemStage = class extends LifeCycleBase {
   ecs = createECS();
   testSystem = null;
   transformSystem = null;
+  behaviorSystems = [];
+  registeredSystemKeys = /* @__PURE__ */ new Set();
   debugDelegate = null;
   cameraDebugDelegate = null;
   debugStateUnsubscribe = null;
   uuid;
   wrapperRef = null;
   camera;
+  cameras = [];
   cameraRef = null;
+  /** Camera manager for multi-camera support */
+  cameraManagerRef = null;
+  /** Shared renderer manager (injected by the game) */
+  rendererManager = null;
   // Delegates
   cameraDelegate;
   loadingDelegate;
+  entityModelDelegate;
   /**
    * Create a new stage.
    * @param options Stage options: partial config, camera, and initial entities or factories
@@ -2185,8 +4856,10 @@ var ZylemStage = class extends LifeCycleBase {
     this.uuid = nanoid2();
     this.cameraDelegate = new StageCameraDelegate(this);
     this.loadingDelegate = new StageLoadingDelegate();
+    this.entityModelDelegate = new StageEntityModelDelegate();
     const parsed = parseStageOptions(options);
     this.camera = parsed.camera;
+    this.cameras = parsed.cameras;
     this.children = parsed.entities;
     this.pendingEntities = parsed.asyncEntities;
     this.saveState({
@@ -2194,11 +4867,12 @@ var ZylemStage = class extends LifeCycleBase {
       inputs: parsed.config.inputs,
       backgroundColor: parsed.config.backgroundColor,
       backgroundImage: parsed.config.backgroundImage,
+      backgroundShader: parsed.config.backgroundShader,
       gravity: parsed.config.gravity,
       variables: parsed.config.variables,
       entities: []
     });
-    this.gravity = parsed.config.gravity ?? new Vector311(0, 0, 0);
+    this.gravity = parsed.config.gravity ?? new Vector318(0, 0, 0);
   }
   handleEntityImmediatelyOrQueue(entity) {
     if (this.isLoaded) {
@@ -2219,7 +4893,7 @@ var ZylemStage = class extends LifeCycleBase {
   }
   setState() {
     const { backgroundColor, backgroundImage } = this.state;
-    const color = backgroundColor instanceof Color7 ? backgroundColor : new Color7(backgroundColor);
+    const color = backgroundColor instanceof Color9 ? backgroundColor : new Color9(backgroundColor);
     setStageBackgroundColor(color);
     setStageBackgroundImage(backgroundImage);
     setStageVariables(this.state.variables ?? {});
@@ -2230,14 +4904,39 @@ var ZylemStage = class extends LifeCycleBase {
    * @param id DOM element id for the renderer container
    * @param camera Optional camera override
    */
-  async load(id, camera) {
+  async load(id, camera, rendererManager) {
     this.setState();
-    const zylemCamera = this.cameraDelegate.resolveCamera(camera, this.camera);
+    if (rendererManager) {
+      this.rendererManager = rendererManager;
+    }
+    if (this.rendererManager) {
+      this.cameraManagerRef = this.cameraDelegate.buildCameraManager(
+        camera,
+        ...this.cameras
+      );
+    }
+    const zylemCamera = this.cameraManagerRef?.primaryCamera ?? this.cameraDelegate.resolveCamera(camera, this.camera);
     this.cameraRef = zylemCamera;
     this.scene = new ZylemScene(id, zylemCamera, this.state);
-    const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector311(0, 0, 0));
+    const physicsWorld = await ZylemWorld.loadPhysics(this.gravity ?? new Vector318(0, 0, 0));
     this.world = new ZylemWorld(physicsWorld);
     this.scene.setup();
+    if (this.cameraManagerRef && this.rendererManager) {
+      await this.scene.setupCameraManager(this.scene.scene, this.cameraManagerRef, this.rendererManager);
+      const primaryCam = this.cameraManagerRef.primaryCamera;
+      if (primaryCam) {
+        this.rendererManager.setupRenderPass(this.scene.scene, primaryCam.camera);
+      }
+      this.rendererManager.startRenderLoop((delta) => {
+        this.cameraManagerRef?.update(delta);
+        this.cameraManagerRef?.render(this.scene.scene);
+      });
+    } else {
+      this.scene.setupCamera(this.scene.scene, zylemCamera);
+    }
+    this.entityModelDelegate.attach(this.scene);
+    this.instanceManager = new InstanceManager();
+    this.instanceManager.setScene(this.scene.scene);
     this.loadingDelegate.emitStart();
     await this.runEntityLoadGenerator();
     this.transformSystem = createTransformSystem(this);
@@ -2276,11 +4975,11 @@ var ZylemStage = class extends LifeCycleBase {
    * 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() {
+  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));
+      new Promise((resolve) => setTimeout(resolve, 0));
     }
   }
   _setup(params) {
@@ -2316,17 +5015,25 @@ var ZylemStage = class extends LifeCycleBase {
       return;
     }
     this.world.update(params);
-    this.transformSystem?.system(this.ecs);
+    for (const system of this.behaviorSystems) {
+      system.update(this.ecs, delta);
+    }
     this._childrenMap.forEach((child, eid) => {
       child.nodeUpdate({
         ...params,
         me: child
       });
+      if (child.transformStore) {
+        applyTransformChanges(child, child.transformStore);
+      }
       if (child.markedForRemoval) {
         this.removeEntityByUuid(child.uuid);
       }
     });
+    this.transformSystem?.system(this.ecs);
+    this.instanceManager?.update();
     this.scene.update({ delta });
+    this.scene.updateSkybox(delta);
   }
   outOfLoop() {
     this.debugUpdate();
@@ -2339,11 +5046,17 @@ var ZylemStage = class extends LifeCycleBase {
   }
   /** Cleanup owned resources when the stage is destroyed. */
   _destroy(params) {
+    for (const system of this.behaviorSystems) {
+      system.destroy?.(this.ecs);
+    }
+    this.behaviorSystems = [];
+    this.registeredSystemKeys.clear();
     this._childrenMap.forEach((child) => {
       try {
         child.nodeDestroy({ me: child, globals: getGlobals() });
       } catch {
       }
+      clearVariables(child);
     });
     this._childrenMap.clear();
     this._removalMap.clear();
@@ -2358,10 +5071,17 @@ var ZylemStage = class extends LifeCycleBase {
     this.debugDelegate = null;
     this.cameraRef?.setDebugDelegate(null);
     this.cameraDebugDelegate = null;
+    this.entityModelDelegate.dispose();
+    this.instanceManager?.dispose();
+    this.instanceManager = null;
+    if (this.rendererManager) {
+      this.rendererManager.stopRenderLoop();
+    }
     this.isLoaded = false;
     this.world = null;
     this.scene = null;
     this.cameraRef = null;
+    this.cameraManagerRef = null;
     this.transformSystem?.destroy(this.ecs);
     this.transformSystem = null;
     resetStageVariables();
@@ -2375,28 +5095,84 @@ var ZylemStage = class extends LifeCycleBase {
     if (!this.scene || !this.world) {
       return;
     }
+    if (child instanceof Vessel) {
+      child.create();
+      for (const childEntity of child.getChildren()) {
+        if (childEntity instanceof BaseNode) {
+          await this.spawnEntity(childEntity);
+        }
+      }
+      const vesselEid = addEntity(this.ecs);
+      child.eid = vesselEid;
+      child.nodeSetup({
+        me: child,
+        globals: getGlobals(),
+        camera: this.scene.zylemCamera
+      });
+      this.addEntityToStage(child);
+      return;
+    }
     const entity = child.create();
     const eid = addEntity(this.ecs);
     entity.eid = eid;
     this.scene.addEntity(entity);
-    if (child.behaviors) {
-      for (let behavior of child.behaviors) {
-        addComponent(this.ecs, behavior.component, entity.eid);
-        const keys = Object.keys(behavior.values);
-        for (const key of keys) {
-          behavior.component[key][entity.eid] = behavior.values[key];
+    if (typeof entity.getBehaviorRefs === "function") {
+      for (const ref of entity.getBehaviorRefs()) {
+        const key = ref.descriptor.key;
+        if (!this.registeredSystemKeys.has(key)) {
+          const system = ref.descriptor.systemFactory({ world: this.world, ecs: this.ecs, scene: this.scene });
+          this.behaviorSystems.push(system);
+          this.registeredSystemKeys.add(key);
         }
       }
     }
     if (entity.colliderDesc) {
       this.world.addEntity(entity);
     }
+    for (const childNode of child.getChildren()) {
+      if (childNode instanceof BaseNode) {
+        await this.spawnEntity(childNode);
+      }
+    }
     child.nodeSetup({
       me: child,
       globals: getGlobals(),
       camera: this.scene.zylemCamera
     });
+    this.tryRegisterInstance(entity);
     this.addEntityToStage(entity);
+    this.entityModelDelegate.observe(entity);
+  }
+  /**
+   * Try to register an entity for instanced rendering.
+   * Batching is enabled by default unless explicitly disabled with batched: false.
+   */
+  tryRegisterInstance(entity) {
+    if (!this.instanceManager) return;
+    const options = entity.options;
+    if (options?.batched !== true) return;
+    if (!entity.mesh?.geometry || !entity.materials?.length) return;
+    const geometry = entity.mesh.geometry;
+    const material = entity.materials[0];
+    const entityType = entity.constructor.type?.description || "unknown";
+    const size = options.size || { x: 1, y: 1, z: 1 };
+    const matOptions = options.material || {};
+    const batchKey = InstanceManager.generateBatchKey({
+      geometryType: entityType,
+      dimensions: { x: size.x, y: size.y, z: size.z },
+      materialPath: matOptions.path || null,
+      shaderType: matOptions.shader ? "custom" : "standard",
+      colorHex: matOptions.color?.getHex?.() || 16777215
+    });
+    const instanceId = this.instanceManager.register(entity, geometry, material, batchKey);
+    if (instanceId >= 0) {
+      entity.batchKey = batchKey;
+      entity.instanceId = instanceId;
+      entity.isInstanced = true;
+      if (entity.mesh) {
+        entity.mesh.visible = false;
+      }
+    }
   }
   buildEntityState(child) {
     if (child instanceof GameEntity) {
@@ -2446,6 +5222,21 @@ var ZylemStage = class extends LifeCycleBase {
   onLoading(callback) {
     return this.loadingDelegate.onLoading(callback);
   }
+  /**
+   * Register an ECS behavior system to run each frame.
+   * @param systemOrFactory A BehaviorSystem instance or factory function
+   * @returns this for chaining
+   */
+  registerSystem(systemOrFactory) {
+    let system;
+    if (typeof systemOrFactory === "function") {
+      system = systemOrFactory({ world: this.world, ecs: this.ecs, scene: this.scene });
+    } else {
+      system = systemOrFactory;
+    }
+    this.behaviorSystems.push(system);
+    return this;
+  }
   /**
    * Remove an entity and its resources by its UUID.
    * @returns true if removed, false if not found or stage not ready
@@ -2455,6 +5246,10 @@ var ZylemStage = class extends LifeCycleBase {
     const mapEntity = this.world.collisionMap.get(uuid);
     const entity = mapEntity ?? this._debugMap.get(uuid);
     if (!entity) return false;
+    this.entityModelDelegate.unobserve(uuid);
+    if (entity.isInstanced && this.instanceManager) {
+      this.instanceManager.unregister(entity);
+    }
     this.world.destroyEntity(entity);
     if (entity.group) {
       this.scene.scene.remove(entity.group);
@@ -2486,6 +5281,35 @@ var ZylemStage = class extends LifeCycleBase {
   logMissingEntities() {
     console.warn("Zylem world or scene is null");
   }
+  // ─── Camera management forwarding ─────────────────────────────────────
+  /**
+   * Add a camera to this stage's camera manager.
+   */
+  addCamera(camera, name) {
+    if (!this.cameraManagerRef) {
+      console.warn("ZylemStage: CameraManager not available. Ensure stage is loaded with a RendererManager.");
+      return null;
+    }
+    return this.cameraManagerRef.addCamera(camera, name);
+  }
+  /**
+   * Remove a camera from this stage's camera manager.
+   */
+  removeCamera(nameOrRef) {
+    return this.cameraManagerRef?.removeCamera(nameOrRef) ?? false;
+  }
+  /**
+   * Set the active camera by name or reference.
+   */
+  setActiveCamera(nameOrRef) {
+    return this.cameraManagerRef?.setActiveCamera(nameOrRef) ?? false;
+  }
+  /**
+   * Get a camera by name from the camera manager.
+   */
+  getCamera(name) {
+    return this.cameraManagerRef?.getCamera(name) ?? null;
+  }
   /** Resize renderer viewport. */
   resize(width, height) {
     if (this.scene) {
@@ -2526,17 +5350,62 @@ var ZylemStage = class extends LifeCycleBase {
 };
 
 // src/lib/camera/camera.ts
-import { Vector2 as Vector26, Vector3 as Vector312 } from "three";
+import { Vector2 as Vector210, Vector3 as Vector319 } from "three";
 var CameraWrapper = class {
   cameraRef;
   constructor(camera) {
     this.cameraRef = camera;
   }
+  // ─── Target management ──────────────────────────────────────────────────
+  /**
+   * Add a target entity for the camera to follow/frame.
+   * With multiple targets, the camera auto-frames to include all of them.
+   */
+  addTarget(entity) {
+    this.cameraRef.addTarget(entity);
+  }
+  /**
+   * Remove a target entity from the camera.
+   */
+  removeTarget(entity) {
+    this.cameraRef.removeTarget(entity);
+  }
+  /**
+   * Clear all targets. Camera will look at world origin.
+   */
+  clearTargets() {
+    this.cameraRef.clearTargets();
+  }
+  // ─── Orbital controls ───────────────────────────────────────────────────
+  /**
+   * Enable orbital controls for this camera.
+   * Allows the user to orbit, pan, and zoom the camera.
+   */
+  enableOrbitalControls() {
+    this.cameraRef.enableOrbitalControls();
+  }
+  /**
+   * Disable orbital controls for this camera.
+   */
+  disableOrbitalControls() {
+    this.cameraRef.disableOrbitalControls();
+  }
+  // ─── Viewport ───────────────────────────────────────────────────────────
+  /**
+   * Set the viewport for this camera (normalized 0-1 coordinates).
+   * @param x Left edge (0 = left of canvas)
+   * @param y Bottom edge (0 = bottom of canvas)
+   * @param width Width as fraction of canvas
+   * @param height Height as fraction of canvas
+   */
+  setViewport(x, y, width, height) {
+    this.cameraRef.setViewport(x, y, width, height);
+  }
 };
 
 // src/lib/stage/stage-default.ts
-import { proxy as proxy4 } from "valtio/vanilla";
-import { Vector3 as Vector313 } from "three";
+import { proxy as proxy5 } from "valtio/vanilla";
+import { Vector3 as Vector320 } from "three";
 var initialDefaults = {
   backgroundColor: ZylemBlueColor,
   backgroundImage: null,
@@ -2544,10 +5413,10 @@ var initialDefaults = {
     p1: ["gamepad-1", "keyboard"],
     p2: ["gamepad-2", "keyboard"]
   },
-  gravity: new Vector313(0, 0, 0),
+  gravity: new Vector320(0, 0, 0),
   variables: {}
 };
-var stageDefaultsState = proxy4({
+var stageDefaultsState = proxy5({
   ...initialDefaults
 });
 function getStageOptions(options) {
@@ -2569,6 +5438,25 @@ function getStageDefaultConfig() {
   };
 }
 
+// src/lib/input/input-presets.ts
+var INPUT_PLAYERS = ["p1", "p2", "p3", "p4", "p5", "p6", "p7", "p8"];
+function mergeInputConfigs(...configs) {
+  const result = {};
+  for (const config of configs) {
+    for (const player of INPUT_PLAYERS) {
+      const source = config[player];
+      if (!source) continue;
+      const target = result[player] ?? {};
+      result[player] = {
+        key: { ...target.key, ...source.key },
+        mouse: { ...target.mouse, ...source.mouse },
+        includeDefaults: source.includeDefaults ?? target.includeDefaults
+      };
+    }
+  }
+  return result;
+}
+
 // src/lib/stage/stage.ts
 var Stage = class {
   wrappedStage;
@@ -2580,11 +5468,34 @@ var Stage = class {
   updateCallbacks = [];
   destroyCallbacks = [];
   pendingLoadingCallbacks = [];
+  // Event delegate for dispatch/listen API
+  eventDelegate = new EventEmitterDelegate();
+  /** Per-stage input configuration overrides. Merged with game-level defaults on stage load. */
+  inputConfig = null;
+  /**
+   * Callback set by the game to trigger input reconfiguration
+   * when this stage's input config changes at runtime.
+   * @internal
+   */
+  onInputConfigChanged = null;
   constructor(options) {
     this.options = options;
     this.wrappedStage = null;
   }
-  async load(id, camera) {
+  /**
+   * Set composable input configuration for this stage.
+   * Multiple configs are deep-merged (later configs win on key conflicts).
+   * If this stage is currently active, the change takes effect immediately.
+   * @example stage.setInputConfiguration(useArrowsForAxes('p1'), useWASDForDirections('p2'));
+   */
+  setInputConfiguration(...configs) {
+    this.inputConfig = mergeInputConfigs(...configs);
+    if (this.onInputConfigChanged) {
+      this.onInputConfigChanged();
+    }
+    return this;
+  }
+  async load(id, camera, rendererManager) {
     stageState.entities = [];
     const loadOptions = [...this.options, ...this._pendingEntities];
     this._pendingEntities = [];
@@ -2595,7 +5506,7 @@ var Stage = class {
     });
     this.pendingLoadingCallbacks = [];
     const zylemCamera = camera instanceof CameraWrapper ? camera.cameraRef : camera;
-    await this.wrappedStage.load(id, zylemCamera);
+    await this.wrappedStage.load(id, zylemCamera, rendererManager);
     this.wrappedStage.onEntityAdded((child) => {
       const next = this.wrappedStage.buildEntityState(child);
       stageState.entities = [...stageState.entities, next];
@@ -2700,6 +5611,66 @@ var Stage = class {
     const entity = this.wrappedStage?.children.find((c) => c.name === name);
     return entity;
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Camera management
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Add a camera to this stage.
+   * @param camera The ZylemCamera or CameraWrapper to add
+   * @param name Optional name for lookup
+   */
+  addCamera(camera, name) {
+    const zylemCam = camera instanceof CameraWrapper ? camera.cameraRef : camera;
+    return this.wrappedStage?.addCamera(zylemCam, name) ?? null;
+  }
+  /**
+   * Remove a camera from this stage by name or reference.
+   */
+  removeCamera(nameOrRef) {
+    if (nameOrRef instanceof CameraWrapper) {
+      return this.wrappedStage?.removeCamera(nameOrRef.cameraRef) ?? false;
+    }
+    return this.wrappedStage?.removeCamera(nameOrRef) ?? false;
+  }
+  /**
+   * Set the active camera by name or reference.
+   */
+  setActiveCamera(nameOrRef) {
+    if (nameOrRef instanceof CameraWrapper) {
+      return this.wrappedStage?.setActiveCamera(nameOrRef.cameraRef) ?? false;
+    }
+    return this.wrappedStage?.setActiveCamera(nameOrRef) ?? false;
+  }
+  /**
+   * Get a camera by name from the camera manager.
+   */
+  getCamera(name) {
+    return this.wrappedStage?.getCamera(name) ?? null;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Events API
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Dispatch an event from the stage.
+   * Events are emitted both locally and to the global event bus.
+   */
+  dispatch(event, payload) {
+    this.eventDelegate.dispatch(event, payload);
+    zylemEventBus.emit(event, payload);
+  }
+  /**
+   * Listen for events on this stage instance.
+   * @returns Unsubscribe function
+   */
+  listen(event, handler) {
+    return this.eventDelegate.listen(event, handler);
+  }
+  /**
+   * Clean up stage resources including event subscriptions.
+   */
+  dispose() {
+    this.eventDelegate.dispose();
+  }
 };
 function createStage(...options) {
   const _options = getStageOptions(options);
@@ -2707,7 +5678,7 @@ function createStage(...options) {
 }
 
 // src/lib/stage/entity-spawner.ts
-import { Euler, Quaternion as Quaternion3, Vector2 as Vector27 } from "three";
+import { Euler as Euler2, Quaternion as Quaternion5, Vector2 as Vector211 } from "three";
 function entitySpawner(factory) {
   return {
     spawn: async (stage, x, y) => {
@@ -2715,7 +5686,7 @@ function entitySpawner(factory) {
       stage.add(instance);
       return instance;
     },
-    spawnRelative: async (source, stage, offset = new Vector27(0, 1)) => {
+    spawnRelative: async (source, stage, offset = new Vector211(0, 1)) => {
       if (!source.body) {
         console.warn("body missing for entity during spawnRelative");
         return void 0;
@@ -2724,8 +5695,8 @@ 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 e = new Euler().setFromQuaternion(q, "XYZ");
+        const q = new Quaternion5(r.x, r.y, r.z, r.w);
+        const e = new Euler2().setFromQuaternion(q, "XYZ");
         rz = e.z;
       } catch {
       }