emeraldengine 2.2.0 → 3.0.0

package/src/Tilemap.js

@@ -0,0 +1,274 @@
+import GameObject from "./components/GameObject.js";
+import InstancedTexture from "./InstancedTexture.js";
+import Instance from "./Instance.js";
+import RigidBody from "./components/RigidBody.js";
+import BoxCollider from "./components/BoxCollider.js";
+import { Vector2, Vector3 } from "./Physics.js";
+
+/**
+ * @class Tilemap
+ * @description Builds a grid of tiles from a 2D array of frame indices, rendered
+ * as a single instanced draw call. Use -1 (or null) for empty cells. The tiles
+ * live on `tilemap.gameObject`, which you add to the scene.
+ *
+ * @example
+ * const map = new Tilemap("level", "tiles.png", {
+ *   tileSize: 32, frameWidth: 16, frameHeight: 16, framesPerRow: 4, totalFrames: 16,
+ * });
+ * map.setMap([
+ *   [0, 0, 0, 0],
+ *   [1, -1, -1, 1],
+ *   [2, 2, 2, 2],
+ * ]);
+ * scene.add(map.gameObject);
+ */
+class Tilemap {
+  /**
+   * @param {string} name - Name for the underlying GameObject
+   * @param {string} texturePath - Path to the tile sheet
+   * @param {Object} [options] - tileSize, frameWidth, frameHeight, framesPerRow, totalFrames, pixelart
+   */
+  constructor(name, texturePath, options = {}) {
+    const {
+      tileSize = 32,
+      frameWidth = tileSize,
+      frameHeight = tileSize,
+      framesPerRow = 1,
+      totalFrames = 1,
+      pixelart = true,
+    } = options;
+
+    this.name = name;
+    this.tileSize = tileSize;
+    /** @private */
+    this._config = {
+      texturePath,
+      frameWidth,
+      frameHeight,
+      framesPerRow,
+      totalFrames,
+      pixelart,
+    };
+
+    this.gameObject = new GameObject(
+      name,
+      new Vector3(0, 0, 0),
+      0,
+      new Vector2(1, 1)
+    );
+    this.texture = null;
+
+    /** @private */
+    this._map = null;
+    /** @private */
+    this._layout = null;
+    /** @private */
+    this._colliders = [];
+  }
+
+  /**
+   * @method setMap
+   * @description Builds (or rebuilds) the tile instances from a 2D array.
+   * @param {number[][]} map - Rows of frame indices (-1/null = empty)
+   * @param {Object} [options] - { originX = 0, originY = 0, flipY = true }
+   * @returns {Tilemap} - this
+   */
+  setMap(map, options = {}) {
+    const { originX = 0, originY = 0, flipY = true } = options;
+    const rows = map.length;
+    const cols = map.reduce(
+      (max, row) => Math.max(max, row ? row.length : 0),
+      0
+    );
+    const count = Math.max(1, rows * cols);
+
+    this._map = map;
+    this._layout = { originX, originY, flipY, rows, cols };
+
+    const existing = this.gameObject.getComponent(InstancedTexture);
+    if (existing) this.gameObject.removeComponent(existing);
+
+    this.texture = new InstancedTexture(
+      this._config.texturePath,
+      count,
+      this._config.frameWidth,
+      this._config.frameHeight,
+      this._config.framesPerRow,
+      this._config.totalFrames,
+      0,
+      false,
+      this._config.pixelart
+    );
+    this.texture.clearInstances();
+
+    const half = this.tileSize / 2;
+    for (let r = 0; r < rows; r++) {
+      const row = map[r];
+      if (!row) continue;
+      for (let c = 0; c < row.length; c++) {
+        const frame = row[c];
+        if (frame == null || frame < 0) continue;
+        const rowIndex = flipY ? rows - 1 - r : r;
+        const x = originX + c * this.tileSize + half;
+        const y = originY + rowIndex * this.tileSize + half;
+        this.texture.addInstance(
+          new Instance(
+            `${this.name}_${r}_${c}`,
+            new Vector3(x, y, 0),
+            new Vector2(half, half),
+            0,
+            frame
+          )
+        );
+      }
+    }
+
+    this.texture.setStatic(true);
+    this.gameObject.addComponent(this.texture);
+    return this;
+  }
+
+  /**
+   * @method buildColliders
+   * @description Generates static physics colliders from the current map. Solid
+   * cells are merged greedily into horizontal runs, so a row of N tiles becomes
+   * one box collider instead of N — far fewer bodies for the physics engine.
+   * The bodies are tagged so collision callbacks resolve back to `ownerObject`
+   * (defaults to the tilemap's GameObject). Call again after setMap to rebuild.
+   *
+   * @param {Physics} physics - The physics engine
+   * @param {Object} [options] - { isSolid, friction = 0.2, restitution = 0,
+   *   density = 0, ownerObject }
+   * @returns {Tilemap} - this
+   */
+  buildColliders(physics, options = {}) {
+    if (!this._map || !this._layout) return this;
+    const {
+      isSolid = (frame) => frame != null && frame >= 0,
+      friction = 0.2,
+      restitution = 0,
+      density = 0,
+      ownerObject = this.gameObject,
+    } = options;
+
+    this.clearColliders();
+
+    const { originX, originY, flipY, rows } = this._layout;
+    const ts = this.tileSize;
+    const half = ts / 2;
+    const scale = physics.getScale();
+
+    for (let r = 0; r < rows; r++) {
+      const row = this._map[r];
+      if (!row) continue;
+      let c = 0;
+      while (c < row.length) {
+        if (!isSolid(row[c])) {
+          c++;
+          continue;
+        }
+        let runStart = c;
+        while (c < row.length && isSolid(row[c])) c++;
+        const runLen = c - runStart;
+
+        const rowIndex = flipY ? rows - 1 - r : r;
+        const runWidth = runLen * ts;
+        const centerX = originX + runStart * ts + runWidth / 2;
+        const centerY = originY + rowIndex * ts + half;
+
+        const body = new RigidBody(
+          physics,
+          "static",
+          new Vector2(centerX, centerY),
+          true,
+          ownerObject,
+          new Vector2(0, 0)
+        );
+        new BoxCollider(
+          body,
+          new Vector2(runWidth / 2 / scale, half / scale),
+          density,
+          friction,
+          restitution,
+          false,
+          ownerObject
+        );
+        this._colliders.push(body);
+      }
+    }
+    return this;
+  }
+
+  /**
+   * @method clearColliders
+   * @description Destroys the physics bodies created by buildColliders.
+   * @returns {Tilemap} - this
+   */
+  clearColliders() {
+    for (const body of this._colliders) {
+      if (body && typeof body.destroy === "function") body.destroy();
+    }
+    this._colliders = [];
+    return this;
+  }
+
+  /**
+   * @method setAutoTiledMap
+   * @description Convenience: computes frame indices from a solidity grid using
+   * bitmask auto-tiling, then builds the map. See Tilemap.computeAutoTile.
+   * @param {Array<Array<boolean|number>>} solidGrid - Truthy = solid cell
+   * @param {Object} [options] - Auto-tile options + setMap options
+   * @returns {Tilemap} - this
+   */
+  setAutoTiledMap(solidGrid, options = {}) {
+    const frames = Tilemap.computeAutoTile(solidGrid, options);
+    return this.setMap(frames, options);
+  }
+
+  /**
+   * @method computeAutoTile
+   * @description Pure helper that converts a 2D solidity grid into a 2D frame
+   * index grid using 4-bit edge bitmasking. For each solid cell the neighbor
+   * mask is built as up|right|down|left (bits 1,2,4,8); empty cells become -1.
+   * Provide `frames` (a length-16 lookup from mask -> frame index) to match your
+   * tilesheet layout; otherwise the mask itself is used as the frame index, and
+   * `base` is added to every solid frame.
+   *
+   * @param {Array<Array<boolean|number>>} grid - Truthy = solid
+   * @param {Object} [options] - { frames, base = 0, edgesSolid = true }
+   * @returns {number[][]} - Frame indices (-1 for empty)
+   */
+  static computeAutoTile(grid, options = {}) {
+    const { frames = null, base = 0, edgesSolid = true } = options;
+    const rows = grid.length;
+    const out = [];
+    const solidAt = (r, c) => {
+      if (r < 0 || c < 0 || r >= rows || !grid[r] || c >= grid[r].length) {
+        return edgesSolid;
+      }
+      return !!grid[r][c];
+    };
+
+    for (let r = 0; r < rows; r++) {
+      const row = grid[r] || [];
+      const outRow = [];
+      for (let c = 0; c < row.length; c++) {
+        if (!row[c]) {
+          outRow.push(-1);
+          continue;
+        }
+        let mask = 0;
+        if (solidAt(r - 1, c)) mask |= 1;
+        if (solidAt(r, c + 1)) mask |= 2;
+        if (solidAt(r + 1, c)) mask |= 4;
+        if (solidAt(r, c - 1)) mask |= 8;
+        const frame = frames ? frames[mask] : mask;
+        outRow.push(base + (frame == null ? 0 : frame));
+      }
+      out.push(outRow);
+    }
+    return out;
+  }
+}
+
+export default Tilemap;

package/src/Time.js

@@ -1,12 +1,13 @@
 /**
  * @class Time
- * @description Represents the time
- * @param {number} deltaTime - The delta time
+ * @description Global time state for the game. `deltaTime` is the (scaled)
+ * seconds since the last frame, `elapsedTime` accumulates total scaled time, and
+ * `timeScale` lets you slow down / speed up / pause the simulation.
  */
 class Time {
   /**
    * @method getDeltaTime
-   * @description Returns the delta time
+   * @description Returns the (time-scaled) delta time in seconds
    * @returns {number} - The delta time
    */
   static getDeltaTime() {
@@ -15,14 +16,58 @@ class Time {
 
   /**
    * @method setDeltaTime
-   * @description Sets the delta time
-   * @param {number} deltaTime - The delta time
+   * @description Sets the delta time. The stored value is multiplied by
+   * `timeScale`, and `elapsedTime` is advanced by the scaled amount. Called by
+   * `Emerald.drawScene`, but can be called manually for custom loops.
+   * @param {number} deltaTime - The unscaled delta time in seconds
    */
   static setDeltaTime(deltaTime) {
-    Time.deltaTime = deltaTime;
+    const scaled = deltaTime * Time.timeScale;
+    Time.unscaledDeltaTime = deltaTime;
+    Time.deltaTime = scaled;
+    Time.elapsedTime += scaled;
+  }
+
+  /**
+   * @method getUnscaledDeltaTime
+   * @description Returns the raw delta time, ignoring timeScale
+   * @returns {number} - The unscaled delta time
+   */
+  static getUnscaledDeltaTime() {
+    return Time.unscaledDeltaTime;
+  }
+
+  /**
+   * @method getElapsedTime
+   * @description Returns the total accumulated (scaled) time in seconds
+   * @returns {number} - The elapsed time
+   */
+  static getElapsedTime() {
+    return Time.elapsedTime;
+  }
+
+  /**
+   * @method setTimeScale
+   * @description Sets the time scale (1 = normal, 0 = paused, 2 = double speed)
+   * @param {number} scale - The time scale (clamped to >= 0)
+   */
+  static setTimeScale(scale) {
+    Time.timeScale = Math.max(0, scale);
+  }
+
+  /**
+   * @method getTimeScale
+   * @description Returns the current time scale
+   * @returns {number} - The time scale
+   */
+  static getTimeScale() {
+    return Time.timeScale;
   }
 }
 
 Time.deltaTime = 0;
+Time.unscaledDeltaTime = 0;
+Time.elapsedTime = 0;
+Time.timeScale = 1;
 
 export default Time;

package/src/Timer.js

@@ -0,0 +1,99 @@
+/**
+ * @class Timer
+ * @description Schedules delayed and repeating callbacks measured in seconds.
+ * Driven by `Emerald.drawScene` with time-scaled delta, so timers honor
+ * pause/slow-mo. Each scheduler call returns a handle you can pass to `clear`.
+ *
+ * @example
+ * Timer.after(2, () => spawnEnemy());        // once, after 2s
+ * Timer.every(0.5, () => tick(), 10);        // 10 times, every 0.5s
+ * const h = Timer.every(1, () => poll());    // forever until cleared
+ * Timer.clear(h);
+ */
+class Timer {
+  /**
+   * @method after
+   * @description Runs a callback once after a delay.
+   * @param {number} seconds - Delay in seconds
+   * @param {Function} callback
+   * @returns {Object} - A handle for clear()
+   */
+  static after(seconds, callback) {
+    return Timer._add(seconds, callback, 1);
+  }
+
+  /**
+   * @method every
+   * @description Runs a callback repeatedly on an interval.
+   * @param {number} seconds - Interval in seconds
+   * @param {Function} callback
+   * @param {number} [repeats] - Number of repeats (default Infinity)
+   * @returns {Object} - A handle for clear()
+   */
+  static every(seconds, callback, repeats = Infinity) {
+    return Timer._add(seconds, callback, repeats);
+  }
+
+  /** @private */
+  static _add(interval, callback, repeats) {
+    const entry = {
+      interval: Math.max(0, interval),
+      callback,
+      repeats,
+      elapsed: 0,
+      cancelled: false,
+    };
+    Timer.entries.push(entry);
+    return entry;
+  }
+
+  /**
+   * @method clear
+   * @description Cancels a scheduled timer by its handle.
+   * @param {Object} handle - The handle returned by after/every
+   */
+  static clear(handle) {
+    if (handle) handle.cancelled = true;
+  }
+
+  /**
+   * @method clearAll
+   * @description Cancels all timers.
+   */
+  static clearAll() {
+    Timer.entries.length = 0;
+  }
+
+  /**
+   * @method update
+   * @description Advances all timers. Driven by Emerald.drawScene.
+   * @param {number} dt - Seconds since the last frame
+   */
+  static update(dt) {
+    const entries = Timer.entries;
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      if (entry.cancelled) {
+        entries.splice(i, 1);
+        continue;
+      }
+
+      entry.elapsed += dt;
+      while (!entry.cancelled && entry.elapsed >= entry.interval) {
+        entry.elapsed -= entry.interval;
+        entry.repeats -= 1;
+        entry.callback();
+        if (entry.repeats <= 0) {
+          entry.cancelled = true;
+        }
+        if (entry.interval === 0) break;
+      }
+
+      if (entry.cancelled) entries.splice(i, 1);
+    }
+  }
+}
+
+Timer.entries = [];
+
+export default Timer;

package/src/Transform.js

@@ -1,15 +1,108 @@
 /**
  * @class Transform
- * @description Represents a transform
- * @param {Vector3} position - The position of the transform
- * @param {number} rotation - The rotation of the transform
- * @param {Vector2} scale - The scale of the transform
+ * @description Represents a transform with optional parent/child hierarchy.
+ * Local position/rotation/scale are composed up the parent chain to produce a
+ * world transform. Objects with no parent behave exactly as before (the world
+ * transform is the local transform), so existing code is unaffected.
+ * @param {Vector3} position - The local position
+ * @param {number} rotation - The local rotation (radians)
+ * @param {Vector2} scale - The local scale
  */
 class Transform {
   constructor(position, rotation, scale) {
     this.position = position;
     this.rotation = rotation;
     this.scale = scale;
+
+    this.parent = null;
+    this.children = [];
+
+    /** @private */
+    this._world = {
+      position: { x: 0, y: 0, z: 0 },
+      rotation: 0,
+      scale: { x: 1, y: 1 },
+    };
+  }
+
+  /**
+   * @method setParent
+   * @description Sets (or clears) the parent transform, maintaining the
+   * children list on both sides.
+   * @param {Transform|null} parent - The parent transform, or null to detach
+   */
+  setParent(parent) {
+    if (this.parent === parent) return;
+    if (this.parent) {
+      const idx = this.parent.children.indexOf(this);
+      if (idx !== -1) this.parent.children.splice(idx, 1);
+    }
+    this.parent = parent || null;
+    if (this.parent && this.parent.children.indexOf(this) === -1) {
+      this.parent.children.push(this);
+    }
+  }
+
+  /**
+   * @method getWorldParts
+   * @description Returns the composed world TRS as primitives. Composition is
+   * standard 2D: child local space is scaled and rotated by the parent.
+   * @returns {{px:number, py:number, pz:number, rot:number, sx:number, sy:number}}
+   */
+  getWorldParts() {
+    if (!this.parent) {
+      return {
+        px: this.position.x,
+        py: this.position.y,
+        pz: this.position.z,
+        rot: this.rotation,
+        sx: this.scale.x,
+        sy: this.scale.y,
+      };
+    }
+
+    const p = this.parent.getWorldParts();
+    const cos = Math.cos(p.rot);
+    const sin = Math.sin(p.rot);
+    const lx = this.position.x * p.sx;
+    const ly = this.position.y * p.sy;
+
+    return {
+      px: p.px + (lx * cos - ly * sin),
+      py: p.py + (lx * sin + ly * cos),
+      pz: p.pz + this.position.z,
+      rot: p.rot + this.rotation,
+      sx: p.sx * this.scale.x,
+      sy: p.sy * this.scale.y,
+    };
+  }
+
+  /**
+   * @method getWorldTransform
+   * @description Returns a transform-shaped object ({position, rotation, scale})
+   * in world space. The returned object is reused between calls.
+   * @returns {{position:{x,y,z}, rotation:number, scale:{x,y}}}
+   */
+  getWorldTransform() {
+    if (!this.parent) return this;
+    const w = this.getWorldParts();
+    const out = this._world;
+    out.position.x = w.px;
+    out.position.y = w.py;
+    out.position.z = w.pz;
+    out.rotation = w.rot;
+    out.scale.x = w.sx;
+    out.scale.y = w.sy;
+    return out;
+  }
+
+  /**
+   * @method getWorldPosition
+   * @description Returns the world-space position as a plain { x, y, z }.
+   */
+  getWorldPosition() {
+    const w = this.getWorldParts();
+    return { x: w.px, y: w.py, z: w.pz };
   }
 
   /**
@@ -30,7 +123,7 @@ class Transform {
 
   /**
    * @method getPosition
-   * @description Returns the position of the transform
+   * @description Returns the local position of the transform
    * @returns {Vector3} - The position of the transform
    */
   getPosition() {
@@ -39,7 +132,7 @@ class Transform {
 
   /**
    * @method getRotation
-   * @description Returns the rotation of the transform
+   * @description Returns the local rotation of the transform
    * @returns {number} - The rotation of the transform
    */
   getRotation() {
@@ -48,7 +141,7 @@ class Transform {
 
   /**
    * @method getScale
-   * @description Returns the scale of the transform
+   * @description Returns the local scale of the transform
    * @returns {Vector2} - The scale of the transform
    */
   getScale() {