@woosh/meep-engine 2.140.0 → 2.142.0

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js

@@ -108,9 +108,10 @@ const MIC_SIGMA = 0.25;
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Solid cells (mask = 0) are excluded from the system: their pressure stays at
- * whatever it was (typically 0), their entries in r, z, s, As stay 0, and they
- * contribute nothing to dot products.
+ * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
+ * fluid (mask = 0), both identified by `(mask & 63) === 0` — are excluded from
+ * the system: their pressure stays at whatever it was (typically 0), their
+ * entries in r, z, s, As stay 0, and they contribute nothing to dot products.
  *
  * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
  *     or with the previous step's solution to warm-start.
@@ -173,9 +174,12 @@ export function v3_grid_solve_pressure_pcg(
     // (Standard fluids practice — see Bridson §5.5. The alternative is to pin
     // one cell to a Dirichlet value and exclude it from the system, but mean
     // subtraction has the same effect with simpler bookkeeping.)
+    // A cell is a degree of freedom iff it has ≥1 fluid neighbour, i.e. any of
+    // the low 6 bits set. Solid cells (bit 7) and isolated fluid (all-zero) are
+    // both excluded by masking off bit 7 with & 63.
     let fluid_count = 0;
     for (let c = 0; c < cells; c++) {
-        if (neighbour_mask[c] !== 0) fluid_count++;
+        if ((neighbour_mask[c] & 63) !== 0) fluid_count++;
     }
     if (fluid_count === 0) {
         return;
@@ -193,7 +197,7 @@ export function v3_grid_solve_pressure_pcg(
     precon.fill(0);
     for (let c = 0; c < cells; c++) {
         const mask = neighbour_mask[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             continue;
         }
         const a_diag = POPCOUNT_6[mask];
@@ -246,7 +250,7 @@ export function v3_grid_solve_pressure_pcg(
 
     for (let c = 0; c < cells; c++) {
         const mask = neighbour_mask[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             r[c] = 0;
             continue;
         }
@@ -285,7 +289,7 @@ export function v3_grid_solve_pressure_pcg(
         let s_dot_As = 0;
         for (let c = 0; c < cells; c++) {
             const mask = neighbour_mask[c];
-            if (mask === 0) {
+            if ((mask & 63) === 0) {
                 As[c] = 0;
                 continue;
             }
@@ -379,11 +383,11 @@ export function v3_grid_solve_pressure_pcg(
 function subtract_mean_fluid(v, mask_array, cells, fluid_count) {
     let sum = 0;
     for (let c = 0; c < cells; c++) {
-        if (mask_array[c] !== 0) sum += v[c];
+        if ((mask_array[c] & 63) !== 0) sum += v[c];
     }
     const mean = sum / fluid_count;
     for (let c = 0; c < cells; c++) {
-        if (mask_array[c] !== 0) v[c] -= mean;
+        if ((mask_array[c] & 63) !== 0) v[c] -= mean;
     }
 }
 
@@ -391,7 +395,7 @@ function apply_preconditioner(r, z, precon, mask_array, cells, rx, slice) {
     // Forward solve L · y = r. Store y in z (we won't read z[c'] for c' > c).
     for (let c = 0; c < cells; c++) {
         const mask = mask_array[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             z[c] = 0;
             continue;
         }
@@ -410,7 +414,7 @@ function apply_preconditioner(r, z, precon, mask_array, cells, rx, slice) {
     // indices, processed first in reverse).
     for (let c = cells - 1; c >= 0; c--) {
         const mask = mask_array[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             continue;
         }
         let t = z[c]; // = y[c] from forward pass

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts

@@ -13,25 +13,28 @@
  * pressure (consistent with the Neumann condition used in the solve), which keeps the
  * flow tangent to the boundary.
  *
- * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
- * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
- * {@link FluidField.recomputeSolidNeighbourMask}). A set bit means "that neighbour is
- * fluid (in-bounds AND non-solid)", so a clear bit reflects the cell's own pressure —
- * folding the boundary check and the solid-neighbour check into one register-resident
- * bit-test per face. Encoding:
- *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
- *
- * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
- * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
- * opposite handling — the solid must be zeroed for no-slip, while the isolated fluid's
- * gradient already nets to zero (every face reflects its own pressure) and must be
- * left alone. `solid` is what tells them apart, so it stays.
+ * Everything this needs is read straight from `neighbour_mask`, the same pre-baked
+ * per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
+ * {@link FluidField.recomputeSolidNeighbourMask}). Encoding:
+ *
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid
+ *
+ * A set neighbour bit means "that neighbour is fluid (in-bounds AND non-solid)", so a
+ * clear bit reflects the cell's own pressure — folding the boundary check and the
+ * solid-neighbour check into one register-resident bit-test per face.
+ *
+ * Bit 7 carries the self-solid flag that used to require the separate `solid` array.
+ * The solve can't use the low 6 bits for this (a solid cell and an isolated fluid cell
+ * both have zero fluid-neighbour bits) but needs opposite handling here — the solid
+ * must be zeroed for no-slip, while the isolated fluid's gradient already nets to zero
+ * (every face reflects its own pressure) and must be left alone. Bit 7 distinguishes
+ * them, so a single mask read drives both the zeroing and the gradient.
  *
  * @param {Float32Array} vel_x          Mutated in place.
  * @param {Float32Array} vel_y          Mutated in place.
@@ -40,9 +43,8 @@
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
  * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
- *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ *     pressure solve uses; MUST be recomputed whenever the solid mask changes.
  */
-export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array, neighbour_mask: Uint8Array): void;
+export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, neighbour_mask: Uint8Array): void;
 //# sourceMappingURL=v3_grid_subtract_pressure_gradient.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,0DAXW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,kBACV,UAAU,QA8CpB"}
+{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAgDpB"}

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js

@@ -15,25 +15,28 @@ import { assert } from "../../../../core/assert.js";
  * pressure (consistent with the Neumann condition used in the solve), which keeps the
  * flow tangent to the boundary.
  *
- * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
- * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
- * {@link FluidField.recomputeSolidNeighbourMask}). A set bit means "that neighbour is
- * fluid (in-bounds AND non-solid)", so a clear bit reflects the cell's own pressure —
- * folding the boundary check and the solid-neighbour check into one register-resident
- * bit-test per face. Encoding:
+ * Everything this needs is read straight from `neighbour_mask`, the same pre-baked
+ * per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
+ * {@link FluidField.recomputeSolidNeighbourMask}). Encoding:
  *
- *     bit 0 (= 1)  : -x neighbour is fluid
- *     bit 1 (= 2)  : +x neighbour is fluid
- *     bit 2 (= 4)  : -y neighbour is fluid
- *     bit 3 (= 8)  : +y neighbour is fluid
- *     bit 4 (= 16) : -z neighbour is fluid
- *     bit 5 (= 32) : +z neighbour is fluid
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid
  *
- * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
- * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
- * opposite handling — the solid must be zeroed for no-slip, while the isolated fluid's
- * gradient already nets to zero (every face reflects its own pressure) and must be
- * left alone. `solid` is what tells them apart, so it stays.
+ * A set neighbour bit means "that neighbour is fluid (in-bounds AND non-solid)", so a
+ * clear bit reflects the cell's own pressure — folding the boundary check and the
+ * solid-neighbour check into one register-resident bit-test per face.
+ *
+ * Bit 7 carries the self-solid flag that used to require the separate `solid` array.
+ * The solve can't use the low 6 bits for this (a solid cell and an isolated fluid cell
+ * both have zero fluid-neighbour bits) but needs opposite handling here — the solid
+ * must be zeroed for no-slip, while the isolated fluid's gradient already nets to zero
+ * (every face reflects its own pressure) and must be left alone. Bit 7 distinguishes
+ * them, so a single mask read drives both the zeroing and the gradient.
  *
  * @param {Float32Array} vel_x          Mutated in place.
  * @param {Float32Array} vel_y          Mutated in place.
@@ -42,11 +45,10 @@ import { assert } from "../../../../core/assert.js";
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
  * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
- *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ *     pressure solve uses; MUST be recomputed whenever the solid mask changes.
  */
-export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, solid, neighbour_mask) {
+export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, neighbour_mask) {
     const cell_count = res_x * res_y * res_z;
     assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
     assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
@@ -65,7 +67,10 @@ export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure
             for (let x = 0; x < res_x; x++) {
                 const c = z_off + y_off + x;
 
-                if (solid[c] !== 0) {
+                const mask = neighbour_mask[c];
+
+                if (mask & 128) {
+                    // Solid cell (bit 7): enforce no-slip.
                     vel_x[c] = 0;
                     vel_y[c] = 0;
                     vel_z[c] = 0;
@@ -75,7 +80,6 @@ export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure
                 // A clear bit means the neighbour is out-of-bounds or solid; reflect
                 // the cell's own pressure so that face contributes 0 to the gradient,
                 // consistent with ∂p/∂n = 0 at the wall.
-                const mask = neighbour_mask[c];
                 const p_xm = (mask & 1)  ? pressure[c - 1]          : pressure[c];
                 const p_xp = (mask & 2)  ? pressure[c + 1]          : pressure[c];
                 const p_ym = (mask & 4)  ? pressure[c - res_x]      : pressure[c];

package/src/engine/physics/island/IslandBuilder.d.ts

@@ -117,8 +117,11 @@ export class IslandBuilder {
      * @param {ManifoldStore} manifolds
      * @param {RigidBody[]} bodies sparse, indexed by body index
      * @param {Array[]} body_collider_lists sparse, indexed by body index
+     * @param {Joint[]} joints live joints (sparse). Jointed dynamic-dynamic
+     *   bodies are unioned into the same island so a chain / ragdoll sleeps
+     *   and wakes as a unit. Callers with no joints pass an empty array.
      */
-    build(storage: BodyStorage, manifolds: ManifoldStore, bodies: RigidBody[], body_collider_lists: any[][]): void;
+    build(storage: BodyStorage, manifolds: ManifoldStore, bodies: RigidBody[], body_collider_lists: any[][], joints: Joint[]): void;
     /**
      * Fill `body_offsets` + `body_data` with awake dynamic bodies grouped
      * by island, sorted ascending within each island.

package/src/engine/physics/island/IslandBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyFI;;;;;OAKG;IACH,gCAUC;IAtGG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAqBvC;;;;;;;;OAQG;IACH,8DAHW,WAAW,uBACX,OAAO,QAuEjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BAwCC;IAED;;;;;;;;OAQG;IACH,yBAcC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}
+{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyFI;;;;;OAKG;IACH,gCAUC;IAtGG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAqBvC;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAgGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BAwCC;IAED;;;;;;;;OAQG;IACH,yBAcC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}

package/src/engine/physics/island/IslandBuilder.js

@@ -1,6 +1,8 @@
+import { ceilPowerOfTwo } from "../../../core/binary/operations/ceilPowerOfTwo.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import { BodyKind } from "../ecs/BodyKind.js";
 import { ColliderFlags } from "../ecs/ColliderFlags.js";
+import { JOINT_WORLD } from "../ecs/Joint.js";
 import { RigidBodyFlags } from "../ecs/RigidBodyFlags.js";
 import { uf_find, uf_init, uf_union } from "./union_find.js";
 
@@ -149,8 +151,11 @@ export class IslandBuilder {
      * @param {ManifoldStore} manifolds
      * @param {RigidBody[]} bodies sparse, indexed by body index
      * @param {Array[]} body_collider_lists sparse, indexed by body index
+     * @param {Joint[]} joints live joints (sparse). Jointed dynamic-dynamic
+     *   bodies are unioned into the same island so a chain / ragdoll sleeps
+     *   and wakes as a unit. Callers with no joints pass an empty array.
      */
-    build(storage, manifolds, bodies, body_collider_lists) {
+    build(storage, manifolds, bodies, body_collider_lists, joints) {
         const hwm = storage.high_water_mark;
         this.__ensure_body_capacity(hwm);
 
@@ -174,6 +179,29 @@ export class IslandBuilder {
             }
         }
 
+        // --- Pass 1b: union dynamic-dynamic bodies connected by a joint, so a
+        //     chain / ragdoll forms one island (and so sleeps/wakes as a unit).
+        //     Joint-to-world and joint-to-static/kinematic anchor the island
+        //     without enlarging it — same rule as a static contact. Stale joint
+        //     references (body unlinked / slot reused) are filtered by the
+        //     generation-checked `is_valid`. (Empty when the caller has no
+        //     joints — the loop is then a no-op.)
+        const jn = joints.length;
+        for (let i = 0; i < jn; i++) {
+            const joint = joints[i];
+            if (joint === undefined || joint === null) continue;
+            if (joint._bodyIdB === JOINT_WORLD) continue;
+            if (!storage.is_valid(joint._bodyIdA) || !storage.is_valid(joint._bodyIdB)) continue;
+            const idxA = body_id_index(joint._bodyIdA);
+            const idxB = body_id_index(joint._bodyIdB);
+            const rbA = bodies[idxA];
+            const rbB = bodies[idxB];
+            if (rbA === undefined || rbB === undefined) continue;
+            if (rbA.kind === BodyKind.Dynamic && rbB.kind === BodyKind.Dynamic) {
+                uf_union(parent, idxA, idxB);
+            }
+        }
+
         // --- Pass 2: collect distinct roots over awake dynamic bodies.
         const island_of_body = this.island_of_body;
         // Cheap reset: only the indices we may write are below hwm.
@@ -357,7 +385,7 @@ export class IslandBuilder {
      */
     __ensure_body_capacity(n) {
         if (this.parent.length < n) {
-            const cap = next_pow2(n);
+            const cap = ceilPowerOfTwo(n);
             this.parent = new Uint32Array(cap);
             this.island_of_body = new Int32Array(cap);
             this.__root_to_island = new Int32Array(cap);
@@ -371,7 +399,7 @@ export class IslandBuilder {
      */
     __ensure_island_count_capacity(n) {
         if (this.body_offsets.length < n + 1) {
-            const cap = next_pow2(n + 1);
+            const cap = ceilPowerOfTwo(n + 1);
             this.body_offsets = new Uint32Array(cap);
             this.contact_offsets = new Uint32Array(cap);
             this.__cursors = new Uint32Array(cap);
@@ -384,7 +412,7 @@ export class IslandBuilder {
      */
     __ensure_body_data_capacity(n) {
         if (this.body_data.length < n) {
-            this.body_data = new Uint32Array(next_pow2(n));
+            this.body_data = new Uint32Array(ceilPowerOfTwo(n));
         }
     }
 
@@ -394,18 +422,7 @@ export class IslandBuilder {
      */
     __ensure_contact_data_capacity(n) {
         if (this.contact_data.length < n) {
-            this.contact_data = new Uint32Array(next_pow2(n));
+            this.contact_data = new Uint32Array(ceilPowerOfTwo(n));
         }
     }
 }
-
-/**
- * @param {number} n
- * @returns {number}
- */
-function next_pow2(n) {
-    if (n <= 1) return 1;
-    let p = 1;
-    while (p < n) p <<= 1;
-    return p;
-}

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA+HA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA0anB;AAvhBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AAqJA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA8anB;AA3hBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}

package/src/engine/physics/narrowphase/box_box_manifold.js

@@ -39,6 +39,28 @@ const MAX_CONTACTS = 4;
 const CONTACT_STRIDE = 7;
 const PARALLEL_EPS_SQR = 1e-8;
 
+/**
+ * Reference-axis tie-break deadband. SAT picks the minimum-overlap axis, but
+ * for aligned boxes two axes (A's face normal and B's face normal along the
+ * contact direction) have *equal* overlap, so floating-point noise from a
+ * sub-degree wobble flips which one wins frame to frame. That flips the
+ * reference/incident assignment, which reorders the contact points, which
+ * flips the solver's Gauss-Seidel sweep order — injecting an alternating
+ * bias that makes symmetric stacks creep and never sleep.
+ *
+ * The deadband makes a later axis replace the current best only if it
+ * reduces the overlap by more than `best · TIE_REL + TIE_ABS`. Axes are
+ * tested A-faces, then B-faces, then edge-crosses, so ties resolve to the
+ * earlier axis (A's face, then a face over an edge) — a stable, consistent
+ * choice. Genuine minima (overlap smaller by more than the band) still win,
+ * so SAT correctness for non-aligned boxes is unchanged; only the
+ * noise-driven flip on near-perfect alignment is suppressed. Box2D's
+ * `b2CollidePolygons` uses the same relative+absolute hysteresis.
+ * @type {number}
+ */
+const TIE_REL = 0.02;
+const TIE_ABS = 1e-5;
+
 /**
  * Length of `out` required by {@link box_box_manifold}.
  * @type {number}
@@ -182,7 +204,11 @@ export function box_box_manifold(
         const dist = proj < 0 ? -proj : proj;
         const overlap = (rA + rB) - dist;
         if (overlap < 0) return true;
-        if (overlap < best_overlap) {
+        // Deadband: the first axis always wins; a later axis replaces it only
+        // if it reduces the overlap past the hysteresis band. This biases ties
+        // toward earlier-tested axes (A faces > B faces > edges) so aligned
+        // boxes pick a stable reference instead of flip-flopping on noise.
+        if (best_source === -1 || overlap < best_overlap - (best_overlap * TIE_REL + TIE_ABS)) {
             best_overlap = overlap;
             const sign = proj > 0 ? -1 : 1; // normal points B→A
             best_nx = ux * sign;

package/src/engine/physics/narrowphase/narrowphase_step.d.ts

@@ -14,4 +14,37 @@ export function narrowphase_step(pair_list: PairList, manifolds: ManifoldStore,
     collider: Collider;
     transform: Transform;
 }>>): void;
+/**
+ * Re-detect contact GEOMETRY for one existing manifold slot at the bodies'
+ * current poses, updating the witness points / normal / depth of the slot's
+ * existing contacts in place. Does NOT change the contact count, the
+ * feature ids, or the accumulated impulses — it only refreshes geometry.
+ *
+ * This is the per-substep concave path (TGS): for a contact pair involving a
+ * concave body, the contact *feature* (which triangle is deepest, and its
+ * normal) genuinely changes as the body rocks, so the solver's cheap analytic
+ * refresh — which freezes the feature for the whole outer step — pumps energy
+ * in. Re-running the narrowphase geometry each substep gives a fresh,
+ * correct normal so the body settles instead of rocking. Convex pairs keep
+ * the analytic refresh and never call this (their feature is stable).
+ *
+ * Matching is by feature id (stable per-triangle for the decomposition path),
+ * so a contact's geometry tracks the same triangle across substeps. A contact
+ * whose triangle isn't found this substep keeps its previous geometry (a rare
+ * transient; the once-per-frame {@link narrowphase_step} re-establishes the
+ * contact set next outer step). Count never changes here, so the solver's
+ * per-contact scratch (sized once at prepare) stays aligned.
+ *
+ * @param {ManifoldStore} manifolds
+ * @param {number} slot
+ * @param {Array<{collider: Collider, transform: Transform}>} list_a
+ * @param {Array<{collider: Collider, transform: Transform}>} list_b
+ */
+export function redetect_pair_geometry(manifolds: ManifoldStore, slot: number, list_a: Array<{
+    collider: Collider;
+    transform: Transform;
+}>, list_b: Array<{
+    collider: Collider;
+    transform: Transform;
+}>): void;
 //# sourceMappingURL=narrowphase_step.d.ts.map

package/src/engine/physics/narrowphase/narrowphase_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA6uCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA6uCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}

package/src/engine/physics/narrowphase/narrowphase_step.js

@@ -1420,3 +1420,78 @@ export function narrowphase_step(pair_list, manifolds, lists) {
         }
     }
 }
+
+/**
+ * Re-detect contact GEOMETRY for one existing manifold slot at the bodies'
+ * current poses, updating the witness points / normal / depth of the slot's
+ * existing contacts in place. Does NOT change the contact count, the
+ * feature ids, or the accumulated impulses — it only refreshes geometry.
+ *
+ * This is the per-substep concave path (TGS): for a contact pair involving a
+ * concave body, the contact *feature* (which triangle is deepest, and its
+ * normal) genuinely changes as the body rocks, so the solver's cheap analytic
+ * refresh — which freezes the feature for the whole outer step — pumps energy
+ * in. Re-running the narrowphase geometry each substep gives a fresh,
+ * correct normal so the body settles instead of rocking. Convex pairs keep
+ * the analytic refresh and never call this (their feature is stable).
+ *
+ * Matching is by feature id (stable per-triangle for the decomposition path),
+ * so a contact's geometry tracks the same triangle across substeps. A contact
+ * whose triangle isn't found this substep keeps its previous geometry (a rare
+ * transient; the once-per-frame {@link narrowphase_step} re-establishes the
+ * contact set next outer step). Count never changes here, so the solver's
+ * per-contact scratch (sized once at prepare) stays aligned.
+ *
+ * @param {ManifoldStore} manifolds
+ * @param {number} slot
+ * @param {Array<{collider: Collider, transform: Transform}>} list_a
+ * @param {Array<{collider: Collider, transform: Transform}>} list_b
+ */
+export function redetect_pair_geometry(manifolds, slot, list_a, list_b) {
+    if (list_a === undefined || list_b === undefined) return;
+    const la_len = list_a.length;
+    const lb_len = list_b.length;
+    if (la_len === 0 || lb_len === 0) return;
+
+    const count = manifolds.contact_count(slot);
+    if (count === 0) return;
+
+    const gjk_axis_buf = manifolds.slot_axis_buffer;
+    const gjk_axis_off = manifolds.slot_axis_offset(slot);
+
+    let cc = 0;
+    for (let a = 0; a < la_len; a++) {
+        const ea = list_a[a];
+        for (let b = 0; b < lb_len; b++) {
+            const eb = list_b[b];
+            cc = dispatch_pair(cc, ea.collider, ea.transform, eb.collider, eb.transform,
+                gjk_axis_buf, gjk_axis_off);
+        }
+    }
+    if (cc === 0) return; // nothing re-detected this substep — keep frozen geometry
+
+    const data = manifolds.data_buffer;
+    const slot_off = manifolds.slot_data_offset(slot);
+    for (let j = 0; j < count; j++) {
+        const off = slot_off + j * CONTACT_STRIDE;
+        const fid = data[off + 13];
+        if (fid === 0) continue; // no feature info to match on
+        for (let k = 0; k < cc; k++) {
+            const co = k * CANDIDATE_STRIDE;
+            if (candidates[co + 10] === fid) {
+                // Overwrite geometry only: witnesses, normal, depth.
+                data[off]     = candidates[co];
+                data[off + 1] = candidates[co + 1];
+                data[off + 2] = candidates[co + 2];
+                data[off + 3] = candidates[co + 3];
+                data[off + 4] = candidates[co + 4];
+                data[off + 5] = candidates[co + 5];
+                data[off + 6] = candidates[co + 6];
+                data[off + 7] = candidates[co + 7];
+                data[off + 8] = candidates[co + 8];
+                data[off + 9] = candidates[co + 9];
+                break;
+            }
+        }
+    }
+}

package/src/engine/physics/narrowphase/ray_shapes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * # Local-frame ray ↔ primitive intersections (raycast narrowphase)
+ *
+ * Each function intersects a ray, **expressed in the shape's local frame**,
+ * against a canonical primitive at the origin (sphere at the origin; box
+ * axis-aligned spanning `[-h, +h]`; capsule along the local Y axis). They
+ * return the hit distance `t` along the ray (`Infinity` on a miss) and write
+ * the **local** outward surface normal (unit) into `outNormal[0..2]`.
+ *
+ * The ray-narrowphase dispatch transforms the world ray into the body's local
+ * frame once (rotate by the inverse body rotation — a unit direction stays
+ * unit, so `t` is preserved), calls the matching primitive, then rotates the
+ * returned local normal back to world. Keeping the primitives canonical lets
+ * the box and capsule tests be axis-aligned (cheap slab / cylinder math) and
+ * shares a single transform across them.
+ *
+ * Conventions:
+ *  - the ray direction is unit length (the caller guarantees it);
+ *  - the first surface crossing at or after the origin within `tMax` is
+ *    returned; a ray starting inside the shape returns its exit crossing;
+ *  - the normal is the geometric outward surface normal at the hit.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Ray vs a sphere of radius `r` centred at the local origin.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r  sphere radius
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_sphere_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, r: number): number;
+/**
+ * Ray vs an axis-aligned box spanning `[-hx,hx] × [-hy,hy] × [-hz,hz]` at the
+ * local origin (the canonical pose of {@link BoxShape3D}). Slab method, with
+ * the entry (or, origin-inside, exit) face's outward normal.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} hx @param {number} hy @param {number} hz  half-extents
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_box_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, hx: number, hy: number, hz: number): number;
+/**
+ * Ray vs a capsule along the local Y axis: a cylinder of radius `r` over
+ * `y ∈ [−hh, hh]` capped by hemispheres of radius `r` at `(0, ±hh, 0)` — the
+ * canonical pose of {@link CapsuleShape3D} (`hh = height/2`). Tests the
+ * infinite cylinder (clamped to the segment) and the two cap spheres, taking
+ * the nearest valid crossing.
+ *
+ * @param {Float64Array} outNormal length-3, written on hit
+ * @param {number} ox @param {number} oy @param {number} oz  ray origin (local)
+ * @param {number} dx @param {number} dy @param {number} dz  ray dir (local, unit)
+ * @param {number} tMax
+ * @param {number} r   capsule radius
+ * @param {number} hh  half-height of the cylindrical section (`height/2`)
+ * @returns {number} hit distance, or `Infinity` on miss
+ */
+export function ray_capsule_local(outNormal: Float64Array, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, r: number, hh: number): number;
+//# sourceMappingURL=ray_shapes.d.ts.map

package/src/engine/physics/narrowphase/ray_shapes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ray_shapes.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/ray_shapes.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;;;;;GASG;AACH,4CAPW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,KACN,MAAM,GACJ,MAAM,CAiBlB;AAED;;;;;;;;;;;GAWG;AACH,yCAPW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,MACN,MAAM,MAAa,MAAM,MAAa,MAAM,GAC1C,MAAM,CA+ClB;AAED;;;;;;;;;;;;;;GAcG;AACH,6CARW,YAAY,MACZ,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,KACN,MAAM,MACN,MAAM,GACJ,MAAM,CA6DlB"}