emeraldengine 3.0.0 → 3.1.0

package/src/managers/Gamepad.js

@@ -0,0 +1,126 @@
+/**
+ * @class Gamepad
+ * @description An autocomplete-friendly way to build the raw gamepad token
+ * strings InputManager already understands ("pad:0:south", etc.). It does
+ * not read input itself, and it is unrelated to the browser's own native
+ * `Gamepad` interface (the objects `navigator.getGamepads()` returns). It
+ * exists purely so you don't have to remember button-name spelling: every
+ * button/stick-direction name InputManager's standard mapping recognizes is
+ * a static constant here, so typing `Gamepad.` in an editor lists them the
+ * way an enum's members would.
+ *
+ * `Gamepad.get(index).key(name)` produces exactly the same string as writing
+ * the token by hand, so the two are fully interchangeable anywhere
+ * InputManager takes one: `mapAction`, `isDown`, `justPressed`,
+ * `justReleased`.
+ *
+ * @example
+ * import { Gamepad, InputManager } from "./index.js";
+ *
+ * const input = new InputManager();
+ * const pad = Gamepad.get(0); // the first controller
+ *
+ * input.mapAction("jump", [pad.key(Gamepad.SOUTH)]);
+ * input.mapAction("left", [pad.key(Gamepad.DPAD_LEFT), pad.key(Gamepad.LEFT_STICK_LEFT)]);
+ *
+ * // in the loop:
+ * if (input.justPressed("jump")) player.jump();
+ */
+class Gamepad {
+  /**
+   * @method get
+   * @description Returns the (cached) handle for a pad index: 0 for the
+   * first controller, 1 for the second, and so on.
+   * @param {number} [index=0]
+   * @returns {Gamepad}
+   */
+  static get(index = 0) {
+    let pad = Gamepad._instances.get(index);
+    if (!pad) {
+      pad = new Gamepad(index);
+      Gamepad._instances.set(index, pad);
+    }
+    return pad;
+  }
+
+  /**
+   * @private Use `Gamepad.get(index)` rather than constructing directly, so
+   * every caller asking for the same pad index shares one instance.
+   */
+  constructor(index) {
+    this.index = index;
+  }
+
+  /**
+   * @method key
+   * @description A face/shoulder/centre/d-pad/stick-as-button token for this
+   * pad. Pass one of the `Gamepad.*` constants (`Gamepad.SOUTH`,
+   * `Gamepad.DPAD_UP`, …). InputManager's standard mapping also accepts a
+   * few vendor aliases these don't cover (e.g. "a", "cross" for `SOUTH`) if
+   * you'd rather think in Xbox/PlayStation terms; those still work as plain
+   * strings, `key()` just doesn't need to name them since `SOUTH` already
+   * reads the same on every pad.
+   * @param {string} name - One of the `Gamepad.*` button constants
+   * @returns {string}
+   */
+  key(name) {
+    return `pad:${this.index}:${name}`;
+  }
+
+  /**
+   * @method button
+   * @description A raw button index, mapping-independent: an escape hatch
+   * for a pad whose layout the standard/custom mapping tables don't cover.
+   * @param {number} n
+   * @returns {string}
+   */
+  button(n) {
+    return `pad:${this.index}:${n}`;
+  }
+
+  /**
+   * @method axis
+   * @description A raw analog axis past the deadzone, in one direction.
+   * @param {number} n - Axis index (0/1 = left stick X/Y, 2/3 = right stick X/Y on a standard pad)
+   * @param {"+"|"-"} [sign="+"]
+   * @returns {string}
+   */
+  axis(n, sign = "+") {
+    return `pad:${this.index}:axis${n}${sign}`;
+  }
+}
+
+Gamepad._instances = new Map();
+
+Gamepad.SOUTH = "south";
+Gamepad.EAST = "east";
+Gamepad.WEST = "west";
+Gamepad.NORTH = "north";
+
+Gamepad.L1 = "l1";
+Gamepad.R1 = "r1";
+Gamepad.L2 = "l2";
+Gamepad.R2 = "r2";
+
+Gamepad.SELECT = "select";
+Gamepad.START = "start";
+Gamepad.HOME = "home";
+
+Gamepad.L3 = "l3";
+Gamepad.R3 = "r3";
+
+Gamepad.DPAD_UP = "dpadUp";
+Gamepad.DPAD_DOWN = "dpadDown";
+Gamepad.DPAD_LEFT = "dpadLeft";
+Gamepad.DPAD_RIGHT = "dpadRight";
+
+Gamepad.LEFT_STICK_UP = "leftStickUp";
+Gamepad.LEFT_STICK_DOWN = "leftStickDown";
+Gamepad.LEFT_STICK_LEFT = "leftStickLeft";
+Gamepad.LEFT_STICK_RIGHT = "leftStickRight";
+Gamepad.RIGHT_STICK_UP = "rightStickUp";
+Gamepad.RIGHT_STICK_DOWN = "rightStickDown";
+Gamepad.RIGHT_STICK_LEFT = "rightStickLeft";
+Gamepad.RIGHT_STICK_RIGHT = "rightStickRight";
+
+export default Gamepad;

package/src/managers/InputManager.js

@@ -173,10 +173,10 @@ for (const b of BUILTIN_MAPPINGS) {
  * gamepad support (analog sticks/triggers, semantic button names, rumble,
  * connect events, and per-controller mapping), with rebindable named actions.
  * Call `update()` once per frame so `justPressed`/`justReleased` edge queries
- * work for every device — including the gamepad.
+ * work for every device, including the gamepad.
  *
  * Gamepad tokens (usable anywhere a key token is, including in mapAction and
- * justPressed) — `<i>` is the pad index:
+ * justPressed); `<i>` is the pad index:
  *   "pad:<i>:south" / "pad:<i>:a"      - face buttons (also east/b, west/x, north/y)
  *   "pad:<i>:l1" / "pad:<i>:r2" ...    - shoulders / triggers
  *   "pad:<i>:start" / "pad:<i>:select" - center buttons
@@ -189,6 +189,11 @@ for (const b of BUILTIN_MAPPINGS) {
  * Names resolve through the active mapping, so "pad:0:south" is the bottom face
  * button regardless of whether the pad reports Xbox or PlayStation ordering.
  *
+ * Typing these by hand means remembering the exact spelling of every button
+ * name above; {@link Gamepad} builds the same strings from named constants
+ * instead (`Gamepad.get(0).key(Gamepad.SOUTH)` === "pad:0:south"), which most
+ * editors will autocomplete the way an enum's members would.
+ *
  * @example
  * const input = new InputManager();
  * input.mapAction("jump", ["Space", " ", "pad:0:south"]);
@@ -245,15 +250,28 @@ class InputManager {
     this._disconnectHandlers = [];
     /** @private */
     this._connected = new Map();
+    /**
+     * Which device last produced real input: "keyboard", "mouse",
+     * "gamepad", "touch", or null before anything has happened yet. See
+     * {@link getLastActiveDevice}.
+     * @private
+     */
+    this._lastActiveDevice = null;
+    /** Pending {@link identifyButton} calls, resolved from `update()`. @private */
+    this._buttonWaiters = [];
 
     /** @private */
-    this._onKeyDown = (e) => this.down.add(this._normKey(e.key));
+    this._onKeyDown = (e) => {
+      this.down.add(this._normKey(e.key));
+      this._lastActiveDevice = "keyboard";
+    };
     /** @private */
     this._onKeyUp = (e) => this.down.delete(this._normKey(e.key));
     /** @private */
     this._onMouseDown = (e) => {
       this.down.add(`mouse:${e.button}`);
       this.mouse.buttons.add(e.button);
+      this._lastActiveDevice = "mouse";
     };
     /** @private */
     this._onMouseUp = (e) => {
@@ -272,6 +290,7 @@ class InputManager {
         y: t.clientY,
         id: t.identifier,
       }));
+      this._lastActiveDevice = "touch";
     };
     /** @private */
     this._onGamepadConnected = (e) => {
@@ -636,6 +655,30 @@ class InputManager {
     return !!this.gamepads[padIndex];
   }
 
+  /**
+   * @method getLastActiveDevice
+   * @description Which device the player most recently *actually used*,
+   * not just "is a gamepad plugged in" (see `isGamepadConnected`, which stays
+   * true all game long once one is), but "did they just press a key, click,
+   * touch, or move a gamepad button/stick". A pad being connected doesn't
+   * mean it's what's driving the game right now; this is the signal for
+   * swapping on-screen prompts between keyboard and gamepad button icons as
+   * the player actually switches between them mid-session.
+   *
+   * Only counts deliberate input: keydown, mousedown, and touch, not
+   * incidental mouse movement, so idly nudging the mouse while playing on a
+   * pad won't flip prompts back to keyboard/mouse.
+   *
+   * @example
+   * // once per frame, after input.update():
+   * hud.setPromptStyle(input.getLastActiveDevice() === "gamepad" ? "pad" : "keyboard");
+   *
+   * @returns {"keyboard"|"mouse"|"gamepad"|"touch"|null} - null before any input at all
+   */
+  getLastActiveDevice() {
+    return this._lastActiveDevice;
+  }
+
   /**
    * @method getPressedButtons
    * @description Diagnostic: raw indices of all currently pressed buttons on a
@@ -655,6 +698,71 @@ class InputManager {
     return out;
   }
 
+  /**
+   * @method identifyButton
+   * @description Resolves with the raw index of the next *new* button press
+   * on a pad: the reliable way to support a controller whose layout isn't
+   * already covered by the standard/registered mapping tables (a Steam
+   * Controller running outside Steam Input, an old flight stick, anything
+   * with a scrambled button order), instead of guessing indices: ask for one
+   * physical press and record wherever it actually lands on that specific
+   * device. Keep calling `update()` as normal while waiting; the promise
+   * resolves on the frame a button transitions from up to down. A button
+   * already held when this is called doesn't count; only a fresh press does.
+   *
+   * @example
+   * console.log("Press the button you want for Jump…");
+   * const index = await input.identifyButton(0);
+   * InputManager.registerGamepadMapping(input.getGamepadInfo(0).id, {
+   *   buttons: { south: index },
+   * });
+   *
+   * @param {number} [padIndex=0]
+   * @returns {Promise<number>} - Never resolves if no new button is ever pressed
+   */
+  identifyButton(padIndex = 0) {
+    return new Promise((resolve) => {
+      this._buttonWaiters.push({
+        padIndex,
+        before: new Set(this.getPressedButtons(padIndex)),
+        resolve,
+      });
+    });
+  }
+
+  /**
+   * @method calibrateGamepad
+   * @description Walks a list of semantic button names one at a time, asking
+   * for a physical press for each (see {@link identifyButton}), and resolves
+   * with a `{name: rawIndex}` map ready to hand straight to
+   * `InputManager.registerGamepadMapping`, a complete fix for an oddball
+   * controller in a few seconds, without knowing anything about its layout
+   * in advance.
+   *
+   * @example
+   * const mapping = await input.calibrateGamepad(
+   *   0,
+   *   ["south", "east", "west", "north", "l1", "r1", "start"],
+   *   (name, i, total) => showPrompt(`(${i + 1}/${total}) Press the button for "${name}"`)
+   * );
+   * InputManager.registerGamepadMapping(input.getGamepadInfo(0).id, { buttons: mapping });
+   *
+   * @param {number} padIndex
+   * @param {string[]} names - Semantic names to calibrate, e.g. ["south", "east", "start"]
+   * @param {(name: string, index: number, total: number) => void} [onPrompt] -
+   *   Called right before waiting for each name, so you can show "press ___" UI
+   * @returns {Promise<Object.<string, number>>} - { [name]: rawButtonIndex }
+   */
+  async calibrateGamepad(padIndex, names, onPrompt) {
+    const mapping = {};
+    for (let i = 0; i < names.length; i++) {
+      const name = names[i];
+      if (onPrompt) onPrompt(name, i, names.length);
+      mapping[name] = await this.identifyButton(padIndex);
+    }
+    return mapping;
+  }
+
   /**
    * @method _decodeHat
    * @description Some non-standard pads report the d-pad as an 8-way "hat" on a
@@ -749,6 +857,24 @@ class InputManager {
     for (const t of this._gamepadTokens) this.down.delete(t);
     this._collectGamepadTokens();
     for (const t of this._gamepadTokens) this.down.add(t);
+    if (this._gamepadTokens.size > 0) this._lastActiveDevice = "gamepad";
+    if (this._buttonWaiters.length) this._resolveButtonWaiters();
+  }
+
+  /**
+   * @method _resolveButtonWaiters
+   * @description Resolves any {@link identifyButton} calls whose pad just
+   * saw a button go from up to down.
+   * @private
+   */
+  _resolveButtonWaiters() {
+    this._buttonWaiters = this._buttonWaiters.filter((waiter) => {
+      const now = this.getPressedButtons(waiter.padIndex);
+      const fresh = now.find((b) => !waiter.before.has(b));
+      if (fresh == null) return true;
+      waiter.resolve(fresh);
+      return false;
+    });
   }
 
   /**

package/src/managers/NetworkManager.js

@@ -4,7 +4,7 @@ import Interpolator from "../Interpolator.js";
  * @class NetworkManager
  * @description A thin, optional multiplayer layer over Colyseus. `colyseus.js`
  * is an optional peer dependency and is imported dynamically, so the engine has
- * no hard dependency on it — games that don't use networking never load it.
+ * no hard dependency on it, so games that don't use networking never load it.
  *
  * It wraps connection/room lifecycle, exposes a small event API
  * (onStateChange / onMessage / onAdd / onRemove / onLeave), and bundles an
@@ -140,7 +140,7 @@ class NetworkManager {
 
   /**
    * @method now
-   * @description Seconds since this manager was created — a convenient clock for
+   * @description Seconds since this manager was created, a convenient clock for
    * feeding the interpolator.
    * @returns {number}
    */

package/src/managers/RenderStats.js

@@ -3,7 +3,7 @@
  * @description Frame-level render counters, incremented by every draw site in
  * the engine (Drawable, InstancedTexture, SpriteBatch, post-processing) and
  * reset at the start of each drawScene. Read the previous completed frame via
- * `RenderStats.frame` or `emerald.getRenderStats()` — DebugOverlay shows it
+ * `RenderStats.frame` or `emerald.getRenderStats()`. DebugOverlay shows it
  * automatically.
  *
  * - drawCalls:    GPU draw commands issued (the batching win shows up here)

package/src/managers/TextureManager.js

@@ -102,7 +102,7 @@ class TextureManager {
    * @method restoreAll
    * @description Re-uploads every cached texture after a WebGL context loss.
    * The image cache survives the loss, so this is upload-only (no network).
-   * Reference counts are untouched — they track logical ownership by
+   * Reference counts are untouched: they track logical ownership by
    * drawables, which still exist.
    */
   static restoreAll() {

package/src/physics/AABB.js

@@ -0,0 +1,207 @@
+import { Vec2 } from "./Math2D.js";
+
+/**
+ * @class AABB
+ * @description An axis-aligned bounding box in physics space. Used by the
+ * broadphase to reject pairs long before any real collision maths runs.
+ */
+class AABB {
+  constructor(lowerX = 0, lowerY = 0, upperX = 0, upperY = 0) {
+    this.lowerBound = new Vec2(lowerX, lowerY);
+    this.upperBound = new Vec2(upperX, upperY);
+  }
+
+  /**
+   * @method set
+   * @description Sets all four bounds in place.
+   * @param {number} lx
+   * @param {number} ly
+   * @param {number} ux
+   * @param {number} uy
+   * @returns {AABB} - this
+   */
+  set(lx, ly, ux, uy) {
+    this.lowerBound.set(lx, ly);
+    this.upperBound.set(ux, uy);
+    return this;
+  }
+
+  /**
+   * @method copy
+   * @description Copies another AABB.
+   * @param {AABB} other
+   * @returns {AABB} - this
+   */
+  copy(other) {
+    this.lowerBound.copy(other.lowerBound);
+    this.upperBound.copy(other.upperBound);
+    return this;
+  }
+
+  /**
+   * @method getCenter
+   * @description Returns the box center.
+   * @returns {Vec2}
+   */
+  getCenter() {
+    return new Vec2(
+      0.5 * (this.lowerBound.x + this.upperBound.x),
+      0.5 * (this.lowerBound.y + this.upperBound.y)
+    );
+  }
+
+  /**
+   * @method getExtents
+   * @description Returns the box half-extents.
+   * @returns {Vec2}
+   */
+  getExtents() {
+    return new Vec2(
+      0.5 * (this.upperBound.x - this.lowerBound.x),
+      0.5 * (this.upperBound.y - this.lowerBound.y)
+    );
+  }
+
+  /**
+   * @method getPerimeter
+   * @description Perimeter of the box, the cost function the AABB tree
+   * minimizes when choosing where to insert a leaf.
+   * @returns {number}
+   */
+  getPerimeter() {
+    return (
+      2 *
+      (this.upperBound.x -
+        this.lowerBound.x +
+        (this.upperBound.y - this.lowerBound.y))
+    );
+  }
+
+  /**
+   * @method combine
+   * @description Sets this box to the union of two others.
+   * @param {AABB} a
+   * @param {AABB} b
+   * @returns {AABB} - this
+   */
+  combine(a, b) {
+    this.lowerBound.x = Math.min(a.lowerBound.x, b.lowerBound.x);
+    this.lowerBound.y = Math.min(a.lowerBound.y, b.lowerBound.y);
+    this.upperBound.x = Math.max(a.upperBound.x, b.upperBound.x);
+    this.upperBound.y = Math.max(a.upperBound.y, b.upperBound.y);
+    return this;
+  }
+
+  /**
+   * @method extend
+   * @description Grows the box by `amount` on every side.
+   * @param {number} amount
+   * @returns {AABB} - this
+   */
+  extend(amount) {
+    this.lowerBound.x -= amount;
+    this.lowerBound.y -= amount;
+    this.upperBound.x += amount;
+    this.upperBound.y += amount;
+    return this;
+  }
+
+  /**
+   * @method contains
+   * @description True when `other` lies entirely inside this box.
+   * @param {AABB} other
+   * @returns {boolean}
+   */
+  contains(other) {
+    return (
+      this.lowerBound.x <= other.lowerBound.x &&
+      this.lowerBound.y <= other.lowerBound.y &&
+      other.upperBound.x <= this.upperBound.x &&
+      other.upperBound.y <= this.upperBound.y
+    );
+  }
+
+  /**
+   * @method containsPoint
+   * @description True when a point lies inside this box.
+   * @param {Object} p - `{ x, y }`
+   * @returns {boolean}
+   */
+  containsPoint(p) {
+    return (
+      this.lowerBound.x <= p.x &&
+      p.x <= this.upperBound.x &&
+      this.lowerBound.y <= p.y &&
+      p.y <= this.upperBound.y
+    );
+  }
+
+  /**
+   * @method testOverlap
+   * @description True when two boxes overlap.
+   * @param {AABB} a
+   * @param {AABB} b
+   * @returns {boolean}
+   */
+  static testOverlap(a, b) {
+    return !(
+      b.lowerBound.x - a.upperBound.x > 0 ||
+      b.lowerBound.y - a.upperBound.y > 0 ||
+      a.lowerBound.x - b.upperBound.x > 0 ||
+      a.lowerBound.y - b.upperBound.y > 0
+    );
+  }
+
+  /**
+   * @method rayCast
+   * @description Slab test of a ray against this box.
+   * @param {Object} input - `{ p1, p2, maxFraction }`
+   * @returns {boolean} - True if the ray hits the box within maxFraction
+   */
+  rayCast(input) {
+    let tmin = -Number.MAX_VALUE;
+    let tmax = Number.MAX_VALUE;
+
+    const p = input.p1;
+    const dx = input.p2.x - input.p1.x;
+    const dy = input.p2.y - input.p1.y;
+    const absDx = Math.abs(dx);
+    const absDy = Math.abs(dy);
+
+    if (absDx < 1e-12) {
+      if (p.x < this.lowerBound.x || this.upperBound.x < p.x) return false;
+    } else {
+      const invD = 1 / dx;
+      let t1 = (this.lowerBound.x - p.x) * invD;
+      let t2 = (this.upperBound.x - p.x) * invD;
+      if (t1 > t2) {
+        const t = t1;
+        t1 = t2;
+        t2 = t;
+      }
+      tmin = Math.max(tmin, t1);
+      tmax = Math.min(tmax, t2);
+      if (tmin > tmax) return false;
+    }
+
+    if (absDy < 1e-12) {
+      if (p.y < this.lowerBound.y || this.upperBound.y < p.y) return false;
+    } else {
+      const invD = 1 / dy;
+      let t1 = (this.lowerBound.y - p.y) * invD;
+      let t2 = (this.upperBound.y - p.y) * invD;
+      if (t1 > t2) {
+        const t = t1;
+        t1 = t2;
+        t2 = t;
+      }
+      tmin = Math.max(tmin, t1);
+      tmax = Math.min(tmax, t2);
+      if (tmin > tmax) return false;
+    }
+
+    return tmax >= 0 && tmin <= (input.maxFraction ?? 1);
+  }
+}
+
+export default AABB;