@woosh/meep-engine 2.147.0 → 2.149.0

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

@@ -1,108 +1,110 @@
-import { assert } from "../../../core/assert.js";
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
-
-const scratch_aabb = new Float64Array(6);
-const candidates = new Uint32Array(1024);
-
-/**
- * Iterate every awake body, query both BVHs from each of its attached
- * collider leaves, dedupe via the {@link ManifoldStore}, optionally gate
- * each candidate through a user-supplied filter, and append each surviving
- * body-pair to `pair_list_out`.
- *
- * Compound-body aware: a body with multiple colliders has multiple BVH
- * leaves (one per collider). Each leaf's AABB query may turn up the same
- * other-body multiple times (across the multiple leaves on either side)
- * but the per-slot touched flag collapses those into one entry in the
- * canonical `(min, max)` pair list — narrowphase then resolves the
- * collider-cross-product internally.
- *
- * Determinism: pair encounter order is fully determined by the awake-list
- * order × per-body collider-list order × BVH leaf traversal order. All
- * three are deterministic functions of the link/unlink sequence and the
- * BVH state, so two worlds with the same scene history produce identical
- * pair lists.
- *
- * @param {BodyStorage} storage
- * @param {BVH} dynamic_bvh
- * @param {BVH} static_bvh
- * @param {ManifoldStore} manifolds
- * @param {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>} body_collider_lists
- * @param {PairList} pair_list_out cleared and filled
- * @param {((idA: number, idB: number) => boolean) | null} pair_filter optional
- *        gate. Returning `false` rejects the pair entirely — no manifold
- *        slot, no narrowphase, no contact events. Existing cached
- *        manifolds for a rejected pair time out naturally via the
- *        manifold-store grace counter.
- */
-export function generate_pairs(
-    storage,
-    dynamic_bvh,
-    static_bvh,
-    manifolds,
-    body_collider_lists,
-    pair_list_out,
-    pair_filter = null
-) {
-    pair_list_out.clear();
-
-    const awake_count = storage.awake_count;
-
-    for (let i = 0; i < awake_count; i++) {
-        const body_idx = storage.awake_at(i);
-        const list = body_collider_lists[body_idx];
-        if (list === undefined || list.length === 0) continue;
-
-        const gen = storage.generation_at(body_idx);
-        const my_packed = (body_idx << 8) | gen;
-
-        for (let k = 0; k < list.length; k++) {
-            const node = list[k].bvhNode;
-            dynamic_bvh.node_get_aabb(node, scratch_aabb);
-
-            // Dynamic ↔ Dynamic.
-            let n = bvh_query_user_data_overlaps_aabb(
-                candidates, 0,
-                dynamic_bvh,
-                scratch_aabb
-            );
-            // The BVH query writes leaves unconditionally — at capacity it both
-            // drops leaves (typed-array OOB writes no-op) AND returns a count
-            // past the buffer end, so the loop below would read `undefined`
-            // candidates and build garbage pairs. Guard the buffer size.
-            assert.lessThan(n, candidates.length, 'generate_pairs: dynamic broadphase overflowed the candidate buffer');
-            for (let c = 0; c < n; c++) {
-                const other = candidates[c];
-                if (other === my_packed) continue;
-
-                const idA = my_packed < other ? my_packed : other;
-                const idB = my_packed < other ? other : my_packed;
-
-                const existing = manifolds.find(idA, idB);
-                if (existing !== -1 && manifolds.is_touched(existing)) continue;
-                if (pair_filter !== null && !pair_filter(idA, idB)) continue;
-                manifolds.acquire(idA, idB);
-                pair_list_out.push(idA, idB);
-            }
-
-            // Dynamic ↔ Static.
-            n = bvh_query_user_data_overlaps_aabb(
-                candidates, 0,
-                static_bvh,
-                scratch_aabb
-            );
-            assert.lessThan(n, candidates.length, 'generate_pairs: static broadphase overflowed the candidate buffer');
-            for (let c = 0; c < n; c++) {
-                const other = candidates[c];
-                const idA = my_packed < other ? my_packed : other;
-                const idB = my_packed < other ? other : my_packed;
-
-                const existing = manifolds.find(idA, idB);
-                if (existing !== -1 && manifolds.is_touched(existing)) continue;
-                if (pair_filter !== null && !pair_filter(idA, idB)) continue;
-                manifolds.acquire(idA, idB);
-                pair_list_out.push(idA, idB);
-            }
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+
+const scratch_aabb = new Float64Array(6);
+const candidates = new Uint32Array(1024);
+
+/**
+ * Iterate every awake body, query both BVHs from each of its attached
+ * collider leaves, dedupe via the {@link ManifoldStore}, optionally gate
+ * each candidate through a user-supplied filter, and append each surviving
+ * body-pair to `pair_list_out`.
+ *
+ * Compound-body aware: a body with multiple colliders has multiple BVH
+ * leaves (one per collider). Each leaf's AABB query may turn up the same
+ * other-body multiple times (across the multiple leaves on either side)
+ * but the per-slot touched flag collapses those into one entry in the
+ * canonical `(min, max)` pair list — narrowphase then resolves the
+ * collider-cross-product internally.
+ *
+ * Determinism: pair encounter order is fully determined by the awake-list
+ * order × per-body collider-list order × BVH leaf traversal order. All
+ * three are deterministic functions of the link/unlink sequence and the
+ * BVH state, so two worlds with the same scene history produce identical
+ * pair lists.
+ *
+ * @param {BodyStorage} storage
+ * @param {BVH} dynamic_bvh
+ * @param {BVH} static_bvh
+ * @param {ManifoldStore} manifolds
+ * @param {Array<Array<{collider: Collider, transform: Transform, entity: number, bvhNode: number}>>} body_collider_lists
+ * @param {PairList} pair_list_out cleared and filled
+ * @param {((idA: number, idB: number) => boolean) | null} pair_filter optional
+ *        gate. Returning `false` rejects the pair entirely — no manifold
+ *        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,
+    dynamic_bvh,
+    static_bvh,
+    manifolds,
+    body_collider_lists,
+    pair_list_out,
+    pair_filter = null,
+    pair_filter_this_arg = null,
+) {
+    pair_list_out.clear();
+
+    const awake_count = storage.awake_count;
+
+    for (let i = 0; i < awake_count; i++) {
+        const body_idx = storage.awake_at(i);
+        const list = body_collider_lists[body_idx];
+        if (list === undefined || list.length === 0) continue;
+
+        const gen = storage.generation_at(body_idx);
+        const my_packed = (body_idx << 8) | gen;
+
+        for (let k = 0; k < list.length; k++) {
+            const node = list[k].bvhNode;
+            dynamic_bvh.node_get_aabb(node, scratch_aabb);
+
+            // Dynamic ↔ Dynamic.
+            let n = bvh_query_user_data_overlaps_aabb(
+                candidates, 0,
+                dynamic_bvh,
+                scratch_aabb
+            );
+            // The BVH query writes leaves unconditionally — at capacity it both
+            // drops leaves (typed-array OOB writes no-op) AND returns a count
+            // past the buffer end, so the loop below would read `undefined`
+            // candidates and build garbage pairs. Guard the buffer size.
+            assert.lessThan(n, candidates.length, 'generate_pairs: dynamic broadphase overflowed the candidate buffer');
+            for (let c = 0; c < n; c++) {
+                const other = candidates[c];
+                if (other === my_packed) continue;
+
+                const idA = my_packed < other ? my_packed : other;
+                const idB = my_packed < other ? other : my_packed;
+
+                const existing = manifolds.find(idA, idB);
+                if (existing !== -1 && manifolds.is_touched(existing)) 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);
+            }
+
+            // Dynamic ↔ Static.
+            n = bvh_query_user_data_overlaps_aabb(
+                candidates, 0,
+                static_bvh,
+                scratch_aabb
+            );
+            assert.lessThan(n, candidates.length, 'generate_pairs: static broadphase overflowed the candidate buffer');
+            for (let c = 0; c < n; c++) {
+                const other = candidates[c];
+                const idA = my_packed < other ? my_packed : other;
+                const idB = my_packed < other ? other : my_packed;
+
+                const existing = manifolds.find(idA, idB);
+                if (existing !== -1 && manifolds.is_touched(existing)) 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"}