@zylem/game-lib 0.6.3 → 0.6.4

package/dist/entities.js

@@ -1,5 +1,5 @@
 // src/lib/entities/box.ts
-import { Vector3 as Vector38 } from "three";
+import { Vector3 as Vector39 } from "three";
 
 // src/lib/entities/entity.ts
 import { Mesh, ShaderMaterial, Group } from "three";
@@ -57,6 +57,8 @@ var BaseNode = class _BaseNode {
     destroy: [],
     cleanup: []
   };
+  trackLifecycleRegistrations = false;
+  userLifecycleRegistrations = [];
   constructor(args = []) {
     const options = args.filter((arg) => !(arg instanceof _BaseNode)).reduce((acc, opt) => ({ ...acc, ...opt }), {});
     this.options = options;
@@ -70,6 +72,7 @@ var BaseNode = class _BaseNode {
    */
   onSetup(...callbacks) {
     this.lifecycleCallbacks.setup.push(...callbacks);
+    this.recordLifecycleRegistration("onSetup", callbacks);
     return this;
   }
   /**
@@ -77,6 +80,7 @@ var BaseNode = class _BaseNode {
    */
   onLoaded(...callbacks) {
     this.lifecycleCallbacks.loaded.push(...callbacks);
+    this.recordLifecycleRegistration("onLoaded", callbacks);
     return this;
   }
   /**
@@ -84,6 +88,7 @@ var BaseNode = class _BaseNode {
    */
   onUpdate(...callbacks) {
     this.lifecycleCallbacks.update.push(...callbacks);
+    this.recordLifecycleRegistration("onUpdate", callbacks);
     return this;
   }
   /**
@@ -91,6 +96,7 @@ var BaseNode = class _BaseNode {
    */
   onDestroy(...callbacks) {
     this.lifecycleCallbacks.destroy.push(...callbacks);
+    this.recordLifecycleRegistration("onDestroy", callbacks);
     return this;
   }
   /**
@@ -98,6 +104,7 @@ var BaseNode = class _BaseNode {
    */
   onCleanup(...callbacks) {
     this.lifecycleCallbacks.cleanup.push(...callbacks);
+    this.recordLifecycleRegistration("onCleanup", callbacks);
     return this;
   }
   /**
@@ -105,6 +112,7 @@ var BaseNode = class _BaseNode {
    */
   prependSetup(...callbacks) {
     this.lifecycleCallbacks.setup.unshift(...callbacks);
+    this.recordLifecycleRegistration("prependSetup", callbacks);
     return this;
   }
   /**
@@ -112,6 +120,7 @@ var BaseNode = class _BaseNode {
    */
   prependUpdate(...callbacks) {
     this.lifecycleCallbacks.update.unshift(...callbacks);
+    this.recordLifecycleRegistration("prependUpdate", callbacks);
     return this;
   }
   // ─────────────────────────────────────────────────────────────────────────────
@@ -140,6 +149,42 @@ var BaseNode = class _BaseNode {
   isComposite() {
     return this.children.length > 0;
   }
+  enableUserLifecycleTracking() {
+    this.trackLifecycleRegistrations = true;
+  }
+  replayUserLifecycleRegistrationsTo(target, wrap) {
+    for (const registration of this.userLifecycleRegistrations) {
+      const callbacks = wrap ? registration.callbacks.map((callback) => wrap(callback)) : [...registration.callbacks];
+      switch (registration.method) {
+        case "onSetup":
+          target.onSetup(...callbacks);
+          break;
+        case "onLoaded":
+          target.onLoaded(...callbacks);
+          break;
+        case "onUpdate":
+          target.onUpdate(...callbacks);
+          break;
+        case "onDestroy":
+          target.onDestroy(...callbacks);
+          break;
+        case "onCleanup":
+          target.onCleanup(...callbacks);
+          break;
+        case "prependSetup":
+          target.prependSetup(...callbacks);
+          break;
+        case "prependUpdate":
+          target.prependUpdate(...callbacks);
+          break;
+      }
+    }
+  }
+  cloneChildrenInto(target) {
+    for (const child of this.children) {
+      target.add(cloneNode(child));
+    }
+  }
   // ─────────────────────────────────────────────────────────────────────────────
   // Node lifecycle execution - runs internal + callback arrays
   // ─────────────────────────────────────────────────────────────────────────────
@@ -213,7 +258,25 @@ var BaseNode = class _BaseNode {
   setOptions(options) {
     this.options = { ...this.options, ...options };
   }
+  recordLifecycleRegistration(method, callbacks) {
+    if (!this.trackLifecycleRegistrations || callbacks.length === 0) {
+      return;
+    }
+    this.userLifecycleRegistrations.push({
+      method,
+      callbacks: [...callbacks]
+    });
+  }
 };
+function cloneNode(node) {
+  const maybeClone = node?.clone;
+  if (typeof maybeClone !== "function") {
+    throw new Error(
+      `Cannot clone child node "${node.name || node.uuid || "unknown"}": missing clone() support.`
+    );
+  }
+  return maybeClone.call(node);
+}
 
 // ../../node_modules/.pnpm/mitt@3.0.1/node_modules/mitt/dist/mitt.mjs
 function mitt_default(n) {
@@ -285,10 +348,15 @@ function createTransformStore(initial) {
     rotation: { x: 0, y: 0, z: 0, w: 1 },
     velocity: { x: 0, y: 0, z: 0 },
     angularVelocity: { x: 0, y: 0, z: 0 },
+    velocityChannels: {},
     dirty: {
       position: false,
       rotation: false,
       velocity: false,
+      velocityX: false,
+      velocityY: false,
+      velocityZ: false,
+      velocityChannels: false,
       angularVelocity: false
     }
   };
@@ -305,39 +373,70 @@ function createTransformStore(initial) {
 
 // src/lib/actions/capabilities/moveable.ts
 import { Vector3 } from "three";
+
+// src/lib/actions/capabilities/velocity-intents.ts
+function setVelocityIntent(store, sourceId, vector, options = {}) {
+  const prev = store.velocityChannels[sourceId];
+  const mode = options.mode ?? prev?.mode ?? "replace";
+  const priority = options.priority ?? prev?.priority ?? 0;
+  const isAdditiveMerge = mode === "add" && prev?.mode === "add";
+  const x = vector.x == null ? prev?.x : isAdditiveMerge ? (prev?.x ?? 0) + vector.x : vector.x;
+  const y = vector.y == null ? prev?.y : isAdditiveMerge ? (prev?.y ?? 0) + vector.y : vector.y;
+  const z = vector.z == null ? prev?.z : isAdditiveMerge ? (prev?.z ?? 0) + vector.z : vector.z;
+  store.velocityChannels[sourceId] = {
+    x,
+    y,
+    z,
+    mode,
+    priority
+  };
+  store.dirty.velocityChannels = true;
+}
+function clearVelocityIntent(store, sourceId) {
+  if (!(sourceId in store.velocityChannels)) return;
+  delete store.velocityChannels[sourceId];
+  store.dirty.velocityChannels = true;
+}
+
+// src/lib/actions/capabilities/moveable.ts
 function moveX(entity, delta) {
   if (!entity.transformStore) return;
-  entity.transformStore.velocity.x = delta;
-  entity.transformStore.dirty.velocity = true;
+  setVelocityIntent(entity.transformStore, "actions", { x: delta }, { mode: "replace" });
 }
 function moveY(entity, delta) {
   if (!entity.transformStore) return;
-  entity.transformStore.velocity.y = delta;
-  entity.transformStore.dirty.velocity = true;
+  setVelocityIntent(entity.transformStore, "actions", { y: delta }, { mode: "replace" });
 }
 function moveZ(entity, delta) {
   if (!entity.transformStore) return;
-  entity.transformStore.velocity.z = delta;
-  entity.transformStore.dirty.velocity = true;
+  setVelocityIntent(entity.transformStore, "actions", { z: delta }, { mode: "replace" });
 }
 function moveXY(entity, deltaX, deltaY) {
   if (!entity.transformStore) return;
-  entity.transformStore.velocity.x = deltaX;
-  entity.transformStore.velocity.y = deltaY;
-  entity.transformStore.dirty.velocity = true;
+  setVelocityIntent(
+    entity.transformStore,
+    "actions",
+    { x: deltaX, y: deltaY },
+    { mode: "replace" }
+  );
 }
 function moveXZ(entity, deltaX, deltaZ) {
   if (!entity.transformStore) return;
-  entity.transformStore.velocity.x = deltaX;
-  entity.transformStore.velocity.z = deltaZ;
-  entity.transformStore.dirty.velocity = true;
+  setVelocityIntent(
+    entity.transformStore,
+    "actions",
+    { x: deltaX, z: deltaZ },
+    { mode: "replace" }
+  );
 }
 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;
+  setVelocityIntent(
+    entity.transformStore,
+    "actions",
+    { x: vector.x, y: vector.y, z: vector.z },
+    { mode: "add" }
+  );
 }
 function resetVelocity(entity) {
   if (!entity.body) return;
@@ -423,6 +522,17 @@ function makeMoveable(entity) {
 
 // src/lib/actions/capabilities/rotatable.ts
 import { Euler, Vector3 as Vector32, MathUtils, Quaternion as Quaternion2 } from "three";
+function syncImmediateRotation(entity) {
+  if (!entity.group || !entity.transformStore) return;
+  entity.group.setRotationFromQuaternion(
+    new Quaternion2(
+      entity.transformStore.rotation.x,
+      entity.transformStore.rotation.y,
+      entity.transformStore.rotation.z,
+      entity.transformStore.rotation.w
+    )
+  );
+}
 function rotateInDirection(entity, moveVector) {
   if (!entity.body) return;
   const rotate = Math.atan2(-moveVector.x, moveVector.z);
@@ -432,9 +542,16 @@ 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);
+  if (!entity.transformStore) return;
+  const quat = new Quaternion2().setFromEuler(
+    new Euler(rotation2.x, rotation2.y, rotation2.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;
+  syncImmediateRotation(entity);
 }
 function rotateY(entity, delta) {
   if (!entity.transformStore) return;
@@ -451,6 +568,7 @@ function rotateY(entity, delta) {
   entity.transformStore.rotation.y = newY;
   entity.transformStore.rotation.z = newZ;
   entity.transformStore.dirty.rotation = true;
+  syncImmediateRotation(entity);
 }
 function rotateX(entity, delta) {
   if (!entity.transformStore) return;
@@ -467,6 +585,7 @@ function rotateX(entity, delta) {
   entity.transformStore.rotation.y = newY;
   entity.transformStore.rotation.z = newZ;
   entity.transformStore.dirty.rotation = true;
+  syncImmediateRotation(entity);
 }
 function rotateZ(entity, delta) {
   if (!entity.transformStore) return;
@@ -483,6 +602,8 @@ function rotateZ(entity, delta) {
   entity.transformStore.rotation.y = newY;
   entity.transformStore.rotation.z = newZ;
   entity.transformStore.dirty.rotation = true;
+  entity._rotation2DAngle = (entity._rotation2DAngle ?? 0) + delta;
+  syncImmediateRotation(entity);
 }
 function setRotationY(entity, y) {
   if (!entity.transformStore) return;
@@ -494,6 +615,7 @@ function setRotationY(entity, y) {
   entity.transformStore.rotation.y = yComponent;
   entity.transformStore.rotation.z = 0;
   entity.transformStore.dirty.rotation = true;
+  syncImmediateRotation(entity);
 }
 function setRotationDegreesY(entity, y) {
   if (!entity.body) return;
@@ -509,6 +631,7 @@ function setRotationX(entity, x) {
   entity.transformStore.rotation.y = 0;
   entity.transformStore.rotation.z = 0;
   entity.transformStore.dirty.rotation = true;
+  syncImmediateRotation(entity);
 }
 function setRotationDegreesX(entity, x) {
   if (!entity.body) return;
@@ -524,6 +647,8 @@ function setRotationZ(entity, z) {
   entity.transformStore.rotation.y = 0;
   entity.transformStore.rotation.z = zComponent;
   entity.transformStore.dirty.rotation = true;
+  entity._rotation2DAngle = z;
+  syncImmediateRotation(entity);
 }
 function setRotationDegreesZ(entity, z) {
   if (!entity.body) return;
@@ -537,6 +662,8 @@ function setRotation(entity, x, y, z) {
   entity.transformStore.rotation.y = quat.y;
   entity.transformStore.rotation.z = quat.z;
   entity.transformStore.dirty.rotation = true;
+  entity._rotation2DAngle = z;
+  syncImmediateRotation(entity);
 }
 function setRotationDegrees(entity, x, y, z) {
   if (!entity.body) return;
@@ -583,7 +710,7 @@ import {
   RigidBodyDesc as RigidBodyDesc2,
   RigidBodyType as RigidBodyType2
 } from "@dimforge/rapier3d-compat";
-import { Vector3 as Vector34 } from "three";
+import { Vector3 as Vector35 } from "three";
 
 // src/lib/collision/collision-builder.ts
 import { ActiveCollisionTypes, ColliderDesc, RigidBodyDesc, RigidBodyType, Vector3 as Vector33 } from "@dimforge/rapier3d-compat";
@@ -645,10 +772,73 @@ var CollisionBuilder = class {
   }
 };
 
+// src/lib/core/clone-utils.ts
+import { Color, Vector2, Vector3 as Vector34 } from "three";
+function isPlainObject(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function deepCloneValue(value) {
+  if (value === null || value === void 0) {
+    return value;
+  }
+  if (typeof value === "function" || typeof value !== "object") {
+    return value;
+  }
+  if (value instanceof Color || value instanceof Vector2 || value instanceof Vector34) {
+    return value.clone();
+  }
+  if (value instanceof Float32Array) {
+    return new Float32Array(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => deepCloneValue(item));
+  }
+  if (isPlainObject(value)) {
+    const cloned = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (key === "_builders") {
+        continue;
+      }
+      cloned[key] = deepCloneValue(entry);
+    }
+    return cloned;
+  }
+  return value;
+}
+function deepMergeValues(base, overrides) {
+  const clonedBase = deepCloneValue(base);
+  if (!overrides) {
+    return clonedBase;
+  }
+  if (!isPlainObject(clonedBase) || !isPlainObject(overrides)) {
+    return deepCloneValue(overrides);
+  }
+  const result = clonedBase;
+  for (const [key, overrideValue] of Object.entries(overrides)) {
+    if (key === "_builders" || overrideValue === void 0) {
+      continue;
+    }
+    const currentValue = result[key];
+    if (isPlainObject(currentValue) && isPlainObject(overrideValue)) {
+      result[key] = deepMergeValues(currentValue, overrideValue);
+      continue;
+    }
+    result[key] = deepCloneValue(overrideValue);
+  }
+  return result;
+}
+
 // src/lib/entities/parts/collision-factories.ts
 function isCollisionComponent(obj) {
   return obj && obj.__kind === "collision";
 }
+function cloneCollisionComponent(component) {
+  return component.cloneComponent();
+}
 function buildBodyDesc(isStatic) {
   const type = isStatic ? RigidBodyType2.Fixed : RigidBodyType2.Dynamic;
   return new RigidBodyDesc2(type).setTranslation(0, 0, 0).setGravityScale(1).setCanSleep(false).setCcdEnabled(true);
@@ -670,57 +860,66 @@ function applyCollisionOptions(colliderDesc, opts) {
     colliderDesc.setCollisionGroups(groupId << 16 | filter);
   }
 }
-function makeComponent(colliderDesc, opts) {
+function makeComponent(colliderDesc, opts, cloneComponentFactory) {
   applyCollisionOptions(colliderDesc, opts);
   return {
     __kind: "collision",
     bodyDesc: buildBodyDesc(opts.static ?? false),
-    colliderDesc
+    colliderDesc,
+    cloneComponent: cloneComponentFactory
   };
 }
 function boxCollision(opts = {}) {
   const size = opts.size ?? { x: 1, y: 1, z: 1 };
   const desc = ColliderDesc2.cuboid(size.x / 2, size.y / 2, size.z / 2);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => boxCollision(clonedOpts));
 }
 function sphereCollision(opts = {}) {
   const desc = ColliderDesc2.ball(opts.radius ?? 1);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => sphereCollision(clonedOpts));
 }
 function coneCollision(opts = {}) {
   const radius = opts.radius ?? 1;
   const height = opts.height ?? 2;
   const desc = ColliderDesc2.cone(height / 2, radius);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => coneCollision(clonedOpts));
 }
 function pyramidCollision(opts = {}) {
   const radius = opts.radius ?? 1;
   const height = opts.height ?? 2;
   const desc = ColliderDesc2.cone(height / 2, radius);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => pyramidCollision(clonedOpts));
 }
 function cylinderCollision(opts = {}) {
   const radius = Math.max(opts.radiusTop ?? 1, opts.radiusBottom ?? 1);
   const height = opts.height ?? 2;
   const desc = ColliderDesc2.cylinder(height / 2, radius);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => cylinderCollision(clonedOpts));
 }
 function pillCollision(opts = {}) {
   const radius = opts.radius ?? 0.5;
   const length = opts.length ?? 1;
   const desc = ColliderDesc2.capsule(length / 2, radius);
-  return makeComponent(desc, opts);
+  const clonedOpts = deepCloneValue(opts);
+  return makeComponent(desc, opts, () => pillCollision(clonedOpts));
 }
 function zoneCollision(opts = {}) {
   const size = opts.size ?? { x: 1, y: 1, z: 1 };
   const desc = ColliderDesc2.cuboid(size.x / 2, size.y / 2, size.z / 2);
   desc.setSensor(true);
   desc.activeCollisionTypes = ActiveCollisionTypes2.KINEMATIC_FIXED;
-  return makeComponent(desc, { ...opts, static: opts.static ?? true, sensor: true });
+  const effectiveOpts = { ...opts, static: opts.static ?? true, sensor: true };
+  const clonedOpts = deepCloneValue(effectiveOpts);
+  return makeComponent(desc, effectiveOpts, () => zoneCollision(clonedOpts));
 }
 
 // src/lib/entities/common.ts
-import { Color, Vector3 as Vector35 } from "three";
+import { Color as Color2, Vector3 as Vector36 } from "three";
 
 // src/lib/graphics/shaders/vertex/object.shader.ts
 var objectVertexShader = `
@@ -752,9 +951,9 @@ var standardShader = {
 
 // src/lib/entities/common.ts
 var commonDefaults = {
-  position: new Vector35(0, 0, 0),
+  position: new Vector36(0, 0, 0),
   material: {
-    color: new Color("#ffffff"),
+    color: new Color2("#ffffff"),
     shader: standardShader
   },
   collision: {
@@ -773,6 +972,21 @@ function mergeArgs(args, defaults) {
 }
 
 // src/lib/entities/entity.ts
+function isCollisionRegistrationOptions(value) {
+  return value != null && typeof value === "object";
+}
+function normalizeCollisionRegistrationOptions(options) {
+  return {
+    phase: options?.phase ?? "stay",
+    cooldownMs: options?.cooldownMs
+  };
+}
+function getCollisionNowMs() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
 var GameEntity = class extends BaseNode {
   behaviors = [];
   group;
@@ -780,6 +994,7 @@ var GameEntity = class extends BaseNode {
   materials;
   bodyDesc = null;
   body = null;
+  physicsAttached = false;
   colliderDesc;
   collider;
   custom = {};
@@ -793,7 +1008,9 @@ var GameEntity = class extends BaseNode {
   debugInfo = {};
   debugMaterial;
   collisionDelegate = {
-    collision: []
+    collision: [],
+    cooldowns: /* @__PURE__ */ new Map(),
+    nextId: 0
   };
   collisionType;
   // Instancing support
@@ -807,6 +1024,9 @@ var GameEntity = class extends BaseNode {
   eventDelegate = new EventEmitterDelegate();
   // Behavior references (new ECS pattern)
   behaviorRefs = [];
+  cloneFactory = null;
+  trackAddedComponents = false;
+  trackedComponents = [];
   // Transform store for batched physics updates (auto-created in create())
   transformStore;
   // Movement & rotation methods are assigned at runtime by makeTransformable.
@@ -865,8 +1085,10 @@ var GameEntity = class extends BaseNode {
     for (const component of components) {
       if (component instanceof Mesh) {
         this.addMeshComponent(component);
+        this.trackComponent(component);
       } else if (isCollisionComponent(component)) {
         this.addCollisionComponent(component);
+        this.trackComponent(component);
       } else {
         super.add(component);
       }
@@ -907,6 +1129,22 @@ var GameEntity = class extends BaseNode {
       this.colliderDescs.push(collision.colliderDesc);
     }
   }
+  trackComponent(component) {
+    if (!this.trackAddedComponents) {
+      return;
+    }
+    if (component instanceof Mesh) {
+      this.trackedComponents.push({
+        kind: "mesh",
+        component: cloneMeshComponent(component)
+      });
+      return;
+    }
+    this.trackedComponents.push({
+      kind: "collision",
+      component: cloneCollisionComponent(component)
+    });
+  }
   // ─────────────────────────────────────────────────────────────────────────────
   // Actions API -- entity-scoped, self-contained stateful actions
   // ─────────────────────────────────────────────────────────────────────────────
@@ -942,7 +1180,7 @@ var GameEntity = class extends BaseNode {
     store.velocity.x = 0;
     store.velocity.y = 0;
     store.velocity.z = 0;
-    store.dirty.velocity = false;
+    clearVelocityIntent(store, "actions");
     store.angularVelocity.x = 0;
     store.angularVelocity.y = 0;
     store.angularVelocity.z = 0;
@@ -958,7 +1196,7 @@ var GameEntity = class extends BaseNode {
       store.velocity.x = 0;
       store.velocity.y = 0;
       store.velocity.z = 0;
-      store.dirty.velocity = false;
+      clearVelocityIntent(store, "actions");
       store.angularVelocity.x = 0;
       store.angularVelocity.y = 0;
       store.angularVelocity.z = 0;
@@ -976,12 +1214,72 @@ var GameEntity = class extends BaseNode {
     this.name = this.options.name || "";
     return this;
   }
-  /**
-   * Add collision callbacks
-   */
-  onCollision(...callbacks) {
-    const existing = this.collisionDelegate.collision ?? [];
-    this.collisionDelegate.collision = [...existing, ...callbacks];
+  clone(overrides) {
+    if (!this.cloneFactory) {
+      throw new Error(
+        `Cannot clone ${this.constructor.name}: clone() is only supported for entities created by official factory helpers.`
+      );
+    }
+    const clone = this.cloneFactory(
+      deepMergeValues(this.options, overrides)
+    );
+    const behaviorAliases = this.copyBehaviorRefsTo(clone);
+    const wrapCallback = (callback) => wrapBehaviorCallback(callback, behaviorAliases);
+    this.replayUserLifecycleRegistrationsTo(clone, wrapCallback);
+    const collisionRegistrations = this.getCollisionRegistrations();
+    if (collisionRegistrations.length > 0) {
+      for (const registration of collisionRegistrations) {
+        clone.onCollision(
+          wrapCallback(registration.callback),
+          registration.options
+        );
+      }
+    }
+    for (const trackedComponent of this.trackedComponents) {
+      if (trackedComponent.kind === "mesh") {
+        clone.add(cloneMeshComponent(trackedComponent.component));
+        continue;
+      }
+      clone.add(cloneCollisionComponent(trackedComponent.component));
+    }
+    this.cloneChildrenInto(clone);
+    return clone;
+  }
+  finalizeCloneSupport(factory) {
+    this.cloneFactory = factory;
+    this.enableUserLifecycleTracking();
+    this.trackAddedComponents = true;
+    return this;
+  }
+  onCollision(...args) {
+    const existing = [...this.collisionDelegate.collision ?? []];
+    let nextId = this.collisionDelegate.nextId ?? 0;
+    if (args.length === 1 || args.length === 2 && (args[1] == null || isCollisionRegistrationOptions(args[1]))) {
+      const callback = args[0];
+      if (!callback) {
+        return this;
+      }
+      const options = args[1];
+      existing.push({
+        id: nextId,
+        callback,
+        options: normalizeCollisionRegistrationOptions(options)
+      });
+      nextId += 1;
+      this.collisionDelegate.collision = existing;
+      this.collisionDelegate.nextId = nextId;
+      return this;
+    }
+    for (const callback of args) {
+      existing.push({
+        id: nextId,
+        callback,
+        options: normalizeCollisionRegistrationOptions()
+      });
+      nextId += 1;
+    }
+    this.collisionDelegate.collision = existing;
+    this.collisionDelegate.nextId = nextId;
     return this;
   }
   /**
@@ -1015,6 +1313,27 @@ var GameEntity = class extends BaseNode {
   getBehaviorRefs() {
     return this.behaviorRefs;
   }
+  getCollisionCallbacks() {
+    return this.getCollisionRegistrations().map((registration) => registration.callback);
+  }
+  getCollisionRegistrations() {
+    return (this.collisionDelegate.collision ?? []).map((registration) => ({
+      id: registration.id,
+      callback: registration.callback,
+      options: { ...registration.options }
+    }));
+  }
+  copyBehaviorRefsTo(target) {
+    const aliases = /* @__PURE__ */ new Map();
+    for (const ref of this.behaviorRefs) {
+      target.use(ref.descriptor, deepCloneValue(ref.options));
+      const targetRef = target.getBehaviorRefs().at(-1);
+      if (targetRef) {
+        aliases.set(ref, targetRef);
+      }
+    }
+    return aliases;
+  }
   /**
    * Entity-specific setup - resets actions for a fresh stage session.
    * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
@@ -1068,12 +1387,29 @@ var GameEntity = class extends BaseNode {
     this.debugMaterial = void 0;
     this.group?.removeFromParent();
   }
-  _collision(other, globals) {
-    if (this.collisionDelegate.collision?.length) {
-      const callbacks = this.collisionDelegate.collision;
-      callbacks.forEach((callback) => {
-        callback({ entity: this, other, globals });
-      });
+  _collision(other, globals, dispatch = {
+    phase: "stay",
+    nowMs: getCollisionNowMs()
+  }) {
+    if (!this.collisionDelegate.collision?.length) {
+      return;
+    }
+    const cooldowns = this.collisionDelegate.cooldowns ?? /* @__PURE__ */ new Map();
+    this.collisionDelegate.cooldowns = cooldowns;
+    for (const registration of this.collisionDelegate.collision) {
+      if (registration.options.phase !== dispatch.phase) {
+        continue;
+      }
+      const cooldownMs = registration.options.cooldownMs;
+      if (cooldownMs != null) {
+        const cooldownKey = `${registration.id}:${other.uuid}`;
+        const lastTriggeredAt = cooldowns.get(cooldownKey);
+        if (lastTriggeredAt != null && dispatch.nowMs - lastTriggeredAt < cooldownMs) {
+          continue;
+        }
+        cooldowns.set(cooldownKey, dispatch.nowMs);
+      }
+      registration.callback({ entity: this, other, globals });
     }
   }
   updateMaterials(params) {
@@ -1120,6 +1456,63 @@ var GameEntity = class extends BaseNode {
     this.eventDelegate.dispose();
   }
 };
+function cloneMeshComponent(mesh) {
+  const clonedMesh = mesh.clone(true);
+  const originalNodes = [];
+  const clonedNodes = [];
+  mesh.traverse((node) => originalNodes.push(node));
+  clonedMesh.traverse((node) => clonedNodes.push(node));
+  for (let i = 0; i < originalNodes.length; i++) {
+    const originalNode = originalNodes[i];
+    const clonedNode = clonedNodes[i];
+    if (originalNode?.geometry?.clone) {
+      clonedNode.geometry = originalNode.geometry.clone();
+    }
+    if (originalNode?.material) {
+      clonedNode.material = Array.isArray(originalNode.material) ? originalNode.material.map((material) => material.clone()) : originalNode.material.clone();
+    }
+  }
+  return clonedMesh;
+}
+function wrapBehaviorCallback(callback, aliases) {
+  if (aliases.size === 0) {
+    return callback;
+  }
+  return ((...args) => {
+    const previousValues = Array.from(aliases.entries()).map(([sourceRef, targetRef]) => ({
+      sourceRef,
+      options: sourceRef.options,
+      fsm: sourceRef.fsm,
+      hasFSM: Object.prototype.hasOwnProperty.call(sourceRef, "fsm"),
+      targetRef
+    }));
+    for (const entry of previousValues) {
+      entry.sourceRef.options = entry.targetRef.options;
+      if (entry.targetRef.fsm === void 0) {
+        delete entry.sourceRef.fsm;
+      } else {
+        entry.sourceRef.fsm = entry.targetRef.fsm;
+      }
+    }
+    try {
+      return callback(...args);
+    } finally {
+      for (let i = previousValues.length - 1; i >= 0; i--) {
+        const entry = previousValues[i];
+        entry.sourceRef.options = entry.options;
+        if (!entry.hasFSM) {
+          delete entry.sourceRef.fsm;
+        } else {
+          entry.sourceRef.fsm = entry.fsm;
+        }
+      }
+    }
+  });
+}
+function finalizeEntityCloneSupport(entity, factory) {
+  entity.finalizeCloneSupport(factory);
+  return entity;
+}
 
 // src/lib/entities/delegates/debug.ts
 import { MeshStandardMaterial, MeshBasicMaterial, MeshPhongMaterial } from "three";
@@ -1222,13 +1615,13 @@ import {
   CapsuleGeometry,
   ConeGeometry,
   CylinderGeometry,
-  Mesh as Mesh2,
+  Mesh as Mesh3,
   MeshStandardMaterial as MeshStandardMaterial3,
   SphereGeometry
 } from "three";
 
 // src/lib/graphics/material.ts
-import { Color as Color3, Vector2 as Vector22, Vector3 as Vector37 } from "three";
+import { Color as Color4, Vector2 as Vector23, Vector3 as Vector38 } from "three";
 import {
   MeshPhongMaterial as MeshPhongMaterial2,
   MeshStandardMaterial as MeshStandardMaterial2,
@@ -1295,10 +1688,44 @@ var TextureLoaderAdapter = class {
 
 // src/lib/core/loaders/gltf-loader.ts
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+
+// src/lib/core/loaders/model-clone.ts
+import { Mesh as Mesh2 } from "three";
+import { clone as cloneSkeleton } from "three/addons/utils/SkeletonUtils.js";
+function cloneModelObject(object) {
+  const clonedObject = cloneSkeleton(object);
+  const originalNodes = [];
+  const clonedNodes = [];
+  object.traverse((node) => originalNodes.push(node));
+  clonedObject.traverse((node) => clonedNodes.push(node));
+  for (let i = 0; i < originalNodes.length; i++) {
+    const originalNode = originalNodes[i];
+    const clonedNode = clonedNodes[i];
+    if (!(originalNode instanceof Mesh2) || !(clonedNode instanceof Mesh2)) {
+      continue;
+    }
+    if (originalNode.geometry?.clone) {
+      clonedNode.geometry = originalNode.geometry.clone();
+    }
+    if (!originalNode.material) {
+      continue;
+    }
+    clonedNode.material = Array.isArray(originalNode.material) ? originalNode.material.map((material) => material.clone()) : originalNode.material.clone();
+  }
+  return clonedObject;
+}
+
+// src/lib/core/loaders/gltf-loader.ts
+var DRACO_DECODER_PATH = "https://www.gstatic.com/draco/v1/decoders/";
 var GLTFLoaderAdapter = class {
   loader;
+  dracoLoader;
   constructor() {
+    this.dracoLoader = new DRACOLoader();
+    this.dracoLoader.setDecoderPath(DRACO_DECODER_PATH);
     this.loader = new GLTFLoader();
+    this.loader.setDRACOLoader(this.dracoLoader);
   }
   isSupported(url) {
     const ext = url.split(".").pop()?.toLowerCase();
@@ -1357,7 +1784,7 @@ var GLTFLoaderAdapter = class {
    */
   clone(result) {
     return {
-      object: result.object.clone(),
+      object: cloneModelObject(result.object),
       animations: result.animations?.map((anim) => anim.clone()),
       gltf: result.gltf
     };
@@ -1425,7 +1852,7 @@ var FBXLoaderAdapter = class {
    */
   clone(result) {
     return {
-      object: result.object.clone(),
+      object: cloneModelObject(result.object),
       animations: result.animations?.map((anim) => anim.clone())
     };
   }
@@ -1486,7 +1913,7 @@ var OBJLoaderAdapter = class {
    */
   clone(result) {
     return {
-      object: result.object.clone(),
+      object: cloneModelObject(result.object),
       animations: []
     };
   }
@@ -1922,6 +2349,14 @@ function isGLSLShader(shader) {
 }
 var MaterialBuilder = class _MaterialBuilder {
   static batchMaterialMap = /* @__PURE__ */ new Map();
+  /**
+   * Clear the static batch material cache.
+   * Should be called during game disposal to prevent stale material references
+   * from persisting across demo/stage switches.
+   */
+  static clearBatchCache() {
+    _MaterialBuilder.batchMaterialMap.clear();
+  }
   materials = [];
   /** Whether to use TSL/NodeMaterial (for WebGPU compatibility) */
   useTSL;
@@ -1946,53 +2381,61 @@ var MaterialBuilder = class _MaterialBuilder {
     }
   }
   build(options, entityType) {
-    const { path, normalMap, repeat, color, shader, useTSL } = options;
+    const { path, normalMap, repeat, color, shader, opacity, useTSL } = options;
     const shouldUseTSL = useTSL ?? this.useTSL;
     if (shader) {
       if (isTSLShader(shader)) {
-        this.setTSLShader(shader);
+        this.setTSLShader(shader, opacity);
       } else if (isGLSLShader(shader)) {
         if (shouldUseTSL) {
           console.warn("MaterialBuilder: GLSL shader provided but TSL mode requested. Using GLSL.");
         }
-        this.setShader(shader);
+        this.setShader(shader, opacity);
       }
     } else if (path) {
-      this.setTexture(path, repeat, shouldUseTSL);
+      this.setTexture(path, repeat, shouldUseTSL, opacity);
     }
     if (color) {
-      this.withColor(color, shouldUseTSL);
+      this.withColor(color, shouldUseTSL, opacity);
     }
     if (this.materials.length === 0) {
-      this.setColor(new Color3("#ffffff"), shouldUseTSL);
+      this.setColor(new Color4("#ffffff"), shouldUseTSL, opacity);
     }
     if (normalMap && this.materials.length > 0) {
       this.setNormalMap(normalMap, repeat);
     }
     this.batchMaterial(options, entityType);
   }
-  withColor(color, useTSL = false) {
-    this.setColor(color, useTSL);
+  withColor(color, useTSL = false, opacity) {
+    this.setColor(color, useTSL, opacity);
     return this;
   }
-  withShader(shader) {
-    this.setShader(shader);
+  withShader(shader, opacity) {
+    this.setShader(shader, opacity);
     return this;
   }
-  withTSLShader(shader) {
-    this.setTSLShader(shader);
+  withTSLShader(shader, opacity) {
+    this.setTSLShader(shader, opacity);
     return this;
   }
+  applyOpacity(material, opacity, forceTransparent = false) {
+    if (opacity !== void 0) {
+      material.opacity = opacity;
+    }
+    material.transparent = forceTransparent || opacity !== void 0 && opacity < 1;
+    material.needsUpdate = true;
+  }
   /**
    * Set texture - loads in background (deferred).
    * Material is created immediately with null map, texture applies when loaded.
    */
-  setTexture(texturePath = null, repeat = new Vector22(1, 1), useTSL = false) {
+  setTexture(texturePath = null, repeat = new Vector23(1, 1), useTSL = false, opacity) {
     if (!texturePath) {
       return;
     }
     if (useTSL) {
       const material = new MeshStandardNodeMaterial();
+      this.applyOpacity(material, opacity);
       this.materials.push(material);
       assetManager.loadTexture(texturePath, {
         clone: true,
@@ -2005,7 +2448,9 @@ var MaterialBuilder = class _MaterialBuilder {
       });
     } else {
       const material = new MeshPhongMaterial2({
-        map: null
+        map: null,
+        opacity: opacity ?? 1,
+        transparent: opacity !== void 0 && opacity < 1
       });
       this.materials.push(material);
       assetManager.loadTexture(texturePath, {
@@ -2022,7 +2467,7 @@ var MaterialBuilder = class _MaterialBuilder {
   /**
    * Set normal map for the current material
    */
-  setNormalMap(normalMapPath, repeat = new Vector22(1, 1)) {
+  setNormalMap(normalMapPath, repeat = new Vector23(1, 1)) {
     const material = this.materials[this.materials.length - 1];
     if (!material) return;
     assetManager.loadTexture(normalMapPath, {
@@ -2046,17 +2491,20 @@ var MaterialBuilder = class _MaterialBuilder {
       }
     });
   }
-  setColor(color, useTSL = false) {
+  setColor(color, useTSL = false, opacity) {
     if (useTSL) {
       const material = new MeshStandardNodeMaterial();
       material.color = color;
+      this.applyOpacity(material, opacity);
       this.materials.push(material);
     } else {
       const material = new MeshStandardMaterial2({
         color,
         emissiveIntensity: 0.5,
         lightMapIntensity: 0.5,
-        fog: true
+        fog: true,
+        opacity: opacity ?? 1,
+        transparent: opacity !== void 0 && opacity < 1
       });
       this.materials.push(material);
     }
@@ -2064,34 +2512,37 @@ var MaterialBuilder = class _MaterialBuilder {
   /**
    * Set GLSL shader (WebGL only)
    */
-  setShader(customShader) {
+  setShader(customShader, opacity) {
     const { fragment: fragment2, vertex } = customShader ?? standardShader;
     const shader = new ShaderMaterial2({
       uniforms: {
-        iResolution: { value: new Vector37(1, 1, 1) },
+        iResolution: { value: new Vector38(1, 1, 1) },
         iTime: { value: 0 },
         tDiffuse: { value: null },
         tDepth: { value: null },
         tNormal: { value: null },
         normalMap: { value: null },
-        lightDir: { value: new Vector37(1, 1, 1) },
+        lightDir: { value: new Vector38(1, 1, 1) },
         normalStrength: { value: 1 }
       },
       vertexShader: vertex,
       fragmentShader: fragment2,
-      transparent: true
+      transparent: true,
+      opacity: opacity ?? 1
     });
     this.materials.push(shader);
   }
   /**
    * Set TSL shader (WebGPU compatible)
    */
-  setTSLShader(tslShader) {
+  setTSLShader(tslShader, opacity) {
     const material = new MeshBasicNodeMaterial();
     material.colorNode = tslShader.colorNode;
-    if (tslShader.transparent) {
-      material.transparent = true;
-    }
+    this.applyOpacity(
+      material,
+      opacity,
+      tslShader.transparent
+    );
     this.materials.push(material);
   }
 };
@@ -2122,12 +2573,12 @@ function boxMesh(opts = {}) {
   const size = opts.size ?? { x: 1, y: 1, z: 1 };
   const geometry = new BoxGeometry(size.x, size.y, size.z);
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 function sphereMesh(opts = {}) {
   const geometry = new SphereGeometry(opts.radius ?? 1);
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 function coneMesh(opts = {}) {
   const geometry = new ConeGeometry(
@@ -2136,12 +2587,12 @@ function coneMesh(opts = {}) {
     opts.radialSegments ?? 32
   );
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 function pyramidMesh(opts = {}) {
   const geometry = new ConeGeometry(opts.radius ?? 1, opts.height ?? 2, 4);
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 function cylinderMesh(opts = {}) {
   const geometry = new CylinderGeometry(
@@ -2151,7 +2602,7 @@ function cylinderMesh(opts = {}) {
     opts.radialSegments ?? 32
   );
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 function pillMesh(opts = {}) {
   const geometry = new CapsuleGeometry(
@@ -2161,13 +2612,13 @@ function pillMesh(opts = {}) {
     opts.radialSegments ?? 20
   );
   const materials = buildMaterial(opts);
-  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+  return finalizeMesh(new Mesh3(geometry, materials.at(-1)), opts);
 }
 
 // src/lib/entities/box.ts
 var boxDefaults = {
   ...commonDefaults,
-  size: new Vector38(1, 1, 1)
+  size: new Vector39(1, 1, 1)
 };
 var BOX_TYPE = /* @__PURE__ */ Symbol("Box");
 var ZylemBox = class _ZylemBox extends GameEntity {
@@ -2200,7 +2651,10 @@ function createBox(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createBox(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/sphere.ts
@@ -2239,12 +2693,15 @@ function createSphere(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createSphere(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/sprite.ts
 import { ColliderDesc as ColliderDesc3 } from "@dimforge/rapier3d-compat";
-import { Euler as Euler2, Group as Group3, Quaternion as Quaternion3, Vector3 as Vector39 } from "three";
+import { Euler as Euler2, Group as Group3, Quaternion as Quaternion3, Vector3 as Vector310 } from "three";
 import {
   TextureLoader as TextureLoader2,
   SpriteMaterial,
@@ -2252,17 +2709,17 @@ import {
 } from "three";
 
 // src/lib/entities/builder.ts
-import { BufferGeometry as BufferGeometry2, Mesh as Mesh4, Color as Color4 } from "three";
+import { BufferGeometry as BufferGeometry2, Mesh as Mesh5, Color as Color5 } from "three";
 
 // src/lib/graphics/mesh.ts
-import { Mesh as Mesh3 } from "three";
+import { Mesh as Mesh4 } from "three";
 var MeshBuilder = class {
   _build(meshOptions, geometry, materials) {
     const { batched, material } = meshOptions;
     if (batched) {
       console.warn("warning: mesh batching is not implemented");
     }
-    const mesh = new Mesh3(geometry, materials.at(-1));
+    const mesh = new Mesh4(geometry, materials.at(-1));
     mesh.position.set(0, 0, 0);
     mesh.castShadow = true;
     mesh.receiveShadow = true;
@@ -2315,7 +2772,7 @@ var EntityBuilder = class {
   }
   applyMaterialToGroup(group, materials) {
     group.traverse((child) => {
-      if (child instanceof Mesh4) {
+      if (child instanceof Mesh5) {
         if (child.type === "SkinnedMesh" && materials[0] && !child.material.map) {
           child.material = materials[0];
         }
@@ -2349,7 +2806,7 @@ var EntityBuilder = class {
     if (this.options.collisionType) {
       entity.collisionType = this.options.collisionType;
     }
-    if (this.options.color instanceof Color4) {
+    if (this.options.color instanceof Color5) {
       const applyColor = (material) => {
         const anyMat = material;
         if (anyMat && anyMat.color && anyMat.color.set) {
@@ -2366,7 +2823,7 @@ var EntityBuilder = class {
       }
       if (entity.group) {
         entity.group.traverse((child) => {
-          if (child instanceof Mesh4 && child.material) {
+          if (child instanceof Mesh5 && child.material) {
             const mat = child.material;
             if (Array.isArray(mat)) mat.forEach(applyColor);
             else applyColor(mat);
@@ -2409,7 +2866,8 @@ function createEntity(params) {
     BuilderClass,
     entityType,
     MeshBuilderClass,
-    CollisionBuilderClass
+    CollisionBuilderClass,
+    cloneFactory
   } = params;
   let builder = null;
   let configuration;
@@ -2448,19 +2906,22 @@ function createEntity(params) {
   if (!builder) {
     throw new Error(`missing options for ${String(entityType)}, builder is not initialized.`);
   }
-  return builder.build();
+  return finalizeEntityCloneSupport(
+    builder.build(),
+    (options) => cloneFactory(options)
+  );
 }
 
 // src/lib/entities/sprite.ts
 var spriteDefaults = {
   ...commonDefaults,
-  size: new Vector39(1, 1, 1),
+  size: new Vector310(1, 1, 1),
   images: [],
   animations: []
 };
 var SpriteCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const size = options.collisionSize || options.size || new Vector39(1, 1, 1);
+    const size = options.collisionSize || options.size || new Vector310(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
     let colliderDesc = ColliderDesc3.cuboid(half.x, half.y, half.z);
     return colliderDesc;
@@ -2485,6 +2946,7 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...spriteDefaults, ...options };
+    this.prependSetup(this.spriteSetup.bind(this));
     this.prependUpdate(this.spriteUpdate.bind(this));
     this.onCleanup(this.spriteDestroy.bind(this));
   }
@@ -2503,6 +2965,7 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
   }
   createSpritesFromImages(images) {
     const textureLoader = new TextureLoader2();
+    const size = this.options.size ?? new Vector310(1, 1, 1);
     images.forEach((image, index) => {
       const spriteMap = textureLoader.load(image.file);
       const material = new SpriteMaterial({
@@ -2511,6 +2974,8 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
       });
       const _sprite = new ThreeSprite(material);
       _sprite.position.normalize();
+      _sprite.scale.set(size.x, size.y, size.z);
+      _sprite.visible = index === 0;
       this.sprites.push(_sprite);
       this.spriteMap.set(image.name, index);
     });
@@ -2564,19 +3029,29 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
       }
     }
   }
-  spriteUpdate(params) {
+  getCurrentRotationQuaternion() {
+    if (this.transformStore?.dirty.rotation) {
+      return this.transformStore.rotation;
+    }
+    return this.body?.rotation?.() ?? null;
+  }
+  syncSpriteMaterials() {
+    const q = this.getCurrentRotationQuaternion();
     this.sprites.forEach((_sprite) => {
-      if (_sprite.material) {
-        const q = this.body?.rotation();
-        if (q) {
-          const quat = new Quaternion3(q.x, q.y, q.z, q.w);
-          const euler = new Euler2().setFromQuaternion(quat, "XYZ");
-          _sprite.material.rotation = euler.z;
-        }
-        _sprite.scale.set(this.options.size?.x ?? 1, this.options.size?.y ?? 1, this.options.size?.z ?? 1);
+      if (_sprite.material && q) {
+        const quat = new Quaternion3(q.x, q.y, q.z, q.w);
+        const euler = new Euler2().setFromQuaternion(quat, "XYZ");
+        _sprite.material.rotation = euler.z;
       }
+      _sprite.scale.set(this.options.size?.x ?? 1, this.options.size?.y ?? 1, this.options.size?.z ?? 1);
     });
   }
+  spriteSetup(_params) {
+    this.syncSpriteMaterials();
+  }
+  spriteUpdate(params) {
+    this.syncSpriteMaterials();
+  }
   spriteDestroy(params) {
     this.sprites.forEach((_sprite) => {
       _sprite.removeFromParent();
@@ -2600,13 +3075,14 @@ function createSprite(...args) {
     EntityClass: ZylemSprite,
     BuilderClass: SpriteBuilder,
     CollisionBuilderClass: SpriteCollisionBuilder,
-    entityType: ZylemSprite.type
+    entityType: ZylemSprite.type,
+    cloneFactory: (options) => createSprite(options ?? {})
   });
 }
 
 // src/lib/entities/plane.ts
 import { ColliderDesc as ColliderDesc4 } from "@dimforge/rapier3d-compat";
-import { PlaneGeometry, Vector2 as Vector23, Vector3 as Vector310 } from "three";
+import { PlaneGeometry, Vector2 as Vector24, Vector3 as Vector311 } from "three";
 
 // src/lib/graphics/geometries/XZPlaneGeometry.ts
 import { BufferGeometry as BufferGeometry3, Float32BufferAttribute } from "three";
@@ -2671,8 +3147,8 @@ var XZPlaneGeometry = class _XZPlaneGeometry extends BufferGeometry3 {
 var DEFAULT_SUBDIVISIONS = 4;
 var planeDefaults = {
   ...commonDefaults,
-  tile: new Vector23(10, 10),
-  repeat: new Vector23(1, 1),
+  tile: new Vector24(10, 10),
+  repeat: new Vector24(1, 1),
   collision: {
     static: true
   },
@@ -2682,11 +3158,11 @@ var planeDefaults = {
 };
 var PlaneCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const tile = options.tile ?? new Vector23(1, 1);
+    const tile = options.tile ?? new Vector24(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
-    const size = new Vector310(tile.x, 1, tile.y);
+    const size = new Vector311(tile.x, 1, tile.y);
     const heightData = options._builders?.meshBuilder?.heightData;
-    const scale2 = new Vector310(size.x, 1, size.z);
+    const scale2 = new Vector311(size.x, 1, size.z);
     let colliderDesc = ColliderDesc4.heightfield(
       subdivisions,
       subdivisions,
@@ -2701,10 +3177,10 @@ var PlaneMeshBuilder = class extends EntityMeshBuilder {
   columnsRows = /* @__PURE__ */ new Map();
   subdivisions = DEFAULT_SUBDIVISIONS;
   build(options) {
-    const tile = options.tile ?? new Vector23(1, 1);
+    const tile = options.tile ?? new Vector24(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
     this.subdivisions = subdivisions;
-    const size = new Vector310(tile.x, 1, tile.y);
+    const size = new Vector311(tile.x, 1, tile.y);
     const heightScale = options.heightScale ?? 1;
     const geometry = new XZPlaneGeometry(size.x, size.z, subdivisions, subdivisions);
     const vertexGeometry = new PlaneGeometry(size.x, size.z, subdivisions, subdivisions);
@@ -2773,12 +3249,13 @@ function createPlane(...args) {
     BuilderClass: PlaneBuilder,
     MeshBuilderClass: PlaneMeshBuilder,
     CollisionBuilderClass: PlaneCollisionBuilder,
-    entityType: ZylemPlane.type
+    entityType: ZylemPlane.type,
+    cloneFactory: (options) => createPlane(options ?? {})
   });
 }
 
 // src/lib/entities/zone.ts
-import { Vector3 as Vector311 } from "three";
+import { Vector3 as Vector312 } from "three";
 
 // src/lib/game/game-state.ts
 import { proxy as proxy2, subscribe } from "valtio/vanilla";
@@ -2791,7 +3268,7 @@ var state = proxy2({
 // src/lib/entities/zone.ts
 var zoneDefaults = {
   ...commonDefaults,
-  size: new Vector311(1, 1, 1),
+  size: new Vector312(1, 1, 1),
   collision: {
     static: true
   }
@@ -2886,23 +3363,34 @@ function createZone(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createZone(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/actor.ts
 import { ActiveCollisionTypes as ActiveCollisionTypes3, ColliderDesc as ColliderDesc5 } from "@dimforge/rapier3d-compat";
-import { MeshStandardMaterial as MeshStandardMaterial4, Group as Group4, Vector3 as Vector312 } from "three";
+import {
+  Box3,
+  BufferAttribute,
+  SkinnedMesh,
+  MeshStandardMaterial as MeshStandardMaterial4,
+  Group as Group4,
+  Vector3 as Vector313,
+  Matrix4
+} from "three";
 
 // 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) {
+  async loadFile(file, options) {
     const ext = file.split(".").pop()?.toLowerCase();
     switch (ext) {
       case "fbx": {
-        const result = await assetManager.loadFBX(file);
+        const result = await assetManager.loadFBX(file, options);
         return {
           object: result.object,
           animation: result.animations?.[0]
@@ -2910,14 +3398,14 @@ var EntityAssetLoader = class {
       }
       case "gltf":
       case "glb": {
-        const result = await assetManager.loadGLTF(file);
+        const result = await assetManager.loadGLTF(file, options);
         return {
           object: result.object,
           gltf: result.gltf
         };
       }
       case "obj": {
-        const result = await assetManager.loadOBJ(file);
+        const result = await assetManager.loadOBJ(file, options);
         return {
           object: result.object
         };
@@ -2931,9 +3419,42 @@ var EntityAssetLoader = class {
 // src/lib/entities/delegates/animation.ts
 import {
   AnimationMixer,
+  Bone,
   LoopOnce,
   LoopRepeat
 } from "three";
+function getTrackTargetName(trackName) {
+  const propertyIndex = trackName.lastIndexOf(".");
+  return propertyIndex >= 0 ? trackName.slice(0, propertyIndex) : trackName;
+}
+function shouldStripRootMotion(track, targetByName) {
+  if (!track?.name?.endsWith(".position")) {
+    return false;
+  }
+  const targetName = getTrackTargetName(track.name);
+  const target = targetByName.get(targetName);
+  if (target instanceof Bone) {
+    return !(target.parent instanceof Bone);
+  }
+  return /hips\.position$/i.test(track.name) || /root\.position$/i.test(track.name);
+}
+function stripClipRootMotion(clip, targetByName) {
+  for (const track of clip.tracks) {
+    if (!shouldStripRootMotion(track, targetByName)) {
+      continue;
+    }
+    if (!track.values || track.values.length < 3) {
+      continue;
+    }
+    const baseX = track.values[0];
+    const baseZ = track.values[2];
+    for (let i = 0; i < track.values.length; i += 3) {
+      track.values[i] = baseX;
+      track.values[i + 2] = baseZ;
+    }
+  }
+  return clip;
+}
 var AnimationDelegate = class {
   constructor(target) {
     this.target = target;
@@ -2951,12 +3472,18 @@ var AnimationDelegate = class {
   async loadAnimations(animations) {
     if (!animations.length) return;
     const results = await Promise.all(animations.map((a) => this._assetLoader.loadFile(a.path)));
+    const targetByName = /* @__PURE__ */ new Map();
+    this.target.traverse((node) => {
+      if (node.name) {
+        targetByName.set(node.name, node);
+      }
+    });
     const loadedAnimations = [];
     results.forEach((result, i) => {
       if (result.animation) {
         loadedAnimations.push({
           key: animations[i].key || i.toString(),
-          clip: result.animation
+          clip: stripClipRootMotion(result.animation, targetByName)
         });
       }
     });
@@ -3039,11 +3566,6 @@ var AnimationDelegate = class {
 // src/lib/entities/actor.ts
 var actorDefaults = {
   ...commonDefaults,
-  collision: {
-    static: false,
-    size: new Vector312(0.5, 0.5, 0.5),
-    position: new Vector312(0, 0, 0)
-  },
   material: {
     shader: standardShader
   },
@@ -3051,74 +3573,333 @@ var actorDefaults = {
   models: [],
   collisionShape: "capsule"
 };
+function getActorScale(options) {
+  return new Vector313(
+    options.scale?.x ?? 1,
+    options.scale?.y ?? 1,
+    options.scale?.z ?? 1
+  );
+}
+function getCollisionPosition(options) {
+  const position2 = options.collision?.position;
+  if (!position2) {
+    return null;
+  }
+  return {
+    x: position2.x ?? 0,
+    y: position2.y ?? 0,
+    z: position2.z ?? 0
+  };
+}
+function hasExplicitCollisionSize(options) {
+  return Boolean(options.collision?.size);
+}
+function warnDynamicTrimeshOnce(actor) {
+  if (actor.hasWarnedDynamicTrimesh) {
+    return;
+  }
+  actor.hasWarnedDynamicTrimesh = true;
+  console.warn(
+    `Actor "${actor.name || actor.uuid}" requested collisionShape="trimesh" on a dynamic body; falling back to bounds.`
+  );
+}
+function resolveCollisionShape(shape, isStatic, onDynamicTrimesh) {
+  const normalized = shape === "model" ? "bounds" : shape ?? "capsule";
+  if (normalized === "trimesh" && !isStatic) {
+    onDynamicTrimesh?.();
+    return "bounds";
+  }
+  return normalized;
+}
+function tagTrimeshCollider(colliderDesc, vertices, indices) {
+  colliderDesc.__zylemShapeData = {
+    shape: "trimesh",
+    vertices: Array.from(vertices),
+    indices: Array.from(indices)
+  };
+  return colliderDesc;
+}
+function createCapsuleColliderFromDimensions(size, translation) {
+  const fullWidth = size.x || 0.5;
+  const fullHeight = size.y || 1;
+  const fullDepth = size.z || 0.5;
+  const radius = Math.max(fullWidth, fullDepth) / 2;
+  const halfTotalHeight = fullHeight / 2;
+  const halfCylinder = Math.max(0, halfTotalHeight - radius);
+  const colliderDesc = ColliderDesc5.capsule(halfCylinder, radius);
+  colliderDesc.setSensor(false);
+  colliderDesc.setTranslation(translation.x, translation.y, translation.z);
+  colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
+  return colliderDesc;
+}
+function createCapsuleCollider(options) {
+  const size = options.collision?.size ?? options.size ?? { x: 0.5, y: 1, z: 0.5 };
+  const fullHeight = size.y || 1;
+  const collisionPosition = getCollisionPosition(options);
+  return createCapsuleColliderFromDimensions(
+    {
+      x: size.x || 0.5,
+      y: fullHeight,
+      z: size.z || 0.5
+    },
+    collisionPosition ?? { x: 0, y: fullHeight / 2, z: 0 }
+  );
+}
+function createExplicitBoxCollider(options) {
+  const collisionSize = options.collision?.size;
+  if (!collisionSize) {
+    return null;
+  }
+  const halfWidth = collisionSize.x / 2;
+  const halfHeight = collisionSize.y / 2;
+  const halfDepth = collisionSize.z / 2;
+  const colliderDesc = ColliderDesc5.cuboid(halfWidth, halfHeight, halfDepth);
+  const collisionPosition = getCollisionPosition(options);
+  colliderDesc.setSensor(false);
+  colliderDesc.setTranslation(
+    collisionPosition?.x ?? 0,
+    collisionPosition?.y ?? halfHeight,
+    collisionPosition?.z ?? 0
+  );
+  colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
+  return colliderDesc;
+}
+function computeActorSpaceMatrix(child, actorRoot, actorScale) {
+  const actorRootInverse = actorRoot.matrixWorld.clone().invert();
+  const actorSpaceMatrix = actorRootInverse.multiply(child.matrixWorld);
+  return new Matrix4().makeScale(actorScale.x, actorScale.y, actorScale.z).multiply(actorSpaceMatrix);
+}
+function computeModelBounds(modelRoot, actorRoot, actorScale) {
+  modelRoot.updateMatrixWorld(true);
+  let foundMesh = false;
+  const aggregated = new Box3();
+  modelRoot.traverse((child) => {
+    if (!child.isMesh) {
+      return;
+    }
+    const mesh = child;
+    const geometry = mesh.geometry;
+    if (!geometry) {
+      return;
+    }
+    let localBounds = null;
+    if (mesh instanceof SkinnedMesh) {
+      mesh.computeBoundingBox();
+      localBounds = mesh.boundingBox?.clone() ?? null;
+    } else {
+      geometry.computeBoundingBox();
+      localBounds = geometry.boundingBox?.clone() ?? null;
+    }
+    if (!localBounds) {
+      return;
+    }
+    const transformedBounds = localBounds.applyMatrix4(computeActorSpaceMatrix(mesh, actorRoot, actorScale));
+    if (!foundMesh) {
+      aggregated.copy(transformedBounds);
+      foundMesh = true;
+      return;
+    }
+    aggregated.union(transformedBounds);
+  });
+  if (!foundMesh || aggregated.isEmpty()) {
+    return null;
+  }
+  const size = new Vector313();
+  const center = new Vector313();
+  aggregated.getSize(size);
+  aggregated.getCenter(center);
+  return { size, center };
+}
+function computeModelTrimesh(modelRoot, actorRoot, actorScale) {
+  modelRoot.updateMatrixWorld(true);
+  const vertices = [];
+  const indices = [];
+  const bounds = new Box3();
+  const point = new Vector313();
+  let foundMesh = false;
+  modelRoot.traverse((child) => {
+    if (!child.isMesh) {
+      return;
+    }
+    const mesh = child;
+    const geometry = mesh.geometry;
+    if (!geometry) {
+      return;
+    }
+    const position2 = geometry.getAttribute("position");
+    if (!(position2 instanceof BufferAttribute)) {
+      return;
+    }
+    const transform = computeActorSpaceMatrix(mesh, actorRoot, actorScale);
+    const vertexOffset = vertices.length / 3;
+    for (let i = 0; i < position2.count; i++) {
+      point.set(position2.getX(i), position2.getY(i), position2.getZ(i));
+      point.applyMatrix4(transform);
+      vertices.push(point.x, point.y, point.z);
+      bounds.expandByPoint(point);
+    }
+    const index = geometry.getIndex();
+    if (index) {
+      for (let i = 0; i < index.count; i++) {
+        indices.push(vertexOffset + index.getX(i));
+      }
+    } else {
+      for (let i = 0; i < position2.count; i++) {
+        indices.push(vertexOffset + i);
+      }
+    }
+    foundMesh = true;
+  });
+  if (!foundMesh || vertices.length === 0 || indices.length === 0) {
+    return null;
+  }
+  const center = new Vector313();
+  bounds.getCenter(center);
+  return {
+    vertices: new Float32Array(vertices),
+    indices: new Uint32Array(indices),
+    center
+  };
+}
+function createBoundsColliderFromModel(modelRoot, actorRoot, options) {
+  const explicitCollider = createExplicitBoxCollider(options);
+  if (explicitCollider) {
+    return explicitCollider;
+  }
+  if (!modelRoot || !actorRoot) {
+    return createCapsuleCollider(options);
+  }
+  const bounds = computeModelBounds(modelRoot, actorRoot, getActorScale(options));
+  if (!bounds) {
+    return createCapsuleCollider(options);
+  }
+  const colliderDesc = ColliderDesc5.cuboid(
+    bounds.size.x / 2,
+    bounds.size.y / 2,
+    bounds.size.z / 2
+  );
+  const collisionPosition = getCollisionPosition(options);
+  colliderDesc.setSensor(false);
+  colliderDesc.setTranslation(
+    collisionPosition?.x ?? bounds.center.x,
+    collisionPosition?.y ?? bounds.center.y,
+    collisionPosition?.z ?? bounds.center.z
+  );
+  colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
+  return colliderDesc;
+}
+function createCapsuleColliderFromModel(sizingRoot, sizingActorRoot, alignmentRoot, alignmentActorRoot, options) {
+  if (hasExplicitCollisionSize(options)) {
+    return createCapsuleCollider(options);
+  }
+  if (!sizingRoot || !sizingActorRoot) {
+    return createCapsuleCollider(options);
+  }
+  const sizingBounds = computeModelBounds(
+    sizingRoot,
+    sizingActorRoot,
+    getActorScale(options)
+  );
+  if (!sizingBounds) {
+    return createCapsuleCollider(options);
+  }
+  const collisionPosition = getCollisionPosition(options);
+  let translation = collisionPosition;
+  if (!translation) {
+    const alignmentBounds = alignmentRoot && alignmentActorRoot ? computeModelBounds(alignmentRoot, alignmentActorRoot, getActorScale(options)) : null;
+    translation = alignmentBounds ? {
+      x: alignmentBounds.center.x,
+      y: alignmentBounds.center.y,
+      z: alignmentBounds.center.z
+    } : {
+      x: sizingBounds.center.x,
+      y: sizingBounds.center.y,
+      z: sizingBounds.center.z
+    };
+  }
+  return createCapsuleColliderFromDimensions(
+    {
+      x: sizingBounds.size.x,
+      y: sizingBounds.size.y,
+      z: sizingBounds.size.z
+    },
+    translation
+  );
+}
+function createTrimeshColliderFromModel(modelRoot, actorRoot, options) {
+  const explicitCollider = createExplicitBoxCollider(options);
+  if (explicitCollider) {
+    return explicitCollider;
+  }
+  if (!modelRoot || !actorRoot) {
+    return createCapsuleCollider(options);
+  }
+  const trimesh = computeModelTrimesh(modelRoot, actorRoot, getActorScale(options));
+  if (!trimesh) {
+    return createCapsuleCollider(options);
+  }
+  const colliderDesc = tagTrimeshCollider(
+    ColliderDesc5.trimesh(trimesh.vertices, trimesh.indices),
+    trimesh.vertices,
+    trimesh.indices
+  );
+  const collisionPosition = getCollisionPosition(options);
+  if (collisionPosition) {
+    colliderDesc.setTranslation(
+      collisionPosition.x - trimesh.center.x,
+      collisionPosition.y - trimesh.center.y,
+      collisionPosition.z - trimesh.center.z
+    );
+  }
+  colliderDesc.setSensor(false);
+  colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
+  return colliderDesc;
+}
+function disposeObjectResources(object) {
+  if (!object) {
+    return;
+  }
+  object.traverse((child) => {
+    if (!child.isMesh) {
+      return;
+    }
+    const mesh = child;
+    mesh.geometry?.dispose();
+    if (Array.isArray(mesh.material)) {
+      mesh.material.forEach((material) => material.dispose());
+    } else {
+      mesh.material?.dispose();
+    }
+  });
+}
 var ActorCollisionBuilder = class extends EntityCollisionBuilder {
   objectModel = null;
+  collisionSource = null;
   collisionShape = "capsule";
   constructor(data) {
     super();
     this.objectModel = data.objectModel;
+    this.collisionSource = data.collisionSource ?? data.objectModel ?? null;
     this.collisionShape = data.collisionShape ?? "capsule";
   }
   collider(options) {
-    if (this.collisionShape === "model") {
-      return this.createColliderFromModel(this.objectModel, options);
+    const resolvedShape = resolveCollisionShape(
+      this.collisionShape,
+      Boolean(options.collision?.static)
+    );
+    if (resolvedShape === "bounds") {
+      return createBoundsColliderFromModel(this.objectModel, this.objectModel, options);
     }
-    return this.createCapsuleCollider(options);
-  }
-  /**
-   * Create a capsule collider based on size options (character controller style).
-   */
-  createCapsuleCollider(options) {
-    const size = options.collision?.size ?? options.size ?? { x: 0.5, y: 1, z: 0.5 };
-    const halfHeight = size.y || 1;
-    const radius = Math.max(size.x || 0.5, size.z || 0.5);
-    let colliderDesc = ColliderDesc5.capsule(halfHeight, radius);
-    colliderDesc.setSensor(false);
-    colliderDesc.setTranslation(0, halfHeight + radius, 0);
-    colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
-    return colliderDesc;
-  }
-  /**
-   * Create a collider based on model geometry (works with Mesh and SkinnedMesh).
-   * If collision.size and collision.position are provided, use those instead of computing from geometry.
-   */
-  createColliderFromModel(objectModel, options) {
-    const collisionSize = options.collision?.size;
-    const collisionPosition = options.collision?.position;
-    if (collisionSize) {
-      const halfWidth = collisionSize.x / 2;
-      const halfHeight = collisionSize.y / 2;
-      const halfDepth = collisionSize.z / 2;
-      let colliderDesc2 = ColliderDesc5.cuboid(halfWidth, halfHeight, halfDepth);
-      colliderDesc2.setSensor(false);
-      const posX = collisionPosition ? collisionPosition.x : 0;
-      const posY = collisionPosition ? collisionPosition.y : halfHeight;
-      const posZ = collisionPosition ? collisionPosition.z : 0;
-      colliderDesc2.setTranslation(posX, posY, posZ);
-      colliderDesc2.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
-      return colliderDesc2;
-    }
-    if (!objectModel) return this.createCapsuleCollider(options);
-    let foundGeometry = null;
-    objectModel.traverse((child) => {
-      if (!foundGeometry && child.isMesh) {
-        foundGeometry = child.geometry;
-      }
-    });
-    if (!foundGeometry) return this.createCapsuleCollider(options);
-    const geometry = foundGeometry;
-    geometry.computeBoundingBox();
-    const box = geometry.boundingBox;
-    if (!box) return this.createCapsuleCollider(options);
-    const height = box.max.y - box.min.y;
-    const width = box.max.x - box.min.x;
-    const depth = box.max.z - box.min.z;
-    let colliderDesc = ColliderDesc5.cuboid(width / 2, height / 2, depth / 2);
-    colliderDesc.setSensor(false);
-    const centerY = (box.max.y + box.min.y) / 2;
-    colliderDesc.setTranslation(0, centerY, 0);
-    colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
-    return colliderDesc;
+    if (resolvedShape === "trimesh") {
+      return createTrimeshColliderFromModel(this.objectModel, this.objectModel, options);
+    }
+    return createCapsuleColliderFromModel(
+      this.collisionSource,
+      this.collisionSource,
+      this.objectModel,
+      this.objectModel,
+      options
+    );
   }
 };
 var ActorBuilder = class extends EntityBuilder {
@@ -3130,96 +3911,228 @@ var ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
 var ZylemActor = class extends GameEntity {
   static type = ACTOR_TYPE;
   _object = null;
+  _collisionSource = null;
   _animationDelegate = null;
   _modelFileNames = [];
   _assetLoader = new EntityAssetLoader();
+  _loadGeneration = 0;
+  _loadStatus = "idle";
   controlledRotation = false;
+  hasWarnedDynamicTrimesh = false;
   constructor(options) {
     super();
     this.options = { ...actorDefaults, ...options };
     this.prependUpdate(this.actorUpdate.bind(this));
     this.controlledRotation = true;
   }
-  /**
-   * Initiates model and animation loading in background (deferred).
-   * Call returns immediately; assets will be ready on subsequent updates.
-   */
+  create() {
+    if (this._loadStatus === "idle" && (this.options.models?.length ?? 0) > 0) {
+      this.load();
+    }
+    return super.create();
+  }
   load() {
-    this._modelFileNames = this.options.models || [];
-    this.loadModelsDeferred();
+    if (this._loadStatus === "loading" || this._loadStatus === "loaded") {
+      return;
+    }
+    this._modelFileNames = [...this.options.models || []];
+    if (this._modelFileNames.length === 0) {
+      return;
+    }
+    this.disposeRuntimeState(true);
+    this._loadStatus = "loading";
+    this.loadModelsDeferred(++this._loadGeneration);
   }
-  /**
-   * Returns current data synchronously.
-   * May return null values if loading is still in progress.
-   */
   data() {
     return {
       animations: this._animationDelegate?.animations,
       objectModel: this._object,
+      collisionSource: this._collisionSource ?? this._object,
       collisionShape: this.options.collisionShape
     };
   }
+  needsDeferredModelCollision() {
+    if (!this.requiresLoadedCollisionSource()) {
+      return false;
+    }
+    return !this.getRuntimeCollisionSource();
+  }
+  synchronizeRuntimeCollider() {
+    const resolvedShape = this.getResolvedCollisionShape();
+    let colliderDesc;
+    if (resolvedShape === "bounds") {
+      colliderDesc = createBoundsColliderFromModel(
+        this._object,
+        this.group ?? this._object,
+        this.options
+      );
+    } else if (resolvedShape === "trimesh") {
+      colliderDesc = createTrimeshColliderFromModel(
+        this._object,
+        this.group ?? this._object,
+        this.options
+      );
+    } else {
+      const collisionSource = this.getRuntimeCollisionSource();
+      colliderDesc = createCapsuleColliderFromModel(
+        collisionSource,
+        collisionSource,
+        this._object,
+        this._object,
+        this.options
+      );
+    }
+    this.colliderDesc = colliderDesc;
+    if (this.colliderDescs.length > 0) {
+      this.colliderDescs[0] = colliderDesc;
+    } else {
+      this.colliderDescs.push(colliderDesc);
+    }
+  }
   actorUpdate(params) {
     this._animationDelegate?.update(params.delta);
   }
-  /**
-   * Clean up actor resources including animations, models, and groups
-   */
   actorDestroy() {
+    this._loadGeneration += 1;
+    this._loadStatus = "idle";
+    this.disposeRuntimeState(true);
+    this._modelFileNames = [];
+  }
+  _cleanup(params) {
+    super._cleanup(params);
+    this.actorDestroy();
+  }
+  playAnimation(animationOptions) {
+    this._animationDelegate?.playAnimation(animationOptions);
+  }
+  get object() {
+    return this._object;
+  }
+  get collisionSource() {
+    return this._collisionSource ?? this._object;
+  }
+  getDebugInfo() {
+    const debugInfo = {
+      type: "Actor",
+      models: this._modelFileNames.length > 0 ? this._modelFileNames : "none",
+      modelLoaded: !!this._object,
+      scale: this.options.scale ? `${this.options.scale.x}, ${this.options.scale.y}, ${this.options.scale.z}` : "1, 1, 1",
+      collisionShape: this.getResolvedCollisionShape()
+    };
     if (this._animationDelegate) {
-      this._animationDelegate.dispose();
-      this._animationDelegate = null;
+      debugInfo.currentAnimation = this._animationDelegate.currentAnimationKey || "none";
+      debugInfo.animationsCount = this.options.animations?.length || 0;
     }
     if (this._object) {
+      let meshCount = 0;
+      let vertexCount = 0;
       this._object.traverse((child) => {
-        if (child.isMesh) {
-          const mesh = child;
-          mesh.geometry?.dispose();
-          if (Array.isArray(mesh.material)) {
-            mesh.material.forEach((m) => m.dispose());
-          } else if (mesh.material) {
-            mesh.material.dispose();
-          }
+        if (!child.isMesh) {
+          return;
+        }
+        meshCount++;
+        const geometry = child.geometry;
+        if (geometry?.attributes.position) {
+          vertexCount += geometry.attributes.position.count;
         }
       });
-      this._object = null;
+      debugInfo.meshCount = meshCount;
+      debugInfo.vertexCount = vertexCount;
+    }
+    return debugInfo;
+  }
+  getResolvedCollisionShape() {
+    return resolveCollisionShape(
+      this.options.collisionShape,
+      Boolean(this.options.collision?.static),
+      () => warnDynamicTrimeshOnce(this)
+    );
+  }
+  requiresLoadedCollisionSource() {
+    const resolvedShape = this.getResolvedCollisionShape();
+    if (resolvedShape === "bounds" || resolvedShape === "trimesh") {
+      return !hasExplicitCollisionSize(this.options);
+    }
+    if (resolvedShape === "capsule") {
+      return !hasExplicitCollisionSize(this.options) && this.getCollisionSourceSelection().file !== null;
+    }
+    return false;
+  }
+  getRuntimeCollisionSource() {
+    const resolvedShape = this.getResolvedCollisionShape();
+    if (resolvedShape === "bounds" || resolvedShape === "trimesh") {
+      return this._object;
+    }
+    return this._collisionSource ?? this._object;
+  }
+  getCollisionSourceSelection() {
+    const modelFile = this.options.models?.[0] ?? null;
+    const animationFile = this.options.animations?.[0]?.path ?? null;
+    if (animationFile) {
+      return {
+        file: animationFile,
+        reuseVisibleModel: animationFile === modelFile
+      };
+    }
+    return {
+      file: modelFile,
+      reuseVisibleModel: true
+    };
+  }
+  disposeRuntimeState(clearGroup) {
+    if (this._animationDelegate) {
+      this._animationDelegate.dispose();
+      this._animationDelegate = null;
+    }
+    const collisionSource = this._collisionSource;
+    disposeObjectResources(this._object);
+    if (collisionSource && collisionSource !== this._object) {
+      disposeObjectResources(collisionSource);
     }
-    if (this.group) {
+    this._object = null;
+    this._collisionSource = null;
+    if (clearGroup && this.group) {
       this.group.clear();
-      this.group = null;
+      this.group = void 0;
     }
-    this._modelFileNames = [];
   }
-  /**
-   * Deferred loading - starts async load and updates entity when complete.
-   * Called by synchronous load() method.
-   */
-  loadModelsDeferred() {
-    if (this._modelFileNames.length === 0) return;
+  loadModelsDeferred(loadGeneration) {
     this.dispatch("entity:model:loading", {
       entityId: this.uuid,
       files: this._modelFileNames
     });
-    const promises = this._modelFileNames.map((file) => this._assetLoader.loadFile(file));
-    Promise.all(promises).then((results) => {
-      if (results[0]?.object) {
-        this._object = results[0].object;
+    const collisionSourceSelection = this.getCollisionSourceSelection();
+    const promises = this._modelFileNames.map(
+      (file) => this._assetLoader.loadFile(file, { clone: true })
+    );
+    const collisionSourcePromise = collisionSourceSelection.file && !collisionSourceSelection.reuseVisibleModel ? this._assetLoader.loadFile(collisionSourceSelection.file, { clone: true }) : Promise.resolve(null);
+    Promise.all([Promise.all(promises), collisionSourcePromise]).then(([results, collisionSourceResult]) => {
+      if (loadGeneration !== this._loadGeneration) {
+        results.forEach((result) => disposeObjectResources(result.object ?? null));
+        if (collisionSourceResult?.object) {
+          disposeObjectResources(collisionSourceResult.object);
+        }
+        return;
       }
+      this._object = results[0]?.object ?? null;
+      this._collisionSource = collisionSourceSelection.reuseVisibleModel ? this._object : collisionSourceResult?.object ?? this._object;
+      this._loadStatus = this._object ? "loaded" : "idle";
       let meshCount = 0;
       if (this._object) {
         this._object.traverse((child) => {
-          if (child.isMesh) meshCount++;
+          if (child.isMesh) {
+            meshCount++;
+          }
         });
         this.group = new Group4();
-        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.group.add(this._object);
+        this.group.scale.copy(getActorScale(this.options));
         this.applyMaterialOverrides();
         this._animationDelegate = new AnimationDelegate(this._object);
-        this._animationDelegate.loadAnimations(this.options.animations || []).then(() => {
+        void this._animationDelegate.loadAnimations(this.options.animations || []).then(() => {
+          if (loadGeneration !== this._loadGeneration) {
+            return;
+          }
           this.dispatch("entity:animation:loaded", {
             entityId: this.uuid,
             animationCount: this.options.animations?.length || 0
@@ -3231,72 +4144,61 @@ var ZylemActor = class extends GameEntity {
         success: !!this._object,
         meshCount
       });
+    }).catch((error) => {
+      if (loadGeneration !== this._loadGeneration) {
+        return;
+      }
+      this._loadStatus = "idle";
+      console.error("Failed to load actor model", error);
+      this.dispatch("entity:model:loaded", {
+        entityId: this.uuid,
+        success: false,
+        meshCount: 0
+      });
     });
   }
-  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) {
+    if (!materialOptions || !materialOptions.color && !materialOptions.path && materialOptions.opacity === void 0) {
+      return;
+    }
+    if (!this._object) {
       return;
     }
-    if (!this._object) return;
     this._object.traverse((child) => {
-      if (child.isMesh) {
-        const mesh = child;
-        if (materialOptions.color) {
-          const newMaterial = new MeshStandardMaterial4({
-            color: materialOptions.color,
-            emissiveIntensity: 0.5,
-            lightMapIntensity: 0.5,
-            fog: true
-          });
-          mesh.castShadow = true;
-          mesh.receiveShadow = true;
-          mesh.material = newMaterial;
-        }
+      if (!child.isMesh) {
+        return;
       }
-    });
-  }
-  get object() {
-    return this._object;
-  }
-  /**
-   * Provide custom debug information for the actor
-   * This will be merged with the default debug information
-   */
-  getDebugInfo() {
-    const debugInfo = {
-      type: "Actor",
-      models: this._modelFileNames.length > 0 ? this._modelFileNames : "none",
-      modelLoaded: !!this._object,
-      scale: this.options.scale ? `${this.options.scale.x}, ${this.options.scale.y}, ${this.options.scale.z}` : "1, 1, 1"
-    };
-    if (this._animationDelegate) {
-      debugInfo.currentAnimation = this._animationDelegate.currentAnimationKey || "none";
-      debugInfo.animationsCount = this.options.animations?.length || 0;
-    }
-    if (this._object) {
-      let meshCount = 0;
-      let vertexCount = 0;
-      this._object.traverse((child) => {
-        if (child.isMesh) {
-          meshCount++;
-          const geometry = child.geometry;
-          if (geometry && geometry.attributes.position) {
-            vertexCount += geometry.attributes.position.count;
-          }
+      const mesh = child;
+      if (materialOptions.color) {
+        const newMaterial = new MeshStandardMaterial4({
+          color: materialOptions.color,
+          emissiveIntensity: 0.5,
+          lightMapIntensity: 0.5,
+          fog: true,
+          opacity: materialOptions.opacity ?? 1,
+          transparent: materialOptions.opacity !== void 0 && materialOptions.opacity < 1
+        });
+        mesh.castShadow = true;
+        mesh.receiveShadow = true;
+        mesh.material = newMaterial;
+        return;
+      }
+      if (materialOptions.opacity === void 0) {
+        return;
+      }
+      const applyOpacity = (material) => {
+        const clonedMaterial = material.clone();
+        if ("opacity" in clonedMaterial && "transparent" in clonedMaterial) {
+          const transparentMaterial = clonedMaterial;
+          transparentMaterial.opacity = materialOptions.opacity;
+          transparentMaterial.transparent = materialOptions.opacity < 1;
+          transparentMaterial.needsUpdate = true;
         }
-      });
-      debugInfo.meshCount = meshCount;
-      debugInfo.vertexCount = vertexCount;
-    }
-    return debugInfo;
+        return clonedMaterial;
+      };
+      mesh.material = Array.isArray(mesh.material) ? mesh.material.map(applyOpacity) : applyOpacity(mesh.material);
+    });
   }
 };
 function createActor(...args) {
@@ -3306,12 +4208,13 @@ function createActor(...args) {
     EntityClass: ZylemActor,
     BuilderClass: ActorBuilder,
     CollisionBuilderClass: ActorCollisionBuilder,
-    entityType: ZylemActor.type
+    entityType: ZylemActor.type,
+    cloneFactory: (options) => createActor(options ?? {})
   });
 }
 
 // src/lib/entities/text.ts
-import { Color as Color6, Group as Group5, Sprite as ThreeSprite2, SpriteMaterial as SpriteMaterial2, CanvasTexture, LinearFilter, Vector2 as Vector24, ClampToEdgeWrapping } from "three";
+import { Color as Color7, Group as Group5, Sprite as ThreeSprite2, SpriteMaterial as SpriteMaterial2, CanvasTexture, LinearFilter, Vector2 as Vector25, ClampToEdgeWrapping } from "three";
 var textDefaults = {
   position: void 0,
   text: "",
@@ -3321,7 +4224,7 @@ var textDefaults = {
   backgroundColor: null,
   padding: 4,
   stickToViewport: true,
-  screenPosition: new Vector24(24, 24),
+  screenPosition: new Vector25(24, 24),
   zDistance: 1
 };
 var TextBuilder = class extends EntityBuilder {
@@ -3433,7 +4336,7 @@ var ZylemText = class _ZylemText extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color6 ? color : new Color6(color);
+    const c = color instanceof Color7 ? color : new Color7(color);
     return `#${c.getHexString()}`;
   }
   textSetup(params) {
@@ -3493,7 +4396,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     if (!this._sprite || !this._cameraRef) return;
     const camera = this._cameraRef.camera;
     const { width, height } = this.getResolution();
-    const sp = this.options.screenPosition ?? new Vector24(24, 24);
+    const sp = this.options.screenPosition ?? new Vector25(24, 24);
     const { px, py } = this.getScreenPixels(sp, width, height);
     const zDist = Math.max(1e-3, this.options.zDistance ?? 1);
     const { worldHalfW, worldHalfH } = this.computeWorldExtents(camera, zDist);
@@ -3546,12 +4449,13 @@ function createText(...args) {
     defaultConfig: { ...textDefaults },
     EntityClass: ZylemText,
     BuilderClass: TextBuilder,
-    entityType: ZylemText.type
+    entityType: ZylemText.type,
+    cloneFactory: (options) => createText(options ?? {})
   });
 }
 
 // src/lib/entities/rect.ts
-import { Color as Color7, Group as Group6, Sprite as ThreeSprite3, SpriteMaterial as SpriteMaterial3, CanvasTexture as CanvasTexture2, LinearFilter as LinearFilter2, Vector2 as Vector25, ClampToEdgeWrapping as ClampToEdgeWrapping2, ShaderMaterial as ShaderMaterial3, Mesh as Mesh6, PlaneGeometry as PlaneGeometry2, Vector3 as Vector313 } from "three";
+import { Color as Color8, Group as Group6, Sprite as ThreeSprite3, SpriteMaterial as SpriteMaterial3, CanvasTexture as CanvasTexture2, LinearFilter as LinearFilter2, Vector2 as Vector26, ClampToEdgeWrapping as ClampToEdgeWrapping2, ShaderMaterial as ShaderMaterial3, Mesh as Mesh7, PlaneGeometry as PlaneGeometry2, Vector3 as Vector314 } from "three";
 var rectDefaults = {
   position: void 0,
   width: 120,
@@ -3562,9 +4466,9 @@ var rectDefaults = {
   radius: 0,
   padding: 0,
   stickToViewport: true,
-  screenPosition: new Vector25(24, 24),
+  screenPosition: new Vector26(24, 24),
   zDistance: 1,
-  anchor: new Vector25(0, 0)
+  anchor: new Vector26(0, 0)
 };
 var RectBuilder = class extends EntityBuilder {
   createEntity(options) {
@@ -3685,7 +4589,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color7 ? color : new Color7(color);
+    const c = color instanceof Color8 ? color : new Color8(color);
     return `#${c.getHexString()}`;
   }
   /**
@@ -3721,7 +4625,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
           if (mat.uniforms?.tDiffuse) mat.uniforms.tDiffuse.value = this._texture;
           if (mat.uniforms?.iResolution && this._canvas) mat.uniforms.iResolution.value.set(this._canvas.width, this._canvas.height, 1);
         }
-        this._mesh = new Mesh6(new PlaneGeometry2(1, 1), mat);
+        this._mesh = new Mesh7(new PlaneGeometry2(1, 1), mat);
         this.group?.add(this._mesh);
         this._sprite.visible = false;
       }
@@ -3736,10 +4640,10 @@ var ZylemRect = class _ZylemRect extends GameEntity {
         const desiredW = Math.max(2, Math.floor(width));
         const desiredH = Math.max(2, Math.floor(height));
         const changed = desiredW !== (this.options.width ?? 0) || desiredH !== (this.options.height ?? 0);
-        this.options.screenPosition = new Vector25(Math.floor(x), Math.floor(y));
+        this.options.screenPosition = new Vector26(Math.floor(x), Math.floor(y));
         this.options.width = desiredW;
         this.options.height = desiredH;
-        this.options.anchor = new Vector25(0, 0);
+        this.options.anchor = new Vector26(0, 0);
         if (changed) {
           this.redrawRect();
         }
@@ -3753,8 +4657,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     if (!this._sprite || !this._cameraRef) return;
     const camera = this._cameraRef.camera;
     const { width, height } = this.getResolution();
-    const px = (this.options.screenPosition ?? new Vector25(24, 24)).x;
-    const py = (this.options.screenPosition ?? new Vector25(24, 24)).y;
+    const px = (this.options.screenPosition ?? new Vector26(24, 24)).x;
+    const py = (this.options.screenPosition ?? new Vector26(24, 24)).y;
     const zDist = Math.max(1e-3, this.options.zDistance ?? 1);
     let worldHalfW = 1;
     let worldHalfH = 1;
@@ -3785,7 +4689,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
       this._sprite.scale.set(scaleX, scaleY, 1);
       if (this._mesh) this._mesh.scale.set(scaleX, scaleY, 1);
     }
-    const anchor = this.options.anchor ?? new Vector25(0, 0);
+    const anchor = this.options.anchor ?? new Vector26(0, 0);
     const ax = Math.min(100, Math.max(0, anchor.x)) / 100;
     const ay = Math.min(100, Math.max(0, anchor.y)) / 100;
     const offsetX = (0.5 - ax) * scaleX;
@@ -3808,8 +4712,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     }
     if (bounds.world) {
       const { left, right, top, bottom, z = 0 } = bounds.world;
-      const tl = this.worldToScreen(new Vector313(left, top, z));
-      const br = this.worldToScreen(new Vector313(right, bottom, z));
+      const tl = this.worldToScreen(new Vector314(left, top, z));
+      const br = this.worldToScreen(new Vector314(right, bottom, z));
       const x = Math.min(tl.x, br.x);
       const y = Math.min(tl.y, br.y);
       const width = Math.abs(br.x - tl.x);
@@ -3843,7 +4747,8 @@ function createRect(...args) {
     defaultConfig: { ...rectDefaults },
     EntityClass: ZylemRect,
     BuilderClass: RectBuilder,
-    entityType: ZylemRect.type
+    entityType: ZylemRect.type,
+    cloneFactory: (options) => createRect(options ?? {})
   });
 }
 
@@ -3894,7 +4799,10 @@ function createCone(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createCone(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/pyramid.ts
@@ -3942,7 +4850,10 @@ function createPyramid(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createPyramid(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/cylinder.ts
@@ -3997,7 +4908,10 @@ function createCylinder(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createCylinder(cloneOptions ?? {})
+  );
 }
 
 // src/lib/entities/pill.ts
@@ -4049,7 +4963,10 @@ function createPill(...args) {
       collisionFilter: options.collisionFilter
     })
   );
-  return entity;
+  return finalizeEntityCloneSupport(
+    entity,
+    (cloneOptions) => createPill(cloneOptions ?? {})
+  );
 }
 export {
   ZylemBox,