@woosh/meep-engine 2.147.0 → 2.148.0

package/src/engine/physics/body/SolverBodyState.d.ts

@@ -0,0 +1,142 @@
+/**
+ * # SolverBodyState — data-oriented mirror of the per-body solver hot state
+ *
+ * The TGS substep window (contact solver, joint solver, gravity / position
+ * integration) reads and writes a small, fixed set of per-body quantities
+ * thousands of times per step: linear / angular velocity, inverse mass,
+ * inverse-inertia diagonal, and orientation. In the object world those live on
+ * the {@link RigidBody} and {@link Transform} *components*, reached via
+ * `system.__bodies[idx]` / `system.__transforms[idx]` — a chain of pointer
+ * dereferences (array → component object → `Vector3` field) on the hottest
+ * inner loop in the engine.
+ *
+ * This class packs exactly those quantities into one ArrayBuffer-backed,
+ * stride-{@link SBS_STRIDE} `Float64Array` indexed by **body slot index** (the
+ * same index the rest of the physics system already uses). A body's whole
+ * solver state sits in one contiguous span, so the solver reads it with flat
+ * typed-array indexing and no object dereference.
+ *
+ * ## Lifecycle within one `fixedUpdate`
+ *
+ *  - {@link begin} once, after islands are built: ensures capacity and rolls
+ *    the per-step gather stamp.
+ *  - {@link gather} every body referenced this step (the awake set + the
+ *    static / kinematic anchors referenced by contacts and joints). Idempotent
+ *    per step via the stamp, so callers may gather the same body redundantly.
+ *    MUST run after the once-per-step force integration (so the gathered
+ *    velocity is post-force) and before any substep stage reads it.
+ *  - the substep loop mutates `data` in place.
+ *  - {@link scatter} once at the end: write the persistent linear / angular
+ *    velocity back to each gathered body's `RigidBody`. Pose is NOT scattered
+ *    here — `integrate_position` keeps the authoritative pose on the
+ *    `Transform` (write-through, so its `onChanged` subscribers and the
+ *    per-substep concave re-detection still see the moved pose); the
+ *    orientation quaternion is mirrored into `data` purely for the impulse
+ *    loop's world-inverse-inertia evaluation.
+ *
+ * ## Material content
+ *
+ * For Static / Kinematic bodies `invMass` and the inverse-inertia diagonal are
+ * stored as **zero** regardless of the component values — the solver treats
+ * "no inverse mass / no inverse inertia" as immovable, which is exactly how the
+ * object path's `kind !== Dynamic` guards behave. Velocity is mirrored as-is
+ * (a kinematic mover carries a real velocity the contact rows must see; a
+ * static reads zero). Scattering velocity back to a non-dynamic body is a
+ * no-op in value (the solver never moves it), so scatter need not special-case.
+ *
+ * The arithmetic the solver performs on this data is identical to the object
+ * path — only the *source of the operands* changes — so the engine's
+ * same-runtime bit-identical determinism contract is preserved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/** Inverse mass (0 for Static / Kinematic). */
+export const SBS_INV_MASS: 0;
+/** Inverse-inertia diagonal, body-local principal frame (0,0,0 for non-dynamic). */
+export const SBS_INV_I_X: 1;
+export const SBS_INV_I_Y: 2;
+export const SBS_INV_I_Z: 3;
+/** Orientation quaternion (mirrors `transform.rotation`, refreshed per substep). */
+export const SBS_QX: 4;
+export const SBS_QY: 5;
+export const SBS_QZ: 6;
+export const SBS_QW: 7;
+/** Persistent linear velocity. */
+export const SBS_LV_X: 8;
+export const SBS_LV_Y: 9;
+export const SBS_LV_Z: 10;
+/** Persistent angular velocity. */
+export const SBS_AV_X: 11;
+export const SBS_AV_Y: 12;
+export const SBS_AV_Z: 13;
+/** Doubles per body. */
+export const SBS_STRIDE: 14;
+export class SolverBodyState {
+    constructor(initial_capacity?: number);
+    /**
+     * Interleaved per-body state, `slot_index * SBS_STRIDE + field`.
+     * @type {Float64Array}
+     */
+    data: Float64Array;
+    /**
+     * Per-body "gathered this step" stamp; equals {@link __gen} when the
+     * body's slot has been gathered in the current step.
+     * @private
+     * @type {Int32Array}
+     */
+    private __stamp;
+    /**
+     * Dense list of slot indices gathered this step, for {@link scatter}.
+     * @private
+     * @type {Uint32Array}
+     */
+    private __gathered;
+    /** @private */
+    private __gathered_count;
+    /**
+     * Monotonic per-step generation. {@link begin} increments it so the
+     * previous step's stamps are stale without an O(n) clear.
+     * @private
+     */
+    private __gen;
+    /** @private */
+    private __capacity;
+    /**
+     * Number of bodies gathered in the current step.
+     * @returns {number}
+     */
+    get gathered_count(): number;
+    /**
+     * Ensure the typed arrays can index slot `[0, hwm)` and roll the per-step
+     * gather state. Call once per `fixedUpdate`, after islands are built.
+     *
+     * @param {number} hwm body-storage high-water mark
+     */
+    begin(hwm: number): void;
+    /**
+     * Mirror one body's solver state into `data` if not already gathered this
+     * step. Idempotent per step. Reads the body's current (post-force)
+     * velocity and current pose.
+     *
+     * @param {number} idx body slot index
+     * @param {RigidBody} rb
+     * @param {Transform} transform
+     */
+    gather(idx: number, rb: RigidBody, transform: Transform): void;
+    /**
+     * Write the solved persistent linear / angular velocity back onto every
+     * gathered body's `RigidBody`. Direct typed-array writes into the
+     * `Vector3` backing — the same observer-bypassing path the solver already
+     * uses for velocity (`lv[0] += …`), so no `onChanged` semantics change.
+     *
+     * @param {RigidBody[]} bodies sparse, indexed by slot
+     */
+    scatter(bodies: RigidBody[]): void;
+    /**
+     * @private
+     * @param {number} hwm
+     */
+    private __grow;
+}
+//# sourceMappingURL=SolverBodyState.d.ts.map

package/src/engine/physics/body/SolverBodyState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SolverBodyState.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/body/SolverBodyState.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,+CAA+C;AAC/C,6BAA8B;AAC9B,oFAAoF;AACpF,4BAA6B;AAC7B,4BAA6B;AAC7B,4BAA6B;AAC7B,oFAAoF;AACpF,uBAAwB;AACxB,uBAAwB;AACxB,uBAAwB;AACxB,uBAAwB;AACxB,kCAAkC;AAClC,yBAA0B;AAC1B,yBAA0B;AAC1B,0BAA2B;AAC3B,mCAAmC;AACnC,0BAA2B;AAC3B,0BAA2B;AAC3B,0BAA2B;AAE3B,wBAAwB;AACxB,4BAA6B;AAE7B;IACI,uCAoCC;IAjCG;;;OAGG;IACH,MAFU,YAAY,CAEwB;IAE9C;;;;;OAKG;IACH,gBAAkC;IAElC;;;;OAIG;IACH,mBAAsC;IAEtC,eAAe;IACf,yBAAyB;IAEzB;;;;OAIG;IACH,cAAc;IAEd,eAAe;IACf,mBAAqB;IAGzB;;;OAGG;IACH,6BAEC;IAED;;;;;OAKG;IACH,WAFW,MAAM,QAiBhB;IAED;;;;;;;;OAQG;IACH,YAJW,MAAM,6CA8ChB;IAED;;;;;;;OAOG;IACH,gBAFW,WAAW,QAoBrB;IAED;;;OAGG;IACH,eAcC;CACJ"}

package/src/engine/physics/body/SolverBodyState.js

@@ -0,0 +1,251 @@
+import { ceilPowerOfTwo } from "../../../core/binary/operations/ceilPowerOfTwo.js";
+import { BodyKind } from "../ecs/BodyKind.js";
+
+/**
+ * # SolverBodyState — data-oriented mirror of the per-body solver hot state
+ *
+ * The TGS substep window (contact solver, joint solver, gravity / position
+ * integration) reads and writes a small, fixed set of per-body quantities
+ * thousands of times per step: linear / angular velocity, inverse mass,
+ * inverse-inertia diagonal, and orientation. In the object world those live on
+ * the {@link RigidBody} and {@link Transform} *components*, reached via
+ * `system.__bodies[idx]` / `system.__transforms[idx]` — a chain of pointer
+ * dereferences (array → component object → `Vector3` field) on the hottest
+ * inner loop in the engine.
+ *
+ * This class packs exactly those quantities into one ArrayBuffer-backed,
+ * stride-{@link SBS_STRIDE} `Float64Array` indexed by **body slot index** (the
+ * same index the rest of the physics system already uses). A body's whole
+ * solver state sits in one contiguous span, so the solver reads it with flat
+ * typed-array indexing and no object dereference.
+ *
+ * ## Lifecycle within one `fixedUpdate`
+ *
+ *  - {@link begin} once, after islands are built: ensures capacity and rolls
+ *    the per-step gather stamp.
+ *  - {@link gather} every body referenced this step (the awake set + the
+ *    static / kinematic anchors referenced by contacts and joints). Idempotent
+ *    per step via the stamp, so callers may gather the same body redundantly.
+ *    MUST run after the once-per-step force integration (so the gathered
+ *    velocity is post-force) and before any substep stage reads it.
+ *  - the substep loop mutates `data` in place.
+ *  - {@link scatter} once at the end: write the persistent linear / angular
+ *    velocity back to each gathered body's `RigidBody`. Pose is NOT scattered
+ *    here — `integrate_position` keeps the authoritative pose on the
+ *    `Transform` (write-through, so its `onChanged` subscribers and the
+ *    per-substep concave re-detection still see the moved pose); the
+ *    orientation quaternion is mirrored into `data` purely for the impulse
+ *    loop's world-inverse-inertia evaluation.
+ *
+ * ## Material content
+ *
+ * For Static / Kinematic bodies `invMass` and the inverse-inertia diagonal are
+ * stored as **zero** regardless of the component values — the solver treats
+ * "no inverse mass / no inverse inertia" as immovable, which is exactly how the
+ * object path's `kind !== Dynamic` guards behave. Velocity is mirrored as-is
+ * (a kinematic mover carries a real velocity the contact rows must see; a
+ * static reads zero). Scattering velocity back to a non-dynamic body is a
+ * no-op in value (the solver never moves it), so scatter need not special-case.
+ *
+ * The arithmetic the solver performs on this data is identical to the object
+ * path — only the *source of the operands* changes — so the engine's
+ * same-runtime bit-identical determinism contract is preserved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Inverse mass (0 for Static / Kinematic). */
+export const SBS_INV_MASS = 0;
+/** Inverse-inertia diagonal, body-local principal frame (0,0,0 for non-dynamic). */
+export const SBS_INV_I_X = 1;
+export const SBS_INV_I_Y = 2;
+export const SBS_INV_I_Z = 3;
+/** Orientation quaternion (mirrors `transform.rotation`, refreshed per substep). */
+export const SBS_QX = 4;
+export const SBS_QY = 5;
+export const SBS_QZ = 6;
+export const SBS_QW = 7;
+/** Persistent linear velocity. */
+export const SBS_LV_X = 8;
+export const SBS_LV_Y = 9;
+export const SBS_LV_Z = 10;
+/** Persistent angular velocity. */
+export const SBS_AV_X = 11;
+export const SBS_AV_Y = 12;
+export const SBS_AV_Z = 13;
+
+/** Doubles per body. */
+export const SBS_STRIDE = 14;
+
+export class SolverBodyState {
+    constructor(initial_capacity = 16) {
+        const cap = ceilPowerOfTwo(Math.max(4, initial_capacity));
+
+        /**
+         * Interleaved per-body state, `slot_index * SBS_STRIDE + field`.
+         * @type {Float64Array}
+         */
+        this.data = new Float64Array(cap * SBS_STRIDE);
+
+        /**
+         * Per-body "gathered this step" stamp; equals {@link __gen} when the
+         * body's slot has been gathered in the current step.
+         * @private
+         * @type {Int32Array}
+         */
+        this.__stamp = new Int32Array(cap);
+
+        /**
+         * Dense list of slot indices gathered this step, for {@link scatter}.
+         * @private
+         * @type {Uint32Array}
+         */
+        this.__gathered = new Uint32Array(cap);
+
+        /** @private */
+        this.__gathered_count = 0;
+
+        /**
+         * Monotonic per-step generation. {@link begin} increments it so the
+         * previous step's stamps are stale without an O(n) clear.
+         * @private
+         */
+        this.__gen = 0;
+
+        /** @private */
+        this.__capacity = cap;
+    }
+
+    /**
+     * Number of bodies gathered in the current step.
+     * @returns {number}
+     */
+    get gathered_count() {
+        return this.__gathered_count;
+    }
+
+    /**
+     * Ensure the typed arrays can index slot `[0, hwm)` and roll the per-step
+     * gather state. Call once per `fixedUpdate`, after islands are built.
+     *
+     * @param {number} hwm body-storage high-water mark
+     */
+    begin(hwm) {
+        if (hwm > this.__capacity) {
+            this.__grow(hwm);
+        }
+
+        // Roll the generation; on (astronomically unlikely) Int32 wrap, clear
+        // stamps so a recycled generation value can't read as "gathered".
+        const next = (this.__gen + 1) | 0;
+        if (next <= 0) {
+            this.__stamp.fill(0);
+            this.__gen = 1;
+        } else {
+            this.__gen = next;
+        }
+        this.__gathered_count = 0;
+    }
+
+    /**
+     * Mirror one body's solver state into `data` if not already gathered this
+     * step. Idempotent per step. Reads the body's current (post-force)
+     * velocity and current pose.
+     *
+     * @param {number} idx body slot index
+     * @param {RigidBody} rb
+     * @param {Transform} transform
+     */
+    gather(idx, rb, transform) {
+        const stamp = this.__stamp;
+        if (stamp[idx] === this.__gen) {
+            return;
+        }
+        stamp[idx] = this.__gen;
+        this.__gathered[this.__gathered_count++] = idx;
+
+        const d = this.data;
+        const base = idx * SBS_STRIDE;
+
+        const dynamic = rb.kind === BodyKind.Dynamic;
+        if (dynamic) {
+            d[base + SBS_INV_MASS] = rb.mass > 0 ? 1 / rb.mass : 0;
+            const ii = rb.inverseInertiaLocal;
+            d[base + SBS_INV_I_X] = ii.x;
+            d[base + SBS_INV_I_Y] = ii.y;
+            d[base + SBS_INV_I_Z] = ii.z;
+        } else {
+            // Static / Kinematic: immovable to the solver — no inverse mass,
+            // no inverse inertia (mirrors the object path's `kind` guards).
+            d[base + SBS_INV_MASS] = 0;
+            d[base + SBS_INV_I_X] = 0;
+            d[base + SBS_INV_I_Y] = 0;
+            d[base + SBS_INV_I_Z] = 0;
+        }
+
+        const q = transform.rotation;
+        d[base + SBS_QX] = q[0];
+        d[base + SBS_QY] = q[1];
+        d[base + SBS_QZ] = q[2];
+        d[base + SBS_QW] = q[3];
+
+        const lv = rb.linearVelocity;
+        d[base + SBS_LV_X] = lv[0];
+        d[base + SBS_LV_Y] = lv[1];
+        d[base + SBS_LV_Z] = lv[2];
+
+        const av = rb.angularVelocity;
+        d[base + SBS_AV_X] = av[0];
+        d[base + SBS_AV_Y] = av[1];
+        d[base + SBS_AV_Z] = av[2];
+    }
+
+    /**
+     * Write the solved persistent linear / angular velocity back onto every
+     * gathered body's `RigidBody`. Direct typed-array writes into the
+     * `Vector3` backing — the same observer-bypassing path the solver already
+     * uses for velocity (`lv[0] += …`), so no `onChanged` semantics change.
+     *
+     * @param {RigidBody[]} bodies sparse, indexed by slot
+     */
+    scatter(bodies) {
+        const d = this.data;
+        const list = this.__gathered;
+        const n = this.__gathered_count;
+        for (let i = 0; i < n; i++) {
+            const idx = list[i];
+            const rb = bodies[idx];
+            if (rb === undefined) continue;
+            const base = idx * SBS_STRIDE;
+            const lv = rb.linearVelocity;
+            lv[0] = d[base + SBS_LV_X];
+            lv[1] = d[base + SBS_LV_Y];
+            lv[2] = d[base + SBS_LV_Z];
+            const av = rb.angularVelocity;
+            av[0] = d[base + SBS_AV_X];
+            av[1] = d[base + SBS_AV_Y];
+            av[2] = d[base + SBS_AV_Z];
+        }
+    }
+
+    /**
+     * @private
+     * @param {number} hwm
+     */
+    __grow(hwm) {
+        const cap = ceilPowerOfTwo(hwm);
+        const next_data = new Float64Array(cap * SBS_STRIDE);
+        const next_stamp = new Int32Array(cap);
+        const next_gathered = new Uint32Array(cap);
+        // No need to copy `data` — it is fully repopulated by `gather` each
+        // step before any read. `__stamp` must NOT carry stale gen values into
+        // the grown region; a fresh zero-filled array plus the live `__gen`
+        // (always >= 1 after begin) guarantees grown slots read as un-gathered.
+        next_stamp.set(this.__stamp);
+        this.data = next_data;
+        this.__stamp = next_stamp;
+        this.__gathered = next_gathered;
+        this.__capacity = cap;
+    }
+}

package/src/engine/physics/broadphase/generate_pairs.d.ts

@@ -28,11 +28,12 @@
  *        slot, no narrowphase, no contact events. Existing cached
  *        manifolds for a rejected pair time out naturally via the
  *        manifold-store grace counter.
+ * @param {*} [pair_filter_this_arg]
  */
 export function generate_pairs(storage: BodyStorage, dynamic_bvh: BVH, static_bvh: BVH, manifolds: ManifoldStore, body_collider_lists: Array<Array<{
     collider: Collider;
     transform: Transform;
     entity: number;
     bvhNode: number;
-}>>, pair_list_out: PairList, pair_filter?: (idA: number, idB: number) => boolean): void;
+}>>, pair_list_out: PairList, pair_filter?: (idA: number, idB: number) => boolean, pair_filter_this_arg?: any): void;
 //# sourceMappingURL=generate_pairs.d.ts.map

package/src/engine/physics/broadphase/generate_pairs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate_pairs.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/generate_pairs.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,uIARW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAY;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,+CAElF,MAAM,OAAO,MAAM,KAAK,OAAO,QA4EhD"}
+{"version":3,"file":"generate_pairs.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/broadphase/generate_pairs.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,uIATW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAY;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC,+CAElF,MAAM,OAAO,MAAM,KAAK,OAAO,oCA8EhD"}

package/src/engine/physics/broadphase/generate_pairs.js

@@ -34,6 +34,7 @@ const candidates = new Uint32Array(1024);
  *        slot, no narrowphase, no contact events. Existing cached
  *        manifolds for a rejected pair time out naturally via the
  *        manifold-store grace counter.
+ * @param {*} [pair_filter_this_arg]
  */
 export function generate_pairs(
     storage,
@@ -42,7 +43,8 @@ export function generate_pairs(
     manifolds,
     body_collider_lists,
     pair_list_out,
-    pair_filter = null
+    pair_filter = null,
+    pair_filter_this_arg = null,
 ) {
     pair_list_out.clear();
 
@@ -80,7 +82,7 @@ export function generate_pairs(
 
                 const existing = manifolds.find(idA, idB);
                 if (existing !== -1 && manifolds.is_touched(existing)) continue;
-                if (pair_filter !== null && !pair_filter(idA, idB)) continue;
+                if (pair_filter !== null && !pair_filter.call(pair_filter_this_arg, idA, idB)) continue;
                 manifolds.acquire(idA, idB);
                 pair_list_out.push(idA, idB);
             }
@@ -99,7 +101,7 @@ export function generate_pairs(
 
                 const existing = manifolds.find(idA, idB);
                 if (existing !== -1 && manifolds.is_touched(existing)) continue;
-                if (pair_filter !== null && !pair_filter(idA, idB)) continue;
+                if (pair_filter !== null && !pair_filter.call(pair_filter_this_arg, idA, idB)) continue;
                 manifolds.acquire(idA, idB);
                 pair_list_out.push(idA, idB);
             }

package/src/engine/physics/constraint/solve_constraints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AA+MA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAHW,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,OAC/D,YAAY,QAkCtB;AA0JD;;;;;;;;;;;;;GAaG;AACH,qCANW,OAAO,iCAEP,MAAM,SAEN,MAAM,QAsPhB"}
+{"version":3,"file":"solve_constraints.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/constraint/solve_constraints.js"],"names":[],"mappings":"AAiOA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAHW,MAAM,MAAa,MAAM,MAAa,MAAM,MAAa,MAAM,OAC/D,YAAY,QAkCtB;AA0JD;;;;;;;;;;;;;GAaG;AACH,qCANW,OAAO,iCAEP,MAAM,SAEN,MAAM,QAsPhB"}