@woosh/meep-engine 3.43.0 → 3.45.0

package/src/core/math/linalg/matrix_symmetric_3x3_solve_ldlt.js

@@ -0,0 +1,71 @@
+/**
+ * Solve `M·x = b` for a symmetric positive definite 3×3 `M`, by LDLᵀ factorisation.
+ *
+ * `M` is read as its six distinct entries, diagonal first: `[m00, m11, m22, m01, m02, m12]`.
+ *
+ * LDLᵀ rather than a cofactor inverse. The two agree in exact arithmetic and do not agree in Float64: an SPD
+ * matrix with a condition number in the billions has a cofactor determinant — a sum of triple products that
+ * has to cancel down by that ratio squared — that can come out *negative* although every eigenvalue is
+ * positive. The factorisation never forms those products, so its pivots stay positive where the determinant
+ * does not, and their product is the determinant to full precision.
+ *
+ * The pivots of an SPD matrix are `M` restricted to nested subspaces, so all three positive *is* positive
+ * definiteness: the function checks exactly that, and returns `false` without writing `out` when a pivot is
+ * not positive and finite — an indefinite, singular or non-finite `M`. An infinite pivot needs refusing
+ * explicitly: it is positive, and dividing by it reads as a finite solution, zero along that axis.
+ *
+ * @param {Float64Array|Float32Array|number[]} out solution `x`, 3 entries at `out_offset`
+ * @param {number} out_offset
+ * @param {Float64Array|Float32Array|number[]} m `[m00, m11, m22, m01, m02, m12]` at `m_offset`
+ * @param {number} m_offset
+ * @param {Float64Array|Float32Array|number[]} b right-hand side, 3 entries at `b_offset`
+ * @param {number} b_offset
+ * @returns {boolean} true when `M` was positive definite and `out` holds the solution
+ */
+export function matrix_symmetric_3x3_solve_ldlt(
+    out, out_offset,
+    m, m_offset,
+    b, b_offset
+) {
+    const m00 = m[m_offset];
+    const m11 = m[m_offset + 1];
+    const m22 = m[m_offset + 2];
+    const m01 = m[m_offset + 3];
+    const m02 = m[m_offset + 4];
+    const m12 = m[m_offset + 5];
+
+    const pivot_0 = m00;
+    const lower_10 = m01 / pivot_0;
+    const lower_20 = m02 / pivot_0;
+
+    const pivot_1 = m11 - lower_10 * m01;
+    const lower_21 = (m12 - lower_20 * m01) / pivot_1;
+
+    const pivot_2 = m22 - lower_20 * m02 - lower_21 * lower_21 * pivot_1;
+
+    if (!(
+        pivot_0 > 0 && pivot_0 < Infinity
+        && pivot_1 > 0 && pivot_1 < Infinity
+        && pivot_2 > 0 && pivot_2 < Infinity
+    )) {
+        return false;
+    }
+
+    const b0 = b[b_offset];
+    const b1 = b[b_offset + 1];
+    const b2 = b[b_offset + 2];
+
+    // Forward substitution through L, scale by D, back substitution through Lᵀ.
+    const forward_1 = b1 - lower_10 * b0;
+    const forward_2 = b2 - lower_20 * b0 - lower_21 * forward_1;
+
+    const x2 = forward_2 / pivot_2;
+    const x1 = forward_1 / pivot_1 - lower_21 * x2;
+    const x0 = b0 / pivot_0 - lower_10 * x1 - lower_20 * x2;
+
+    out[out_offset] = x0;
+    out[out_offset + 1] = x1;
+    out[out_offset + 2] = x2;
+
+    return true;
+}

package/src/core/math/max2_exact.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `Math.max(a, b)` without the call, as {@link min2_exact}: the larger, NaN if either is, and `+0`
+ * above `-0`.
+ *
+ * {@link max2} drops a NaN in `b` and lets the first of two zeros win; this does neither.
+ *
+ * The same as `Math.max` under `Object.is` for every pair of numbers, except that a NaN answer is the
+ * canonical NaN.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function max2_exact(a: number, b: number): number;
+//# sourceMappingURL=max2_exact.d.ts.map

package/src/core/math/max2_exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max2_exact.d.ts","sourceRoot":"","sources":["../../../../src/core/math/max2_exact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAkBlB"}

package/src/core/math/max2_exact.js

@@ -0,0 +1,30 @@
+/**
+ * `Math.max(a, b)` without the call, as {@link min2_exact}: the larger, NaN if either is, and `+0`
+ * above `-0`.
+ *
+ * {@link max2} drops a NaN in `b` and lets the first of two zeros win; this does neither.
+ *
+ * The same as `Math.max` under `Object.is` for every pair of numbers, except that a NaN answer is the
+ * canonical NaN.
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function max2_exact(a, b) {
+    if (a > b) {
+        return a;
+    }
+
+    if (b > a) {
+        return b;
+    }
+
+    if (a === b) {
+        // equal, and of two zeros the positive one if either is
+        return a === 0 && 1 / a < 0 ? b : a;
+    }
+
+    // one of them is NaN
+    return NaN;
+}

package/src/core/math/min2_exact.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Math.min(a, b)` without the call: the smaller, NaN if either is, and `-0` below `+0`.
+ *
+ * {@link min2} is `a < b ? a : b`, which answers `b` whenever the comparison is false — a NaN in `a`
+ * is dropped, and of two zeros the second one wins. That is right for a running minimum over values
+ * known to be numbers, and wrong for a bound that has to stay poisoned when its input was.
+ *
+ * Why not `Math.min` itself: in code V8 has not optimised yet (a function run a few times a step can
+ * stay unoptimised for thousands of steps), `Math.min` is a call into a builtin that hands its answer
+ * back boxed into a heap object. This is comparisons only.
+ *
+ * The same as `Math.min` under `Object.is` for every pair of numbers. A NaN answer is the canonical
+ * NaN; which NaN `Math.min` answers is the platform's (on x64, the one with the sign bit set).
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function min2_exact(a: number, b: number): number;
+//# sourceMappingURL=min2_exact.d.ts.map

package/src/core/math/min2_exact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"min2_exact.d.ts","sourceRoot":"","sources":["../../../../src/core/math/min2_exact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAJW,MAAM,KACN,MAAM,GACJ,MAAM,CAkBlB"}

package/src/core/math/min2_exact.js

@@ -0,0 +1,35 @@
+/**
+ * `Math.min(a, b)` without the call: the smaller, NaN if either is, and `-0` below `+0`.
+ *
+ * {@link min2} is `a < b ? a : b`, which answers `b` whenever the comparison is false — a NaN in `a`
+ * is dropped, and of two zeros the second one wins. That is right for a running minimum over values
+ * known to be numbers, and wrong for a bound that has to stay poisoned when its input was.
+ *
+ * Why not `Math.min` itself: in code V8 has not optimised yet (a function run a few times a step can
+ * stay unoptimised for thousands of steps), `Math.min` is a call into a builtin that hands its answer
+ * back boxed into a heap object. This is comparisons only.
+ *
+ * The same as `Math.min` under `Object.is` for every pair of numbers. A NaN answer is the canonical
+ * NaN; which NaN `Math.min` answers is the platform's (on x64, the one with the sign bit set).
+ *
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function min2_exact(a, b) {
+    if (a < b) {
+        return a;
+    }
+
+    if (b < a) {
+        return b;
+    }
+
+    if (a === b) {
+        // equal, and of two zeros the negative one if either is
+        return a === 0 && 1 / a > 0 ? b : a;
+    }
+
+    // one of them is NaN
+    return NaN;
+}

package/src/engine/Clock.d.ts

@@ -52,6 +52,21 @@ declare class Clock {
      * @returns {number} in seconds
      */
     getDelta(): number;
+    /**
+     * {@link getDelta}, measured to a given moment instead of to now - an animation frame's
+     * timestamp, so that the simulation shown by a frame is the simulation at that frame's time and
+     * not at whenever the code reading the clock happened to run.
+     *
+     * Only a moment between the clock's last reading and now can be measured to; anything else is
+     * measured to now. A frame's timestamp is when the frame began, so it can sit behind a reading
+     * taken earlier in that frame (a resume() from an input handler). And it is only on this
+     * clock's timeline where the environment keeps its promise that it is - jsdom stamps frames
+     * 1.5 s behind `performance.now()`, a `Date.now()` polyfill decades ahead - and measured to
+     * those, the clock froze or leapt.
+     * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+     * @returns {number} in seconds
+     */
+    getDeltaAt(time: number): number;
     /**
      *
      * @returns {number} in seconds

package/src/engine/Clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAeC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA1IgB,4BAA4B"}
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAeC;IAED;;;OAGG;IACH,YAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;;OAaG;IACH,iBAHW,MAAM,GACJ,MAAM,CAalB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBAlKgB,4BAA4B"}

package/src/engine/Clock.js

@@ -4,9 +4,9 @@ import { current_time_in_seconds } from "../core/time/current_time_in_seconds.js
 /**
  *
  * @param {Clock} clock
+ * @param {number} now in seconds, on the {@link current_time_in_seconds} timeline
  */
-function updateElapsedTime(clock) {
-    const now = current_time_in_seconds();
+function updateElapsedTime(clock, now) {
     const delta = (now - clock.__lastMeasurement) * clock.speed;
     clock.__lastMeasurement = now;
     clock.elapsedTime += delta;
@@ -98,7 +98,7 @@ class Clock {
 
         this.__isRunning = false;
         //update time
-        updateElapsedTime(this);
+        updateElapsedTime(this, current_time_in_seconds());
     }
 
     /**
@@ -106,7 +106,31 @@ class Clock {
      * @returns {number} in seconds
      */
     getDelta() {
-        const elapsedTime = this.updateElapsedTime();
+        return this.getDeltaAt(current_time_in_seconds());
+    }
+
+    /**
+     * {@link getDelta}, measured to a given moment instead of to now - an animation frame's
+     * timestamp, so that the simulation shown by a frame is the simulation at that frame's time and
+     * not at whenever the code reading the clock happened to run.
+     *
+     * Only a moment between the clock's last reading and now can be measured to; anything else is
+     * measured to now. A frame's timestamp is when the frame began, so it can sit behind a reading
+     * taken earlier in that frame (a resume() from an input handler). And it is only on this
+     * clock's timeline where the environment keeps its promise that it is - jsdom stamps frames
+     * 1.5 s behind `performance.now()`, a `Date.now()` polyfill decades ahead - and measured to
+     * those, the clock froze or leapt.
+     * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+     * @returns {number} in seconds
+     */
+    getDeltaAt(time) {
+        if (this.__isRunning) {
+            const now = current_time_in_seconds();
+
+            updateElapsedTime(this, time >= this.__lastMeasurement && time <= now ? time : now);
+        }
+
+        const elapsedTime = this.elapsedTime;
         const delta = elapsedTime - this.timeAtDelta;
         this.timeAtDelta = elapsedTime;
         return delta;
@@ -118,7 +142,7 @@ class Clock {
      */
     updateElapsedTime() {
         if (this.__isRunning) {
-            updateElapsedTime(this);
+            updateElapsedTime(this, current_time_in_seconds());
         }
         return this.elapsedTime;
     }

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IAiGI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA2GC;IAqBD;;OAEG;IACH,sBAgEC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAt5B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAqCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IA4FI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OAiPjB;IAtSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;;MAKC;IA8BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA0GC;IAoBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA94B8B,+BAA+B;wBAWtC,wBAAwB;0BArBtB,0CAA0C;wCAeN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BAtBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BAUxE,0BAA0B;+BArBvB,iCAAiC;4CAapB,qDAAqD;AAgBjG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAvC4B,sCAAsC;sBA4B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BAFhC,kCAAkC;8BAClC,kCAAkC;sBAb1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -86,11 +86,6 @@ class Engine {
      */
     #last_render_simulation_time = 0;
 
-    /**
-     * Handle of the pending render-loop frame, `-1` when the loop is not running
-     * @type {number}
-     */
-    #animation_frame_handle = -1;
 
     /**
      * Handle of the pending "pause the simulation, this outage is taking a while" timer, `-1` when none
@@ -699,14 +694,14 @@ class Engine {
              scene's speed modifiers (see SceneManager), so a paused game holds its particles still
              and a slowed one slows them. A wall-clock measurement would do neither.
 
-             `updateElapsedTime` advances the clock and reads it without touching the anchor
-             `getDelta` keeps, so this does not consume the delta the entity manager's tick is
-             about to be handed.
+             Read, not advanced: a frame draws right after the ticker advanced the clock to the
+             frame's timestamp (see Ticker#onFrame), so this is the simulation time of the frame.
+             Advancing it here would step the renderer by however long that tick took to run.
 
              Moved only when a frame is actually drawn, so simulation time that passes while
              rendering is off is caught up by the next frame rather than lost.
             */
-            const simulation_time = this.ticker.clock.updateElapsedTime();
+            const simulation_time = this.ticker.clock.getElapsedTime();
             const time_delta_seconds = simulation_time - this.#last_render_simulation_time;
 
             this.#last_render_simulation_time = simulation_time;
@@ -781,10 +776,9 @@ class Engine {
 
             this.#last_frame_timestamp = performance.now();
 
-            /**
-             * Starting the engine
-             */
-            this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
+            // Drawn from the ticker's frame, after that frame's tick. A render loop of its own drew
+            // each frame before the tick, i.e. the simulation as of whenever the previous tick ran.
+            this.ticker.onFrame.add(this.#animation_frame);
 
             //start simulation
             this.ticker.start({ maxTimeout: 200 });
@@ -835,13 +829,12 @@ class Engine {
     }
 
     /**
-     * Fired every animation frame via {@link requestAnimationFrame}
+     * Fired every animation frame via {@link Ticker#onFrame}
      */
     #animation_frame = () => {
 
         const t0 = this.#last_frame_timestamp;
         const t1 = performance.now();
-        this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
         this.render();
 
         const frame_delay = (t1 - t0) / 1000;
@@ -865,10 +858,9 @@ class Engine {
         // running, which would abort the whole teardown below
         this.ticker.stop();
 
-        // and the render loop, which re-requests itself every frame and would
-        // otherwise keep calling render() on a torn-down engine forever
-        cancelAnimationFrame(this.#animation_frame_handle);
-        this.#animation_frame_handle = -1;
+        // which also ends the render loop, as it draws from the ticker's frames. Unsubscribed too,
+        // so a restart does not draw twice per frame
+        this.ticker.onFrame.remove(this.#animation_frame);
 
         // the input devices the constructor started. The gamepad one polls on its own animation
         // frame loop, so left alone it outlives the engine the same way the render loop would;

package/src/engine/ecs/ik/IKGoalSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IKGoalSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoalSystem.js"],"names":[],"mappings":"AAyOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;;IAEI,6DAA6C;IAE7C,kbASE;IAEF;;;OAGG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAkDjB;;;;OAIG;IACH,WAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAgChB;IAED;;;;OAIG;IACH,aAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAkBhB;IAED,sCA+BC;;CA6nBJ;uBA1hCsB,cAAc;oCAED,gDAAgD;uBAQ7D,aAAa;4BAD7B,6BAA6B;4CA1BQ,oDAAoD;yCAEvD,uDAAuD;0BAQtE,2BAA2B;kCAEnB,6BAA6B;6BAIlC,2BAA2B;sBAPlC,4BAA4B"}
+{"version":3,"file":"IKGoalSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/ik/IKGoalSystem.js"],"names":[],"mappings":"AA0OA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;;IAEI,6DAA6C;IAE7C,kbASE;IAEF;;;OAGG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,WAFU,MAAM,CAEC;IAkDjB;;;;OAIG;IACH,WAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAgChB;IAED;;;;OAIG;IACH,aAJW,MAAM,cACN,mBAAmB,UACnB,MAAM,QAkBhB;IAED,sCA+BC;;CA6nBJ;uBA1hCsB,cAAc;oCAED,gDAAgD;uBAQ7D,aAAa;4BAD7B,6BAA6B;4CA3BQ,oDAAoD;yCAEvD,uDAAuD;0BAQtE,2BAA2B;kCAEnB,6BAA6B;6BAIlC,2BAA2B;sBAPlC,4BAA4B"}

package/src/engine/ecs/ik/IKGoalSystem.js

@@ -19,6 +19,7 @@ import { GPUStateAuthorityFlags } from "../gpu/GPUStateAuthorityFlags.js";
 import { gpu_authority_hold } from "../gpu/gpu_authority_hold.js";
 import { gpu_authority_unhold } from "../gpu/gpu_authority_unhold.js";
 import { ParentEntity } from "../parent/ParentEntity.js";
+import { parent_entity_model_of } from "../parent/parent_entity_model_of.js";
 import { System } from "../System.js";
 import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
 import { TransformAttachment } from "../transform-attachment/TransformAttachment.js";
@@ -354,8 +355,8 @@ export class IKGoalSystem extends System {
         record.entity = entity;
         record.goal = goal;
         record.system = this;
-        record.model = model_of(dataset, entity);
-        record.target_model = dataset.entityExists(goal.target) ? model_of(dataset, goal.target) : -1;
+        record.model = parent_entity_model_of(dataset, entity);
+        record.target_model = dataset.entityExists(goal.target) ? parent_entity_model_of(dataset, goal.target) : -1;
 
         this.#records.set(entity, record);
 
@@ -1071,23 +1072,6 @@ export class IKGoalSystem extends System {
     }
 }
 
-/**
- * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
- *
- * @param {EntityComponentDataset} dataset
- * @param {number} entity
- * @returns {number}
- */
-function model_of(dataset, entity) {
-    const owner = dataset.getComponent(entity, ParentEntity);
-
-    if (owner === undefined || owner === null) {
-        return entity;
-    }
-
-    return owner.entity;
-}
-
 /**
  * Goals grouped by connected paths: two goals whose paths share a bone are solved together.
  *

package/src/engine/ecs/parent/parent_entity_model_of.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
+ *
+ * A placed model's bones each carry a {@link ParentEntity} naming the model's root, and the root is
+ * where the model's clips and animation drivers live. So the model of a bone is one step up the
+ * lifetime edge, and an entity without one — a root, a prop, a hand-made rig — is its own model.
+ *
+ * One step, not a walk to the top: a model placed under another model is still its own model, with
+ * its own clips.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number} the model entity; `entity` itself when it has no {@link ParentEntity}, or one
+ * naming no entity yet (`-1`)
+ */
+export function parent_entity_model_of(dataset: EntityComponentDataset, entity: number): number;
+//# sourceMappingURL=parent_entity_model_of.d.ts.map

package/src/engine/ecs/parent/parent_entity_model_of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parent_entity_model_of.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/parent/parent_entity_model_of.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,gFAJW,MAAM,GACJ,MAAM,CAWlB"}

package/src/engine/ecs/parent/parent_entity_model_of.js

@@ -0,0 +1,26 @@
+import { ParentEntity } from "./ParentEntity.js";
+
+/**
+ * The entity whose clips drive `entity`: the model its lifetime belongs to, or itself.
+ *
+ * A placed model's bones each carry a {@link ParentEntity} naming the model's root, and the root is
+ * where the model's clips and animation drivers live. So the model of a bone is one step up the
+ * lifetime edge, and an entity without one — a root, a prop, a hand-made rig — is its own model.
+ *
+ * One step, not a walk to the top: a model placed under another model is still its own model, with
+ * its own clips.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number} the model entity; `entity` itself when it has no {@link ParentEntity}, or one
+ * naming no entity yet (`-1`)
+ */
+export function parent_entity_model_of(dataset, entity) {
+    const owner = dataset.getComponent(entity, ParentEntity);
+
+    if (owner === undefined || owner === null || owner.entity < 0) {
+        return entity;
+    }
+
+    return owner.entity;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Pack a transform's rigid pose, `[tx, ty, tz, qx, qy, qz, qw]`, into an array: the translation and
+ * the rotation, without the scale or the matrix.
+ *
+ * Seven floats is the shape a contact kernel, an oriented box transform or a cloth holder takes a
+ * pose in. Read off the transform's lanes (a {@link Transform64} is a `Float64Array`) rather than
+ * through `translation_x` and the rest: a hot caller that does not inline those accessor calls gets
+ * each number back boxed, and the vector getters allocate outright.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset receives 7 floats
+ * @param {Transform64|Float64Array} transform a `Transform64`, or an array in its layout
+ */
+export function t64_read_pose_array(out: number[] | Float32Array | Float64Array, out_offset: number, transform: Transform64 | Float64Array): void;
+//# sourceMappingURL=t64_read_pose_array.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"t64_read_pose_array.d.ts","sourceRoot":"","sources":["../../../../../src/engine/ecs/transform/t64_read_pose_array.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,yCAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,cAClC,MAAM,aACN,cAAY,YAAY,QAUlC"}

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

@@ -0,0 +1,24 @@
+import { TRANSFORM64_ROTATION_OFFSET, TRANSFORM64_TRANSLATION_OFFSET } from "./Transform64.js";
+
+/**
+ * Pack a transform's rigid pose, `[tx, ty, tz, qx, qy, qz, qw]`, into an array: the translation and
+ * the rotation, without the scale or the matrix.
+ *
+ * Seven floats is the shape a contact kernel, an oriented box transform or a cloth holder takes a
+ * pose in. Read off the transform's lanes (a {@link Transform64} is a `Float64Array`) rather than
+ * through `translation_x` and the rest: a hot caller that does not inline those accessor calls gets
+ * each number back boxed, and the vector getters allocate outright.
+ *
+ * @param {number[]|Float32Array|Float64Array} out
+ * @param {number} out_offset receives 7 floats
+ * @param {Transform64|Float64Array} transform a `Transform64`, or an array in its layout
+ */
+export function t64_read_pose_array(out, out_offset, transform) {
+    out[out_offset] = transform[TRANSFORM64_TRANSLATION_OFFSET];
+    out[out_offset + 1] = transform[TRANSFORM64_TRANSLATION_OFFSET + 1];
+    out[out_offset + 2] = transform[TRANSFORM64_TRANSLATION_OFFSET + 2];
+    out[out_offset + 3] = transform[TRANSFORM64_ROTATION_OFFSET];
+    out[out_offset + 4] = transform[TRANSFORM64_ROTATION_OFFSET + 1];
+    out[out_offset + 5] = transform[TRANSFORM64_ROTATION_OFFSET + 2];
+    out[out_offset + 6] = transform[TRANSFORM64_ROTATION_OFFSET + 3];
+}

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How the geometry on this entity deforms: the joints its vertices are weighted to, as entities,
+ * and where each joint stood when the mesh was bound to it.
+ *
+ * **It describes the mesh, so it lives on the mesh entity.** The geometry's per-vertex joint indices
+ * index {@link joints}, and an inverse bind belongs to the pair (this mesh, that joint) — one joint
+ * can bind with different matrices in different skins. The joints are entities like any other: a
+ * clip, IK, a ragdoll or a cloth moves them, and the skin follows.
+ *
+ * The geometry beside it says it draws a deformed clone (`ShadedGeometryFlags.Skinned`); without
+ * that it draws the shared source and nothing would deform. `MeshSkinSystem` deforms it; a model
+ * loaded by `MeshSystem` carries one on each skinned primitive, and code builds one the same way.
+ *
+ * **Replaced, never edited.** A skin is registered once with the joints and matrices it has then;
+ * to change either, take the component off and put another on. Meshes of one model that share a
+ * skeleton and bind it the same way — a body and its hair — share one registration on the GPU,
+ * whether or not they share the arrays.
+ *
+ * **Not saved**, for the reason {@link ShadedGeometry} is not: the joint indices address the vertex
+ * attribute of a geometry no save holds, so whatever builds the geometry builds its skin.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MeshSkin {
+    /**
+     * @param {Int32Array} joints entities
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16
+     * @returns {MeshSkin}
+     */
+    static from(joints: Int32Array, inverse_bind_matrices: Float32Array): MeshSkin;
+    /**
+     * The joints, as entities, in the order the geometry's per-vertex joint indices address them.
+     * Read-only once the component is on an entity.
+     *
+     * @type {Int32Array}
+     */
+    joints: Int32Array;
+    /**
+     * `joints.length` × 16 column-major matrices, flat: joint `j`'s at `[j * 16, j * 16 + 16)`, taking
+     * a vertex from the mesh's frame into the joint's at bind. Read-only, and shared — a model's
+     * placements all hold the one array their prefab compiled.
+     *
+     * @type {Float32Array}
+     */
+    inverse_bind_matrices: Float32Array;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isMeshSkin: boolean;
+}
+export namespace MeshSkin {
+    let typeName: string;
+    let serializable: boolean;
+}
+//# sourceMappingURL=MeshSkin.d.ts.map

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MeshSkin.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/mesh-v2/MeshSkin.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAkBI;;;;OAIG;IACH,oBAJW,UAAU,yBACV,YAAY,GACV,QAAQ,CAiBpB;IArCD;;;;;OAKG;IACH,QAFU,UAAU,CAEO;IAE3B;;;;;;OAMG;IACH,uBAFU,YAAY,CAEsB;IAyBhD;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAN5B;;kBAUS,MAAM;sBAMN,OAAO"}

package/src/engine/graphics/ecs/mesh-v2/MeshSkin.js

@@ -0,0 +1,84 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * How the geometry on this entity deforms: the joints its vertices are weighted to, as entities,
+ * and where each joint stood when the mesh was bound to it.
+ *
+ * **It describes the mesh, so it lives on the mesh entity.** The geometry's per-vertex joint indices
+ * index {@link joints}, and an inverse bind belongs to the pair (this mesh, that joint) — one joint
+ * can bind with different matrices in different skins. The joints are entities like any other: a
+ * clip, IK, a ragdoll or a cloth moves them, and the skin follows.
+ *
+ * The geometry beside it says it draws a deformed clone (`ShadedGeometryFlags.Skinned`); without
+ * that it draws the shared source and nothing would deform. `MeshSkinSystem` deforms it; a model
+ * loaded by `MeshSystem` carries one on each skinned primitive, and code builds one the same way.
+ *
+ * **Replaced, never edited.** A skin is registered once with the joints and matrices it has then;
+ * to change either, take the component off and put another on. Meshes of one model that share a
+ * skeleton and bind it the same way — a body and its hair — share one registration on the GPU,
+ * whether or not they share the arrays.
+ *
+ * **Not saved**, for the reason {@link ShadedGeometry} is not: the joint indices address the vertex
+ * attribute of a geometry no save holds, so whatever builds the geometry builds its skin.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class MeshSkin {
+    /**
+     * The joints, as entities, in the order the geometry's per-vertex joint indices address them.
+     * Read-only once the component is on an entity.
+     *
+     * @type {Int32Array}
+     */
+    joints = new Int32Array(0);
+
+    /**
+     * `joints.length` × 16 column-major matrices, flat: joint `j`'s at `[j * 16, j * 16 + 16)`, taking
+     * a vertex from the mesh's frame into the joint's at bind. Read-only, and shared — a model's
+     * placements all hold the one array their prefab compiled.
+     *
+     * @type {Float32Array}
+     */
+    inverse_bind_matrices = new Float32Array(0);
+
+    /**
+     * @param {Int32Array} joints entities
+     * @param {Float32Array} inverse_bind_matrices `joints.length` × 16
+     * @returns {MeshSkin}
+     */
+    static from(joints, inverse_bind_matrices) {
+        assert.equal(joints instanceof Int32Array, true, 'joints must be an Int32Array of entities');
+        assert.greaterThanOrEqual(joints.length, 1, 'a skin has at least one joint');
+        assert.equal(inverse_bind_matrices instanceof Float32Array, true, 'inverse_bind_matrices must be a Float32Array');
+        assert.equal(
+            inverse_bind_matrices.length, joints.length * 16,
+            'inverse_bind_matrices.length !== joints.length * 16'
+        );
+
+        const r = new MeshSkin();
+
+        r.joints = joints;
+        r.inverse_bind_matrices = inverse_bind_matrices;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+MeshSkin.prototype.isMeshSkin = true;
+
+/**
+ * @readonly
+ * @type {string}
+ */
+MeshSkin.typeName = "MeshSkin";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+MeshSkin.serializable = false;