@woosh/meep-engine 2.126.64 → 2.126.66

package/package.json

@@ -5,7 +5,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.126.64",
+  "version": "2.126.66",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/math/spline/spline3_hermite.js

@@ -19,7 +19,7 @@ export function spline3_hermite(t, p0, p1, m0, m1) {
     const a = 2 * t3 - 3 * t2 + 1;
     const b = t3 - 2 * t2 + t;
     const c = t3 - t2;
-    const d = -2 * t3 + 3 * t2;
+    const d = 3 * t2 - 2 * t3;
 
     return a * p0 + b * m0 + c * m1 + d * p1;
 }

package/src/core/math/spline/spline3_hermite_nearest_point.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Finds the parameter 't' of the nearest point on a 1D Hermite spline
+ * function graph to a reference point. The curve is defined by (t, p(t)).
+ * This version is optimized to avoid allocations.
+ *
+ * @param {number} ref_t - The 't' coordinate of the reference point.
+ * @param {number} ref_p - The 'p' coordinate of the reference point.
+ * @param {number} p0 - The start value of the spline (at t=0).
+ * @param {number} p1 - The end value of the spline (at t=1).
+ * @param {number} m0 - The tangent at the start.
+ * @param {number} m1 - The tangent at the end.
+ * @returns {number} The parameter 't' of the nearest point. This value is always in [0..1] range
+ */
+export function spline3_hermite_nearest_point(ref_t: number, ref_p: number, p0: number, p1: number, m0: number, m1: number): number;
+//# sourceMappingURL=spline3_hermite_nearest_point.d.ts.map

package/src/core/math/spline/spline3_hermite_nearest_point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_nearest_point.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_nearest_point.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;GAYG;AACH,qDARW,MAAM,SACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAuFlB"}

package/src/core/math/spline/spline3_hermite_nearest_point.js

@@ -0,0 +1,124 @@
+import { spline3_hermite } from "./spline3_hermite.js";
+
+/**
+ * Helper to evaluate a polynomial given its coefficients.
+ * @param {Float32Array} p - Polynomial coefficients [c0, c1, c2, ...]
+ * @param {number} t - The value at which to evaluate.
+ * @param {number} size
+ * @returns {number}
+ */
+function polyval(p, t, size) {
+    let result = 0;
+
+    for (let i = size - 1; i >= 0; i--) {
+        result = result * t + p[i];
+    }
+
+    return result;
+}
+
+const quintic_coeffs = new Float32Array(6);
+const quartic_coeffs = new Float32Array(5);
+
+const NEWTON_STEPS = 3;
+const START_ROOT_COUNT = 5;
+
+/**
+ * Finds the parameter 't' of the nearest point on a 1D Hermite spline
+ * function graph to a reference point. The curve is defined by (t, p(t)).
+ * This version is optimized to avoid allocations.
+ *
+ * @param {number} ref_t - The 't' coordinate of the reference point.
+ * @param {number} ref_p - The 'p' coordinate of the reference point.
+ * @param {number} p0 - The start value of the spline (at t=0).
+ * @param {number} p1 - The end value of the spline (at t=1).
+ * @param {number} m0 - The tangent at the start.
+ * @param {number} m1 - The tangent at the end.
+ * @returns {number} The parameter 't' of the nearest point. This value is always in [0..1] range
+ */
+export function spline3_hermite_nearest_point(
+    ref_t, ref_p,
+    p0, p1, m0, m1
+) {
+
+    // 1. Calculate polynomial coefficients A, B, C for p(t)
+    const A = 2 * p0 - 2 * p1 + m0 + m1;
+    const B = -3 * p0 + 3 * p1 - 2 * m0 - m1;
+    const C = m0;
+    const D_minus_Rp = p0 - ref_p;
+
+    // 2. Form the quintic polynomial f(t) = c5*t^5 + ... + c0
+
+    quintic_coeffs[0] = (C * D_minus_Rp - ref_t)
+    quintic_coeffs[1] = (C * C + 2 * B * D_minus_Rp + 1)
+    quintic_coeffs[2] = (3 * B * C + 3 * A * D_minus_Rp)
+    quintic_coeffs[3] = (4 * A * C + 2 * B * B)
+    quintic_coeffs[4] = (5 * A * B)
+    quintic_coeffs[5] = (3 * A * A)
+
+    // Derivative of the quintic (a quartic) for Newton's method
+
+    quartic_coeffs[0] = quintic_coeffs[1]
+    quartic_coeffs[1] = 2 * quintic_coeffs[2]
+    quartic_coeffs[2] = 3 * quintic_coeffs[3]
+    quartic_coeffs[3] = 4 * quintic_coeffs[4]
+    quartic_coeffs[4] = 5 * quintic_coeffs[5]
+
+
+    // 3. Initialize by checking the endpoints t=0 and t=1
+    let best_t = 0;
+    let dt = 0 - ref_t;
+    let dp = p0 - ref_p;
+    let min_dist_sq = dt * dt + dp * dp;
+
+    dt = 1 - ref_t;
+    dp = p1 - ref_p;
+    const dist_sq_at_1 = dt * dt + dp * dp;
+    if (dist_sq_at_1 < min_dist_sq) {
+        min_dist_sq = dist_sq_at_1;
+        best_t = 1;
+    }
+
+    // 4. Find roots and check them on the fly
+    const tolerance = 1e-7;
+
+
+    // Start Newton's method from several points to find multiple roots
+    for (let i = 0; i <= START_ROOT_COUNT; i++) {
+        let t = i / START_ROOT_COUNT; // Starting guess for the root
+
+        for (let j = NEWTON_STEPS; j > 0; j--) {
+
+            const f_t = polyval(quintic_coeffs, t, 6);
+            const fp_t = polyval(quartic_coeffs, t, 5);
+
+            if (Math.abs(fp_t) < tolerance) {
+                break;
+            }
+
+            const t_new = t - f_t / fp_t;
+
+            if (Math.abs(t_new - t) < tolerance) {
+                break;
+            }
+
+            t = t_new;
+        }
+
+        // Check if the found root is valid and yields a better distance
+        if (t > 0 && t < 1) {
+            // Endpoints already checked
+            const p = spline3_hermite(t, p0, p1, m0, m1);
+            const current_dt = t - ref_t;
+            const current_dp = p - ref_p;
+            const dist_sq = current_dt * current_dt + current_dp * current_dp;
+
+            if (dist_sq < min_dist_sq) {
+                min_dist_sq = dist_sq;
+                best_t = t;
+            }
+        }
+    }
+
+    return best_t;
+}

package/src/engine/animation/curve/AnimationCurve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;GAgBG;AACH;IAkXI;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;OAQG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAYzB;IAjbD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAiClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CA0ClB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAmChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAWhB;IAED,0BAKC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAeC;IAsEL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;CARxC;yBAhdwB,eAAe"}
+{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;GAgBG;AACH;IAkXI;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;OAQG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAezB;IApbD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAiClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CA0ClB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAmChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAWhB;IAED,0BAKC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAeC;IAyEL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;CARxC;yBAndwB,eAAe"}

package/src/engine/animation/curve/AnimationCurve.js

@@ -464,7 +464,10 @@ export class AnimationCurve {
         timeStart = 0, valueStart = 0,
         timeEnd = 1, valueEnd = 1
     ) {
-        const tangent = valueEnd - valueStart;
+        const time_delta = timeEnd - timeStart;
+
+        // tangent needs to be normalized
+        const tangent = time_delta === 0 ? 0 : (valueEnd - valueStart) / time_delta;
 
         return AnimationCurve.from([
             Keyframe.from(timeStart, valueStart, 0, tangent),

package/src/engine/animation/curve/Keyframe.js

@@ -120,7 +120,7 @@ export class Keyframe {
      */
     hash() {
         return computeHashFloat(this.time)
-            ^ computeHashFloat(this.value);
+            ^ (computeHashFloat(this.value) * 31);
     }
 
     toJSON() {

package/src/engine/animation/curve/animation_curve_nearest_point.d.ts

@@ -0,0 +1,13 @@
+/**
+ * NOTE: this operation has O(n) complexity, where n is the number of keys in the curve.
+ * @param {AnimationCurve} curve
+ * @param {number} ref_time
+ * @param {number} ref_value
+ * @returns {number} time of the nearest point on the curve
+ * @see AnimationCurve
+ * @example
+ *      const nearest_time = animation_curve_nearest_point(curve, 0.5, 10);
+ *      const nearest_value = curve.evaluate(nearest_time);
+ */
+export function animation_curve_nearest_point(curve: AnimationCurve, ref_time: number, ref_value: number): number;
+//# sourceMappingURL=animation_curve_nearest_point.d.ts.map

package/src/engine/animation/curve/animation_curve_nearest_point.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation_curve_nearest_point.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_nearest_point.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH,+EARW,MAAM,aACN,MAAM,GACJ,MAAM,CA2DlB"}

package/src/engine/animation/curve/animation_curve_nearest_point.js

@@ -0,0 +1,71 @@
+import { v2_distance_sqr } from "../../../core/geom/vec2/v2_distance_sqr.js";
+import { inverseLerp } from "../../../core/math/inverseLerp.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { spline3_hermite } from "../../../core/math/spline/spline3_hermite.js";
+import { spline3_hermite_nearest_point } from "../../../core/math/spline/spline3_hermite_nearest_point.js";
+
+/**
+ * NOTE: this operation has O(n) complexity, where n is the number of keys in the curve.
+ * @param {AnimationCurve} curve
+ * @param {number} ref_time
+ * @param {number} ref_value
+ * @returns {number} time of the nearest point on the curve
+ * @see AnimationCurve
+ * @example
+ *      const nearest_time = animation_curve_nearest_point(curve, 0.5, 10);
+ *      const nearest_value = curve.evaluate(nearest_time);
+ */
+export function animation_curve_nearest_point(curve, ref_time, ref_value) {
+
+    const keys = curve.keys;
+    const key_count = keys.length;
+
+    if (key_count === 0) {
+        // special case: empty curve
+        return ref_time;
+    }
+
+    if (key_count === 1) {
+        // special case: single key
+        return keys[0].time;
+    }
+
+    let nearest_time = keys[0].time;
+    let nearest_value = keys[0].value;
+    let nearest_distance_sqr = v2_distance_sqr(nearest_time, nearest_value, ref_time, ref_value);
+
+    for (let i = 0; i <= key_count - 2; i++) {
+        const key0 = keys[i];
+        const key1 = keys[i + 1];
+
+        const time_delta = key1.time - key0.time;
+
+        // Normalize reference time to the segment's [0, 1] space
+        const ref_t = inverseLerp(key0.time, key1.time, ref_time);
+
+        // Scale tangents by the segment duration
+        const m0 = key0.outTangent * time_delta;
+        const m1 = key1.inTangent * time_delta;
+
+        const t = spline3_hermite_nearest_point(
+            ref_t, ref_value,
+            key0.value, key1.value,
+            m0, m1
+        );
+
+        // De-normalize the resulting time back to the global timeline
+        const curve_time = lerp(key0.time, key1.time, t);
+        const curve_value = spline3_hermite(t, key0.value, key1.value, m0, m1);
+
+        const distance_sqr = v2_distance_sqr(curve_time, curve_value, ref_time, ref_value);
+
+        if (distance_sqr < nearest_distance_sqr) {
+            nearest_time = curve_time;
+            nearest_value = curve_value;
+            nearest_distance_sqr = distance_sqr;
+        }
+
+    }
+
+    return nearest_time;
+}

package/src/engine/animation/curve/animation_curve_subdivide.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Subdivide a curve segment by introducing a new keyframe at a given normalized time.
+ * Subdivision does not alter the curve shape in any way, it is intended primarily for editing purposes.
+ * @param {Keyframe} out keyframe to be added at the point of subdivision, its tangents, time and value will be overwritten
+ * @param {Keyframe} key0
+ * @param {Keyframe} key1
+ * @param {number} t normalized time in [0..1] between key0 and key1 where new frame is to be inserted
+ * @returns {Keyframe} `out`, for convenience
+ * @see AnimationCurve
+ * @example
+ *  const new_frame = animation_curve_subdivide(new Keyframe(), key0, key1, 0.5);
+ *  curve.add(new_frame);
+ */
+export function animation_curve_subdivide(out: Keyframe, key0: Keyframe, key1: Keyframe, t: number): Keyframe;
+//# sourceMappingURL=animation_curve_subdivide.d.ts.map

package/src/engine/animation/curve/animation_curve_subdivide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animation_curve_subdivide.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_subdivide.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,+CAVW,QAAQ,QACR,QAAQ,QACR,QAAQ,KACR,MAAM,GACJ,QAAQ,CAqDpB"}

package/src/engine/animation/curve/animation_curve_subdivide.js

@@ -0,0 +1,66 @@
+import { assert } from "../../../core/assert.js";
+import { lerp } from "../../../core/math/lerp.js";
+import { spline3_hermite } from "../../../core/math/spline/spline3_hermite.js";
+import { spline3_hermite_derivative } from "../../../core/math/spline/spline3_hermite_derivative.js";
+
+/**
+ * Subdivide a curve segment by introducing a new keyframe at a given normalized time.
+ * Subdivision does not alter the curve shape in any way, it is intended primarily for editing purposes.
+ * @param {Keyframe} out keyframe to be added at the point of subdivision, its tangents, time and value will be overwritten
+ * @param {Keyframe} key0
+ * @param {Keyframe} key1
+ * @param {number} t normalized time in [0..1] between key0 and key1 where new frame is to be inserted
+ * @returns {Keyframe} `out`, for convenience
+ * @see AnimationCurve
+ * @example
+ *  const new_frame = animation_curve_subdivide(new Keyframe(), key0, key1, 0.5);
+ *  curve.add(new_frame);
+ */
+export function animation_curve_subdivide(
+    out,
+    key0,
+    key1,
+    t
+) {
+    assert.isObject(out, 'out');
+    assert.isObject(key0, 'key0');
+    assert.isObject(key1, 'key1');
+
+    assert.equal(out.isKeyframe,true,'out.isKeyframe !== true');
+    assert.equal(key0.isKeyframe,true,'key0.isKeyframe !== true');
+    assert.equal(key1.isKeyframe,true,'key1.isKeyframe !== true');
+
+    assert.isNumber(t, 't');
+    assert.ok(t >= 0 && t <= 1);
+
+    const v0 = key0.value;
+    const v1 = key1.value;
+
+    const time_span = key1.time - key0.time;
+
+    // Note that Keyframe tangents are normalized, so we denomalize them before using them
+    const m0 = key0.outTangent * time_span;
+    const m1 = key1.inTangent * time_span;
+
+    const xm = spline3_hermite(
+        t,
+        v0, v1,
+        m0, m1
+    );
+    const vm = spline3_hermite_derivative(
+        t,
+        v0, v1,
+        m0, m1
+    );
+
+    out.time = lerp(key0.time, key1.time, t);
+    out.value = xm;
+
+    // re-normalize tangent
+    const new_tangent = vm / time_span;
+
+    out.inTangent = new_tangent;
+    out.outTangent = new_tangent;
+
+    return out;
+}