emeraldengine 2.2.1 → 3.0.0

package/src/CollisionLayers.js

@@ -0,0 +1,86 @@
+/**
+ * @class CollisionLayers
+ * @description A small registry that maps human-readable layer names to the
+ * category bits planck uses for collision filtering, so games can say
+ * "players collide with ground and enemies, but not with each other" without
+ * juggling raw bitmasks.
+ *
+ * Two fixtures collide only if each one's category is in the other's mask, so
+ * filtering is symmetric by construction. Up to 16 distinct layers are
+ * supported (planck filter bits are 16-bit).
+ *
+ * @example
+ * CollisionLayers.define("ground", "player", "enemy", "pickup");
+ * playerCollider.setCategory("player");
+ * playerCollider.setCollidesWith(["ground", "enemy", "pickup"]);
+ * enemyCollider.setCategory("enemy");
+ * enemyCollider.setCollidesWith(["ground", "player"]); // enemies ignore each other
+ */
+const ALL_BITS = 0xffff;
+
+class CollisionLayers {
+  /**
+   * @method define
+   * @description Registers one or more named layers (in order), assigning each
+   * the next free category bit. Re-defining an existing name returns its
+   * existing bit. Returns the bit of the last name passed.
+   * @param {...string} names
+   * @returns {number}
+   */
+  static define(...names) {
+    let last = 0;
+    for (const name of names) last = CollisionLayers.bit(name);
+    return last;
+  }
+
+  /**
+   * @method bit
+   * @description Returns the category bit for a layer name, registering it on
+   * first use.
+   * @param {string} name
+   * @returns {number}
+   */
+  static bit(name) {
+    if (CollisionLayers._bits.has(name)) return CollisionLayers._bits.get(name);
+    if (CollisionLayers._next > 15) {
+      throw new Error(
+        "[CollisionLayers] Exceeded 16 collision layers (planck filter limit)."
+      );
+    }
+    const bit = 1 << CollisionLayers._next++;
+    CollisionLayers._bits.set(name, bit);
+    return bit;
+  }
+
+  /**
+   * @method mask
+   * @description Computes a combined mask from layer names. Accepts a single
+   * name, an array of names, a number (passed through), or "all"/null for
+   * "collide with everything".
+   * @param {string|string[]|number|null} layers
+   * @returns {number}
+   */
+  static mask(layers) {
+    if (layers == null || layers === "all") return ALL_BITS;
+    if (typeof layers === "number") return layers;
+    const list = Array.isArray(layers) ? layers : [layers];
+    let m = 0;
+    for (const name of list) m |= CollisionLayers.bit(name);
+    return m;
+  }
+
+  /**
+   * @method reset
+   * @description Clears all registered layers (mainly for tests).
+   */
+  static reset() {
+    CollisionLayers._bits.clear();
+    CollisionLayers._next = 0;
+  }
+}
+
+CollisionLayers._bits = new Map();
+CollisionLayers._next = 0;
+CollisionLayers.ALL = ALL_BITS;
+
+export default CollisionLayers;

package/src/Color.js

@@ -1,18 +1,18 @@
-/**
- * @class Color
- * @description Represents a color
- * @param {number} r - The red value
- * @param {number} g - The green value
- * @param {number} b - The blue value
- * @param {number} a - The alpha value
- */
-class Color {
-  constructor(r, g, b, a = 255) {
-    this.r = r;
-    this.g = g;
-    this.b = b;
-    this.a = a;
-  }
-}
-
-export default Color;
+/**
+ * @class Color
+ * @description Represents a color
+ * @param {number} r - The red value
+ * @param {number} g - The green value
+ * @param {number} b - The blue value
+ * @param {number} a - The alpha value
+ */
+class Color {
+  constructor(r, g, b, a = 255) {
+    this.r = r;
+    this.g = g;
+    this.b = b;
+    this.a = a;
+  }
+}
+
+export default Color;

package/src/Coroutine.js

@@ -0,0 +1,259 @@
+/**
+ * @class Coroutine
+ * @description Generator-based sequencing for time-based logic, layered on top of
+ * the same per-frame delta the rest of the engine uses. Write a generator that
+ * `yield`s instructions, and the runner advances it each frame:
+ *
+ *   - `yield seconds` (a number)        -> wait that many seconds
+ *   - `yield Coroutine.waitFrames(n)`   -> wait n frames
+ *   - `yield Coroutine.waitUntil(fn)`   -> wait until fn() is truthy
+ *   - `yield Coroutine.waitWhile(fn)`   -> wait while fn() is truthy
+ *   - `yield somePromise`               -> wait for the promise to resolve
+ *   - `yield anotherCoroutine`          -> wait for a nested coroutine to finish
+ *   - `yield Coroutine.tween(...)`      -> drive a value over time, then continue
+ *
+ * Coroutines are driven by `Coroutine.update(dt)` (called automatically from
+ * `Emerald.drawScene`, so they honor pause/slow-mo via Time.timeScale).
+ *
+ * @example
+ * Coroutine.start(function* () {
+ *   door.open();
+ *   yield 1.5;                       // wait 1.5s
+ *   yield Coroutine.waitUntil(() => player.isReady);
+ *   boss.spawn();
+ * });
+ */
+class Coroutine {
+  /**
+   * @method start
+   * @description Starts a coroutine from a generator function (or an existing
+   * generator/iterator). Returns a handle with `cancel()` and `done`.
+   * @param {GeneratorFunction|Generator} gen - The generator (function) to run
+   * @param {...*} args - Arguments forwarded to the generator function
+   * @returns {Object} - A handle: { cancel(), done, isRunning() }
+   */
+  static start(gen, ...args) {
+    const iterator = typeof gen === "function" ? gen(...args) : gen;
+    const routine = {
+      iterator,
+      wait: null,
+      cancelled: false,
+      done: false,
+      _resolve: null,
+    };
+    routine.promise = new Promise((resolve) => (routine._resolve = resolve));
+    routine.cancel = () => {
+      routine.cancelled = true;
+    };
+    routine.isRunning = () => !routine.done && !routine.cancelled;
+    Coroutine._routines.push(routine);
+    Coroutine._advance(routine, undefined, 0);
+    return routine;
+  }
+
+  /**
+   * @method waitFrames
+   * @description Yieldable that waits a number of frames.
+   * @param {number} count - Frames to wait
+   */
+  static waitFrames(count) {
+    return { __coroutine: "frames", count: Math.max(0, count | 0) };
+  }
+
+  /**
+   * @method waitUntil
+   * @description Yieldable that blocks until the predicate returns truthy.
+   * @param {Function} predicate
+   */
+  static waitUntil(predicate) {
+    return { __coroutine: "until", predicate };
+  }
+
+  /**
+   * @method waitWhile
+   * @description Yieldable that blocks while the predicate returns truthy.
+   * @param {Function} predicate
+   */
+  static waitWhile(predicate) {
+    return { __coroutine: "until", predicate: () => !predicate() };
+  }
+
+  /**
+   * @method tween
+   * @description Yieldable that interpolates from `from` to `to` over `duration`
+   * seconds, calling `onUpdate(value)` each frame, then resumes the coroutine.
+   * @param {number} from
+   * @param {number} to
+   * @param {number} duration - Seconds
+   * @param {Function} onUpdate - Receives the current value each step
+   * @param {Function} [easing] - Optional easing t -> t
+   */
+  static tween(from, to, duration, onUpdate, easing) {
+    return {
+      __coroutine: "tween",
+      from,
+      to,
+      duration: Math.max(0, duration),
+      onUpdate,
+      easing: easing || ((t) => t),
+      elapsed: 0,
+    };
+  }
+
+  /**
+   * @method update
+   * @description Advances all running coroutines by dt seconds. Driven by
+   * Emerald.drawScene.
+   * @param {number} dt - Seconds since the last frame (time-scaled)
+   */
+  static update(dt) {
+    const routines = Coroutine._routines;
+    for (let i = routines.length - 1; i >= 0; i--) {
+      const routine = routines[i];
+      if (routine.cancelled || routine.done) {
+        Coroutine._finish(routine);
+        routines.splice(i, 1);
+        continue;
+      }
+      Coroutine._step(routine, dt);
+      if (routine.cancelled || routine.done) {
+        Coroutine._finish(routine);
+        routines.splice(i, 1);
+      }
+    }
+  }
+
+  /**
+   * @method clearAll
+   * @description Cancels and removes every running coroutine.
+   */
+  static clearAll() {
+    for (const r of Coroutine._routines) r.cancelled = true;
+    Coroutine._routines.length = 0;
+  }
+
+  /**
+   * @method count
+   * @returns {number} - Number of currently running coroutines
+   */
+  static count() {
+    return Coroutine._routines.length;
+  }
+
+  /** @private */
+  static _finish(routine) {
+    if (routine._resolve) {
+      const resolve = routine._resolve;
+      routine._resolve = null;
+      resolve();
+    }
+  }
+
+  /** @private */
+  static _step(routine, dt) {
+    const wait = routine.wait;
+    if (!wait) {
+      Coroutine._advance(routine, undefined, dt);
+      return;
+    }
+
+    switch (wait.kind) {
+      case "time":
+        wait.remaining -= dt;
+        if (wait.remaining <= 0) {
+          const overflow = -wait.remaining;
+          Coroutine._advance(routine, undefined, overflow);
+        }
+        break;
+      case "frames":
+        wait.remaining -= 1;
+        if (wait.remaining <= 0) Coroutine._advance(routine, undefined, 0);
+        break;
+      case "until":
+        if (wait.predicate()) Coroutine._advance(routine, undefined, 0);
+        break;
+      case "tween": {
+        const t = wait.spec;
+        t.elapsed += dt;
+        const k = t.duration <= 0 ? 1 : Math.min(1, t.elapsed / t.duration);
+        const eased = t.easing(k);
+        t.onUpdate(t.from + (t.to - t.from) * eased);
+        if (k >= 1) Coroutine._advance(routine, undefined, 0);
+        break;
+      }
+      case "promise":
+        if (wait.resolved) {
+          Coroutine._advance(routine, wait.value, 0);
+        }
+        break;
+      case "nested":
+        if (wait.routine.done || wait.routine.cancelled) {
+          Coroutine._advance(routine, undefined, 0);
+        }
+        break;
+      default:
+        Coroutine._advance(routine, undefined, dt);
+    }
+  }
+
+  /** @private */
+  static _advance(routine, sendValue, leftoverDt) {
+    if (routine.cancelled || routine.done) return;
+    let result;
+    try {
+      result = routine.iterator.next(sendValue);
+    } catch (err) {
+      console.error("[Coroutine] Error in coroutine:", err);
+      routine.done = true;
+      return;
+    }
+    if (result.done) {
+      routine.done = true;
+      return;
+    }
+    routine.wait = Coroutine._interpret(result.value, routine);
+    if (routine.wait && routine.wait.kind === "time" && leftoverDt > 0) {
+      Coroutine._step(routine, leftoverDt);
+    }
+  }
+
+  /** @private */
+  static _interpret(value, routine) {
+    if (value == null) {
+      return { kind: "time", remaining: 0 };
+    }
+    if (typeof value === "number") {
+      return { kind: "time", remaining: value };
+    }
+    if (typeof value.then === "function") {
+      const wait = { kind: "promise", resolved: false, value: undefined };
+      value.then(
+        (v) => {
+          wait.resolved = true;
+          wait.value = v;
+        },
+        () => {
+          wait.resolved = true;
+        }
+      );
+      return wait;
+    }
+    if (value.iterator && typeof value.cancel === "function") {
+      return { kind: "nested", routine: value };
+    }
+    switch (value.__coroutine) {
+      case "frames":
+        return { kind: "frames", remaining: value.count };
+      case "until":
+        return { kind: "until", predicate: value.predicate };
+      case "tween":
+        return { kind: "tween", spec: value };
+      default:
+        return { kind: "time", remaining: 0 };
+    }
+  }
+}
+
+Coroutine._routines = [];
+
+export default Coroutine;

package/src/DebugOverlay.js

@@ -0,0 +1,246 @@
+import RigidBody from "./components/RigidBody.js";
+
+/**
+ * @class DebugOverlay
+ * @description A DOM panel that profiles the running game: FPS, frame-time stats
+ * with a live sparkline graph, object/camera counts, the primary camera's
+ * position/zoom, JS heap usage (where available), and any extra metrics you
+ * push. It can also toggle physics collider debug shapes on a scene.
+ *
+ * Call `update(emerald, scene)` each frame; toggle visibility with `setVisible`.
+ *
+ * @example
+ * const debug = new DebugOverlay();
+ * // each frame, after drawScene:
+ * debug.update(emerald, scene);
+ * debug.setMetric("draws", spriteBatch.drawCalls);
+ * debug.showColliders(scene, true); // visualize physics colliders
+ */
+class DebugOverlay {
+  constructor(options = {}) {
+    this.element = document.createElement("div");
+    Object.assign(this.element.style, {
+      position: "absolute",
+      top: options.top || "10px",
+      right: options.right || "10px",
+      padding: "8px 10px",
+      background: "rgba(0,0,0,0.6)",
+      color: "#9be7c4",
+      font: "12px/1.5 monospace",
+      whiteSpace: "pre",
+      borderRadius: "6px",
+      pointerEvents: "none",
+      zIndex: "9999",
+    });
+
+    /** @private */
+    this._graph = document.createElement("canvas");
+    this._graph.width = options.graphWidth || 160;
+    this._graph.height = options.graphHeight || 36;
+    this._graph.style.display = "block";
+    this._graph.style.marginTop = "6px";
+    this._graph.style.borderRadius = "3px";
+    /** @private */
+    this._gctx = this._graph.getContext("2d");
+
+    /** @private */
+    this._text = document.createElement("div");
+    this.element.appendChild(this._text);
+    this.element.appendChild(this._graph);
+
+    (options.parent || document.body).appendChild(this.element);
+
+    /** @private */
+    this._last = performance.now();
+    /** @private */
+    this._frames = 0;
+    /** @private */
+    this._accum = 0;
+    this.fps = 0;
+
+    /** @private */
+    this._frameTimes = [];
+    /** @private */
+    this._maxSamples = this._graph.width;
+    /** @private */
+    this._dtMs = 0;
+    /** @private */
+    this._minMs = 0;
+    /** @private */
+    this._maxMs = 0;
+    /** @private */
+    this._avgMs = 0;
+
+    /** @private */
+    this._metrics = {};
+    /** @private */
+    this._colliderScene = null;
+    /** @private */
+    this._collidersShown = false;
+  }
+
+  /**
+   * @method setMetric
+   * @description Adds/updates a custom metric line shown in the panel.
+   * @param {string} key
+   * @param {*} value
+   */
+  setMetric(key, value) {
+    this._metrics[key] = value;
+  }
+
+  /**
+   * @method update
+   * @description Updates the overlay. Pass the engine and current scene.
+   * @param {Emerald} emerald
+   * @param {Scene} scene
+   */
+  update(emerald, scene) {
+    const now = performance.now();
+    const dt = now - this._last;
+    this._last = now;
+    this._dtMs = dt;
+    this._accum += dt;
+    this._frames++;
+
+    this._frameTimes.push(dt);
+    if (this._frameTimes.length > this._maxSamples) this._frameTimes.shift();
+
+    if (this._accum >= 500) {
+      this.fps = Math.round((this._frames * 1000) / this._accum);
+      this._frames = 0;
+      this._accum = 0;
+
+      let min = Infinity;
+      let max = 0;
+      let sum = 0;
+      for (const t of this._frameTimes) {
+        if (t < min) min = t;
+        if (t > max) max = t;
+        sum += t;
+      }
+      this._minMs = min === Infinity ? 0 : min;
+      this._maxMs = max;
+      this._avgMs = this._frameTimes.length ? sum / this._frameTimes.length : 0;
+    }
+
+    const objectCount = scene && scene.objects ? scene.objects.length : 0;
+    const cameras = emerald && emerald.cameras ? emerald.cameras.length : 0;
+    let camLine = "";
+    if (emerald && emerald.camera && emerald.camera.getPosition) {
+      const p = emerald.camera.getPosition();
+      const z = emerald.camera.getZoom ? emerald.camera.getZoom() : 1;
+      camLine = `\ncam   ${p.x.toFixed(0)}, ${p.y.toFixed(0)}  zoom ${z.toFixed(2)}`;
+    }
+
+    let renderLines = "";
+    if (emerald && typeof emerald.getRenderStats === "function") {
+      const rs = emerald.getRenderStats();
+      renderLines =
+        `\ndraws ${rs.drawCalls}  quads ${rs.quads}` +
+        `\nbinds ${rs.textureBinds}`;
+    }
+
+    let memLine = "";
+    if (performance && performance.memory) {
+      const mb = performance.memory.usedJSHeapSize / (1024 * 1024);
+      memLine = `\nheap  ${mb.toFixed(1)} MB`;
+    }
+
+    let metricLines = "";
+    for (const key in this._metrics) {
+      metricLines += `\n${key.padEnd(5)} ${this._metrics[key]}`;
+    }
+
+    this._text.textContent =
+      `FPS    ${this.fps}` +
+      `\nframe  ${this._dtMs.toFixed(1)}ms` +
+      `\nmin/avg/max ${this._minMs.toFixed(1)}/${this._avgMs.toFixed(1)}/${this._maxMs.toFixed(1)}` +
+      `\nobjs   ${objectCount}` +
+      `\ncams   ${cameras}` +
+      renderLines +
+      camLine +
+      memLine +
+      metricLines;
+
+    this._drawGraph();
+  }
+
+  /** @private */
+  _drawGraph() {
+    const ctx = this._gctx;
+    const w = this._graph.width;
+    const h = this._graph.height;
+    ctx.clearRect(0, 0, w, h);
+    ctx.fillStyle = "rgba(255,255,255,0.05)";
+    ctx.fillRect(0, 0, w, h);
+
+    const scale = h / 50;
+    ctx.strokeStyle = "rgba(120,220,160,0.35)";
+    ctx.beginPath();
+    ctx.moveTo(0, h - 16.7 * scale);
+    ctx.lineTo(w, h - 16.7 * scale);
+    ctx.stroke();
+    ctx.strokeStyle = "rgba(220,180,120,0.3)";
+    ctx.beginPath();
+    ctx.moveTo(0, h - 33.3 * scale);
+    ctx.lineTo(w, h - 33.3 * scale);
+    ctx.stroke();
+
+    ctx.strokeStyle = "#7fdcff";
+    ctx.beginPath();
+    const n = this._frameTimes.length;
+    for (let i = 0; i < n; i++) {
+      const x = w - n + i;
+      const y = h - Math.min(h, this._frameTimes[i] * scale);
+      if (i === 0) ctx.moveTo(x, y);
+      else ctx.lineTo(x, y);
+    }
+    ctx.stroke();
+  }
+
+  /**
+   * @method showColliders
+   * @description Toggles physics collider debug shapes for every RigidBody in a
+   * scene's objects (uses the lazy debug shapes on each collider).
+   * @param {Scene} scene
+   * @param {boolean} show
+   */
+  showColliders(scene, show) {
+    this._collidersShown = show;
+    this._colliderScene = scene;
+    if (!scene || !scene.objects) return;
+    for (const obj of scene.objects) {
+      if (!obj.getComponent) continue;
+      const rb = obj.getComponent(RigidBody);
+      if (!rb) continue;
+      const collider = rb.getCollider();
+      if (!collider) continue;
+      if (show && typeof collider.showDebugShape === "function") {
+        collider.showDebugShape();
+      } else if (!show && typeof collider.hideDebugShape === "function") {
+        collider.hideDebugShape();
+      }
+    }
+  }
+
+  /**
+   * @method setVisible
+   * @param {boolean} visible
+   */
+  setVisible(visible) {
+    this.element.style.display = visible ? "block" : "none";
+  }
+
+  /**
+   * @method destroy
+   * @description Removes the overlay from the DOM.
+   */
+  destroy() {
+    if (this.element.parentNode) {
+      this.element.parentNode.removeChild(this.element);
+    }
+  }
+}
+
+export default DebugOverlay;