@woosh/meep-engine 2.131.17 → 2.131.19

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

@@ -0,0 +1,35 @@
+/**
+ * Calculates the integral (area under the curve) of a cubic hermite spline from 0 to t.
+ *
+ * @param {number} t normalized interpolation position in interval [0,1]
+ * @param {number} p0 first value
+ * @param {number} p1 second value
+ * @param {number} m0 first tangent
+ * @param {number} m1 second tangent
+ * @returns {number} The definite integral from 0 to t
+ *
+ * @see spline3_hermite_derivative
+ */
+export function spline3_hermite_integral(t, p0, p1, m0, m1) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    const t4 = t3 * t;
+
+    // Integral of (2t^3 - 3t^2 + 1)
+    // Result: 0.5t^4 - t^3 + t
+    const int_p0 = 0.5 * t4 - t3 + t;
+
+    // Integral of (t^3 - 2t^2 + t)
+    // Result: 0.25t^4 - (2/3)t^3 + 0.5t^2
+    const int_m0 = 0.25 * t4 - (2.0 / 3.0) * t3 + 0.5 * t2;
+
+    // Integral of (t^3 - t^2)
+    // Result: 0.25t^4 - (1/3)t^3
+    const int_m1 = 0.25 * t4 - (1.0 / 3.0) * t3;
+
+    // Integral of (3t^2 - 2t^3)
+    // Result: t^3 - 0.5t^4
+    const int_p1 = t3 - 0.5 * t4;
+
+    return int_p0 * p0 + int_m0 * m0 + int_m1 * m1 + int_p1 * p1;
+}

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

@@ -1,5 +1,5 @@
 /**
- * Subdivides a hermite curve into two hermite curves.
+ * Subdivides a Hermite curve into two hermite curves.
  * The result is written in form [a_p0, a_p1, a_m0, a_m1, b_p0, b_p1, b_m0, b_m1], note the stride and offset.
  * @param {number[]} output where to write the result
  * @param {number} output_offset where to start writing

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

@@ -3,7 +3,7 @@ import { spline3_hermite } from "./spline3_hermite.js";
 import { spline3_hermite_derivative } from "./spline3_hermite_derivative.js";
 
 /**
- * Subdivides a hermite curve into two hermite curves.
+ * Subdivides a Hermite curve into two hermite curves.
  * The result is written in form [a_p0, a_p1, a_m0, a_m1, b_p0, b_p1, b_m0, b_m1], note the stride and offset.
  * @param {number[]} output where to write the result
  * @param {number} output_offset where to start writing

package/src/core/model/node-graph/NodeGraph.d.ts

@@ -223,6 +223,7 @@ export class NodeGraph {
      * @returns {number} number of found connections
      */
     getConnectionsAttachedToNode(id: number, result: number[]): number;
+    toString(): string;
     /**
      * Useful for type checks
      * @example

package/src/core/model/node-graph/NodeGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;OAEG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CAyBnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BAtqB4B,wBAAwB;2BAD1B,iBAAiB"}
+{"version":3,"file":"NodeGraph.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/node-graph/NodeGraph.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IAEI;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,6BAAyB;IAEzB;;;;;OAKG;IACH,4BAA0B;IAE1B;;;;;OAKG;IACH,kCAAgC;IAQhC;;;;;OAKG;IACH,+BAEC;IAED;;OAEG;IACH;QACI;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;QAGH;;;WAGG;;MAEL;IAEF;;OAEG;IACH,cAQC;IAED;;;OAGG;IACH,YAFW,SAAS,QAYnB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;;;OAMG;IACH,aAHW,SAAS,GACP;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAe5D;IAED;;;;;;;;OAQG;IACH,sCAJW,YAAY,EAAE,GAEZ;QAAC,WAAW,EAAC,UAAU,EAAE,CAAC;QAAC,KAAK,EAAC,YAAY,EAAE,CAAA;KAAC,CAmF5D;IAED;;;;OAIG;IACH,8BAHoB,YAAY,+BAK/B;IAED;;;;OAIG;IACH,oCAHoB,UAAU,+BAK7B;IAED;;;;OAIG;IACH,YAFY,YAAY,EAAE,CAIzB;IAED;;;;OAIG;IACH,kBAFY,UAAU,EAAE,CAIvB;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAgBnB;IAED;;;;OAIG;IACH,qDAFa,YAAY,EAAE,CAsB1B;IAED;;;;OAIG;IACH,0DAFa,YAAY,EAAE,CAqB1B;IAED;;;;OAIG;IACH,YAHW,MAAM,GACJ,YAAY,GAAC,SAAS,CAkBlC;IAED;;;;;OAKG;IACH,gBAJW,MAAM,GACJ,YAAY,CAWxB;IAED;;;;OAIG;IACH,kBAHW,MAAM,GACJ,UAAU,GAAC,SAAS,CAgBhC;IAED;;;;;OAKG;IACH,+BAJW,MAAM,WACN,MAAM,GACJ,4BAA0B,SAAS,CAY/C;IAED;;;;OAIG;IACH,mCAFa,MAAM,CAclB;IAED;;;OAGG;IACH,cAFW,YAAY,QAkBtB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;;OAQG;IACH,uCANW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqClB;IAED;;;;;;;;OAQG;IACH,6BAPW,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAuDlB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,OAAO,CAyBnB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,UACN,MAAM,EAAE,GACN,MAAM,CAyBlB;IAED,mBAEC;IAGL;;;;;;;;OAQG;IACH,sBAFU,OAAO,CAEc;;CAX9B;6BA1qB4B,wBAAwB;2BAD1B,iBAAiB"}

package/src/core/model/node-graph/NodeGraph.js

@@ -682,6 +682,10 @@ export class NodeGraph {
 
         return count;
     }
+
+    toString() {
+        return `NodeGraph{ nodes=${this.nodes.length}, connections=${this.connections.length}, version=${this.version} }`
+    }
 }
 
 /**

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

@@ -0,0 +1,17 @@
+/**
+ * Fits a smooth {@link AnimationCurve} to a set of discrete 2D points using adaptive Cubic Hermite Spline fitting.
+ *
+ * This utility performs data reduction (lossy compression) on dense time-series data.
+ * It recursively subdivides the dataset, inserting {@link Keyframe}s only where the interpolated curve deviates from the original points by more than `maxError`.
+ *
+ * Tangents are automatically estimated based on the slope of the input data (Catmull-Rom style), ensuring smooth transitions between keyframes.
+ *
+ * @param {number[]} points flat array of coordinates [x0, y0, x1, y1, ... xn, yn]
+ * @param {number} [input_offset] flat offset into the input array where to start reading data
+ * @param {number} [input_count] number of points to fit, counted in points i.e., pairs of (x,y) values
+ * @param {number} [maxError] Maximum allowed deviation. Higher values produce fewer keys (more compression), lower values preserve more detail.
+ * @returns {AnimationCurve}
+ */
+export function animation_curve_fit(points: number[], input_offset?: number, input_count?: number, maxError?: number): AnimationCurve;
+import { AnimationCurve } from "./AnimationCurve.js";
+//# sourceMappingURL=animation_curve_fit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"animation_curve_fit.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_fit.js"],"names":[],"mappings":"AAkEA;;;;;;;;;;;;;GAaG;AACH,4CANW,MAAM,EAAE,iBACR,MAAM,gBACN,MAAM,aACN,MAAM,GACJ,cAAc,CAoH1B;+BA/L8B,qBAAqB"}

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

@@ -0,0 +1,195 @@
+import { assert } from "../../../core/assert.js";
+import { spline3_hermite } from "../../../core/math/spline/spline3_hermite.js";
+import { number_compare_ascending } from "../../../core/primitives/numbers/number_compare_ascending.js";
+import { AnimationCurve } from "./AnimationCurve.js";
+import { Keyframe } from "./Keyframe.js";
+
+/**
+ * Calculates a Catmull-Rom style tangent (slope) for a point in the dataset.
+ * @param {number[]} points
+ * @param {number} points_offset
+ * @param {number} points_count
+ * @param {number} index
+ */
+function calculateTangent(
+    points,
+    points_offset,
+    points_count,
+    index
+) {
+
+    const current = points_offset + index * 2;
+
+    // Handle boundaries: Linear slope to neighbor
+    if (index === 0) {
+        const next = points_offset + 2;
+
+        const dt = points[next] - points[current];
+
+        if (dt === 0) {
+            return 0;
+        } else {
+            return (points[next + 1] - points[current + 1]) / dt;
+        }
+
+    }
+    if (index === points_count - 1) {
+        const prev = points_offset + (points_count - 2) * 2;
+
+        const dt = points[current] - points[prev];
+
+        if (dt === 0) {
+            return 0;
+        } else {
+            return (points[current + 1] - points[prev + 1]) / dt;
+        }
+
+    }
+
+    // Handle internal points: Average slope between prev and next (Finite Difference)
+    const next = points_offset + (index + 1) * 2;
+    const prev = points_offset + (index - 1) * 2;
+
+    // A simpler approach is the slope between prev and next directly:
+    // return (next.value - prev.value) / (next.time - prev.time);
+
+    // However, weighted average often looks better for non-uniform time steps:
+    const dt0 = points[current] - points[prev];
+    const slope0 = dt0 === 0 ? 0 : (points[current + 1] - points[prev + 1]) / dt0;
+
+    const dt1 = points[next] - points[current];
+    const slope1 = dt1 === 0 ? 0 : (points[next + 1] - points[current + 1]) / dt1;
+
+    // Average the slopes
+    return (slope0 + slope1) * 0.5;
+}
+
+/**
+ * Fits a smooth {@link AnimationCurve} to a set of discrete 2D points using adaptive Cubic Hermite Spline fitting.
+ *
+ * This utility performs data reduction (lossy compression) on dense time-series data.
+ * It recursively subdivides the dataset, inserting {@link Keyframe}s only where the interpolated curve deviates from the original points by more than `maxError`.
+ *
+ * Tangents are automatically estimated based on the slope of the input data (Catmull-Rom style), ensuring smooth transitions between keyframes.
+ *
+ * @param {number[]} points flat array of coordinates [x0, y0, x1, y1, ... xn, yn]
+ * @param {number} [input_offset] flat offset into the input array where to start reading data
+ * @param {number} [input_count] number of points to fit, counted in points i.e., pairs of (x,y) values
+ * @param {number} [maxError] Maximum allowed deviation. Higher values produce fewer keys (more compression), lower values preserve more detail.
+ * @returns {AnimationCurve}
+ */
+export function animation_curve_fit(
+    points,
+    input_offset = 0,
+    input_count = ((points.length - input_offset) / 2),
+    maxError = 0.01
+) {
+    assert.defined(points, 'points');
+    assert.isNonNegativeInteger(input_offset, 'input_offset');
+    assert.isNonNegativeInteger(input_count, 'input_count');
+    assert.notNaN(maxError, 'maxError');
+    assert.greaterThanOrEqual(maxError, 0, 'maxError must be non-negative');
+
+    if (input_count === 0) {
+        return new AnimationCurve();
+    }
+
+    if (input_count === 1) {
+        return AnimationCurve.from([Keyframe.from(points[input_offset], points[input_offset + 1])]);
+    }
+
+    // 1. Identify which indices from the source array we need to keep as Keyframes
+    const keyIndices = new Set();
+
+    // Always keep first and last
+    keyIndices.add(0);
+    keyIndices.add(input_count - 1);
+
+    /**
+     * Recursive function to find split points
+     * @param {number} firstIndex
+     * @param {number} lastIndex
+     */
+    function fitSegment(firstIndex, lastIndex) {
+        if (lastIndex - firstIndex <= 1) {
+            // done
+            return;
+        }
+
+        // A. Estimate tangents for the start and end of this segment
+        // We calculate tangents based on the *original* dense data to ensure accurate slope
+        const m0 = calculateTangent(points, input_offset, input_count, firstIndex);
+        const m1 = calculateTangent(points, input_offset, input_count, lastIndex);
+
+        const address_0 = input_offset + firstIndex * 2;
+        const address_1 = input_offset + lastIndex * 2;
+
+        const tStart = points[address_0];
+        const tEnd = points[address_1];
+        const vStart = points[address_0 + 1];
+        const vEnd = points[address_1 + 1];
+        const duration = tEnd - tStart;
+
+        if (duration < 1e-12) {
+            // duration is very low, we're in division-by-zero territory
+            return;
+        }
+
+        // B. Find the point in this range with the greatest error vs the hypothetical curve
+        let maxSegmentError = 0;
+        let splitIndex = -1;
+
+        for (let i = firstIndex + 1; i < lastIndex; i++) {
+            const address = input_offset + i * 2;
+
+            // Normalize time t to [0, 1] for the Hermite formula
+            const t = (points[address] - tStart) / duration;
+
+            // Evaluate Cubic Hermite Spline
+            const evaluatedValue = spline3_hermite(t, vStart, vEnd, m0 * duration, m1 * duration);
+
+            const error = Math.abs(points[address + 1] - evaluatedValue);
+
+            if (error > maxSegmentError) {
+                maxSegmentError = error;
+                splitIndex = i;
+            }
+        }
+
+        // C. If error is too high, mark the split point as a Keyframe and recurse
+        if (maxSegmentError > maxError) {
+            keyIndices.add(splitIndex);
+            fitSegment(firstIndex, splitIndex);
+            fitSegment(splitIndex, lastIndex);
+        }
+    }
+
+    // Start the recursion
+    fitSegment(0, input_count - 1);
+
+    // 2. Build the final curve from the selected indices
+    const sortedIndices = Array.from(keyIndices).sort(number_compare_ascending);
+
+    /**
+     *
+     * @type {Keyframe[]}
+     */
+    const resultKeys = [];
+
+    const fitted_key_count = sortedIndices.length;
+
+    for (let i = 0; i < fitted_key_count; i++) {
+        const idx = sortedIndices[i];
+        const address = input_offset + idx * 2;
+
+        // Calculate the smooth tangent for this key
+        // Note: For sharp transitions, you might want to break continuity,
+        // but for approximation, continuous slope is usually desired.
+        const tangent = calculateTangent(points, input_offset, input_count, idx);
+
+        // Create a keyframe. Assuming inTangent == outTangent for smooth fitting.
+        resultKeys.push(Keyframe.from(points[address], points[address + 1], tangent, tangent));
+    }
+
+    return AnimationCurve.from(resultKeys);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"animation_curve_optimize.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_optimize.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;GAUG;AACH,kFANW,MAAM,GACJ,MAAM,CAqDlB"}
+{"version":3,"file":"animation_curve_optimize.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_optimize.js"],"names":[],"mappings":"AA+EA;;;;;;;;;;GAUG;AACH,kFANW,MAAM,GACJ,MAAM,CAoElB"}

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

@@ -1,14 +1,19 @@
 import { assert } from "../../../core/assert.js";
 import AABB2 from "../../../core/geom/2d/aabb/AABB2.js";
+import { spline3_hermite_derivative } from "../../../core/math/spline/spline3_hermite_derivative.js";
 import { animation_curve_compute_aabb } from "./animation_curve_compute_aabb.js";
 import { evaluate_two_key_curve } from "./evaluate_two_key_curve.js";
 
 const bounds = new AABB2();
 
-const NORMALIZED_CHECK_DISTANCE = 0.07;
+// Scaling factor to project slope error into value error.
+// 0.125 (1/8th) is a standard approximation for cubic bezier error bounds.
+const TANGENT_ERROR_WEIGHT = 0.125;
 
 /**
- * Compute the value difference in the curve if the `middle` key between `previous` and `next` is removed
+ * Computes importance by checking Position AND Slope integrity.
+ * Uses exact derivative calculation instead of neighbor sampling
+ *
  * @param {Keyframe} key_middle
  * @param {Keyframe} key_previous
  * @param {Keyframe} key_next
@@ -22,30 +27,54 @@ function compute_keyframe_value_effect(
     key_previous,
     key_next
 ) {
+    const duration = key_next.time - key_previous.time;
+
+    // Safety check for zero-duration (duplicate keys handled by outer loop, but safe to guard)
+    if (duration < 1e-9){
+        return 0;
+    }
+
+    // 1. Calculate Normalized Time t [0, 1]
+    const t_relative = key_middle.time - key_previous.time;
+    const t_normalized = t_relative / duration;
 
-    // check if this key contributes to the shape
-    const v1_actual = evaluate_two_key_curve(key_middle.time, key_previous, key_next);
-    const v1_expected = key_middle.value;
+    // 2. Calculate Position Error (The "Hit Test")
+    // Does the simplified curve actually hit the middle key's value?
+    const v_actual = evaluate_two_key_curve(key_middle.time, key_previous, key_next);
+    const v_error = Math.abs(v_actual - key_middle.value);
 
-    const v1_error = Math.abs(v1_actual - v1_expected);
+    // 3. Calculate Derivative Error (The "Shape Test")
+    // Does the simplified curve flow in the same direction as the original key?
 
-    // sample just before the current frame
-    const v0_time = key_middle.time - (key_middle.time - key_previous.time) * NORMALIZED_CHECK_DISTANCE;
+    // NOTE: Hermite basis requires tangents scaled by duration (m0, m1)
+    // We assume keyframes have .outTangent and .inTangent or similar.
+    // If you use standard Hermite data, it looks like this:
+    const m0 = key_previous.outTangent * duration;
+    const m1 = key_next.inTangent * duration;
 
-    const v0_actual = evaluate_two_key_curve(v0_time, key_previous, key_next);
-    const v0_expected = evaluate_two_key_curve(v0_time, key_previous, key_middle);
+    // This returns the derivative in "Value per Normalized Time"
+    const slope_normalized = spline3_hermite_derivative(
+        t_normalized,
+        key_previous.value,
+        key_next.value,
+        m0,
+        m1
+    );
 
-    const v0_error = Math.abs(v0_actual - v0_expected);
+    // Convert to "Value per Second" to match the keyframe's stored tangent
+    const slope_actual = slope_normalized / duration;
 
-    // sample just after the current frame
-    const v2_time = key_middle.time + (key_next.time - key_middle.time) * NORMALIZED_CHECK_DISTANCE;
+    // We compare against the explicit tangent stored on the middle key (or calculated implicit tangent)
+    // Assuming the key has a unified tangent or we use the inTangent
+    const slope_expected = key_middle.inTangent; // or .outTangent, or average if smooth
 
-    const v2_actual = evaluate_two_key_curve(v2_time, key_previous, key_next);
-    const v2_expected = evaluate_two_key_curve(v2_time, key_middle, key_next);
+    const slope_delta = Math.abs(slope_actual - slope_expected);
 
-    const v2_error = Math.abs(v2_actual - v2_expected);
+    // 4. Project Slope Delta into Value Units
+    // If the slope is off by 1 unit/sec, how much drift does that cause over the duration?
+    const slope_error_projected = slope_delta * duration * TANGENT_ERROR_WEIGHT;
 
-    return Math.max(v0_error, v1_error, v2_error);
+    return Math.max(v_error, slope_error_projected);
 }
 
 /**
@@ -65,11 +94,22 @@ export function animation_curve_optimize(
 ) {
     assert.lessThan(error_tolerance, 1, 'error_tolerance must be less than 1');
 
+    let key_count = curve.length;
+
+    if (key_count <= 1) {
+        // nothing to remove
+        return 0;
+    }
+
     animation_curve_compute_aabb(bounds, curve);
 
-    const absolute_error_tolerance = bounds.height * error_tolerance;
+    const EPSILON = 1e-9;
 
-    let key_count = curve.length;
+    // Clamp against epsilon to handle the flat-line case or very low tolerances resulting in precision issues
+    const absolute_error_tolerance = Math.max(
+        bounds.height * error_tolerance,
+        EPSILON,
+    );
 
     const keyframes = curve.keys;
 
@@ -84,9 +124,8 @@ export function animation_curve_optimize(
         if (key_current.equals(key_previous)) {
             // adds no semantic value
             should_remove = true;
-        }
+        } else if (i < key_count - 1) {
 
-        if (!should_remove && i < key_count - 1) {
             const key_next = keyframes[i + 1];
 
             const max_error = compute_keyframe_value_effect(key_current, key_previous, key_next);
@@ -95,13 +134,18 @@ export function animation_curve_optimize(
                 // does not significantly affect the curve shape
                 should_remove = true;
             }
+
         }
 
 
         if (should_remove) {
+
             curve.remove(key_current);
+
+            // update iterator
             i--;
             key_count--;
+
         }
     }
 

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

@@ -1,11 +1,13 @@
 /**
  * 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 {Keyframe} key0 start of the segment
+ * @param {Keyframe} key1 end of the segment
  * @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);

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

@@ -1 +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"}
+{"version":3,"file":"animation_curve_subdivide.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/animation_curve_subdivide.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,+CAXW,QAAQ,QACR,QAAQ,QACR,QAAQ,KACR,MAAM,GACJ,QAAQ,CAsDpB"}

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

@@ -6,11 +6,13 @@ import { spline3_hermite_derivative } from "../../../core/math/spline/spline3_he
 /**
  * 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 {Keyframe} key0 start of the segment
+ * @param {Keyframe} key1 end of the segment
  * @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);

package/src/engine/ecs/transform/Transform.d.ts

@@ -1,9 +1,7 @@
 /**
  * A Transform represents the position, rotation, and scale of an object in 3D space.
  * Think of it like the object's location, orientation, and size.
- * It has properties for position (like coordinates), rotation (how it's turned), and scale (how big it is).
- *
- * It also uses a "matrix" (a table of numbers) internally to efficiently store and calculate transformations, but you usually interact with the position, rotation, and scale directly.
+ * It has properties for {@link position} (like coordinates), {@link rotation} (how it's oriented), and {@link scale} (how big it is).
  *
  * @example
  *  const t = new Transform();
@@ -50,8 +48,11 @@ export class Transform {
      */
     readonly scale: Vector3;
     /**
-     * transform matrix, position, rotation, and scale must match, but shear can be different
-     * Note: this is managed by the Transform itself, do not modify the matrix directly. If you want to set it - use {@link fromMatrix} method instead
+     * Affine transform matrix, {@link position}, {@link rotation}, and {@link scale} must match, but shear can be different.
+     * Note: this is managed by the {@link Transform} itself unless {@link TransformFlags.AutomaticChangeDetection} is disabled; do not modify the matrix directly.
+     * Generally, if you want to modify it - use {@link fromMatrix} method instead.
+     *
+     * If you're not comfortable with matrices, just leave defaults on and stick to primary attributes i.e. {@link position}, {@link rotation}, and {@link scale}.
      * @readonly
      * @type {Float32Array}
      */
@@ -115,7 +116,9 @@ export class Transform {
      */
     getFlag(flag: number | TransformFlags): boolean;
     /**
-     * Update {@link matrix} attribute from current position/rotation/scale
+     * Update {@link matrix} attribute from current {@link position}/{@link rotation}/{@link scale}
+     *
+     * Useful for when {@link TransformFlags.AutomaticChangeDetection} is disabled.
      */
     updateMatrix(): void;
     /**

package/src/engine/ecs/transform/Transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transform.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;GAaG;AACH;IA6QI;;;;OAIG;IACH,4BAFa,SAAS,CAQrB;IAED;;;;OAIG;IACH,uBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,SAAS,CAQrB;IA0FD;;;;;OAKG;IACH,wCAJW,UAAU,gBACV,OAAO,wBAejB;IA/YD;;;OAGG;IACH,mBAHU,OAAO,CAGe;IAEhC;;;;;OAKG;IACH,mBAHU,UAAU,CAGkB;IAEtC;;;OAGG;IACH,gBAHU,OAAO,CAGY;IAE7B;;;;;OAKG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;;OAIG;IACH,OAFU,MAAM,CAEM;IAOtB;;;;OAIG;IACH,uBAMC;IAED;;;OAGG;IACH,kBAMC;IAED;;;OAGG;IACH,qBAMC;IAED;;;;OAIG;IACH,kDAIC;IAED;;;;OAIG;IACH,oDAIC;IAYD;;;;OAIG;IACH,cAHW,MAAM,GAAC,cAAc,GACnB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,cAAc,GACnB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,cAAc,SACrB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,cAAc,GACnB,OAAO,CAInB;IAED;;OAEG;IACH,qBAEC;IAED;;;;OAIG;IACH,eAHW,OAAO,OACP,OAAO,QAmBjB;IAED,0BAwBC;IAED;;;;;;;;;;;;;;;;;MAMC;IAED;;;;;OAKG;IACH,YAFW,SAAS,QAenB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAMnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAKlB;IA4BD;;;;;;OAMG;IACH,gBAHW,SAAS,GACP,IAAI,CAIhB;IAED;;;;;OAKG;IACH,sBAJW,SAAS,KACT,SAAS,GACP,IAAI,CAWhB;IAED;;;;OAIG;IACH,mBAHW,OAAK,MAAM,EAAE,GAAC,YAAY,GACxB,IAAI,CAmBhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,EAAE,CAOpB;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;OAGG;IACH,cAFa,OAAO,CAMnB;IAED,mBAEC;IA6BL;;;;;;;;OAQG;IACH,sBANU,OAAO,CAMc;IAE/B;;;OAGG;IACH,8BA5Ee,MAAM,EAAE,GAAC,YAAY,KACnB,MAAM,EAAE,CA2EI;IAE7B;;;OAGG;IACH,+BA1Ge,OAAK,MAAM,EAAE,GAAC,YAAY,KACxB,IAAI,CAyGU;;CA7B9B;;kBAIS,MAAM;;oBAnbI,+BAA+B;uBAD5B,kCAAkC;+BAE1B,qBAAqB"}
+{"version":3,"file":"Transform.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/Transform.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;GAWG;AACH;IAsRI;;;;OAIG;IACH,4BAFa,SAAS,CAQrB;IAED;;;;OAIG;IACH,uBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,SAAS,CAQrB;IA0FD;;;;;OAKG;IACH,wCAJW,UAAU,gBACV,OAAO,wBAejB;IAxZD;;;OAGG;IACH,mBAHU,OAAO,CAGe;IAEhC;;;;;OAKG;IACH,mBAHU,UAAU,CAGkB;IAEtC;;;OAGG;IACH,gBAHU,OAAO,CAGY;IAE7B;;;;;;;;OAQG;IACH,iBAFU,YAAY,CAEC;IAEvB;;;;OAIG;IACH,OAFU,MAAM,CAEM;IAStB;;;;OAIG;IACH,uBAMC;IAED;;;OAGG;IACH,kBAMC;IAED;;;OAGG;IACH,qBAMC;IAED;;;;OAIG;IACH,kDAIC;IAED;;;;OAIG;IACH,oDAIC;IAYD;;;;OAIG;IACH,cAHW,MAAM,GAAC,cAAc,GACnB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,cAAc,GACnB,IAAI,CAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,cAAc,SACrB,OAAO,QAQjB;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,cAAc,GACnB,OAAO,CAInB;IAED;;;;OAIG;IACH,qBAEC;IAED;;;;OAIG;IACH,eAHW,OAAO,OACP,OAAO,QAqBjB;IAED,0BAwBC;IAED;;;;;;;;;;;;;;;;;MAMC;IAED;;;;;OAKG;IACH,YAFW,SAAS,QAenB;IAED;;;OAGG;IACH,SAFa,SAAS,CAQrB;IAED;;;;OAIG;IACH,cAHW,SAAS,GACP,OAAO,CAMnB;IAED;;;OAGG;IACH,QAFa,MAAM,CAKlB;IA4BD;;;;;;OAMG;IACH,gBAHW,SAAS,GACP,IAAI,CAIhB;IAED;;;;;OAKG;IACH,sBAJW,SAAS,KACT,SAAS,GACP,IAAI,CAWhB;IAED;;;;OAIG;IACH,mBAHW,OAAK,MAAM,EAAE,GAAC,YAAY,GACxB,IAAI,CAmBhB;IAED;;;;OAIG;IACH,kBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,EAAE,CAOpB;IAED;;;;;OAKG;IACH,qBAEC;IAED;;;OAGG;IACH,cAFa,OAAO,CAMnB;IAED,mBAEC;IA6BL;;;;;;;;OAQG;IACH,sBANU,OAAO,CAMc;IAE/B;;;OAGG;IACH,8BA5Ee,MAAM,EAAE,GAAC,YAAY,KACnB,MAAM,EAAE,CA2EI;IAE7B;;;OAGG;IACH,+BA1Ge,OAAK,MAAM,EAAE,GAAC,YAAY,KACxB,IAAI,CAyGU;;CA7B9B;;kBAIS,MAAM;;oBA1bI,+BAA+B;uBAD5B,kCAAkC;+BAE1B,qBAAqB"}

package/src/engine/ecs/transform/Transform.js

@@ -23,9 +23,7 @@ const FLAGS_DEFAULT = TransformFlags.AutomaticChangeDetection;
 /**
  * A Transform represents the position, rotation, and scale of an object in 3D space.
  * Think of it like the object's location, orientation, and size.
- * It has properties for position (like coordinates), rotation (how it's turned), and scale (how big it is).
- *
- * It also uses a "matrix" (a table of numbers) internally to efficiently store and calculate transformations, but you usually interact with the position, rotation, and scale directly.
+ * It has properties for {@link position} (like coordinates), {@link rotation} (how it's oriented), and {@link scale} (how big it is).
  *
  * @example
  *  const t = new Transform();
@@ -57,8 +55,11 @@ export class Transform {
     scale = new Vector3(1, 1, 1);
 
     /**
-     * transform matrix, position, rotation, and scale must match, but shear can be different
-     * Note: this is managed by the Transform itself, do not modify the matrix directly. If you want to set it - use {@link fromMatrix} method instead
+     * Affine transform matrix, {@link position}, {@link rotation}, and {@link scale} must match, but shear can be different.
+     * Note: this is managed by the {@link Transform} itself unless {@link TransformFlags.AutomaticChangeDetection} is disabled; do not modify the matrix directly.
+     * Generally, if you want to modify it - use {@link fromMatrix} method instead.
+     *
+     * If you're not comfortable with matrices, just leave defaults on and stick to primary attributes i.e. {@link position}, {@link rotation}, and {@link scale}.
      * @readonly
      * @type {Float32Array}
      */
@@ -72,7 +73,9 @@ export class Transform {
     flags = FLAGS_DEFAULT;
 
     constructor() {
-        // watch changes
+        // Watch changes.
+        // This creates a data dependency, which makes GC impossible if we keep references to position/rotation/scale
+        // Please clone those properties if you need to keep them past the expiry of the Transform
         this.subscribe(this.#handle_component_change, this);
     }
 
@@ -186,7 +189,9 @@ export class Transform {
     }
 
     /**
-     * Update {@link matrix} attribute from current position/rotation/scale
+     * Update {@link matrix} attribute from current {@link position}/{@link rotation}/{@link scale}
+     *
+     * Useful for when {@link TransformFlags.AutomaticChangeDetection} is disabled.
      */
     updateMatrix() {
         compose_matrix4_array(this.matrix, this.position, this.rotation, this.scale);
@@ -206,7 +211,9 @@ export class Transform {
         const delta_z = target.z - position.z;
 
         if (delta_x === 0 && delta_y === 0 && delta_z === 0) {
-            // target is at the same location as this transform, no valid rotation, keep whatever we have
+            // Target is at the same location as this transform, no valid rotation, keep whatever we have.
+            // Generally this is a programmer mistake, making any changes to the rotation would be undesirable.
+            // The most valid option is to keep the current state.
             return;
         }
 

package/src/engine/graphics/ecs/camera/topdown/ComputeCameraFacingVector.js

@@ -11,7 +11,7 @@ const q = new Quaternion();
  * @param {Vector3} result
  */
 export function computeCameraFacingVector(yaw, pitch, roll, result) {
-    q.__setFromEuler(pitch, yaw, roll, 'ZYX');
+    q.fromEulerAnglesZYX(pitch, yaw, roll);
     q.normalize();
 
     result.copy(Vector3.forward);

package/src/engine/graphics/ecs/camera/topdown/TopDownCameraControllerSystem.js

@@ -74,7 +74,7 @@ export function computeTopDownTransform(control, result) {
     const roll = control.roll;
 
     // compute rotation
-    rotation.__setFromEuler(pitch, yaw, roll, 'ZYX');
+    rotation.fromEulerAnglesZYX(pitch, yaw, roll);
 
     // compute camera position
     v3_scratch.copy(Vector3.forward);

package/src/engine/graphics/ecs/mesh-v2/aggregate/prototypeSGMesh.js

@@ -62,7 +62,7 @@ function make_grid(ecd, engine) {
         for (let j = 0; j < GRID_SIZE; j++) {
             const quaternion = new Quaternion();
 
-            quaternion.__setFromEuler(0, random() * Math.PI, 0);
+            quaternion.fromEulerAnglesXYZ(0, random() * Math.PI, 0);
 
             const center = new Vector3(i * 8, 0, j * 8);
 

package/src/engine/graphics/render/forward_plus/plugin/ptototypeFPPlugin.js

@@ -1083,7 +1083,7 @@ function makeKnot(engine, position, scale, rotation) {
         }
     });
 
-    transform.rotation.__setFromEuler(position[0], position[1], position[2]);
+    transform.rotation.fromEulerAnglesXYZ(position[0], position[1], position[2]);
 
     transform.scale.multiplyScalar(scale);
 

package/src/generation/markers/transform/MarkerNodeTransformerYRotateByFilter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MarkerNodeTransformerYRotateByFilter.d.ts","sourceRoot":"","sources":["../../../../../src/generation/markers/transform/MarkerNodeTransformerYRotateByFilter.js"],"names":[],"mappings":"AAQA;IAqBI;;;;OAIG;IACH,yCAFW,MAAM,wCAahB;IAnCD;;;OAGG;IACH,mBAAc;IAEd;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,uCAIC;IAqBD,qCAmBC;CACJ;sCAnEqC,4BAA4B"}
+{"version":3,"file":"MarkerNodeTransformerYRotateByFilter.d.ts","sourceRoot":"","sources":["../../../../../src/generation/markers/transform/MarkerNodeTransformerYRotateByFilter.js"],"names":[],"mappings":"AAQA;IAqBI;;;;OAIG;IACH,yCAFW,MAAM,wCAahB;IAnCD;;;OAGG;IACH,mBAAc;IAEd;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX,uCAIC;IAqBD,qCAmBC;CACJ;sCA/DqC,4BAA4B"}