emeraldengine 2.2.1 → 3.0.0

package/src/Interpolator.js

@@ -0,0 +1,124 @@
+/**
+ * @class Interpolator
+ * @description Snapshot interpolation buffer for smoothing networked state.
+ * Authoritative updates arrive at a low, irregular rate (e.g. 10–20 Hz); this
+ * buffers timestamped snapshots and lets you sample a position "in the past" by
+ * a fixed render delay, so remote entities move smoothly between updates instead
+ * of teleporting.
+ *
+ * It is transport-agnostic and pure (no network/DOM dependency), so it works
+ * with the built-in NetworkManager, any other transport, or in tests.
+ *
+ * @example
+ * const interp = new Interpolator({ delay: 0.1 });
+ * // on each server update for an entity:
+ * interp.push(entityId, { x, y }, serverTimeSeconds);
+ * // each frame:
+ * const pos = interp.sample(entityId, nowSeconds); // { x, y } or null
+ */
+class Interpolator {
+  /**
+   * @param {Object} [options] - { delay = 0.1, maxBuffer = 60 }
+   */
+  constructor(options = {}) {
+    this.delay = options.delay ?? 0.1;
+    this.maxBuffer = options.maxBuffer ?? 60;
+    /** @private */
+    this._buffers = new Map();
+  }
+
+  /**
+   * @method push
+   * @description Records a snapshot for an entity at a given timestamp.
+   * @param {string|number} id - Entity id
+   * @param {Object} state - Any object with numeric fields to interpolate (e.g. {x,y})
+   * @param {number} time - Snapshot timestamp in seconds
+   */
+  push(id, state, time) {
+    let buf = this._buffers.get(id);
+    if (!buf) {
+      buf = [];
+      this._buffers.set(id, buf);
+    }
+    buf.push({ t: time, state });
+    if (buf.length > 1 && buf[buf.length - 2].t > time) {
+      buf.sort((a, b) => a.t - b.t);
+    }
+    if (buf.length > this.maxBuffer) buf.shift();
+  }
+
+  /**
+   * @method sample
+   * @description Returns the interpolated state for an entity at (now - delay).
+   * Linearly interpolates numeric fields between the two surrounding snapshots.
+   * Returns the latest snapshot if rendering ahead of the buffer, or null if no
+   * data exists.
+   * @param {string|number} id - Entity id
+   * @param {number} now - Current time in seconds
+   * @returns {Object|null} - Interpolated state, or null
+   */
+  sample(id, now) {
+    const buf = this._buffers.get(id);
+    if (!buf || buf.length === 0) return null;
+    const renderTime = now - this.delay;
+
+    if (renderTime <= buf[0].t) return { ...buf[0].state };
+    const last = buf[buf.length - 1];
+    if (renderTime >= last.t) return { ...last.state };
+
+    let a = buf[0];
+    let b = buf[buf.length - 1];
+    for (let i = 0; i < buf.length - 1; i++) {
+      if (buf[i].t <= renderTime && buf[i + 1].t >= renderTime) {
+        a = buf[i];
+        b = buf[i + 1];
+        break;
+      }
+    }
+
+    const span = b.t - a.t;
+    const k = span <= 0 ? 0 : (renderTime - a.t) / span;
+    const out = {};
+    for (const key in a.state) {
+      const av = a.state[key];
+      const bv = b.state[key];
+      out[key] =
+        typeof av === "number" && typeof bv === "number"
+          ? av + (bv - av) * k
+          : bv;
+    }
+    return out;
+  }
+
+  /**
+   * @method remove
+   * @description Drops an entity's buffer (e.g. when it leaves).
+   */
+  remove(id) {
+    this._buffers.delete(id);
+  }
+
+  /**
+   * @method prune
+   * @description Drops snapshots older than (now - delay - keep) to bound memory
+   * for long-lived entities.
+   * @param {number} now - Current time in seconds
+   * @param {number} [keep] - Extra history to retain past the render point
+   */
+  prune(now, keep = 1) {
+    const cutoff = now - this.delay - keep;
+    for (const buf of this._buffers.values()) {
+      while (buf.length > 2 && buf[0].t < cutoff) buf.shift();
+    }
+  }
+
+  /**
+   * @method clear
+   * @description Removes all buffered snapshots.
+   */
+  clear() {
+    this._buffers.clear();
+  }
+}
+
+export default Interpolator;

package/src/Material.js

@@ -0,0 +1,202 @@
+import { initShaderProgram } from "./GLUtils.js";
+import { STANDARD_VERTEX_SHADER } from "./Shaders.js";
+import GLManager from "./managers/GLManager.js";
+
+const MATERIAL_FRAGMENT_HEADER = `
+  #ifdef GL_ES
+  precision highp float;
+  #endif
+  varying highp vec2 vTexCoord;
+  varying vec2 vFragPos;
+  varying vec4 vInstanceColor;
+  uniform sampler2D uSampler;
+  uniform vec4 uColor;
+  uniform float uOpacity;
+  uniform float uTime;
+`;
+
+const MATERIAL_VERTEX_HEADER = `
+  attribute vec4 aVertexPosition;
+  attribute vec2 aTextureCoord;
+  uniform mat4 uProjectionMatrix;
+  uniform mat4 uModelViewMatrix;
+  uniform float uTime;
+  varying highp vec2 vTexCoord;
+  varying vec2 vFragPos;
+  varying vec4 vInstanceColor;
+`;
+
+/**
+ * @class Material
+ * @description A custom shader for a Drawable. By default it reuses the engine's
+ * standard vertex shader (so transforms, the camera, and instancing keep
+ * working) and only overrides the fragment program. Pass `options.vertex` to
+ * also supply a custom VERTEX program — the escape hatch for effects the fixed
+ * pipeline can't express (perspective tilt, vertex waves, billboarding, ...).
+ *
+ * The fragment shader always has: `vTexCoord`, `vFragPos`, `vInstanceColor`,
+ * `uSampler`, `uColor`, `uOpacity`, `uTime`. A custom vertex shader gets
+ * `aVertexPosition`, `aTextureCoord`, `uProjectionMatrix`, `uModelViewMatrix`,
+ * `uTime`, and must write `vTexCoord` + `gl_Position`.
+ *
+ * Declare extra uniforms and set them via `set(name, value)`. A uniform value
+ * may be a number, an array (vec2/3/4), or a FUNCTION — the function is called
+ * each draw and receives the Drawable currently rendering, so a single shared
+ * Material can read PER-OBJECT state (e.g. each card's own tilt angle).
+ *
+ * @example
+ * // Per-object 3D tilt with one shared material:
+ * const tilt = new Material(fragSrc, {
+ *   vertex: tiltVertexSrc,
+ *   uniforms: { uTiltX: (d) => d._tiltX || 0, uTiltY: (d) => d._tiltY || 0 },
+ * });
+ * cardA.setMaterial(tilt); cardB.setMaterial(tilt);
+ * cardA.getComponent(Texture)._tiltX = 0.3; // each object animates independently
+ */
+class Material {
+  /**
+   * @param {string} fragmentSource - Fragment shader body (declares void main)
+   * @param {Object} [options] - { vertex?: string, uniforms?: { name: value|function } }
+   */
+  constructor(fragmentSource, options = {}) {
+    const gl = GLManager.getGL();
+    this.gl = gl;
+
+    const vertexSource = options.vertex
+      ? MATERIAL_VERTEX_HEADER + options.vertex
+      : STANDARD_VERTEX_SHADER;
+
+    /** @private */
+    this._vertexSource = vertexSource;
+    /** @private */
+    this._fragmentSource = MATERIAL_FRAGMENT_HEADER + fragmentSource;
+
+    this.program = initShaderProgram(
+      gl,
+      this._vertexSource,
+      this._fragmentSource
+    );
+
+    this.programInfo = {
+      program: this.program,
+      attribLocations: {
+        vertexPosition: gl.getAttribLocation(this.program, "aVertexPosition"),
+        aTexCoord: gl.getAttribLocation(this.program, "aTextureCoord"),
+      },
+      uniformLocations: {
+        projectionMatrix: gl.getUniformLocation(
+          this.program,
+          "uProjectionMatrix"
+        ),
+        globalViewMatrix: gl.getUniformLocation(
+          this.program,
+          "uModelViewMatrix"
+        ),
+        useInstances: gl.getUniformLocation(this.program, "useInstances"),
+        uSampler: gl.getUniformLocation(this.program, "uSampler"),
+        color: gl.getUniformLocation(this.program, "uColor"),
+        uOpacity: gl.getUniformLocation(this.program, "uOpacity"),
+        uTime: gl.getUniformLocation(this.program, "uTime"),
+      },
+    };
+
+    this.uniforms = Object.assign({}, options.uniforms);
+    /** @private */
+    this._locCache = new Map();
+
+    GLManager.registerRestorable(this);
+  }
+
+  /**
+   * @method _restoreGL
+   * @description Recompiles the material's program and refreshes every cached
+   * location after a WebGL context loss.
+   * @private
+   */
+  _restoreGL() {
+    const gl = this.gl;
+    if (!gl) return;
+    this.program = initShaderProgram(
+      gl,
+      this._vertexSource,
+      this._fragmentSource
+    );
+    this._locCache.clear();
+    this.programInfo.program = this.program;
+    const a = this.programInfo.attribLocations;
+    a.vertexPosition = gl.getAttribLocation(this.program, "aVertexPosition");
+    a.aTexCoord = gl.getAttribLocation(this.program, "aTextureCoord");
+    const u = this.programInfo.uniformLocations;
+    u.projectionMatrix = gl.getUniformLocation(
+      this.program,
+      "uProjectionMatrix"
+    );
+    u.globalViewMatrix = gl.getUniformLocation(
+      this.program,
+      "uModelViewMatrix"
+    );
+    u.useInstances = gl.getUniformLocation(this.program, "useInstances");
+    u.uSampler = gl.getUniformLocation(this.program, "uSampler");
+    u.color = gl.getUniformLocation(this.program, "uColor");
+    u.uOpacity = gl.getUniformLocation(this.program, "uOpacity");
+    u.uTime = gl.getUniformLocation(this.program, "uTime");
+  }
+
+  /**
+   * @method set
+   * @description Sets (or schedules) a custom uniform value. Numbers, arrays
+   * (vec2/3/4), and functions returning those are supported. A function uniform
+   * receives the Drawable currently being rendered.
+   * @param {string} name - Uniform name
+   * @param {number|number[]|Function} value
+   * @returns {Material} - this
+   */
+  set(name, value) {
+    this.uniforms[name] = value;
+    return this;
+  }
+
+  /** @private */
+  _loc(name) {
+    if (!this._locCache.has(name)) {
+      this._locCache.set(name, this.gl.getUniformLocation(this.program, name));
+    }
+    return this._locCache.get(name);
+  }
+
+  /**
+   * @method applyCustomUniforms
+   * @description Uploads all user-declared uniforms. Called by Drawable each draw
+   * after the program is bound. Inferred by value shape. Function uniforms are
+   * called with the rendering Drawable so shared materials can read per-object data.
+   * @param {Drawable} [drawable] - The drawable currently rendering
+   */
+  applyCustomUniforms(drawable) {
+    const gl = this.gl;
+    for (const name in this.uniforms) {
+      let value = this.uniforms[name];
+      if (typeof value === "function") value = value(drawable);
+      const loc = this._loc(name);
+      if (loc == null) continue;
+      if (typeof value === "number") {
+        gl.uniform1f(loc, value);
+      } else if (Array.isArray(value) || value instanceof Float32Array) {
+        switch (value.length) {
+          case 2:
+            gl.uniform2fv(loc, value);
+            break;
+          case 3:
+            gl.uniform3fv(loc, value);
+            break;
+          case 4:
+            gl.uniform4fv(loc, value);
+            break;
+          default:
+            gl.uniform1fv(loc, value);
+        }
+      }
+    }
+  }
+}
+
+export default Material;

package/src/MathUtils.js

@@ -0,0 +1,133 @@
+/**
+ * @class MathUtils
+ * @description Common math helpers for games: interpolation, clamping, angle
+ * conversion, random ranges, and lightweight 2D vector operations that work on
+ * any `{ x, y }` object (including planck Vec2 and Emerald Vector2).
+ */
+class MathUtils {
+  /**
+   * Clamps a value to the [min, max] range.
+   */
+  static clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+  }
+
+  /**
+   * Linearly interpolates between a and b by t (t is not clamped).
+   */
+  static lerp(a, b, t) {
+    return a + (b - a) * t;
+  }
+
+  /**
+   * Inverse lerp: returns the t for which lerp(a, b, t) === value.
+   */
+  static inverseLerp(a, b, value) {
+    return a === b ? 0 : (value - a) / (b - a);
+  }
+
+  /**
+   * Remaps a value from one range to another.
+   */
+  static map(value, inMin, inMax, outMin, outMax) {
+    return MathUtils.lerp(
+      outMin,
+      outMax,
+      MathUtils.inverseLerp(inMin, inMax, value)
+    );
+  }
+
+  /**
+   * Converts degrees to radians.
+   */
+  static degToRad(degrees) {
+    return (degrees * Math.PI) / 180;
+  }
+
+  /**
+   * Converts radians to degrees.
+   */
+  static radToDeg(radians) {
+    return (radians * 180) / Math.PI;
+  }
+
+  /**
+   * Returns a random float in [min, max).
+   */
+  static randomRange(min, max) {
+    return min + Math.random() * (max - min);
+  }
+
+  /**
+   * Returns a random integer in [min, max] (inclusive).
+   */
+  static randomInt(min, max) {
+    return Math.floor(min + Math.random() * (max - min + 1));
+  }
+
+  /**
+   * Returns a random element of an array (or undefined if empty).
+   */
+  static randomChoice(array) {
+    return array.length
+      ? array[Math.floor(Math.random() * array.length)]
+      : undefined;
+  }
+
+  /**
+   * Euclidean distance between two `{ x, y }` points.
+   */
+  static distance(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+
+  /**
+   * Squared distance between two points (cheaper than distance for comparisons).
+   */
+  static distanceSquared(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return dx * dx + dy * dy;
+  }
+
+  /**
+   * Vector length (magnitude) of an `{ x, y }`.
+   */
+  static length(v) {
+    return Math.sqrt(v.x * v.x + v.y * v.y);
+  }
+
+  /**
+   * Returns a normalized copy of `{ x, y }` as a plain object. Zero-length
+   * vectors return { x: 0, y: 0 }.
+   */
+  static normalize(v) {
+    const len = MathUtils.length(v);
+    return len === 0 ? { x: 0, y: 0 } : { x: v.x / len, y: v.y / len };
+  }
+
+  /**
+   * Dot product of two `{ x, y }` vectors.
+   */
+  static dot(a, b) {
+    return a.x * b.x + a.y * b.y;
+  }
+
+  /**
+   * Angle in radians from a to b.
+   */
+  static angleBetween(a, b) {
+    return Math.atan2(b.y - a.y, b.x - a.x);
+  }
+
+  /**
+   * Linearly interpolates between two `{ x, y }` points, returning a plain object.
+   */
+  static lerpVector(a, b, t) {
+    return { x: MathUtils.lerp(a.x, b.x, t), y: MathUtils.lerp(a.y, b.y, t) };
+  }
+}
+
+export default MathUtils;