emeraldengine 2.2.1 → 3.1.0

package/src/managers/GLManager.js

@@ -56,10 +56,67 @@ class GLManager {
   static getCanvas() {
     return GLManager.canvas;
   }
+
+  /**
+   * @method registerRestorable
+   * @description Registers an object holding GL resources (buffers, textures,
+   * programs) for re-creation after a WebGL context loss. The object must
+   * implement `_restoreGL()`. Drawables register themselves automatically and
+   * unregister on dispose().
+   * @param {Object} obj - An object with a _restoreGL() method
+   */
+  static registerRestorable(obj) {
+    GLManager.restorables.add(obj);
+  }
+
+  /**
+   * @method unregisterRestorable
+   * @description Removes an object from the context-restore registry.
+   */
+  static unregisterRestorable(obj) {
+    GLManager.restorables.delete(obj);
+  }
+
+  /**
+   * @method restoreAll
+   * @description Calls _restoreGL() on every registered object. Invoked by
+   * Emerald after the context is restored and the default shaders/textures
+   * have been rebuilt.
+   */
+  static restoreAll() {
+    for (const obj of GLManager.restorables) {
+      try {
+        obj._restoreGL();
+      } catch (e) {
+        console.error("[GLManager] > restore failed for", obj, e);
+      }
+    }
+  }
+
+  /**
+   * @method setProjection
+   * @description Stores the current camera's projection matrix so custom
+   * Materials (which use their own shader program) can upload it.
+   * @param {Float32Array} matrix - The projection matrix
+   */
+  static setProjection(matrix) {
+    GLManager.projection = matrix;
+  }
+
+  /**
+   * @method getProjection
+   * @description Returns the last projection matrix set by the renderer.
+   * @returns {Float32Array}
+   */
+  static getProjection() {
+    return GLManager.projection;
+  }
 }
 
 GLManager.gl = null;
 GLManager.programInfo = null;
 GLManager.canvas = null;
+GLManager.projection = null;
+GLManager.restorables = new Set();
 
 export default GLManager;

package/src/managers/GLState.js

@@ -0,0 +1,70 @@
+/**
+ * @class GLState
+ * @description Tiny redundant-uniform filter. The renderer sets the same handful
+ * of per-object uniforms (useTexture, useInstances, useLighting, color, opacity)
+ * for every object every frame; most calls repeat the previous value. These
+ * helpers skip the GL call when the value is unchanged. Keyed by uniform
+ * location, which is program-specific, so the cache is safe across objects.
+ */
+class GLState {
+  /**
+   * @method reset
+   * @description Clears the cache. Called at the start of each frame so the
+   * first object always re-establishes state.
+   */
+  static reset() {
+    GLState.ints.clear();
+    GLState.floats.clear();
+    GLState.vec4s.clear();
+  }
+
+  /**
+   * @method uniform1i
+   * @description Cached gl.uniform1i (accepts booleans, coerced like WebGL does).
+   */
+  static uniform1i(gl, location, value) {
+    if (location == null) return;
+    const v = value === true ? 1 : value === false ? 0 : value;
+    if (GLState.ints.get(location) !== v) {
+      gl.uniform1i(location, v);
+      GLState.ints.set(location, v);
+    }
+  }
+
+  /**
+   * @method uniform1f
+   * @description Cached gl.uniform1f.
+   */
+  static uniform1f(gl, location, value) {
+    if (location == null) return;
+    if (GLState.floats.get(location) !== value) {
+      gl.uniform1f(location, value);
+      GLState.floats.set(location, value);
+    }
+  }
+
+  /**
+   * @method uniform4fv
+   * @description Cached gl.uniform4fv (compares the four components).
+   */
+  static uniform4fv(gl, location, value) {
+    if (location == null) return;
+    const cached = GLState.vec4s.get(location);
+    if (
+      !cached ||
+      cached[0] !== value[0] ||
+      cached[1] !== value[1] ||
+      cached[2] !== value[2] ||
+      cached[3] !== value[3]
+    ) {
+      gl.uniform4fv(location, value);
+      GLState.vec4s.set(location, [value[0], value[1], value[2], value[3]]);
+    }
+  }
+}
+
+GLState.ints = new Map();
+GLState.floats = new Map();
+GLState.vec4s = new Map();
+
+export default GLState;

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/IDManager.js

@@ -5,11 +5,22 @@
 class IDManager {
   /**
    * @method generateID
-   * @description Generates a random ID
+   * @description Generates a random ID, preferring the collision-resistant
+   * crypto.randomUUID when available and falling back to a random string.
    * @returns {string} - The random ID
    */
   static generateID() {
-    return Math.random().toString(36).substring(2, 10);
+    if (
+      typeof globalThis !== "undefined" &&
+      globalThis.crypto &&
+      typeof globalThis.crypto.randomUUID === "function"
+    ) {
+      return globalThis.crypto.randomUUID();
+    }
+    return (
+      Math.random().toString(36).substring(2, 10) +
+      Math.random().toString(36).substring(2, 10)
+    );
   }
 
   /**
@@ -25,6 +36,17 @@ class IDManager {
     IDManager.existingIDs.add(id);
     return id;
   }
+
+  /**
+   * @method release
+   * @description Releases a previously-generated ID so the global registry
+   * doesn't grow without bound. Call this when an object/instance is destroyed
+   * (e.g. particles removed from an InstancedTexture).
+   * @param {string} id - The ID to release
+   */
+  static release(id) {
+    if (id != null) IDManager.existingIDs.delete(id);
+  }
 }
 
 IDManager.existingIDs = new Set();