@zylem/game-lib 0.6.0 → 0.6.3

package/dist/entities.js

@@ -1,10 +1,8 @@
 // src/lib/entities/box.ts
-import { ColliderDesc as ColliderDesc2 } from "@dimforge/rapier3d-compat";
-import { BoxGeometry, Color as Color4 } from "three";
-import { Vector3 as Vector33 } from "three";
+import { Vector3 as Vector38 } from "three";
 
 // src/lib/entities/entity.ts
-import { ShaderMaterial } from "three";
+import { Mesh, ShaderMaterial, Group } from "three";
 
 // src/lib/systems/transformable.system.ts
 import {
@@ -48,6 +46,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: [],
@@ -161,12 +162,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);
@@ -175,6 +180,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") {
@@ -184,12 +195,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);
     }
   }
   // ─────────────────────────────────────────────────────────────────────────────
@@ -203,136 +215,378 @@ var BaseNode = class _BaseNode {
   }
 };
 
-// src/lib/entities/entity.ts
-var GameEntity = class extends BaseNode {
-  behaviors = [];
-  group;
-  mesh;
-  materials;
-  bodyDesc = null;
-  body = null;
-  colliderDesc;
-  collider;
-  custom = {};
-  debugInfo = {};
-  debugMaterial;
-  collisionDelegate = {
-    collision: []
-  };
-  collisionType;
-  behaviorCallbackMap = {
-    setup: [],
-    update: [],
-    destroy: [],
-    collision: []
-  };
+// ../../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() {
-    super();
-  }
-  create() {
-    const { position: setupPosition } = this.options;
-    const { x, y, z } = setupPosition || { x: 0, y: 0, z: 0 };
-    this.behaviors = [
-      { component: position, values: { x, y, z } },
-      { component: scale, values: { x: 0, y: 0, z: 0 } },
-      { component: rotation, values: { x: 0, y: 0, z: 0, w: 0 } }
-    ];
-    this.name = this.options.name || "";
-    return this;
+    this.emitter = mitt_default();
   }
   /**
-   * Add collision callbacks
+   * Dispatch an event to all listeners.
    */
-  onCollision(...callbacks) {
-    const existing = this.collisionDelegate.collision ?? [];
-    this.collisionDelegate.collision = [...existing, ...callbacks];
-    return this;
+  dispatch(event, payload) {
+    this.emitter.emit(event, payload);
   }
   /**
-   * Entity-specific setup - runs behavior callbacks
-   * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+   * Subscribe to an event. Returns an unsubscribe function.
    */
-  _setup(params) {
-    this.behaviorCallbackMap.setup.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
-  }
-  async _loaded(_params) {
+  listen(event, handler) {
+    this.emitter.on(event, handler);
+    const unsub = () => this.emitter.off(event, handler);
+    this.unsubscribes.push(unsub);
+    return unsub;
   }
   /**
-   * Entity-specific update - updates materials and runs behavior callbacks
-   * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+   * Subscribe to all events.
    */
-  _update(params) {
-    this.updateMaterials(params);
-    this.behaviorCallbackMap.update.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
+  listenAll(handler) {
+    this.emitter.on("*", handler);
+    const unsub = () => this.emitter.off("*", handler);
+    this.unsubscribes.push(unsub);
+    return unsub;
   }
   /**
-   * Entity-specific destroy - runs behavior callbacks
-   * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+   * Clean up all subscriptions.
    */
-  _destroy(params) {
-    this.behaviorCallbackMap.destroy.forEach((callback) => {
-      callback({ ...params, me: this });
-    });
-  }
-  async _cleanup(_params) {
-  }
-  _collision(other, globals) {
-    if (this.collisionDelegate.collision?.length) {
-      const callbacks = this.collisionDelegate.collision;
-      callbacks.forEach((callback) => {
-        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;
+  dispose() {
+    this.unsubscribes.forEach((fn) => fn());
+    this.unsubscribes = [];
+    this.emitter.all.clear();
   }
-  updateMaterials(params) {
-    if (!this.materials?.length) {
-      return;
+};
+
+// src/lib/events/zylem-events.ts
+var zylemEventBus = mitt_default();
+
+// src/lib/actions/capabilities/transform-store.ts
+import { proxy } 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
     }
-    for (const material of this.materials) {
-      if (material instanceof ShaderMaterial) {
-        if (material.uniforms) {
-          material.uniforms.iTime && (material.uniforms.iTime.value += params.delta);
-        }
-      }
+  };
+  return proxy({
+    ...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);
   }
-  buildInfo() {
-    const info = {};
-    info.name = this.name;
-    info.uuid = this.uuid;
-    info.eid = this.eid.toString();
-    return info;
+}
+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/entities/builder.ts
-import { BufferGeometry as BufferGeometry2, Mesh as Mesh3, Color as Color3 } from "three";
+// 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 as ActiveCollisionTypes2,
+  ColliderDesc as ColliderDesc2,
+  RigidBodyDesc as RigidBodyDesc2,
+  RigidBodyType as RigidBodyType2
+} from "@dimforge/rapier3d-compat";
+import { Vector3 as Vector34 } from "three";
 
 // src/lib/collision/collision-builder.ts
-import { ActiveCollisionTypes, ColliderDesc, RigidBodyDesc, RigidBodyType, Vector3 } from "@dimforge/rapier3d-compat";
+import { ActiveCollisionTypes, ColliderDesc, RigidBodyDesc, RigidBodyType, Vector3 as Vector33 } from "@dimforge/rapier3d-compat";
 var typeToGroup = /* @__PURE__ */ new Map();
 var nextGroupId = 0;
 function getOrCreateCollisionGroupId(type) {
@@ -354,7 +608,7 @@ function createCollisionFilter(allowedTypes) {
 var CollisionBuilder = class {
   static = false;
   sensor = false;
-  gravity = new Vector3(0, 0, 0);
+  gravity = new Vector33(0, 0, 0);
   build(options) {
     const bodyDesc = this.bodyDesc({
       isDynamicBody: !this.static
@@ -379,7 +633,7 @@ var CollisionBuilder = class {
     return this;
   }
   collider(options) {
-    const size = options.size ?? new Vector3(1, 1, 1);
+    const size = options.size ?? new Vector33(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
     let colliderDesc = ColliderDesc.cuboid(half.x, half.y, half.z);
     return colliderDesc;
@@ -391,283 +645,484 @@ var CollisionBuilder = class {
   }
 };
 
-// src/lib/graphics/mesh.ts
-import { Mesh as Mesh2 } 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 Mesh2(geometry, materials.at(-1));
-    mesh.position.set(0, 0, 0);
-    mesh.castShadow = true;
-    mesh.receiveShadow = true;
-    return mesh;
+// src/lib/entities/parts/collision-factories.ts
+function isCollisionComponent(obj) {
+  return obj && obj.__kind === "collision";
+}
+function buildBodyDesc(isStatic) {
+  const type = isStatic ? RigidBodyType2.Fixed : RigidBodyType2.Dynamic;
+  return new RigidBodyDesc2(type).setTranslation(0, 0, 0).setGravityScale(1).setCanSleep(false).setCcdEnabled(true);
+}
+function applyCollisionOptions(colliderDesc, opts) {
+  if (opts.offset) {
+    colliderDesc.setTranslation(opts.offset.x, opts.offset.y, opts.offset.z);
   }
-  _postBuild() {
-    return;
+  if (opts.sensor) {
+    colliderDesc.setSensor(true);
+    colliderDesc.activeCollisionTypes = ActiveCollisionTypes2.KINEMATIC_FIXED;
   }
-};
-
-// src/lib/graphics/material.ts
-import {
-  Color as Color2,
-  MeshPhongMaterial,
-  MeshStandardMaterial,
-  RepeatWrapping,
-  ShaderMaterial as ShaderMaterial2,
-  TextureLoader,
-  Vector2,
-  Vector3 as Vector32
-} from "three";
-
-// 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;
+  if (opts.collisionType) {
+    const groupId = getOrCreateCollisionGroupId(opts.collisionType);
+    let filter = 65535;
+    if (opts.collisionFilter) {
+      filter = createCollisionFilter(opts.collisionFilter);
+    }
+    colliderDesc.setCollisionGroups(groupId << 16 | filter);
   }
-  return hash.toString(36);
+}
+function makeComponent(colliderDesc, opts) {
+  applyCollisionOptions(colliderDesc, opts);
+  return {
+    __kind: "collision",
+    bodyDesc: buildBodyDesc(opts.static ?? false),
+    colliderDesc
+  };
+}
+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);
+}
+function sphereCollision(opts = {}) {
+  const desc = ColliderDesc2.ball(opts.radius ?? 1);
+  return makeComponent(desc, opts);
+}
+function coneCollision(opts = {}) {
+  const radius = opts.radius ?? 1;
+  const height = opts.height ?? 2;
+  const desc = ColliderDesc2.cone(height / 2, radius);
+  return makeComponent(desc, opts);
+}
+function pyramidCollision(opts = {}) {
+  const radius = opts.radius ?? 1;
+  const height = opts.height ?? 2;
+  const desc = ColliderDesc2.cone(height / 2, radius);
+  return makeComponent(desc, opts);
+}
+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);
+}
+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);
+}
+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 });
 }
 
-// src/lib/graphics/shaders/fragment/stars.glsl
-var stars_default = "#include <common>\n\nuniform vec3 iResolution;\nuniform float iTime;\nvarying vec2 vUv;\n\n// Credit goes to:\n// https://www.shadertoy.com/view/mtyGWy\n\nvec3 palette( float t ) {\n    vec3 a = vec3(0.5, 0.5, 0.5);\n    vec3 b = vec3(0.5, 0.5, 0.5);\n    vec3 c = vec3(1.0, 1.0, 1.0);\n    vec3 d = vec3(0.263,0.416,0.557);\n\n    return a + b*cos( 6.28318*(c*t+d) );\n}\n\nvoid mainImage( out vec4 fragColor, in vec2 fragCoord ) {\n    vec2 uv = (fragCoord * 2.0 - iResolution.xy) / iResolution.y;\n    vec2 uv0 = uv;\n    vec3 finalColor = vec3(0.0);\n    \n    for (float i = 0.0; i < 4.0; i++) {\n        uv = fract(uv * 1.5) - 0.5;\n\n        float d = length(uv) * exp(-length(uv0));\n\n        vec3 col = palette(length(uv0) + i*.4 + iTime*.4);\n\n        d = sin(d*5. + iTime)/5.;\n        d = abs(d);\n\n        d = pow(0.01 / d, 1.2);\n\n        finalColor += col * d;\n    }\n        \n    fragColor = vec4(finalColor, 1.0);\n}\n \nvoid main() {\n  mainImage(gl_FragColor, vUv);\n}";
-
-// src/lib/graphics/shaders/fragment/fire.glsl
-var fire_default = "#include <common>\n \nuniform vec3 iResolution;\nuniform float iTime;\nuniform vec2 iOffset;\nvarying vec2 vUv;\n\nfloat snoise(vec3 uv, float res)\n{\n	const vec3 s = vec3(1e0, 1e2, 1e3);\n	\n	uv *= res;\n	\n	vec3 uv0 = floor(mod(uv, res))*s;\n	vec3 uv1 = floor(mod(uv+vec3(1.), res))*s;\n	\n	vec3 f = fract(uv); f = f*f*(3.0-2.0*f);\n\n	vec4 v = vec4(uv0.x+uv0.y+uv0.z, uv1.x+uv0.y+uv0.z,\n		      	  uv0.x+uv1.y+uv0.z, uv1.x+uv1.y+uv0.z);\n\n	vec4 r = fract(sin(v*1e-1)*1e3);\n	float r0 = mix(mix(r.x, r.y, f.x), mix(r.z, r.w, f.x), f.y);\n	\n	r = fract(sin((v + uv1.z - uv0.z)*1e-1)*1e3);\n	float r1 = mix(mix(r.x, r.y, f.x), mix(r.z, r.w, f.x), f.y);\n	\n	return mix(r0, r1, f.z)*2.-1.;\n}\n\nvoid mainImage( out vec4 fragColor, in vec2 fragCoord ) {\n	vec2 p = -.5 + fragCoord.xy / iResolution.xy;\n	p.x *= iResolution.x/iResolution.y;\n	\n	float color = 3.0 - (3.*length(2.*p));\n	\n	vec3 coord = vec3(atan(p.x,p.y)/6.2832+.5, length(p)*.4, .5);\n	\n	for(int i = 1; i <= 7; i++)\n	{\n		float power = pow(2.0, float(i));\n		color += (1.5 / power) * snoise(coord + vec3(0.,-iTime*.05, iTime*.01), power*16.);\n	}\n	fragColor = vec4( color, pow(max(color,0.),2.)*0.4, pow(max(color,0.),3.)*0.15 , 1.0);\n}\n\nvoid main() {\n  mainImage(gl_FragColor, vUv);\n}";
+// src/lib/entities/common.ts
+import { Color, Vector3 as Vector35 } from "three";
 
-// 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/shaders/vertex/object.shader.ts
+var objectVertexShader = `
+uniform vec2 uvScale;
+varying vec2 vUv;
 
-// src/lib/graphics/shaders/fragment/debug.glsl
-var debug_default = "varying vec3 vBarycentric;\nuniform vec3 baseColor;\nuniform vec3 wireframeColor;\nuniform float wireframeThickness;\n\nfloat edgeFactor() {\n    vec3 d = fwidth(vBarycentric);\n    vec3 a3 = smoothstep(vec3(0.0), d * wireframeThickness, vBarycentric);\n    return min(min(a3.x, a3.y), a3.z);\n}\n\nvoid main() {\n    float edge = edgeFactor();\n\n    vec3 wireColor = wireframeColor;\n\n    vec3 finalColor = mix(wireColor, baseColor, edge);\n    \n    gl_FragColor = vec4(finalColor, 1.0);\n}\n";
+void main() {
+	vUv = uv;
+	vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+	gl_Position = projectionMatrix * mvPosition;
+}
+`;
 
-// src/lib/graphics/shaders/vertex/object-shader.glsl
-var object_shader_default = "uniform vec2 uvScale;\nvarying vec2 vUv;\n\nvoid main() {\n	vUv = uv;\n	vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );\n	gl_Position = projectionMatrix * mvPosition;\n}";
+// src/lib/graphics/shaders/standard.shader.ts
+var fragment = `
+uniform sampler2D tDiffuse;
+varying vec2 vUv;
 
-// src/lib/graphics/shaders/vertex/debug.glsl
-var debug_default2 = "varying vec3 vBarycentric;\n\nvoid main() {\n    vec3 barycentric = vec3(0.0);\n    int index = gl_VertexID % 3;\n    if (index == 0) barycentric = vec3(1.0, 0.0, 0.0);\n    else if (index == 1) barycentric = vec3(0.0, 1.0, 0.0);\n    else barycentric = vec3(0.0, 0.0, 1.0);\n    vBarycentric = barycentric;\n    \n    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}\n";
+void main() {
+	vec4 texel = texture2D( tDiffuse, vUv );
 
-// src/lib/core/preset-shader.ts
-var starShader = {
-  fragment: stars_default,
-  vertex: object_shader_default
-};
-var fireShader = {
-  fragment: fire_default,
-  vertex: object_shader_default
-};
+	gl_FragColor = texel;
+}
+`;
 var standardShader = {
-  fragment: standard_default,
-  vertex: object_shader_default
+  vertex: objectVertexShader,
+  fragment
 };
-var debugShader = {
-  fragment: debug_default,
-  vertex: debug_default2
+
+// src/lib/entities/common.ts
+var commonDefaults = {
+  position: new Vector35(0, 0, 0),
+  material: {
+    color: new Color("#ffffff"),
+    shader: standardShader
+  },
+  collision: {
+    static: false
+  }
 };
-var shaderMap = /* @__PURE__ */ new Map();
-shaderMap.set("standard", standardShader);
-shaderMap.set("fire", fireShader);
-shaderMap.set("star", starShader);
-shaderMap.set("debug", debugShader);
-var preset_shader_default = shaderMap;
+function mergeArgs(args, defaults) {
+  const configArgs = args.filter(
+    (arg) => !(arg instanceof BaseNode)
+  );
+  let merged = { ...defaults };
+  for (const opt of configArgs) {
+    merged = { ...merged, ...opt };
+  }
+  return merged;
+}
 
-// src/lib/graphics/material.ts
-var MaterialBuilder = class _MaterialBuilder {
-  static batchMaterialMap = /* @__PURE__ */ new Map();
-  materials = [];
-  batchMaterial(options, entityType) {
-    const batchKey = shortHash(sortedStringify(options));
-    const mappedObject = _MaterialBuilder.batchMaterialMap.get(batchKey);
-    if (mappedObject) {
-      const count = mappedObject.geometryMap.get(entityType);
-      if (count) {
-        mappedObject.geometryMap.set(entityType, count + 1);
+// src/lib/entities/entity.ts
+var GameEntity = class extends BaseNode {
+  behaviors = [];
+  group;
+  mesh;
+  materials;
+  bodyDesc = null;
+  body = null;
+  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;
+  // 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 {
-        mappedObject.geometryMap.set(entityType, 1);
+        super.add(component);
       }
-    } else {
-      _MaterialBuilder.batchMaterialMap.set(
-        batchKey,
-        {
-          geometryMap: /* @__PURE__ */ new Map([[entityType, 1]]),
-          material: this.materials[0]
+    }
+    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);
     }
   }
-  async build(options, entityType) {
-    const { path, repeat, color, shader } = options;
-    if (shader) this.withShader(shader);
-    if (color) this.withColor(color);
-    await this.setTexture(path ?? null, repeat);
-    if (this.materials.length === 0) {
-      this.setColor(new Color2("#ffffff"));
+  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);
     }
-    this.batchMaterial(options, entityType);
   }
-  withColor(color) {
-    this.setColor(color);
-    return this;
+  // ─────────────────────────────────────────────────────────────────────────────
+  // 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;
   }
-  withShader(shaderType) {
-    this.setShader(shaderType);
-    return this;
+  /**
+   * 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;
   }
-  async setTexture(texturePath = null, repeat = new Vector2(1, 1)) {
-    if (!texturePath) {
-      return;
+  /**
+   * 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;
     }
-    const loader = new TextureLoader();
-    const texture = await loader.loadAsync(texturePath);
-    texture.repeat = repeat;
-    texture.wrapS = RepeatWrapping;
-    texture.wrapT = RepeatWrapping;
-    const material = new MeshPhongMaterial({
-      map: texture
-    });
-    this.materials.push(material);
-  }
-  setColor(color) {
-    const material = new MeshStandardMaterial({
-      color,
-      emissiveIntensity: 0.5,
-      lightMapIntensity: 0.5,
-      fog: true
-    });
-    this.materials.push(material);
-  }
-  setShader(customShader) {
-    const { fragment, vertex } = preset_shader_default.get(customShader) ?? preset_shader_default.get("standard");
-    const shader = new ShaderMaterial2({
-      uniforms: {
-        iResolution: { value: new Vector32(1, 1, 1) },
-        iTime: { value: 0 },
-        tDiffuse: { value: null },
-        tDepth: { value: null },
-        tNormal: { value: null }
-      },
-      vertexShader: vertex,
-      fragmentShader: fragment
-    });
-    this.materials.push(shader);
   }
-};
-
-// src/lib/entities/builder.ts
-var EntityCollisionBuilder = class extends CollisionBuilder {
-};
-var EntityMeshBuilder = class extends MeshBuilder {
-  build(options) {
-    return new BufferGeometry2();
+  create() {
+    const { position: setupPosition } = this.options;
+    const { x, y, z } = setupPosition || { x: 0, y: 0, z: 0 };
+    this.behaviors = [
+      { component: position, values: { x, y, z } },
+      { component: scale, values: { x: 0, y: 0, z: 0 } },
+      { component: rotation, values: { x: 0, y: 0, z: 0, w: 0 } }
+    ];
+    this.name = this.options.name || "";
+    return this;
   }
-  postBuild() {
-    return;
+  /**
+   * Add collision callbacks
+   */
+  onCollision(...callbacks) {
+    const existing = this.collisionDelegate.collision ?? [];
+    this.collisionDelegate.collision = [...existing, ...callbacks];
+    return this;
   }
-};
-var EntityBuilder = class {
-  meshBuilder;
-  collisionBuilder;
-  materialBuilder;
-  options;
-  entity;
-  constructor(options, entity, meshBuilder, collisionBuilder) {
-    this.options = options;
-    this.entity = entity;
-    this.meshBuilder = meshBuilder;
-    this.collisionBuilder = collisionBuilder;
-    this.materialBuilder = new MaterialBuilder();
-    const builders = {
-      meshBuilder: this.meshBuilder,
-      collisionBuilder: this.collisionBuilder,
-      materialBuilder: this.materialBuilder
+  /**
+   * 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
     };
-    this.options._builders = builders;
   }
-  withPosition(setupPosition) {
-    this.options.position = setupPosition;
-    return this;
+  /**
+   * Get all behavior references attached to this entity.
+   * Used by the stage to auto-register required systems.
+   */
+  getBehaviorRefs() {
+    return this.behaviorRefs;
   }
-  async withMaterial(options, entityType) {
-    if (this.materialBuilder) {
-      await this.materialBuilder.build(options, entityType);
+  /**
+   * Entity-specific setup - resets actions for a fresh stage session.
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+   */
+  _setup(params) {
+    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();
+      }
     }
-    return this;
   }
-  applyMaterialToGroup(group, materials) {
-    group.traverse((child) => {
-      if (child instanceof Mesh3) {
-        if (child.type === "SkinnedMesh" && materials[0] && !child.material.map) {
-          child.material = materials[0];
-        }
-      }
-      child.castShadow = true;
-      child.receiveShadow = true;
-    });
+  async _loaded(_params) {
   }
-  async build() {
-    const entity = this.entity;
-    if (this.materialBuilder) {
-      entity.materials = this.materialBuilder.materials;
-    }
-    if (this.meshBuilder && entity.materials) {
-      const geometry = this.meshBuilder.build(this.options);
-      entity.mesh = this.meshBuilder._build(this.options, geometry, entity.materials);
-      this.meshBuilder.postBuild();
-    }
-    if (entity.group && entity.materials) {
-      this.applyMaterialToGroup(entity.group, entity.materials);
+  /**
+   * 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);
+  }
+  /**
+   * Entity-specific destroy -- reserved for consumer game logic.
+   * Engine-internal resource disposal runs in _cleanup() instead.
+   */
+  _destroy(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();
+      }
     }
-    if (this.collisionBuilder) {
-      this.collisionBuilder.withCollision(this.options?.collision || {});
-      const [bodyDesc, colliderDesc] = this.collisionBuilder.build(this.options);
-      entity.bodyDesc = bodyDesc;
-      entity.colliderDesc = colliderDesc;
-      const { x, y, z } = this.options.position || { x: 0, y: 0, z: 0 };
-      entity.bodyDesc.setTranslation(x, y, z);
+    this.compoundMeshes.length = 0;
+    this.debugMaterial?.dispose();
+    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 });
+      });
     }
-    if (this.options.collisionType) {
-      entity.collisionType = this.options.collisionType;
+  }
+  updateMaterials(params) {
+    if (!this.materials?.length) {
+      return;
     }
-    if (this.options.color instanceof Color3) {
-      const applyColor = (material) => {
-        const anyMat = material;
-        if (anyMat && anyMat.color && anyMat.color.set) {
-          anyMat.color.set(this.options.color);
+    for (const material of this.materials) {
+      if (material instanceof ShaderMaterial) {
+        if (material.uniforms) {
+          material.uniforms.iTime && (material.uniforms.iTime.value += params.delta);
         }
-      };
-      if (entity.materials?.length) {
-        for (const mat of entity.materials) applyColor(mat);
-      }
-      if (entity.mesh && entity.mesh.material) {
-        const mat = entity.mesh.material;
-        if (Array.isArray(mat)) mat.forEach(applyColor);
-        else applyColor(mat);
-      }
-      if (entity.group) {
-        entity.group.traverse((child) => {
-          if (child instanceof Mesh3 && child.material) {
-            const mat = child.material;
-            if (Array.isArray(mat)) mat.forEach(applyColor);
-            else applyColor(mat);
-          }
-        });
       }
     }
-    return entity;
+  }
+  buildInfo() {
+    const info = {};
+    info.name = this.name;
+    info.uuid = this.uuid;
+    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/entities/delegates/debug.ts
-import { MeshStandardMaterial as MeshStandardMaterial2, MeshBasicMaterial, MeshPhongMaterial as MeshPhongMaterial2 } from "three";
+import { MeshStandardMaterial, MeshBasicMaterial, MeshPhongMaterial } from "three";
 function hasDebugInfo(obj) {
   return obj && typeof obj.getDebugInfo === "function";
 }
@@ -711,7 +1166,7 @@ var DebugDelegate = class {
     const info = {
       type: material.type
     };
-    if (material instanceof MeshStandardMaterial2 || material instanceof MeshBasicMaterial || material instanceof MeshPhongMaterial2) {
+    if (material instanceof MeshStandardMaterial || material instanceof MeshBasicMaterial || material instanceof MeshPhongMaterial) {
       info.color = `#${material.color.getHexString()}`;
       info.opacity = material.opacity;
       info.transparent = material.transparent;
@@ -761,110 +1216,959 @@ var DebugDelegate = class {
   }
 };
 
-// src/lib/entities/delegates/loader.ts
-function isLoadable(obj) {
-  return typeof obj?.load === "function" && typeof obj?.data === "function";
+// src/lib/entities/parts/mesh-factories.ts
+import {
+  BoxGeometry,
+  CapsuleGeometry,
+  ConeGeometry,
+  CylinderGeometry,
+  Mesh as Mesh2,
+  MeshStandardMaterial as MeshStandardMaterial3,
+  SphereGeometry
+} from "three";
+
+// src/lib/graphics/material.ts
+import { Color as Color3, Vector2 as Vector22, Vector3 as Vector37 } from "three";
+import {
+  MeshPhongMaterial as MeshPhongMaterial2,
+  MeshStandardMaterial as MeshStandardMaterial2,
+  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);
 }
-var EntityLoader = class {
-  entityReference;
-  constructor(entity) {
-    this.entityReference = entity;
+function shortHash(objString) {
+  let hash = 0;
+  for (let i = 0; i < objString.length; i++) {
+    hash = Math.imul(31, hash) + objString.charCodeAt(i) | 0;
   }
-  async load() {
-    if (this.entityReference.load) {
-      await this.entityReference.load();
-    }
+  return hash.toString(36);
+}
+
+// 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();
   }
-  async data() {
-    if (this.entityReference.data) {
-      return this.entityReference.data();
+  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);
     }
-    return null;
+    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/entities/create.ts
-async function createEntity(params) {
-  const {
-    args,
-    defaultConfig,
-    EntityClass,
-    BuilderClass,
-    entityType,
-    MeshBuilderClass,
-    CollisionBuilderClass
-  } = params;
-  let builder = null;
-  let configuration;
-  const configurationIndex = args.findIndex((node) => !(node instanceof BaseNode));
-  if (configurationIndex !== -1) {
-    const subArgs = args.splice(configurationIndex, 1);
-    configuration = subArgs.find((node) => !(node instanceof BaseNode));
+// src/lib/core/loaders/gltf-loader.ts
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+var GLTFLoaderAdapter = class {
+  loader;
+  constructor() {
+    this.loader = new GLTFLoader();
   }
-  const mergedConfiguration = configuration ? { ...defaultConfig, ...configuration } : defaultConfig;
-  args.push(mergedConfiguration);
-  for (const arg of args) {
-    if (arg instanceof BaseNode) {
-      continue;
+  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);
     }
-    let entityData = null;
-    const entity = new EntityClass(arg);
+    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 {
-      if (isLoadable(entity)) {
-        const loader = new EntityLoader(entity);
-        await loader.load();
-        entityData = await loader.data();
+      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("Error creating entity with loader:", error);
+      console.error(`Async fetch GLTF load failed for ${url}, falling back to loader.load():`, error);
+      return this.loadMainThread(url, options);
     }
-    builder = new BuilderClass(
-      arg,
-      entity,
-      MeshBuilderClass ? new MeshBuilderClass(entityData) : null,
-      CollisionBuilderClass ? new CollisionBuilderClass(entityData) : null
-    );
-    if (arg.material) {
-      await builder.withMaterial(arg.material, entityType);
+  }
+  async loadMainThread(url, options) {
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (gltf) => {
+          resolve({
+            object: gltf.scene,
+            animations: gltf.animations,
+            gltf
+          });
+        },
+        (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
+    };
+  }
+};
+
+// 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);
   }
-  if (!builder) {
-    throw new Error(`missing options for ${String(entityType)}, builder is not initialized.`);
+  /**
+   * 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);
+    }
   }
-  return await builder.build();
-}
+  async loadMainThread(url, options) {
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (object) => {
+          resolve({
+            object,
+            animations: object.animations || []
+          });
+        },
+        (event) => {
+          if (options?.onProgress && event.lengthComputable) {
+            options.onProgress(event.loaded / event.total);
+          }
+        },
+        (error) => reject(error)
+      );
+    });
+  }
+  /**
+   * Clone a loaded FBX object for reuse
+   */
+  clone(result) {
+    return {
+      object: result.object.clone(),
+      animations: result.animations?.map((anim) => anim.clone())
+    };
+  }
+};
 
-// src/lib/entities/box.ts
-var boxDefaults = {
-  size: new Vector33(1, 1, 1),
-  position: new Vector33(0, 0, 0),
-  collision: {
-    static: false
-  },
-  material: {
-    color: new Color4("#ffffff"),
-    shader: "standard"
+// 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();
+  }
+  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: []
+    };
   }
 };
-var BoxCollisionBuilder = class extends EntityCollisionBuilder {
-  collider(options) {
-    const size = options.size || new Vector33(1, 1, 1);
-    const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
-    let colliderDesc = ColliderDesc2.cuboid(half.x, half.y, half.z);
-    return colliderDesc;
+
+// 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)
+      );
+    });
   }
 };
-var BoxMeshBuilder = class extends EntityMeshBuilder {
-  build(options) {
-    const size = options.size ?? new Vector33(1, 1, 1);
-    return new BoxGeometry(size.x, size.y, size.z);
+
+// 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 BoxBuilder = class extends EntityBuilder {
-  createEntity(options) {
-    return new ZylemBox(options);
+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/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;
+}
+var MaterialBuilder = class _MaterialBuilder {
+  static batchMaterialMap = /* @__PURE__ */ new Map();
+  materials = [];
+  /** Whether to use TSL/NodeMaterial (for WebGPU compatibility) */
+  useTSL;
+  constructor(useTSL = false) {
+    this.useTSL = useTSL;
+  }
+  batchMaterial(options, entityType) {
+    const batchKey = shortHash(sortedStringify(options));
+    const mappedObject = _MaterialBuilder.batchMaterialMap.get(batchKey);
+    if (mappedObject) {
+      const count = mappedObject.geometryMap.get(entityType);
+      if (count) {
+        mappedObject.geometryMap.set(entityType, count + 1);
+      } else {
+        mappedObject.geometryMap.set(entityType, 1);
+      }
+    } else {
+      _MaterialBuilder.batchMaterialMap.set(batchKey, {
+        geometryMap: /* @__PURE__ */ new Map([[entityType, 1]]),
+        material: this.materials[0]
+      });
+    }
+  }
+  build(options, entityType) {
+    const { path, normalMap, repeat, color, shader, useTSL } = options;
+    const shouldUseTSL = useTSL ?? this.useTSL;
+    if (shader) {
+      if (isTSLShader(shader)) {
+        this.setTSLShader(shader);
+      } else if (isGLSLShader(shader)) {
+        if (shouldUseTSL) {
+          console.warn("MaterialBuilder: GLSL shader provided but TSL mode requested. Using GLSL.");
+        }
+        this.setShader(shader);
+      }
+    } else if (path) {
+      this.setTexture(path, repeat, shouldUseTSL);
+    }
+    if (color) {
+      this.withColor(color, shouldUseTSL);
+    }
+    if (this.materials.length === 0) {
+      this.setColor(new Color3("#ffffff"), shouldUseTSL);
+    }
+    if (normalMap && this.materials.length > 0) {
+      this.setNormalMap(normalMap, repeat);
+    }
+    this.batchMaterial(options, entityType);
+  }
+  withColor(color, useTSL = false) {
+    this.setColor(color, useTSL);
+    return this;
+  }
+  withShader(shader) {
+    this.setShader(shader);
+    return this;
+  }
+  withTSLShader(shader) {
+    this.setTSLShader(shader);
+    return this;
+  }
+  /**
+   * 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) {
+    if (!texturePath) {
+      return;
+    }
+    if (useTSL) {
+      const material = new MeshStandardNodeMaterial();
+      this.materials.push(material);
+      assetManager.loadTexture(texturePath, {
+        clone: true,
+        repeat
+      }).then((texture) => {
+        texture.wrapS = RepeatWrapping2;
+        texture.wrapT = RepeatWrapping2;
+        material.map = texture;
+        material.needsUpdate = true;
+      });
+    } else {
+      const material = new MeshPhongMaterial2({
+        map: null
+      });
+      this.materials.push(material);
+      assetManager.loadTexture(texturePath, {
+        clone: true,
+        repeat
+      }).then((texture) => {
+        texture.wrapS = RepeatWrapping2;
+        texture.wrapT = RepeatWrapping2;
+        material.map = texture;
+        material.needsUpdate = true;
+      });
+    }
+  }
+  /**
+   * Set normal map for the current material
+   */
+  setNormalMap(normalMapPath, repeat = new Vector22(1, 1)) {
+    const material = this.materials[this.materials.length - 1];
+    if (!material) return;
+    assetManager.loadTexture(normalMapPath, {
+      clone: true,
+      repeat
+    }).then((texture) => {
+      texture.wrapS = RepeatWrapping2;
+      texture.wrapT = RepeatWrapping2;
+      if (material instanceof MeshStandardMaterial2 || material instanceof MeshPhongMaterial2 || material instanceof MeshStandardNodeMaterial) {
+        material.normalMap = texture;
+        material.needsUpdate = true;
+      } else if (material instanceof ShaderMaterial2) {
+        if (material.uniforms.tNormal) {
+          material.uniforms.tNormal.value = texture;
+          material.needsUpdate = true;
+        }
+        if (material.uniforms.normalMap) {
+          material.uniforms.normalMap.value = texture;
+          material.needsUpdate = true;
+        }
+      }
+    });
+  }
+  setColor(color, useTSL = false) {
+    if (useTSL) {
+      const material = new MeshStandardNodeMaterial();
+      material.color = color;
+      this.materials.push(material);
+    } else {
+      const material = new MeshStandardMaterial2({
+        color,
+        emissiveIntensity: 0.5,
+        lightMapIntensity: 0.5,
+        fog: true
+      });
+      this.materials.push(material);
+    }
+  }
+  /**
+   * Set GLSL shader (WebGL only)
+   */
+  setShader(customShader) {
+    const { fragment: fragment2, vertex } = customShader ?? standardShader;
+    const shader = new ShaderMaterial2({
+      uniforms: {
+        iResolution: { value: new Vector37(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) },
+        normalStrength: { value: 1 }
+      },
+      vertexShader: vertex,
+      fragmentShader: fragment2,
+      transparent: true
+    });
+    this.materials.push(shader);
+  }
+  /**
+   * Set TSL shader (WebGPU compatible)
+   */
+  setTSLShader(tslShader) {
+    const material = new MeshBasicNodeMaterial();
+    material.colorNode = tslShader.colorNode;
+    if (tslShader.transparent) {
+      material.transparent = true;
+    }
+    this.materials.push(material);
+  }
+};
+
+// src/lib/entities/parts/mesh-factories.ts
+function buildMaterial(opts, entityType = /* @__PURE__ */ Symbol("mesh")) {
+  if (opts.material || opts.color) {
+    const builder = new MaterialBuilder();
+    builder.build(
+      { ...opts.material, color: opts.color ?? opts.material?.color },
+      entityType
+    );
+    if (builder.materials.length > 0) {
+      return builder.materials;
+    }
+  }
+  return [new MeshStandardMaterial3()];
+}
+function finalizeMesh(mesh, opts) {
+  if (opts.position) {
+    mesh.position.set(opts.position.x, opts.position.y, opts.position.z);
+  }
+  mesh.castShadow = true;
+  mesh.receiveShadow = true;
+  return mesh;
+}
+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);
+}
+function sphereMesh(opts = {}) {
+  const geometry = new SphereGeometry(opts.radius ?? 1);
+  const materials = buildMaterial(opts);
+  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+}
+function coneMesh(opts = {}) {
+  const geometry = new ConeGeometry(
+    opts.radius ?? 1,
+    opts.height ?? 2,
+    opts.radialSegments ?? 32
+  );
+  const materials = buildMaterial(opts);
+  return finalizeMesh(new Mesh2(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);
+}
+function cylinderMesh(opts = {}) {
+  const geometry = new CylinderGeometry(
+    opts.radiusTop ?? 1,
+    opts.radiusBottom ?? 1,
+    opts.height ?? 2,
+    opts.radialSegments ?? 32
+  );
+  const materials = buildMaterial(opts);
+  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+}
+function pillMesh(opts = {}) {
+  const geometry = new CapsuleGeometry(
+    opts.radius ?? 0.5,
+    opts.length ?? 1,
+    opts.capSegments ?? 10,
+    opts.radialSegments ?? 20
+  );
+  const materials = buildMaterial(opts);
+  return finalizeMesh(new Mesh2(geometry, materials.at(-1)), opts);
+}
+
+// src/lib/entities/box.ts
+var boxDefaults = {
+  ...commonDefaults,
+  size: new Vector38(1, 1, 1)
+};
 var BOX_TYPE = /* @__PURE__ */ Symbol("Box");
 var ZylemBox = class _ZylemBox extends GameEntity {
   static type = BOX_TYPE;
@@ -883,107 +2187,282 @@ var ZylemBox = class _ZylemBox extends GameEntity {
     };
   }
 };
-async function box(...args) {
-  return createEntity({
-    args,
-    defaultConfig: boxDefaults,
-    EntityClass: ZylemBox,
-    BuilderClass: BoxBuilder,
-    MeshBuilderClass: BoxMeshBuilder,
-    CollisionBuilderClass: BoxCollisionBuilder,
-    entityType: ZylemBox.type
-  });
+function createBox(...args) {
+  const options = mergeArgs(args, boxDefaults);
+  const entity = new ZylemBox(options);
+  entity.add(
+    boxMesh({ size: options.size, material: options.material, color: options.color }),
+    boxCollision({
+      size: options.size,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
 }
 
 // src/lib/entities/sphere.ts
-import { ColliderDesc as ColliderDesc3 } from "@dimforge/rapier3d-compat";
-import { Color as Color5, SphereGeometry } from "three";
-import { Vector3 as Vector34 } from "three";
 var sphereDefaults = {
-  radius: 1,
-  position: new Vector34(0, 0, 0),
-  collision: {
-    static: false
-  },
-  material: {
-    color: new Color5("#ffffff"),
-    shader: "standard"
+  ...commonDefaults,
+  radius: 1
+};
+var SPHERE_TYPE = /* @__PURE__ */ Symbol("Sphere");
+var ZylemSphere = class _ZylemSphere extends GameEntity {
+  static type = SPHERE_TYPE;
+  constructor(options) {
+    super();
+    this.options = { ...sphereDefaults, ...options };
+  }
+  buildInfo() {
+    const delegate = new DebugDelegate(this);
+    const baseInfo = delegate.buildDebugInfo();
+    const radius = this.options.radius ?? 1;
+    return {
+      ...baseInfo,
+      type: String(_ZylemSphere.type),
+      radius: radius.toFixed(2)
+    };
   }
 };
-var SphereCollisionBuilder = class extends EntityCollisionBuilder {
-  collider(options) {
-    const radius = options.radius ?? 1;
-    let colliderDesc = ColliderDesc3.ball(radius);
-    return colliderDesc;
+function createSphere(...args) {
+  const options = mergeArgs(args, sphereDefaults);
+  const entity = new ZylemSphere(options);
+  entity.add(
+    sphereMesh({ radius: options.radius, material: options.material, color: options.color }),
+    sphereCollision({
+      radius: options.radius,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
+}
+
+// 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 {
+  TextureLoader as TextureLoader2,
+  SpriteMaterial,
+  Sprite as ThreeSprite
+} from "three";
+
+// src/lib/entities/builder.ts
+import { BufferGeometry as BufferGeometry2, Mesh as Mesh4, Color as Color4 } from "three";
+
+// src/lib/graphics/mesh.ts
+import { Mesh as Mesh3 } 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));
+    mesh.position.set(0, 0, 0);
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    return mesh;
+  }
+  _postBuild() {
+    return;
   }
 };
-var SphereMeshBuilder = class extends EntityMeshBuilder {
+
+// src/lib/entities/builder.ts
+var EntityCollisionBuilder = class extends CollisionBuilder {
+};
+var EntityMeshBuilder = class extends MeshBuilder {
   build(options) {
-    const radius = options.radius ?? 1;
-    return new SphereGeometry(radius);
+    return new BufferGeometry2();
+  }
+  postBuild() {
+    return;
+  }
+};
+var EntityBuilder = class {
+  meshBuilder;
+  collisionBuilder;
+  materialBuilder;
+  options;
+  entity;
+  constructor(options, entity, meshBuilder, collisionBuilder) {
+    this.options = options;
+    this.entity = entity;
+    this.meshBuilder = meshBuilder;
+    this.collisionBuilder = collisionBuilder;
+    this.materialBuilder = new MaterialBuilder();
+    const builders = {
+      meshBuilder: this.meshBuilder,
+      collisionBuilder: this.collisionBuilder,
+      materialBuilder: this.materialBuilder
+    };
+    this.options._builders = builders;
+  }
+  withPosition(setupPosition) {
+    this.options.position = setupPosition;
+    return this;
+  }
+  withMaterial(options, entityType) {
+    if (this.materialBuilder) {
+      this.materialBuilder.build(options, entityType);
+    }
+    return this;
+  }
+  applyMaterialToGroup(group, materials) {
+    group.traverse((child) => {
+      if (child instanceof Mesh4) {
+        if (child.type === "SkinnedMesh" && materials[0] && !child.material.map) {
+          child.material = materials[0];
+        }
+      }
+      child.castShadow = true;
+      child.receiveShadow = true;
+    });
+  }
+  build() {
+    const entity = this.entity;
+    if (this.materialBuilder) {
+      entity.materials = this.materialBuilder.materials;
+    }
+    if (this.meshBuilder && entity.materials) {
+      const geometry = this.meshBuilder.build(this.options);
+      entity.mesh = this.meshBuilder._build(this.options, geometry, entity.materials);
+      this.meshBuilder.postBuild();
+    }
+    if (entity.group && entity.materials) {
+      this.applyMaterialToGroup(entity.group, entity.materials);
+    }
+    if (this.collisionBuilder) {
+      this.collisionBuilder.withCollision(this.options?.collision || {});
+      const [bodyDesc, colliderDesc] = this.collisionBuilder.build(this.options);
+      entity.bodyDesc = bodyDesc;
+      entity.colliderDesc = colliderDesc;
+      entity.colliderDescs.push(colliderDesc);
+      const { x, y, z } = this.options.position || { x: 0, y: 0, z: 0 };
+      entity.bodyDesc.setTranslation(x, y, z);
+    }
+    if (this.options.collisionType) {
+      entity.collisionType = this.options.collisionType;
+    }
+    if (this.options.color instanceof Color4) {
+      const applyColor = (material) => {
+        const anyMat = material;
+        if (anyMat && anyMat.color && anyMat.color.set) {
+          anyMat.color.set(this.options.color);
+        }
+      };
+      if (entity.materials?.length) {
+        for (const mat of entity.materials) applyColor(mat);
+      }
+      if (entity.mesh && entity.mesh.material) {
+        const mat = entity.mesh.material;
+        if (Array.isArray(mat)) mat.forEach(applyColor);
+        else applyColor(mat);
+      }
+      if (entity.group) {
+        entity.group.traverse((child) => {
+          if (child instanceof Mesh4 && child.material) {
+            const mat = child.material;
+            if (Array.isArray(mat)) mat.forEach(applyColor);
+            else applyColor(mat);
+          }
+        });
+      }
+    }
+    return entity;
+  }
+};
+
+// src/lib/entities/delegates/loader.ts
+function isLoadable(obj) {
+  return typeof obj?.load === "function" && typeof obj?.data === "function";
+}
+var EntityLoader = class {
+  entityReference;
+  constructor(entity) {
+    this.entityReference = entity;
+  }
+  load() {
+    if (this.entityReference.load) {
+      this.entityReference.load();
+    }
+  }
+  data() {
+    if (this.entityReference.data) {
+      return this.entityReference.data();
+    }
+    return null;
   }
 };
-var SphereBuilder = class extends EntityBuilder {
-  createEntity(options) {
-    return new ZylemSphere(options);
+
+// src/lib/entities/create.ts
+function createEntity(params) {
+  const {
+    args,
+    defaultConfig,
+    EntityClass,
+    BuilderClass,
+    entityType,
+    MeshBuilderClass,
+    CollisionBuilderClass
+  } = params;
+  let builder = null;
+  let configuration;
+  const configurationIndex = args.findIndex((node) => !(node instanceof BaseNode));
+  if (configurationIndex !== -1) {
+    const subArgs = args.splice(configurationIndex, 1);
+    configuration = subArgs.find((node) => !(node instanceof BaseNode));
   }
-};
-var SPHERE_TYPE = /* @__PURE__ */ Symbol("Sphere");
-var ZylemSphere = class _ZylemSphere extends GameEntity {
-  static type = SPHERE_TYPE;
-  constructor(options) {
-    super();
-    this.options = { ...sphereDefaults, ...options };
+  const mergedConfiguration = configuration ? { ...defaultConfig, ...configuration } : defaultConfig;
+  args.push(mergedConfiguration);
+  for (const arg of args) {
+    if (arg instanceof BaseNode) {
+      continue;
+    }
+    let entityData = null;
+    const entity = new EntityClass(arg);
+    try {
+      if (isLoadable(entity)) {
+        const loader = new EntityLoader(entity);
+        loader.load();
+        entityData = loader.data();
+      }
+    } catch (error) {
+      console.error("Error creating entity with loader:", error);
+    }
+    builder = new BuilderClass(
+      arg,
+      entity,
+      MeshBuilderClass ? new MeshBuilderClass(entityData) : null,
+      CollisionBuilderClass ? new CollisionBuilderClass(entityData) : null
+    );
+    if (arg.material) {
+      builder.withMaterial(arg.material, entityType);
+    }
   }
-  buildInfo() {
-    const delegate = new DebugDelegate(this);
-    const baseInfo = delegate.buildDebugInfo();
-    const radius = this.options.radius ?? 1;
-    return {
-      ...baseInfo,
-      type: String(_ZylemSphere.type),
-      radius: radius.toFixed(2)
-    };
+  if (!builder) {
+    throw new Error(`missing options for ${String(entityType)}, builder is not initialized.`);
   }
-};
-async function sphere(...args) {
-  return createEntity({
-    args,
-    defaultConfig: sphereDefaults,
-    EntityClass: ZylemSphere,
-    BuilderClass: SphereBuilder,
-    MeshBuilderClass: SphereMeshBuilder,
-    CollisionBuilderClass: SphereCollisionBuilder,
-    entityType: ZylemSphere.type
-  });
+  return builder.build();
 }
 
 // src/lib/entities/sprite.ts
-import { ColliderDesc as ColliderDesc4 } from "@dimforge/rapier3d-compat";
-import { Color as Color6, Euler, Group as Group3, Quaternion as Quaternion2, Vector3 as Vector35 } from "three";
-import {
-  TextureLoader as TextureLoader2,
-  SpriteMaterial,
-  Sprite as ThreeSprite
-} from "three";
 var spriteDefaults = {
-  size: new Vector35(1, 1, 1),
-  position: new Vector35(0, 0, 0),
-  collision: {
-    static: false
-  },
-  material: {
-    color: new Color6("#ffffff"),
-    shader: "standard"
-  },
+  ...commonDefaults,
+  size: new Vector39(1, 1, 1),
   images: [],
   animations: []
 };
 var SpriteCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const size = options.collisionSize || options.size || new Vector35(1, 1, 1);
+    const size = options.collisionSize || options.size || new Vector39(1, 1, 1);
     const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
-    let colliderDesc = ColliderDesc4.cuboid(half.x, half.y, half.z);
+    let colliderDesc = ColliderDesc3.cuboid(half.x, half.y, half.z);
     return colliderDesc;
   }
 };
@@ -1007,7 +2486,7 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
     super();
     this.options = { ...spriteDefaults, ...options };
     this.prependUpdate(this.spriteUpdate.bind(this));
-    this.onDestroy(this.spriteDestroy.bind(this));
+    this.onCleanup(this.spriteDestroy.bind(this));
   }
   create() {
     this.sprites = [];
@@ -1085,20 +2564,20 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
       }
     }
   }
-  async spriteUpdate(params) {
+  spriteUpdate(params) {
     this.sprites.forEach((_sprite) => {
       if (_sprite.material) {
         const q = this.body?.rotation();
         if (q) {
-          const quat = new Quaternion2(q.x, q.y, q.z, q.w);
-          const euler = new Euler().setFromQuaternion(quat, "XYZ");
+          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);
       }
     });
   }
-  async spriteDestroy(params) {
+  spriteDestroy(params) {
     this.sprites.forEach((_sprite) => {
       _sprite.removeFromParent();
     });
@@ -1114,7 +2593,7 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
     };
   }
 };
-async function sprite(...args) {
+function createSprite(...args) {
   return createEntity({
     args,
     defaultConfig: spriteDefaults,
@@ -1126,8 +2605,8 @@ async function sprite(...args) {
 }
 
 // src/lib/entities/plane.ts
-import { ColliderDesc as ColliderDesc5 } from "@dimforge/rapier3d-compat";
-import { Color as Color7, PlaneGeometry, Vector2 as Vector22, Vector3 as Vector36 } from "three";
+import { ColliderDesc as ColliderDesc4 } from "@dimforge/rapier3d-compat";
+import { PlaneGeometry, Vector2 as Vector23, Vector3 as Vector310 } from "three";
 
 // src/lib/graphics/geometries/XZPlaneGeometry.ts
 import { BufferGeometry as BufferGeometry3, Float32BufferAttribute } from "three";
@@ -1191,26 +2670,24 @@ var XZPlaneGeometry = class _XZPlaneGeometry extends BufferGeometry3 {
 // src/lib/entities/plane.ts
 var DEFAULT_SUBDIVISIONS = 4;
 var planeDefaults = {
-  tile: new Vector22(10, 10),
-  repeat: new Vector22(1, 1),
-  position: new Vector36(0, 0, 0),
+  ...commonDefaults,
+  tile: new Vector23(10, 10),
+  repeat: new Vector23(1, 1),
   collision: {
     static: true
   },
-  material: {
-    color: new Color7("#ffffff"),
-    shader: "standard"
-  },
-  subdivisions: DEFAULT_SUBDIVISIONS
+  subdivisions: DEFAULT_SUBDIVISIONS,
+  randomizeHeight: false,
+  heightScale: 1
 };
 var PlaneCollisionBuilder = class extends EntityCollisionBuilder {
   collider(options) {
-    const tile = options.tile ?? new Vector22(1, 1);
+    const tile = options.tile ?? new Vector23(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
-    const size = new Vector36(tile.x, 1, tile.y);
+    const size = new Vector310(tile.x, 1, tile.y);
     const heightData = options._builders?.meshBuilder?.heightData;
-    const scale2 = new Vector36(size.x, 1, size.z);
-    let colliderDesc = ColliderDesc5.heightfield(
+    const scale2 = new Vector310(size.x, 1, size.z);
+    let colliderDesc = ColliderDesc4.heightfield(
       subdivisions,
       subdivisions,
       heightData,
@@ -1222,10 +2699,13 @@ var PlaneCollisionBuilder = class extends EntityCollisionBuilder {
 var PlaneMeshBuilder = class extends EntityMeshBuilder {
   heightData = new Float32Array();
   columnsRows = /* @__PURE__ */ new Map();
+  subdivisions = DEFAULT_SUBDIVISIONS;
   build(options) {
-    const tile = options.tile ?? new Vector22(1, 1);
+    const tile = options.tile ?? new Vector23(1, 1);
     const subdivisions = options.subdivisions ?? DEFAULT_SUBDIVISIONS;
-    const size = new Vector36(tile.x, 1, tile.y);
+    this.subdivisions = subdivisions;
+    const size = new Vector310(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);
     const dx = size.x / subdivisions;
@@ -1233,30 +2713,40 @@ var PlaneMeshBuilder = class extends EntityMeshBuilder {
     const originalVertices = geometry.attributes.position.array;
     const vertices = vertexGeometry.attributes.position.array;
     const columsRows = /* @__PURE__ */ new Map();
+    const heightMapData = options.heightMap;
+    const useRandomHeight = options.randomizeHeight ?? false;
     for (let i = 0; i < vertices.length; i += 3) {
+      const vertexIndex = i / 3;
       let row = Math.floor(Math.abs(vertices[i] + size.x / 2) / dx);
       let column = Math.floor(Math.abs(vertices[i + 1] - size.z / 2) / dy);
-      const randomHeight = Math.random() * 4;
-      vertices[i + 2] = randomHeight;
-      originalVertices[i + 1] = randomHeight;
+      let height = 0;
+      if (heightMapData && heightMapData.length > 0) {
+        const heightIndex = vertexIndex % heightMapData.length;
+        height = heightMapData[heightIndex] * heightScale;
+      } else if (useRandomHeight) {
+        height = Math.random() * 4 * heightScale;
+      }
+      vertices[i + 2] = height;
+      originalVertices[i + 1] = height;
       if (!columsRows.get(column)) {
         columsRows.set(column, /* @__PURE__ */ new Map());
       }
-      columsRows.get(column).set(row, randomHeight);
+      columsRows.get(column).set(row, height);
     }
     this.columnsRows = columsRows;
     return geometry;
   }
   postBuild() {
     const heights = [];
-    for (let i = 0; i <= DEFAULT_SUBDIVISIONS; ++i) {
-      for (let j = 0; j <= DEFAULT_SUBDIVISIONS; ++j) {
+    for (let i = 0; i <= this.subdivisions; ++i) {
+      for (let j = 0; j <= this.subdivisions; ++j) {
         const row = this.columnsRows.get(j);
         if (!row) {
+          heights.push(0);
           continue;
         }
         const data = row.get(i);
-        heights.push(data);
+        heights.push(data ?? 0);
       }
     }
     this.heightData = new Float32Array(heights);
@@ -1275,7 +2765,7 @@ var ZylemPlane = class extends GameEntity {
     this.options = { ...planeDefaults, ...options };
   }
 };
-async function plane(...args) {
+function createPlane(...args) {
   return createEntity({
     args,
     defaultConfig: planeDefaults,
@@ -1288,12 +2778,11 @@ async function plane(...args) {
 }
 
 // src/lib/entities/zone.ts
-import { ActiveCollisionTypes as ActiveCollisionTypes2, ColliderDesc as ColliderDesc6 } from "@dimforge/rapier3d-compat";
-import { Vector3 as Vector37 } from "three";
+import { Vector3 as Vector311 } from "three";
 
 // src/lib/game/game-state.ts
-import { proxy, subscribe } from "valtio/vanilla";
-var state = proxy({
+import { proxy as proxy2, subscribe } from "valtio/vanilla";
+var state = proxy2({
   id: "",
   globals: {},
   time: 0
@@ -1301,28 +2790,10 @@ var state = proxy({
 
 // src/lib/entities/zone.ts
 var zoneDefaults = {
-  size: new Vector37(1, 1, 1),
-  position: new Vector37(0, 0, 0),
+  ...commonDefaults,
+  size: new Vector311(1, 1, 1),
   collision: {
     static: true
-  },
-  material: {
-    shader: "standard"
-  }
-};
-var ZoneCollisionBuilder = class extends EntityCollisionBuilder {
-  collider(options) {
-    const size = options.size || new Vector37(1, 1, 1);
-    const half = { x: size.x / 2, y: size.y / 2, z: size.z / 2 };
-    let colliderDesc = ColliderDesc6.cuboid(half.x, half.y, half.z);
-    colliderDesc.setSensor(true);
-    colliderDesc.activeCollisionTypes = ActiveCollisionTypes2.KINEMATIC_FIXED;
-    return colliderDesc;
-  }
-};
-var ZoneBuilder = class extends EntityBuilder {
-  createEntity(options) {
-    return new ZylemZone(options);
   }
 };
 var ZONE_TYPE = /* @__PURE__ */ Symbol("Zone");
@@ -1404,78 +2875,56 @@ var ZylemZone = class extends GameEntity {
     }
   }
 };
-async function zone(...args) {
-  return createEntity({
-    args,
-    defaultConfig: zoneDefaults,
-    EntityClass: ZylemZone,
-    BuilderClass: ZoneBuilder,
-    CollisionBuilderClass: ZoneCollisionBuilder,
-    entityType: ZylemZone.type
-  });
+function createZone(...args) {
+  const options = mergeArgs(args, zoneDefaults);
+  const entity = new ZylemZone(options);
+  entity.add(
+    zoneCollision({
+      size: options.size,
+      static: options.collision?.static ?? true,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
 }
 
 // src/lib/entities/actor.ts
-import { ActiveCollisionTypes as ActiveCollisionTypes3, ColliderDesc as ColliderDesc7 } from "@dimforge/rapier3d-compat";
-import { SkinnedMesh, Group as Group4, Vector3 as Vector38 } from "three";
+import { ActiveCollisionTypes as ActiveCollisionTypes3, ColliderDesc as ColliderDesc5 } from "@dimforge/rapier3d-compat";
+import { MeshStandardMaterial as MeshStandardMaterial4, Group as Group4, Vector3 as Vector312 } from "three";
 
 // src/lib/core/entity-asset-loader.ts
-import { FBXLoader } from "three/addons/loaders/FBXLoader.js";
-import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
-var FBXAssetLoader = class {
-  loader = new FBXLoader();
-  isSupported(file) {
-    return file.toLowerCase().endsWith("fbx" /* FBX */);
-  }
-  async load(file) {
-    return new Promise((resolve, reject) => {
-      this.loader.load(
-        file,
-        (object) => {
-          const animation = object.animations[0];
-          resolve({
-            object,
-            animation
-          });
-        },
-        void 0,
-        reject
-      );
-    });
-  }
-};
-var GLTFAssetLoader = class {
-  loader = new GLTFLoader();
-  isSupported(file) {
-    return file.toLowerCase().endsWith("gltf" /* GLTF */);
-  }
-  async load(file) {
-    return new Promise((resolve, reject) => {
-      this.loader.load(
-        file,
-        (gltf) => {
-          resolve({
-            object: gltf.scene,
-            gltf
-          });
-        },
-        void 0,
-        reject
-      );
-    });
-  }
-};
 var EntityAssetLoader = class {
-  loaders = [
-    new FBXAssetLoader(),
-    new GLTFAssetLoader()
-  ];
+  /**
+   * Load a model file (FBX, GLTF, GLB, OBJ) using the asset manager
+   */
   async loadFile(file) {
-    const loader = this.loaders.find((l) => l.isSupported(file));
-    if (!loader) {
-      throw new Error(`Unsupported file type: ${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}`);
     }
-    return loader.load(file);
   }
 };
 
@@ -1502,14 +2951,22 @@ var AnimationDelegate = class {
   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;
@@ -1533,14 +2990,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;
@@ -1548,10 +3004,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;
   }
@@ -1582,46 +3038,86 @@ var AnimationDelegate = class {
 
 // src/lib/entities/actor.ts
 var actorDefaults = {
-  position: { x: 0, y: 0, z: 0 },
+  ...commonDefaults,
   collision: {
     static: false,
-    size: new Vector38(0.5, 0.5, 0.5),
-    position: new Vector38(0, 0, 0)
+    size: new Vector312(0.5, 0.5, 0.5),
+    position: new Vector312(0, 0, 0)
   },
   material: {
-    shader: "standard"
+    shader: standardShader
   },
   animations: [],
-  models: []
+  models: [],
+  collisionShape: "capsule"
 };
 var ActorCollisionBuilder = class extends EntityCollisionBuilder {
-  height = 1;
   objectModel = null;
+  collisionShape = "capsule";
   constructor(data) {
     super();
     this.objectModel = data.objectModel;
+    this.collisionShape = data.collisionShape ?? "capsule";
   }
-  createColliderFromObjectModel(objectModel) {
-    if (!objectModel) return ColliderDesc7.capsule(1, 1);
-    const skinnedMesh = objectModel.children.find((child) => child instanceof SkinnedMesh);
-    const geometry = skinnedMesh.geometry;
-    if (geometry) {
-      geometry.computeBoundingBox();
-      if (geometry.boundingBox) {
-        const maxY = geometry.boundingBox.max.y;
-        const minY = geometry.boundingBox.min.y;
-        this.height = maxY - minY;
-      }
+  collider(options) {
+    if (this.collisionShape === "model") {
+      return this.createColliderFromModel(this.objectModel, options);
     }
-    this.height = 1;
-    let colliderDesc = ColliderDesc7.capsule(this.height / 2, 1);
+    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, this.height + 0.5, 0);
+    colliderDesc.setTranslation(0, halfHeight + radius, 0);
     colliderDesc.activeCollisionTypes = ActiveCollisionTypes3.DEFAULT;
     return colliderDesc;
   }
-  collider(options) {
-    let colliderDesc = this.createColliderFromObjectModel(this.objectModel);
+  /**
+   * 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;
   }
 };
@@ -1644,21 +3140,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);
   }
   /**
@@ -1689,26 +3190,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 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
-      );
-    }
+    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 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.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 MeshStandardMaterial4({
+            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;
   }
@@ -1745,8 +3299,8 @@ var ZylemActor = class extends GameEntity {
     return debugInfo;
   }
 };
-async function actor(...args) {
-  return await createEntity({
+function createActor(...args) {
+  return createEntity({
     args,
     defaultConfig: actorDefaults,
     EntityClass: ZylemActor,
@@ -1757,7 +3311,7 @@ async function actor(...args) {
 }
 
 // src/lib/entities/text.ts
-import { Color as Color8, Group as Group5, Sprite as ThreeSprite2, SpriteMaterial as SpriteMaterial2, CanvasTexture, LinearFilter, Vector2 as Vector23, ClampToEdgeWrapping } from "three";
+import { Color as Color6, Group as Group5, Sprite as ThreeSprite2, SpriteMaterial as SpriteMaterial2, CanvasTexture, LinearFilter, Vector2 as Vector24, ClampToEdgeWrapping } from "three";
 var textDefaults = {
   position: void 0,
   text: "",
@@ -1767,7 +3321,7 @@ var textDefaults = {
   backgroundColor: null,
   padding: 4,
   stickToViewport: true,
-  screenPosition: new Vector23(24, 24),
+  screenPosition: new Vector24(24, 24),
   zDistance: 1
 };
 var TextBuilder = class extends EntityBuilder {
@@ -1790,7 +3344,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     this.options = { ...textDefaults, ...options };
     this.prependSetup(this.textSetup.bind(this));
     this.prependUpdate(this.textUpdate.bind(this));
-    this.onDestroy(this.textDestroy.bind(this));
+    this.onCleanup(this.textDestroy.bind(this));
   }
   create() {
     this._sprite = null;
@@ -1820,10 +3374,10 @@ var ZylemText = class _ZylemText extends GameEntity {
     this.group?.add(this._sprite);
     this.redrawText(this.options.text ?? "");
   }
-  measureAndResizeCanvas(text2, fontSize, fontFamily, padding) {
+  measureAndResizeCanvas(text, fontSize, fontFamily, padding) {
     if (!this._canvas || !this._ctx) return { sizeChanged: false };
     this._ctx.font = `${fontSize}px ${fontFamily}`;
-    const metrics = this._ctx.measureText(text2);
+    const metrics = this._ctx.measureText(text);
     const textWidth = Math.ceil(metrics.width);
     const textHeight = Math.ceil(fontSize * 1.4);
     const nextW = Math.max(2, textWidth + padding * 2);
@@ -1835,7 +3389,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     this._lastCanvasH = nextH;
     return { sizeChanged };
   }
-  drawCenteredText(text2, fontSize, fontFamily) {
+  drawCenteredText(text, fontSize, fontFamily) {
     if (!this._canvas || !this._ctx) return;
     this._ctx.font = `${fontSize}px ${fontFamily}`;
     this._ctx.textAlign = "center";
@@ -1846,7 +3400,7 @@ var ZylemText = class _ZylemText extends GameEntity {
       this._ctx.fillRect(0, 0, this._canvas.width, this._canvas.height);
     }
     this._ctx.fillStyle = this.toCssColor(this.options.fontColor ?? "#FFFFFF");
-    this._ctx.fillText(text2, this._canvas.width / 2, this._canvas.height / 2);
+    this._ctx.fillText(text, this._canvas.width / 2, this._canvas.height / 2);
   }
   updateTexture(sizeChanged) {
     if (!this._texture || !this._canvas) return;
@@ -1879,7 +3433,7 @@ var ZylemText = class _ZylemText extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color8 ? color : new Color8(color);
+    const c = color instanceof Color6 ? color : new Color6(color);
     return `#${c.getHexString()}`;
   }
   textSetup(params) {
@@ -1939,7 +3493,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 Vector23(24, 24);
+    const sp = this.options.screenPosition ?? new Vector24(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);
@@ -1970,7 +3524,7 @@ var ZylemText = class _ZylemText extends GameEntity {
   /**
    * Dispose of Three.js resources when the entity is destroyed.
    */
-  async textDestroy() {
+  textDestroy() {
     this._texture?.dispose();
     if (this._sprite?.material) {
       this._sprite.material.dispose();
@@ -1986,7 +3540,7 @@ var ZylemText = class _ZylemText extends GameEntity {
     this._cameraRef = null;
   }
 };
-async function text(...args) {
+function createText(...args) {
   return createEntity({
     args,
     defaultConfig: { ...textDefaults },
@@ -1997,7 +3551,7 @@ async function text(...args) {
 }
 
 // src/lib/entities/rect.ts
-import { Color as Color9, Group as Group6, Sprite as ThreeSprite3, SpriteMaterial as SpriteMaterial3, CanvasTexture as CanvasTexture2, LinearFilter as LinearFilter2, Vector2 as Vector24, ClampToEdgeWrapping as ClampToEdgeWrapping2, ShaderMaterial as ShaderMaterial3, Mesh as Mesh4, PlaneGeometry as PlaneGeometry2, Vector3 as Vector39 } from "three";
+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";
 var rectDefaults = {
   position: void 0,
   width: 120,
@@ -2008,9 +3562,9 @@ var rectDefaults = {
   radius: 0,
   padding: 0,
   stickToViewport: true,
-  screenPosition: new Vector24(24, 24),
+  screenPosition: new Vector25(24, 24),
   zDistance: 1,
-  anchor: new Vector24(0, 0)
+  anchor: new Vector25(0, 0)
 };
 var RectBuilder = class extends EntityBuilder {
   createEntity(options) {
@@ -2111,6 +3665,12 @@ var ZylemRect = class _ZylemRect extends GameEntity {
       }
     }
   }
+  getWidth() {
+    return this.options.width ?? 0;
+  }
+  getHeight() {
+    return this.options.height ?? 0;
+  }
   roundedRectPath(ctx, x, y, w, h, r) {
     const radius = Math.min(r, Math.floor(Math.min(w, h) / 2));
     ctx.moveTo(x + radius, y);
@@ -2125,9 +3685,27 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   }
   toCssColor(color) {
     if (typeof color === "string") return color;
-    const c = color instanceof Color9 ? color : new Color9(color);
+    const c = color instanceof Color7 ? color : new Color7(color);
     return `#${c.getHexString()}`;
   }
+  /**
+   * Get the viewport resolution from the renderer DOM element,
+   * falling back to the camera's screenResolution if the renderer
+   * is not available (e.g. when using the new RendererManager path).
+   */
+  getResolution() {
+    try {
+      const dom = this._cameraRef?.renderer?.domElement;
+      if (dom) {
+        return { width: dom.clientWidth || 1, height: dom.clientHeight || 1 };
+      }
+    } catch {
+    }
+    return {
+      width: this._cameraRef?.screenResolution?.x ?? 1,
+      height: this._cameraRef?.screenResolution?.y ?? 1
+    };
+  }
   rectSetup(params) {
     this._cameraRef = params.camera;
     if (this.options.stickToViewport && this._cameraRef) {
@@ -2143,7 +3721,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 Mesh4(new PlaneGeometry2(1, 1), mat);
+        this._mesh = new Mesh6(new PlaneGeometry2(1, 1), mat);
         this.group?.add(this._mesh);
         this._sprite.visible = false;
       }
@@ -2152,17 +3730,16 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   rectUpdate(params) {
     if (!this._sprite) return;
     if (this._cameraRef && this.options.bounds) {
-      const dom = this._cameraRef.renderer.domElement;
       const screen = this.computeScreenBoundsFromOptions(this.options.bounds);
       if (screen) {
         const { x, y, width, height } = screen;
         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 Vector24(Math.floor(x), Math.floor(y));
+        this.options.screenPosition = new Vector25(Math.floor(x), Math.floor(y));
         this.options.width = desiredW;
         this.options.height = desiredH;
-        this.options.anchor = new Vector24(0, 0);
+        this.options.anchor = new Vector25(0, 0);
         if (changed) {
           this.redrawRect();
         }
@@ -2175,11 +3752,9 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   updateStickyTransform() {
     if (!this._sprite || !this._cameraRef) return;
     const camera = this._cameraRef.camera;
-    const dom = this._cameraRef.renderer.domElement;
-    const width = dom.clientWidth;
-    const height = dom.clientHeight;
-    const px = (this.options.screenPosition ?? new Vector24(24, 24)).x;
-    const py = (this.options.screenPosition ?? new Vector24(24, 24)).y;
+    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 zDist = Math.max(1e-3, this.options.zDistance ?? 1);
     let worldHalfW = 1;
     let worldHalfH = 1;
@@ -2210,7 +3785,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 Vector24(0, 0);
+    const anchor = this.options.anchor ?? new Vector25(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;
@@ -2220,22 +3795,21 @@ var ZylemRect = class _ZylemRect extends GameEntity {
   worldToScreen(point) {
     if (!this._cameraRef) return { x: 0, y: 0 };
     const camera = this._cameraRef.camera;
-    const dom = this._cameraRef.renderer.domElement;
+    const { width, height } = this.getResolution();
     const v = point.clone().project(camera);
-    const x = (v.x + 1) / 2 * dom.clientWidth;
-    const y = (1 - v.y) / 2 * dom.clientHeight;
+    const x = (v.x + 1) / 2 * width;
+    const y = (1 - v.y) / 2 * height;
     return { x, y };
   }
   computeScreenBoundsFromOptions(bounds) {
     if (!this._cameraRef) return null;
-    const dom = this._cameraRef.renderer.domElement;
     if (bounds.screen) {
       return { ...bounds.screen };
     }
     if (bounds.world) {
       const { left, right, top, bottom, z = 0 } = bounds.world;
-      const tl = this.worldToScreen(new Vector39(left, top, z));
-      const br = this.worldToScreen(new Vector39(right, bottom, z));
+      const tl = this.worldToScreen(new Vector313(left, top, z));
+      const br = this.worldToScreen(new Vector313(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);
@@ -2263,7 +3837,7 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     };
   }
 };
-async function rect(...args) {
+function createRect(...args) {
   return createEntity({
     args,
     defaultConfig: { ...rectDefaults },
@@ -2272,15 +3846,224 @@ async function rect(...args) {
     entityType: ZylemRect.type
   });
 }
+
+// src/lib/entities/cone.ts
+var coneDefaults = {
+  ...commonDefaults,
+  radius: 1,
+  height: 2,
+  radialSegments: 32
+};
+var CONE_TYPE = /* @__PURE__ */ Symbol("Cone");
+var ZylemCone = class _ZylemCone extends GameEntity {
+  static type = CONE_TYPE;
+  constructor(options) {
+    super();
+    this.options = { ...coneDefaults, ...options };
+  }
+  buildInfo() {
+    const delegate = new DebugDelegate(this);
+    const baseInfo = delegate.buildDebugInfo();
+    const radius = this.options.radius ?? 1;
+    const height = this.options.height ?? 2;
+    return {
+      ...baseInfo,
+      type: String(_ZylemCone.type),
+      radius: radius.toFixed(2),
+      height: height.toFixed(2)
+    };
+  }
+};
+function createCone(...args) {
+  const options = mergeArgs(args, coneDefaults);
+  const entity = new ZylemCone(options);
+  entity.add(
+    coneMesh({
+      radius: options.radius,
+      height: options.height,
+      radialSegments: options.radialSegments,
+      material: options.material,
+      color: options.color
+    }),
+    coneCollision({
+      radius: options.radius,
+      height: options.height,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
+}
+
+// src/lib/entities/pyramid.ts
+var pyramidDefaults = {
+  ...commonDefaults,
+  radius: 1,
+  height: 2
+};
+var PYRAMID_TYPE = /* @__PURE__ */ Symbol("Pyramid");
+var ZylemPyramid = class _ZylemPyramid extends GameEntity {
+  static type = PYRAMID_TYPE;
+  constructor(options) {
+    super();
+    this.options = { ...pyramidDefaults, ...options };
+  }
+  buildInfo() {
+    const delegate = new DebugDelegate(this);
+    const baseInfo = delegate.buildDebugInfo();
+    const radius = this.options.radius ?? 1;
+    const height = this.options.height ?? 2;
+    return {
+      ...baseInfo,
+      type: String(_ZylemPyramid.type),
+      radius: radius.toFixed(2),
+      height: height.toFixed(2)
+    };
+  }
+};
+function createPyramid(...args) {
+  const options = mergeArgs(args, pyramidDefaults);
+  const entity = new ZylemPyramid(options);
+  entity.add(
+    pyramidMesh({
+      radius: options.radius,
+      height: options.height,
+      material: options.material,
+      color: options.color
+    }),
+    pyramidCollision({
+      radius: options.radius,
+      height: options.height,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
+}
+
+// src/lib/entities/cylinder.ts
+var cylinderDefaults = {
+  ...commonDefaults,
+  radiusTop: 1,
+  radiusBottom: 1,
+  height: 2,
+  radialSegments: 32
+};
+var CYLINDER_TYPE = /* @__PURE__ */ Symbol("Cylinder");
+var ZylemCylinder = class _ZylemCylinder extends GameEntity {
+  static type = CYLINDER_TYPE;
+  constructor(options) {
+    super();
+    this.options = { ...cylinderDefaults, ...options };
+  }
+  buildInfo() {
+    const delegate = new DebugDelegate(this);
+    const baseInfo = delegate.buildDebugInfo();
+    const radiusTop = this.options.radiusTop ?? 1;
+    const radiusBottom = this.options.radiusBottom ?? 1;
+    const height = this.options.height ?? 2;
+    return {
+      ...baseInfo,
+      type: String(_ZylemCylinder.type),
+      radiusTop: radiusTop.toFixed(2),
+      radiusBottom: radiusBottom.toFixed(2),
+      height: height.toFixed(2)
+    };
+  }
+};
+function createCylinder(...args) {
+  const options = mergeArgs(args, cylinderDefaults);
+  const entity = new ZylemCylinder(options);
+  entity.add(
+    cylinderMesh({
+      radiusTop: options.radiusTop,
+      radiusBottom: options.radiusBottom,
+      height: options.height,
+      radialSegments: options.radialSegments,
+      material: options.material,
+      color: options.color
+    }),
+    cylinderCollision({
+      radiusTop: options.radiusTop,
+      radiusBottom: options.radiusBottom,
+      height: options.height,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
+}
+
+// src/lib/entities/pill.ts
+var pillDefaults = {
+  ...commonDefaults,
+  radius: 0.5,
+  length: 1,
+  capSegments: 10,
+  radialSegments: 20
+};
+var PILL_TYPE = /* @__PURE__ */ Symbol("Pill");
+var ZylemPill = class _ZylemPill extends GameEntity {
+  static type = PILL_TYPE;
+  constructor(options) {
+    super();
+    this.options = { ...pillDefaults, ...options };
+  }
+  buildInfo() {
+    const delegate = new DebugDelegate(this);
+    const baseInfo = delegate.buildDebugInfo();
+    const radius = this.options.radius ?? 0.5;
+    const length = this.options.length ?? 1;
+    return {
+      ...baseInfo,
+      type: String(_ZylemPill.type),
+      radius: radius.toFixed(2),
+      length: length.toFixed(2)
+    };
+  }
+};
+function createPill(...args) {
+  const options = mergeArgs(args, pillDefaults);
+  const entity = new ZylemPill(options);
+  entity.add(
+    pillMesh({
+      radius: options.radius,
+      length: options.length,
+      capSegments: options.capSegments,
+      radialSegments: options.radialSegments,
+      material: options.material,
+      color: options.color
+    }),
+    pillCollision({
+      radius: options.radius,
+      length: options.length,
+      static: options.collision?.static,
+      sensor: options.collision?.sensor,
+      collisionType: options.collisionType,
+      collisionFilter: options.collisionFilter
+    })
+  );
+  return entity;
+}
 export {
   ZylemBox,
-  actor,
-  box,
-  plane,
-  rect,
-  sphere,
-  sprite,
-  text,
-  zone
+  createActor,
+  createBox,
+  createCone,
+  createCylinder,
+  createPill,
+  createPlane,
+  createPyramid,
+  createRect,
+  createSphere,
+  createSprite,
+  createText,
+  createZone
 };
 //# sourceMappingURL=entities.js.map