@zylem/game-lib 0.5.1 → 0.6.0

package/dist/entities.js

@@ -11,7 +11,8 @@ import {
   defineSystem,
   defineQuery,
   defineComponent,
-  Types
+  Types,
+  removeQuery
 } from "bitecs";
 import { Quaternion } from "three";
 var position = defineComponent({
@@ -30,6 +31,7 @@ var scale = defineComponent({
   y: Types.f32,
   z: Types.f32
 });
+var _tempQuaternion = new Quaternion();
 
 // src/lib/core/flags.ts
 var DEBUG_FLAG = import.meta.env.VITE_DEBUG_FLAG === "true";
@@ -44,21 +46,76 @@ var BaseNode = class _BaseNode {
   uuid = "";
   name = "";
   markedForRemoval = false;
-  setup = () => {
-  };
-  loaded = () => {
-  };
-  update = () => {
-  };
-  destroy = () => {
-  };
-  cleanup = () => {
+  /**
+   * Lifecycle callback arrays - use onSetup(), onUpdate(), etc. to add callbacks
+   */
+  lifecycleCallbacks = {
+    setup: [],
+    loaded: [],
+    update: [],
+    destroy: [],
+    cleanup: []
   };
   constructor(args = []) {
     const options = args.filter((arg) => !(arg instanceof _BaseNode)).reduce((acc, opt) => ({ ...acc, ...opt }), {});
     this.options = options;
     this.uuid = nanoid();
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Fluent API for adding lifecycle callbacks
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Add setup callbacks to be executed in order during nodeSetup
+   */
+  onSetup(...callbacks) {
+    this.lifecycleCallbacks.setup.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add loaded callbacks to be executed in order during nodeLoaded
+   */
+  onLoaded(...callbacks) {
+    this.lifecycleCallbacks.loaded.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add update callbacks to be executed in order during nodeUpdate
+   */
+  onUpdate(...callbacks) {
+    this.lifecycleCallbacks.update.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add destroy callbacks to be executed in order during nodeDestroy
+   */
+  onDestroy(...callbacks) {
+    this.lifecycleCallbacks.destroy.push(...callbacks);
+    return this;
+  }
+  /**
+   * Add cleanup callbacks to be executed in order during nodeCleanup
+   */
+  onCleanup(...callbacks) {
+    this.lifecycleCallbacks.cleanup.push(...callbacks);
+    return this;
+  }
+  /**
+   * Prepend setup callbacks (run before existing ones)
+   */
+  prependSetup(...callbacks) {
+    this.lifecycleCallbacks.setup.unshift(...callbacks);
+    return this;
+  }
+  /**
+   * Prepend update callbacks (run before existing ones)
+   */
+  prependUpdate(...callbacks) {
+    this.lifecycleCallbacks.update.unshift(...callbacks);
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tree structure
+  // ─────────────────────────────────────────────────────────────────────────────
   setParent(parent) {
     this.parent = parent;
   }
@@ -82,6 +139,9 @@ var BaseNode = class _BaseNode {
   isComposite() {
     return this.children.length > 0;
   }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Node lifecycle execution - runs internal + callback arrays
+  // ─────────────────────────────────────────────────────────────────────────────
   nodeSetup(params) {
     if (DEBUG_FLAG) {
     }
@@ -89,8 +149,8 @@ var BaseNode = class _BaseNode {
     if (typeof this._setup === "function") {
       this._setup(params);
     }
-    if (this.setup) {
-      this.setup(params);
+    for (const callback of this.lifecycleCallbacks.setup) {
+      callback(params);
     }
     this.children.forEach((child) => child.nodeSetup(params));
   }
@@ -101,21 +161,40 @@ var BaseNode = class _BaseNode {
     if (typeof this._update === "function") {
       this._update(params);
     }
-    if (this.update) {
-      this.update(params);
+    for (const callback of this.lifecycleCallbacks.update) {
+      callback(params);
     }
     this.children.forEach((child) => child.nodeUpdate(params));
   }
   nodeDestroy(params) {
     this.children.forEach((child) => child.nodeDestroy(params));
-    if (this.destroy) {
-      this.destroy(params);
+    for (const callback of this.lifecycleCallbacks.destroy) {
+      callback(params);
     }
     if (typeof this._destroy === "function") {
       this._destroy(params);
     }
     this.markedForRemoval = true;
   }
+  async nodeLoaded(params) {
+    if (typeof this._loaded === "function") {
+      await this._loaded(params);
+    }
+    for (const callback of this.lifecycleCallbacks.loaded) {
+      callback(params);
+    }
+  }
+  async nodeCleanup(params) {
+    for (const callback of this.lifecycleCallbacks.cleanup) {
+      callback(params);
+    }
+    if (typeof this._cleanup === "function") {
+      await this._cleanup(params);
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Options
+  // ─────────────────────────────────────────────────────────────────────────────
   getOptions() {
     return this.options;
   }
@@ -137,11 +216,6 @@ var GameEntity = class extends BaseNode {
   custom = {};
   debugInfo = {};
   debugMaterial;
-  lifeCycleDelegate = {
-    setup: [],
-    update: [],
-    destroy: []
-  };
   collisionDelegate = {
     collision: []
   };
@@ -166,67 +240,40 @@ var GameEntity = class extends BaseNode {
     this.name = this.options.name || "";
     return this;
   }
-  onSetup(...callbacks) {
-    const combineCallbacks = [...this.lifeCycleDelegate.setup ?? [], ...callbacks];
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      setup: combineCallbacks
-    };
-    return this;
-  }
-  onUpdate(...callbacks) {
-    const combineCallbacks = [...this.lifeCycleDelegate.update ?? [], ...callbacks];
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      update: combineCallbacks
-    };
-    return this;
-  }
-  onDestroy(...callbacks) {
-    this.lifeCycleDelegate = {
-      ...this.lifeCycleDelegate,
-      destroy: callbacks.length > 0 ? callbacks : void 0
-    };
-    return this;
-  }
+  /**
+   * Add collision callbacks
+   */
   onCollision(...callbacks) {
-    this.collisionDelegate = {
-      collision: callbacks.length > 0 ? callbacks : void 0
-    };
+    const existing = this.collisionDelegate.collision ?? [];
+    this.collisionDelegate.collision = [...existing, ...callbacks];
     return this;
   }
+  /**
+   * Entity-specific setup - runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.setup)
+   */
   _setup(params) {
     this.behaviorCallbackMap.setup.forEach((callback) => {
       callback({ ...params, me: this });
     });
-    if (this.lifeCycleDelegate.setup?.length) {
-      const callbacks = this.lifeCycleDelegate.setup;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
   }
   async _loaded(_params) {
   }
+  /**
+   * Entity-specific update - updates materials and runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.update)
+   */
   _update(params) {
     this.updateMaterials(params);
-    if (this.lifeCycleDelegate.update?.length) {
-      const callbacks = this.lifeCycleDelegate.update;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
     this.behaviorCallbackMap.update.forEach((callback) => {
       callback({ ...params, me: this });
     });
   }
+  /**
+   * Entity-specific destroy - runs behavior callbacks
+   * (User callbacks are handled by BaseNode's lifecycleCallbacks.destroy)
+   */
   _destroy(params) {
-    if (this.lifeCycleDelegate.destroy?.length) {
-      const callbacks = this.lifeCycleDelegate.destroy;
-      callbacks.forEach((callback) => {
-        callback({ ...params, me: this });
-      });
-    }
     this.behaviorCallbackMap.destroy.forEach((callback) => {
       callback({ ...params, me: this });
     });
@@ -818,7 +865,7 @@ var BoxBuilder = class extends EntityBuilder {
     return new ZylemBox(options);
   }
 };
-var BOX_TYPE = Symbol("Box");
+var BOX_TYPE = /* @__PURE__ */ Symbol("Box");
 var ZylemBox = class _ZylemBox extends GameEntity {
   static type = BOX_TYPE;
   constructor(options) {
@@ -881,7 +928,7 @@ var SphereBuilder = class extends EntityBuilder {
     return new ZylemSphere(options);
   }
 };
-var SPHERE_TYPE = Symbol("Sphere");
+var SPHERE_TYPE = /* @__PURE__ */ Symbol("Sphere");
 var ZylemSphere = class _ZylemSphere extends GameEntity {
   static type = SPHERE_TYPE;
   constructor(options) {
@@ -945,7 +992,7 @@ var SpriteBuilder = class extends EntityBuilder {
     return new ZylemSprite(options);
   }
 };
-var SPRITE_TYPE = Symbol("Sprite");
+var SPRITE_TYPE = /* @__PURE__ */ Symbol("Sprite");
 var ZylemSprite = class _ZylemSprite extends GameEntity {
   static type = SPRITE_TYPE;
   sprites = [];
@@ -959,12 +1006,21 @@ var ZylemSprite = class _ZylemSprite extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...spriteDefaults, ...options };
-    this.createSpritesFromImages(options?.images || []);
-    this.createAnimations(options?.animations || []);
-    this.lifeCycleDelegate = {
-      update: [this.spriteUpdate.bind(this)],
-      destroy: [this.spriteDestroy.bind(this)]
-    };
+    this.prependUpdate(this.spriteUpdate.bind(this));
+    this.onDestroy(this.spriteDestroy.bind(this));
+  }
+  create() {
+    this.sprites = [];
+    this.spriteMap.clear();
+    this.animations.clear();
+    this.currentAnimation = null;
+    this.currentAnimationFrame = "";
+    this.currentAnimationIndex = 0;
+    this.currentAnimationTime = 0;
+    this.group = void 0;
+    this.createSpritesFromImages(this.options?.images || []);
+    this.createAnimations(this.options?.animations || []);
+    return super.create();
   }
   createSpritesFromImages(images) {
     const textureLoader = new TextureLoader2();
@@ -1211,7 +1267,7 @@ var PlaneBuilder = class extends EntityBuilder {
     return new ZylemPlane(options);
   }
 };
-var PLANE_TYPE = Symbol("Plane");
+var PLANE_TYPE = /* @__PURE__ */ Symbol("Plane");
 var ZylemPlane = class extends GameEntity {
   static type = PLANE_TYPE;
   constructor(options) {
@@ -1269,7 +1325,7 @@ var ZoneBuilder = class extends EntityBuilder {
     return new ZylemZone(options);
   }
 };
-var ZONE_TYPE = Symbol("Zone");
+var ZONE_TYPE = /* @__PURE__ */ Symbol("Zone");
 var ZylemZone = class extends GameEntity {
   static type = ZONE_TYPE;
   _enteredZone = /* @__PURE__ */ new Map();
@@ -1499,6 +1555,23 @@ var AnimationDelegate = class {
     this._currentAction = action;
     this._currentKey = key;
   }
+  /**
+   * Dispose of all animation resources
+   */
+  dispose() {
+    Object.values(this._actions).forEach((action) => {
+      action.stop();
+    });
+    if (this._mixer) {
+      this._mixer.stopAllAction();
+      this._mixer.uncacheRoot(this.target);
+      this._mixer = null;
+    }
+    this._actions = {};
+    this._animations = [];
+    this._currentAction = null;
+    this._currentKey = "";
+  }
   get currentAnimationKey() {
     return this._currentKey;
   }
@@ -1557,7 +1630,7 @@ var ActorBuilder = class extends EntityBuilder {
     return new ZylemActor(options);
   }
 };
-var ACTOR_TYPE = Symbol("Actor");
+var ACTOR_TYPE = /* @__PURE__ */ Symbol("Actor");
 var ZylemActor = class extends GameEntity {
   static type = ACTOR_TYPE;
   _object = null;
@@ -1568,9 +1641,7 @@ var ZylemActor = class extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...actorDefaults, ...options };
-    this.lifeCycleDelegate = {
-      update: [this.actorUpdate.bind(this)]
-    };
+    this.prependUpdate(this.actorUpdate.bind(this));
     this.controlledRotation = true;
   }
   async load() {
@@ -1590,6 +1661,34 @@ var ZylemActor = class extends GameEntity {
   async actorUpdate(params) {
     this._animationDelegate?.update(params.delta);
   }
+  /**
+   * Clean up actor resources including animations, models, and groups
+   */
+  actorDestroy() {
+    if (this._animationDelegate) {
+      this._animationDelegate.dispose();
+      this._animationDelegate = null;
+    }
+    if (this._object) {
+      this._object.traverse((child) => {
+        if (child.isMesh) {
+          const mesh = child;
+          mesh.geometry?.dispose();
+          if (Array.isArray(mesh.material)) {
+            mesh.material.forEach((m) => m.dispose());
+          } else if (mesh.material) {
+            mesh.material.dispose();
+          }
+        }
+      });
+      this._object = null;
+    }
+    if (this.group) {
+      this.group.clear();
+      this.group = null;
+    }
+    this._modelFileNames = [];
+  }
   async loadModels() {
     if (this._modelFileNames.length === 0) return;
     const promises = this._modelFileNames.map((file) => this._assetLoader.loadFile(file));
@@ -1676,7 +1775,7 @@ var TextBuilder = class extends EntityBuilder {
     return new ZylemText(options);
   }
 };
-var TEXT_TYPE = Symbol("Text");
+var TEXT_TYPE = /* @__PURE__ */ Symbol("Text");
 var ZylemText = class _ZylemText extends GameEntity {
   static type = TEXT_TYPE;
   _sprite = null;
@@ -1689,12 +1788,20 @@ var ZylemText = class _ZylemText extends GameEntity {
   constructor(options) {
     super();
     this.options = { ...textDefaults, ...options };
+    this.prependSetup(this.textSetup.bind(this));
+    this.prependUpdate(this.textUpdate.bind(this));
+    this.onDestroy(this.textDestroy.bind(this));
+  }
+  create() {
+    this._sprite = null;
+    this._texture = null;
+    this._canvas = null;
+    this._ctx = null;
+    this._lastCanvasW = 0;
+    this._lastCanvasH = 0;
     this.group = new Group5();
     this.createSprite();
-    this.lifeCycleDelegate = {
-      setup: [this.textSetup.bind(this)],
-      update: [this.textUpdate.bind(this)]
-    };
+    return super.create();
   }
   createSprite() {
     this._canvas = document.createElement("canvas");
@@ -1860,6 +1967,24 @@ var ZylemText = class _ZylemText extends GameEntity {
       sticky: this.options.stickToViewport
     };
   }
+  /**
+   * Dispose of Three.js resources when the entity is destroyed.
+   */
+  async textDestroy() {
+    this._texture?.dispose();
+    if (this._sprite?.material) {
+      this._sprite.material.dispose();
+    }
+    if (this._sprite) {
+      this._sprite.removeFromParent();
+    }
+    this.group?.removeFromParent();
+    this._sprite = null;
+    this._texture = null;
+    this._canvas = null;
+    this._ctx = null;
+    this._cameraRef = null;
+  }
 };
 async function text(...args) {
   return createEntity({
@@ -1892,7 +2017,7 @@ var RectBuilder = class extends EntityBuilder {
     return new ZylemRect(options);
   }
 };
-var RECT_TYPE = Symbol("Rect");
+var RECT_TYPE = /* @__PURE__ */ Symbol("Rect");
 var ZylemRect = class _ZylemRect extends GameEntity {
   static type = RECT_TYPE;
   _sprite = null;
@@ -1908,10 +2033,8 @@ var ZylemRect = class _ZylemRect extends GameEntity {
     this.options = { ...rectDefaults, ...options };
     this.group = new Group6();
     this.createSprite();
-    this.lifeCycleDelegate = {
-      setup: [this.rectSetup.bind(this)],
-      update: [this.rectUpdate.bind(this)]
-    };
+    this.prependSetup(this.rectSetup.bind(this));
+    this.prependUpdate(this.rectUpdate.bind(this));
   }
   createSprite() {
     this._canvas = document.createElement("canvas");