@woosh/meep-engine 3.38.0 → 3.40.0

package/src/engine/physics/solver/solve_contacts.js

@@ -1,6 +1,6 @@
-import { apply_impulse_to_body } from "./apply_impulse_to_body.js";
+import { apply_impulse_to_body_oriented } from "./apply_impulse_to_body.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
-import { v3_quaternion_apply_inverse } from "../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { v3_quaternion_apply_inverse_array } from "../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import {
     SBS_AV_X,
@@ -22,7 +22,7 @@ import {
 import { CONTACT_FLAG_SENSOR, CONTACT_FLAGS_OFFSET, CONTACT_STRIDE } from "../contact/ManifoldStore.js";
 import { BodyKind } from "../ecs/BodyKind.js";
 import { body_is_wholly_sensor } from "../ecs/is_sensor.js";
-import { angular_effective_mass_raw, world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
+import { angular_effective_mass_array, world_inverse_inertia_apply_array } from "../inertia/world_inverse_inertia.js";
 import { redetect_pair_geometry } from "../narrowphase/narrowphase_step.js";
 import { friction_cone_clamp } from "./friction_cone.js";
 
@@ -43,7 +43,7 @@ import { friction_cone_clamp } from "./friction_cone.js";
  *       solve_velocity(manifolds, system, iters)   // non-penetration + friction
  *       solve_position(manifolds, system, pos_iters)
  *       (system integrates position by h, folding pseudo-velocity)
- *   apply_restitution(manifolds, system)           // once, after the loop
+ *   apply_restitution(manifolds, system, passes)   // after the loop
  *
  * The three concerns are fully decoupled (Phases 1–2) and substepping
  * (Phase 3) re-runs only the velocity + position solve per substep —
@@ -53,6 +53,23 @@ import { friction_cone_clamp } from "./friction_cone.js";
  * adapts as the stack settles (the mechanism behind TGS stack stability)
  * without paying for narrowphase N times.
  *
+ * Only the penetration moves. The rest of a row — its lever arms, and the
+ * orientation each body's world inverse inertia is evaluated at — is fixed
+ * at prepare for the whole outer step, because the row's effective mass is
+ * computed from exactly those once, at prepare. Every pass (warm start,
+ * biased solve, relax, restitution, position) applies its impulse through
+ * the same Jacobian and inertia the mass was built from. Let either drift
+ * under a fixed mass and each Gauss-Seidel update over-corrects by
+ * K_applied / K_prepared; past 2 the iteration diverges — a box knocked out
+ * from under a stack (levers following the contact metres past both bodies)
+ * or a long body spinning flat (world inertia turning over within the step)
+ * gained energy by factors of 1e11 and more. Box3D does the same: "fixed
+ * anchor points for applying impulses" (`cp->rA`, `cp->rB`) and the
+ * prepare-time `invInertiaWorld` (contact_solver.c). Concave pairs re-detect
+ * their levers every substep, and take the orientations at that same pose and
+ * recompute their masses from both: the row is re-prepared, whole, at the
+ * substep, and fixed from there to the next re-detect.
+ *
  * Why staged module functions sharing module scratch, rather than one call:
  * the substep loop interleaves solver stages with whole-body integration
  * that lives in the system. The stages communicate through module-scoped
@@ -114,7 +131,7 @@ const DEFAULT_POSITION_ITERATIONS = 2;
  * micro-jitter at near-zero overlap.
  * @type {number}
  */
-const PENETRATION_SLOP = 0.005;
+export const PENETRATION_SLOP = 0.005;
 
 /**
  * SPOOK contact stiffness `k`. Effectively infinite for rigid-body
@@ -144,11 +161,12 @@ const CONTACT_RELAXATION = 4.75;
 const MAX_POSITION_BIAS = 3;
 
 /**
- * Velocity below which restitution is suppressed (no micro-bounce buzz on
- * resting stacks).
+ * Default approach speed, m/s, below which restitution is suppressed (no
+ * micro-bounce buzz on resting stacks) — the default of
+ * `PhysicsSystem.restitutionThreshold`, which is what the solver reads.
  * @type {number}
  */
-const RESTITUTION_VELOCITY_THRESHOLD = 1.0;
+export const RESTITUTION_VELOCITY_THRESHOLD = 1.0;
 
 /**
  * Box2D-v3 soft-constraint scales (`b2MakeSoft`) for a damped spring of
@@ -196,11 +214,12 @@ const g_soft_dyn = new Float64Array([1, 0, 0]);
 const g_soft_static = new Float64Array([1, 0, 0]);
 
 /**
- * Per-contact pre-step scratch stride: 23 doubles.
+ * Per-contact pre-step scratch stride: 34 doubles.
  *   0..2 : localWA  (A's contact witness, in A's LOCAL frame — constant)
  *   3..5 : localWB  (B's contact witness, in B's LOCAL frame — constant)
- *   6..8 : rA       (lever from A's COM to the contact midpoint — refreshed)
- *   9..11: rB       (lever from B's COM to the contact midpoint — refreshed)
+ *   6..8 : rA       (lever from A's COM to the contact midpoint — fixed at prepare;
+ *                    concave contacts re-detect it each substep)
+ *   9..11: rB       (lever from B's COM to the contact midpoint — likewise)
  *   12..14: t1      (tangent 1, unit, world — constant)
  *   15..17: t2      (tangent 2, unit, world — constant)
  *   18   : m_eff_n
@@ -211,16 +230,29 @@ const g_soft_static = new Float64Array([1, 0, 0]);
  *   23   : soft_mass_scale (soft-contact velocity scale — 1 when hard)
  *   24   : soft_imp_scale  (soft-contact impulse-decay scale — 0 when hard)
  *   25   : soft_bias_rate  (penetration-bias rate — 0 when hard)
+ *   26..29: qA      (A's orientation at prepare — what A's world inverse inertia
+ *                    is evaluated at for the whole step; concave contacts
+ *                    re-take it each substep with their levers)
+ *   30..33: qB      (B's, likewise)
  *
  * `localWA` / `localWB` are the per-body contact witnesses expressed in body
  * local frames at prepare time. Each substep, `refresh_contacts` rotates
  * them back to world by the body's current pose to recover the moved contact
- * points, re-derives the current penetration depth (anchored on the trusted
- * prepare-time depth via a delta, so it's sign-robust), and rebuilds the
- * impulse lever arms `rA` / `rB` and the position bias.
+ * points and re-derives the current penetration depth (anchored on the trusted
+ * prepare-time depth via a delta, so it's sign-robust) and the position bias.
+ * The levers, the orientations and the effective masses built from them stay
+ * as prepared (see the file header).
  * @type {number}
  */
-const PRE_STRIDE = 26;
+const PRE_STRIDE = 34;
+
+/** Offset of `qA` within a contact's pre span; `qB` follows at +4. */
+const PRE_QA = 26;
+const PRE_QB = 30;
+
+/** Offset of the lever `rA` within a contact's pre span; `rB` follows at +3. */
+const PRE_RA = 6;
+const PRE_RB = 9;
 
 /** Per-contact index list — 4 uint32 per contact: slot, idx, idxA, idxB. */
 const INDEX_STRIDE = 4;
@@ -239,21 +271,46 @@ let scratch_mu = new Float64Array(64);
 let scratch_pos_jn = new Float64Array(64);
 
 /**
- * Per-contact maximum normal impulse seen across the whole outer step's
- * velocity solving (all substeps, all iterations). Reset in
- * {@link prepare_contacts}, updated in {@link solve_velocity}, read by
- * {@link apply_restitution}.
+ * Per-contact total normal impulse over the outer step (Box3D
+ * `totalNormalImpulse`): the normal impulse the contact delivered, then grown
+ * by every restitution pass's impulse. Reset in {@link prepare_contacts},
+ * summed in {@link solve_velocity} and {@link apply_restitution}.
  *
- * Restitution must fire whenever a contact *was* compressive at some point
- * in the step, even if its accumulated impulse later relaxes back to ~0 — a
- * transient collision (ball bouncing, head-on hit) under per-substep
- * warm-start ends the loop with `j_n ≈ 0` because there's no sustained load
- * to hold the impulse up. Gating on this running max (Box2D-v3
- * `maxNormalImpulse`) rather than the end-of-loop `j_n` is what makes
- * bounces fire.
+ * A substep warm-starts the contact with its accumulated impulse and the
+ * velocity solve adjusts it, so the impulse the contact delivers in a substep
+ * is the accumulated value the substep ends on: {@link solve_velocity} adds
+ * that once per substep, at the end of the relax pass (soft contacts) or of
+ * the solve (hard). Box3D adds the value after its solve AND after its relax,
+ * about twice the delivered impulse, and a cap built on that rarely binds:
+ * counted that way here, it bound in 0 of 814 armed checks over ten
+ * restitution scenes at 2 passes, and a tumbling cube striking frictionless
+ * ground at e = 1 in zero gravity with one pass left with up to 7.0% more
+ * kinetic energy than it struck with (13 of 300 strikes gaining over 0.5%).
+ * Counted once per substep, it binds where a pass overshoots and the worst
+ * strike gains 0.2%. (Under gravity a landing's depth correction adds energy
+ * the cap does not see; see `PhysicsSystem.restitutionIterations`.)
+ *
+ * It is also the restitution gate: a contact bounces only if it *was*
+ * compressive at some point in the step, even if its accumulated impulse later
+ * relaxed back to ~0 — a transient collision (ball bouncing, head-on hit)
+ * under per-substep warm-start ends the loop with `j_n ≈ 0` because there's
+ * no sustained load to hold the impulse up. (The peak accumulated impulse, an
+ * earlier measure, understated the compression: capped on it, a cube dropped
+ * flat onto a cube resting on the floor at e = 0.8 rebounded at 3.32 m/s of
+ * the 3.53 m/s it is owed, however many passes ran.)
+ * @type {Float64Array}
+ */
+let scratch_total_jn = new Float64Array(64);
+
+/**
+ * Per-contact restitution impulse (Box3D `restitutionImpulse`): the part of
+ * {@link apply_restitution}'s impulse that went past stopping what was left of
+ * the approach, i.e. into sending the bodies apart. `total − restitution` is
+ * the compression impulse a bounce may return `e` times of, and no more.
+ * Reset at the start of {@link apply_restitution}.
  * @type {Float64Array}
  */
-let scratch_max_jn = new Float64Array(64);
+let scratch_rest_jn = new Float64Array(64);
 
 /**
  * Per-contact flag: 1 if the contact's pair involves a concave body, else 0.
@@ -265,6 +322,22 @@ let scratch_max_jn = new Float64Array(64);
  */
 let scratch_concave = new Uint8Array(64);
 
+/**
+ * Per-contact: which side of the pair the solver cannot move (zero inverse mass — static,
+ * kinematic, or a sleeping neighbour) while the other side it can: {@link IMMOVABLE_NONE},
+ * {@link IMMOVABLE_A} or {@link IMMOVABLE_B}. Filled by {@link prepare_contacts}; read by
+ * {@link refresh_contacts}, which lets that side's lever follow the movable side (see there).
+ * @type {Uint8Array}
+ */
+let scratch_immovable = new Uint8Array(64);
+
+/** Both sides move, or neither does. */
+const IMMOVABLE_NONE = 0;
+/** Body A has zero inverse mass, body B does not. */
+const IMMOVABLE_A = 1;
+/** Body B has zero inverse mass, body A does not. */
+const IMMOVABLE_B = 2;
+
 /**
  * Distinct concave-involved manifold slots touched this step, with the body
  * indices needed to fetch their collider lists for re-detection. Parallel
@@ -288,6 +361,9 @@ let g_spook_eps = 0;
 /** Scratch for re-deriving contact world points in {@link refresh_contacts}. */
 const scratch_cp = new Float64Array(6);
 
+/** A contact pair's two orientations, A's then B's, for the witness anchors in {@link prepare_contacts}. */
+const scratch_orientations = new Float64Array(8);
+
 function ensure_capacity(n) {
     if (scratch_pre.length < n * PRE_STRIDE) {
         scratch_pre = new Float64Array(n * PRE_STRIDE * 2);
@@ -301,11 +377,13 @@ function ensure_capacity(n) {
     if (scratch_pos_jn.length < n) {
         scratch_pos_jn = new Float64Array(n * 2);
     }
-    if (scratch_max_jn.length < n) {
-        scratch_max_jn = new Float64Array(n * 2);
+    if (scratch_total_jn.length < n) {
+        scratch_total_jn = new Float64Array(n * 2);
+        scratch_rest_jn = new Float64Array(n * 2);
     }
     if (scratch_concave.length < n) {
         scratch_concave = new Uint8Array(n * 2);
+        scratch_immovable = new Uint8Array(n * 2);
     }
 }
 
@@ -334,13 +412,19 @@ function ensure_concave_slot_capacity(n) {
 /**
  * Build an orthonormal tangent basis perpendicular to a unit normal.
  *
+ * The normal is read from an array: this is not inlined into its callers, and
+ * a call that is not inlined boxes every number passed to it.
+ *
  * @param {Float64Array} out  6 floats: t1.xyz then t2.xyz
  * @param {number} off
- * @param {number} nx
- * @param {number} ny
- * @param {number} nz
+ * @param {Float64Array} normal
+ * @param {number} normal_offset where in `normal` its x is, y and z following
  */
-function build_tangents(out, off, nx, ny, nz) {
+function build_tangents(out, off, normal, normal_offset) {
+    const nx = normal[normal_offset];
+    const ny = normal[normal_offset + 1];
+    const nz = normal[normal_offset + 2];
+
     const ax = nx < 0 ? -nx : nx;
     const ay = ny < 0 ? -ny : ny;
     const az = nz < 0 ? -nz : nz;
@@ -394,57 +478,73 @@ const scratch_clamp = new Float64Array(2);
 const scratch_inertia_a = new Float64Array(3);
 const scratch_inertia_b = new Float64Array(3);
 
+/**
+ * The impulse a row applies to both of its bodies, handed to {@link apply_impulse_to_body_oriented} in
+ * an array: a call it is not inlined into would box three loose numbers per body.
+ */
+const scratch_impulse = new Float64Array(3);
+
 
 /**
  * Apply a position-pass impulse `P` at body-relative offset `r` to the
  * body's pseudo-velocity (linear + angular) in the `pseudo_velocity` flat
- * buffer. Mirrors {@link apply_impulse_to_body} but the result is consumed
- * by `integrate_position` the same substep and never persists. Inverse
- * inertia / orientation are read from the body's {@link SolverBodyState} span.
+ * buffer. Mirrors {@link apply_impulse_to_body_oriented} but the result is
+ * consumed by `integrate_position` the same substep and never persists. The
+ * inverse mass and inverse-inertia diagonal are read from the body's
+ * {@link SolverBodyState} span, the orientation it is evaluated at is the
+ * contact's prepared one. Lever and impulse come in arrays, for the reason
+ * {@link apply_impulse_to_body_oriented} gives.
  *
  * @param {Float64Array} pseudo_velocity stride = {@link PSEUDO_STRIDE}
  * @param {number} pbase offset = `body_index * PSEUDO_STRIDE`
  * @param {Float64Array} ss solver-body-state data array
  * @param {number} sbase `body_index * SBS_STRIDE`
- * @param {number} invM
- * @param {number} rx
- * @param {number} ry
- * @param {number} rz
- * @param {number} Px
- * @param {number} Py
- * @param {number} Pz
+ * @param {Float64Array} rotation holds the orientation at prepare, a unit quaternion
+ * @param {number} rotation_offset
+ * @param {Float64Array} lever
+ * @param {number} lever_offset
+ * @param {Float64Array} impulse
+ * @param {number} impulse_offset
  * @param {number} sign +1 for body A, -1 for body B
  * @param {Float64Array} scratch_inertia
  */
 function apply_impulse_to_pseudo(
     pseudo_velocity, pbase,
-    ss, sbase, invM,
-    rx, ry, rz,
-    Px, Py, Pz,
+    ss, sbase,
+    rotation, rotation_offset,
+    lever, lever_offset,
+    impulse, impulse_offset,
     sign,
     scratch_inertia
 ) {
+    const invM = ss[sbase + SBS_INV_MASS];
+
     if (invM === 0) {
         return;
     }
 
-    const sPx = sign * Px;
-    const sPy = sign * Py;
-    const sPz = sign * Pz;
+    const sPx = sign * impulse[impulse_offset];
+    const sPy = sign * impulse[impulse_offset + 1];
+    const sPz = sign * impulse[impulse_offset + 2];
 
     pseudo_velocity[pbase] += sPx * invM;
     pseudo_velocity[pbase + 1] += sPy * invM;
     pseudo_velocity[pbase + 2] += sPz * invM;
 
-    const tx = ry * sPz - rz * sPy;
-    const ty = rz * sPx - rx * sPz;
-    const tz = rx * sPy - ry * sPx;
+    const rx = lever[lever_offset];
+    const ry = lever[lever_offset + 1];
+    const rz = lever[lever_offset + 2];
+
+    // the torque r x P, transformed in place by the world inverse inertia
+    scratch_inertia[0] = ry * sPz - rz * sPy;
+    scratch_inertia[1] = rz * sPx - rx * sPz;
+    scratch_inertia[2] = rx * sPy - ry * sPx;
 
-    world_inverse_inertia_apply_raw(
+    world_inverse_inertia_apply_array(
         scratch_inertia, 0,
-        ss[sbase + SBS_INV_I_X], ss[sbase + SBS_INV_I_Y], ss[sbase + SBS_INV_I_Z],
-        ss[sbase + SBS_QX], ss[sbase + SBS_QY], ss[sbase + SBS_QZ], ss[sbase + SBS_QW],
-        tx, ty, tz
+        ss, sbase + SBS_INV_I_X,
+        rotation, rotation_offset,
+        scratch_inertia, 0
     );
 
     pseudo_velocity[pbase + 3] += scratch_inertia[0];
@@ -454,45 +554,94 @@ function apply_impulse_to_pseudo(
 
 /**
  * Quadratic-form contribution of one body to the constraint effective mass
- * along a unit axis: `(r × axis)^T · I⁻¹_world · (r × axis)`. Reads the body's
- * inverse-inertia diagonal + orientation from its {@link SolverBodyState} span.
- * Non-dynamic bodies carry a zero inverse-inertia diagonal there, so the
- * zero-guard returns 0 for them — matching the object path's `kind` guard.
+ * along a unit axis: `(r × axis)^T · I⁻¹_world · (r × axis)`, with `I⁻¹_world`
+ * evaluated at orientation `q` — the contact's prepared one, the same the
+ * row's impulses are applied through. Reads the body's inverse-inertia
+ * diagonal from its {@link SolverBodyState} span. Non-dynamic bodies carry a
+ * zero inverse-inertia diagonal there, so the zero-guard gives 0 for them —
+ * matching the object path's `kind` guard.
  *
+ * Inputs come in arrays and the contribution goes out through `result`: six
+ * of these run per contact, more than V8 will inline into one function, and a
+ * call that is not inlined boxes every number passed to it or returned.
+ *
+ * @param {Float64Array} result receives the contribution at `result_offset`
+ * @param {number} result_offset
  * @param {Float64Array} ss solver-body-state data array
  * @param {number} base `body_index * SBS_STRIDE`
- * @param {number} rx
- * @param {number} ry
- * @param {number} rz
- * @param {number} ax
- * @param {number} ay
- * @param {number} az
+ * @param {Float64Array} rotation holds the orientation at prepare, a unit quaternion
+ * @param {number} rotation_offset
+ * @param {Float64Array} lever
+ * @param {number} lever_offset
+ * @param {Float64Array} axis
+ * @param {number} axis_offset
  * @param {Float64Array} scratch_inertia
- * @returns {number}
  */
 function angular_jacobian_contribution(
+    result, result_offset,
     ss, base,
-    rx, ry, rz,
-    ax, ay, az,
+    rotation, rotation_offset,
+    lever, lever_offset,
+    axis, axis_offset,
     scratch_inertia
 ) {
-    const iix = ss[base + SBS_INV_I_X];
-    const iiy = ss[base + SBS_INV_I_Y];
-    const iiz = ss[base + SBS_INV_I_Z];
-
-    if (iix === 0 && iiy === 0 && iiz === 0) {
-        return 0;
+    if (ss[base + SBS_INV_I_X] === 0 && ss[base + SBS_INV_I_Y] === 0 && ss[base + SBS_INV_I_Z] === 0) {
+        result[result_offset] = 0;
+        return;
     }
 
-    return angular_effective_mass_raw(
-        iix, iiy, iiz,
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW],
-        rx, ry, rz,
-        ax, ay, az,
+    angular_effective_mass_array(
+        result, result_offset,
+        ss, base + SBS_INV_I_X,
+        rotation, rotation_offset,
+        lever, lever_offset,
+        axis, axis_offset,
         scratch_inertia
     );
 }
 
+/**
+ * Effective-mass contributions of one contact's two bodies, written by
+ * {@link prepare_row_masses}: A·n, B·n, A·t1, B·t1, A·t2, B·t2.
+ */
+const scratch_row_mass = new Float64Array(6);
+
+/**
+ * The three effective masses of a contact's rows (normal, tangent 1, tangent 2)
+ * from its prepared levers, orientations and tangents and its normal, into the
+ * pre span (lanes 18..20). The normal row is softened by the SPOOK `eps`.
+ *
+ * @param {Float64Array} pre
+ * @param {number} pre_off
+ * @param {Float64Array} ss solver-body-state data array
+ * @param {number} baseA
+ * @param {number} baseB
+ * @param {Float64Array} data the manifold store's buffer, holding the normal
+ * @param {number} normal_offset where in `data` the contact normal's x is
+ */
+function prepare_row_masses(pre, pre_off, ss, baseA, baseB, data, normal_offset) {
+    const mass = scratch_row_mass;
+
+    angular_jacobian_contribution(mass, 0, ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, data, normal_offset, scratch_inertia_a);
+    angular_jacobian_contribution(mass, 1, ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, data, normal_offset, scratch_inertia_b);
+    angular_jacobian_contribution(mass, 2, ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, pre, pre_off + 12, scratch_inertia_a);
+    angular_jacobian_contribution(mass, 3, ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, pre, pre_off + 12, scratch_inertia_b);
+    angular_jacobian_contribution(mass, 4, ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, pre, pre_off + 15, scratch_inertia_a);
+    angular_jacobian_contribution(mass, 5, ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, pre, pre_off + 15, scratch_inertia_b);
+
+    const invMA = ss[baseA + SBS_INV_MASS];
+    const invMB = ss[baseB + SBS_INV_MASS];
+
+    const k_n = invMA + invMB + mass[0] + mass[1];
+    const k_t1 = invMA + invMB + mass[2] + mass[3];
+    const k_t2 = invMA + invMB + mass[4] + mass[5];
+
+    const k_n_eff = k_n + g_spook_eps;
+    pre[pre_off + 18] = k_n_eff > 0 ? 1 / k_n_eff : 0;
+    pre[pre_off + 19] = k_t1 > 0 ? 1 / k_t1 : 0;
+    pre[pre_off + 20] = k_t2 > 0 ? 1 / k_t2 : 0;
+}
+
 /**
  * Flat count of all touched contacts across every island, plus the slot
  * list to iterate. Islands are concatenated densely in `contact_data`;
@@ -642,7 +791,14 @@ export function prepare_contacts(manifolds, system, dt_sub) {
 
         const pAx = trA.translation_x, pAy = trA.translation_y, pAz = trA.translation_z;
         const pBx = trB.translation_x, pBy = trB.translation_y, pBz = trB.translation_z;
-        const qA = trA.rotation, qB = trB.rotation;
+
+        // The two orientations the witnesses are taken into the bodies' frames by, in an array (see
+        // the witness anchors below).
+        const orientations = scratch_orientations;
+        orientations[0] = trA.rotation_x; orientations[1] = trA.rotation_y;
+        orientations[2] = trA.rotation_z; orientations[3] = trA.rotation_w;
+        orientations[4] = trB.rotation_x; orientations[5] = trB.rotation_y;
+        orientations[6] = trB.rotation_z; orientations[7] = trB.rotation_w;
 
         for (let k = 0; k < cc; k++) {
             const off = slot_off + k * CONTACT_STRIDE;
@@ -676,12 +832,18 @@ export function prepare_contacts(manifolds, system, dt_sub) {
             const pre_off = c * PRE_STRIDE;
 
             // Per-body witness anchors in LOCAL frame (constant across the
-            // outer step). localW = R⁻¹ · (witness − COM).
-            v3_quaternion_apply_inverse(pre, pre_off, wax - pAx, way - pAy, waz - pAz, qA[0], qA[1], qA[2], qA[3]);
-            v3_quaternion_apply_inverse(pre, pre_off + 3, wbx - pBx, wby - pBy, wbz - pBz, qB[0], qB[1], qB[2], qB[3]);
-
-            // Lever arms from COM to the contact midpoint (refreshed each
-            // substep; seeded here from prepare-time pose).
+            // outer step). localW = R⁻¹ · (witness − COM). The offsets are
+            // staged in the pre span itself and rotated in place, through
+            // the array form: this function's inlining budget is spent, and
+            // the scalar form, not inlined, boxed its seven numbers twice
+            // per contact.
+            pre[pre_off] = wax - pAx; pre[pre_off + 1] = way - pAy; pre[pre_off + 2] = waz - pAz;
+            pre[pre_off + 3] = wbx - pBx; pre[pre_off + 4] = wby - pBy; pre[pre_off + 5] = wbz - pBz;
+            v3_quaternion_apply_inverse_array(pre, pre_off, pre, pre_off, orientations, 0);
+            v3_quaternion_apply_inverse_array(pre, pre_off + 3, pre, pre_off + 3, orientations, 4);
+
+            // Lever arms from COM to the contact midpoint, fixed for the step
+            // (concave contacts re-detect theirs each substep).
             pre[pre_off + 6] = rax;
             pre[pre_off + 7] = ray;
             pre[pre_off + 8] = raz;
@@ -689,24 +851,22 @@ export function prepare_contacts(manifolds, system, dt_sub) {
             pre[pre_off + 10] = rby;
             pre[pre_off + 11] = rbz;
 
-            build_tangents(pre, pre_off + 12, nx, ny, nz);
-            const t1x = pre[pre_off + 12], t1y = pre[pre_off + 13], t1z = pre[pre_off + 14];
-            const t2x = pre[pre_off + 15], t2y = pre[pre_off + 16], t2z = pre[pre_off + 17];
-
-            const k_n = invMA + invMB
-                + angular_jacobian_contribution(ss, baseA, rax, ray, raz, nx, ny, nz, scratch_inertia_a)
-                + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, nx, ny, nz, scratch_inertia_b);
-            const k_t1 = invMA + invMB
-                + angular_jacobian_contribution(ss, baseA, rax, ray, raz, t1x, t1y, t1z, scratch_inertia_a)
-                + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, t1x, t1y, t1z, scratch_inertia_b);
-            const k_t2 = invMA + invMB
-                + angular_jacobian_contribution(ss, baseA, rax, ray, raz, t2x, t2y, t2z, scratch_inertia_a)
-                + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, t2x, t2y, t2z, scratch_inertia_b);
-
-            const k_n_eff = k_n + g_spook_eps;
-            pre[pre_off + 18] = k_n_eff > 0 ? 1 / k_n_eff : 0;
-            pre[pre_off + 19] = k_t1 > 0 ? 1 / k_t1 : 0;
-            pre[pre_off + 20] = k_t2 > 0 ? 1 / k_t2 : 0;
+            // Orientations each body's world inverse inertia is evaluated at for
+            // the whole step: by the masses below and by every impulse this row
+            // applies, whatever the substeps do to the pose meanwhile.
+            const qAx = ss[baseA + SBS_QX], qAy = ss[baseA + SBS_QY], qAz = ss[baseA + SBS_QZ], qAw = ss[baseA + SBS_QW];
+            const qBx = ss[baseB + SBS_QX], qBy = ss[baseB + SBS_QY], qBz = ss[baseB + SBS_QZ], qBw = ss[baseB + SBS_QW];
+            pre[pre_off + PRE_QA] = qAx;
+            pre[pre_off + PRE_QA + 1] = qAy;
+            pre[pre_off + PRE_QA + 2] = qAz;
+            pre[pre_off + PRE_QA + 3] = qAw;
+            pre[pre_off + PRE_QB] = qBx;
+            pre[pre_off + PRE_QB + 1] = qBy;
+            pre[pre_off + PRE_QB + 2] = qBz;
+            pre[pre_off + PRE_QB + 3] = qBw;
+
+            build_tangents(pre, pre_off + 12, data, off + 6);
+            prepare_row_masses(pre, pre_off, ss, baseA, baseB, data, off + 6);
 
             // Restitution approach velocity (captured once, this is the
             // closing speed entering the step). n is B → A; vn < 0 closing.
@@ -721,7 +881,7 @@ export function prepare_contacts(manifolds, system, dt_sub) {
             const vn_pre = (vAx_at - vBx_at) * nx + (vAy_at - vBy_at) * ny + (vAz_at - vBz_at) * nz;
 
             let rest_bias = 0;
-            if (vn_pre < -RESTITUTION_VELOCITY_THRESHOLD) {
+            if (vn_pre < -system.restitutionThreshold) {
                 rest_bias = restitution_combined * vn_pre;
             }
             pre[pre_off + 21] = rest_bias;
@@ -738,8 +898,11 @@ export function prepare_contacts(manifolds, system, dt_sub) {
 
             mus[c] = friction_combined;
             pos_jn[c] = 0;
-            scratch_max_jn[c] = 0;
+            scratch_total_jn[c] = 0;
             scratch_concave[c] = slot_concave ? 1 : 0;
+            scratch_immovable[c] = invMA === 0
+                ? (invMB === 0 ? IMMOVABLE_NONE : IMMOVABLE_A)
+                : (invMB === 0 ? IMMOVABLE_B : IMMOVABLE_NONE);
 
             idx[c * INDEX_STRIDE] = slot;
             idx[c * INDEX_STRIDE + 1] = k;
@@ -763,8 +926,8 @@ export function prepare_contacts(manifolds, system, dt_sub) {
 
 /**
  * Stage 1b (per substep) — warm-start: replay the cached accumulated
- * impulses `(j_n, j_t1, j_t2)` onto persistent velocity using the current
- * (refreshed) lever arms and tangents. Run once per substep, after
+ * impulses `(j_n, j_t1, j_t2)` onto persistent velocity through the row's
+ * lever arms, tangents and prepared orientations. Run once per substep, after
  * {@link refresh_contacts} and before {@link solve_velocity}.
  *
  * Per-substep warm-start is the crux of stable TGS: the stored impulse is a
@@ -785,6 +948,7 @@ export function warm_start_contacts(manifolds, system) {
     const pre = scratch_pre;
     const idx = scratch_idx;
     const ss = system.__solver_state.data;
+    const impulse = scratch_impulse;
 
     for (let ci = 0; ci < count; ci++) {
         const slot = idx[ci * INDEX_STRIDE];
@@ -793,14 +957,8 @@ export function warm_start_contacts(manifolds, system) {
         const baseA = idx[ci * INDEX_STRIDE + 2] * SBS_STRIDE;
         const baseB = idx[ci * INDEX_STRIDE + 3] * SBS_STRIDE;
 
-        const invMA = ss[baseA + SBS_INV_MASS];
-        const invMB = ss[baseB + SBS_INV_MASS];
-
         const pre_off = ci * PRE_STRIDE;
 
-        const rax = pre[pre_off + 6], ray = pre[pre_off + 7], raz = pre[pre_off + 8];
-        const rbx = pre[pre_off + 9], rby = pre[pre_off + 10], rbz = pre[pre_off + 11];
-
         const t1x = pre[pre_off + 12], t1y = pre[pre_off + 13], t1z = pre[pre_off + 14];
         const t2x = pre[pre_off + 15], t2y = pre[pre_off + 16], t2z = pre[pre_off + 17];
 
@@ -812,12 +970,12 @@ export function warm_start_contacts(manifolds, system) {
         const j_t1 = data[off + 11];
         const j_t2 = data[off + 12];
 
-        const Px = nx * j_n + t1x * j_t1 + t2x * j_t2;
-        const Py = ny * j_n + t1y * j_t1 + t2y * j_t2;
-        const Pz = nz * j_n + t1z * j_t1 + t2z * j_t2;
+        impulse[0] = nx * j_n + t1x * j_t1 + t2x * j_t2;
+        impulse[1] = ny * j_n + t1y * j_t1 + t2y * j_t2;
+        impulse[2] = nz * j_n + t1z * j_t1 + t2z * j_t2;
 
-        apply_impulse_to_body(ss, baseA, invMA, rax, ray, raz, Px, Py, Pz, +1, scratch_inertia_a);
-        apply_impulse_to_body(ss, baseB, invMB, rbx, rby, rbz, Px, Py, Pz, -1, scratch_inertia_b);
+        apply_impulse_to_body_oriented(ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, impulse, 0, +1, scratch_inertia_a);
+        apply_impulse_to_body_oriented(ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, impulse, 0, -1, scratch_inertia_b);
     }
 }
 
@@ -832,11 +990,23 @@ export function warm_start_contacts(manifolds, system) {
  *    `Δseparation = (cpA − wA − (cpB − wB)) · n` is the change since prepare.
  *    Anchoring on the trusted prepare-time depth makes the sign convention
  *    irrelevant — only the analytic delta uses the anchors;
- *  - rebuild the impulse levers `rA`/`rB` from the moved midpoint;
  *  - recompute the position-correction bias from `depth_now`.
  *
  * The contact normal and tangents are held fixed for the outer step (valid
- * for the small per-step rotation), so they are not recomputed here.
+ * for the small per-step rotation), so they are not recomputed here. Nor are
+ * the impulse levers `rA` / `rB`: the row's effective mass was built from the
+ * prepared ones, and the levers must stay inside the bodies — the midpoint of
+ * the moved witnesses travels at half the slip speed, so a box sliding out
+ * from under another at 150 m/s carried it a metre past both within the step.
+ *
+ * Except a side with zero inverse mass (static, kinematic, asleep): its lever
+ * enters no mass, so it is moved to where the other side's contact point now
+ * is (that side's fixed lever from its current centre). Held at the prepared
+ * point, a kinematic turntable's surface velocity was read along the tangent
+ * of where the rider had been at the start of the step, for the whole step:
+ * a box gripped at 3 m on a table at 1 rad/s crept outward 0.33 m in 10 s,
+ * whatever the substep count. Two movable bodies keep both levers fixed, as
+ * Box3D does for every pair; a box on a free spinning disc creeps as that did.
  *
  * @param {ManifoldStore} manifolds
  * @param {Transform64[]} transforms
@@ -889,12 +1059,14 @@ export function refresh_contacts(manifolds, transforms) {
         const pBy = trB.translation_y;
         const pBz = trB.translation_z;
 
-        const qA = trA.rotation;
-        const qB = trB.rotation;
+        // Read as scalars: a Transform64's `rotation` getter makes a new view on every read, and
+        // this runs for every contact every substep.
+        const qAx = trA.rotation_x, qAy = trA.rotation_y, qAz = trA.rotation_z, qAw = trA.rotation_w;
+        const qBx = trB.rotation_x, qBy = trB.rotation_y, qBz = trB.rotation_z, qBw = trB.rotation_w;
 
         // Current world contact points: COM + R · localWitness.
-        v3_quaternion_apply(cp, 0, pre[pre_off], pre[pre_off + 1], pre[pre_off + 2], qA[0], qA[1], qA[2], qA[3]);
-        v3_quaternion_apply(cp, 3, pre[pre_off + 3], pre[pre_off + 4], pre[pre_off + 5], qB[0], qB[1], qB[2], qB[3]);
+        v3_quaternion_apply(cp, 0, pre[pre_off], pre[pre_off + 1], pre[pre_off + 2], qAx, qAy, qAz, qAw);
+        v3_quaternion_apply(cp, 3, pre[pre_off + 3], pre[pre_off + 4], pre[pre_off + 5], qBx, qBy, qBz, qBw);
 
         const cpAx = pAx + cp[0], cpAy = pAy + cp[1], cpAz = pAz + cp[2];
         const cpBx = pBx + cp[3], cpBy = pBy + cp[4], cpBz = pBz + cp[5];
@@ -907,17 +1079,19 @@ export function refresh_contacts(manifolds, transforms) {
 
         const depth_now = depth0 - dsep;
 
-        // Impulse levers from each COM to the current contact midpoint.
-        const mx = (cpAx + cpBx) * 0.5;
-        const my = (cpAy + cpBy) * 0.5;
-        const mz = (cpAz + cpBz) * 0.5;
-
-        pre[pre_off + 6] = mx - pAx;
-        pre[pre_off + 7] = my - pAy;
-        pre[pre_off + 8] = mz - pAz;
-        pre[pre_off + 9] = mx - pBx;
-        pre[pre_off + 10] = my - pBy;
-        pre[pre_off + 11] = mz - pBz;
+        // A side the solver cannot move adds nothing to the row's mass, so its lever is free: it
+        // follows the movable side's contact point - that side's fixed lever from where its centre
+        // is now - so a turning or moving kinematic surface is read at its velocity under the body.
+        const immovable = scratch_immovable[ci];
+        if (immovable === IMMOVABLE_B) {
+            pre[pre_off + 9] = pAx + pre[pre_off + 6] - pBx;
+            pre[pre_off + 10] = pAy + pre[pre_off + 7] - pBy;
+            pre[pre_off + 11] = pAz + pre[pre_off + 8] - pBz;
+        } else if (immovable === IMMOVABLE_A) {
+            pre[pre_off + 6] = pBx + pre[pre_off + 9] - pAx;
+            pre[pre_off + 7] = pBy + pre[pre_off + 10] - pAy;
+            pre[pre_off + 8] = pBz + pre[pre_off + 11] - pAz;
+        }
 
         let bias_position = 0;
 
@@ -946,8 +1120,8 @@ export function refresh_contacts(manifolds, transforms) {
  * For each concave-involved slot, re-runs the narrowphase geometry at the
  * current substep pose ({@link redetect_pair_geometry}, which rewrites the
  * manifold's witness / normal / depth in place), then re-derives the solver
- * scratch (lever arms, tangent basis, effective masses, position bias) for
- * that slot's contacts from the fresh geometry. This is the whole point of
+ * scratch (lever arms, orientations, tangent basis, effective masses, position
+ * bias) for that slot's contacts from the fresh geometry. This is the whole point of
  * the concave path: a body rocking on a mesh changes which triangle (and
  * normal) it rests on within a single outer step, and freezing that — as the
  * convex analytic refresh does — pumps energy in. Re-detecting gives a
@@ -961,7 +1135,7 @@ export function refresh_contacts(manifolds, transforms) {
  * with prepare.
  *
  * Must run before {@link refresh_contacts} / {@link warm_start_contacts} each
- * substep. `rest_bias` (captured at prepare) and the `scratch_max_jn`
+ * substep. `rest_bias` (captured at prepare) and the `scratch_total_jn`
  * restitution gate are preserved.
  *
  * @param {ManifoldStore} manifolds
@@ -993,7 +1167,6 @@ export function redetect_concave_contacts(manifolds, system) {
     const pre = scratch_pre;
     const idx = scratch_idx;
     const spook_a = g_spook_a;
-    const spook_eps = g_spook_eps;
     const ss = system.__solver_state.data;
 
     for (let ci = 0; ci < count; ci++) {
@@ -1012,15 +1185,11 @@ export function redetect_concave_contacts(manifolds, system) {
         const trA = system.__transforms[idxA];
         const trB = system.__transforms[idxB];
 
-        const invMA = ss[baseA + SBS_INV_MASS];
-        const invMB = ss[baseB + SBS_INV_MASS];
-
         const slot_off = manifolds.slot_data_offset(slot);
         const off = slot_off + cidx * CONTACT_STRIDE;
 
         const wax = data[off], way = data[off + 1], waz = data[off + 2];
         const wbx = data[off + 3], wby = data[off + 4], wbz = data[off + 5];
-        const nx = data[off + 6], ny = data[off + 7], nz = data[off + 8];
         const depth = data[off + 9];
 
         const px = (wax + wbx) * 0.5;
@@ -1038,24 +1207,26 @@ export function redetect_concave_contacts(manifolds, system) {
         pre[pre_off + 10] = rby;
         pre[pre_off + 11] = rbz;
 
-        build_tangents(pre, pre_off + 12, nx, ny, nz);
-        const t1x = pre[pre_off + 12], t1y = pre[pre_off + 13], t1z = pre[pre_off + 14];
-        const t2x = pre[pre_off + 15], t2y = pre[pre_off + 16], t2z = pre[pre_off + 17];
-
-        const k_n = invMA + invMB
-            + angular_jacobian_contribution(ss, baseA, rax, ray, raz, nx, ny, nz, scratch_inertia_a)
-            + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, nx, ny, nz, scratch_inertia_b);
-        const k_t1 = invMA + invMB
-            + angular_jacobian_contribution(ss, baseA, rax, ray, raz, t1x, t1y, t1z, scratch_inertia_a)
-            + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, t1x, t1y, t1z, scratch_inertia_b);
-        const k_t2 = invMA + invMB
-            + angular_jacobian_contribution(ss, baseA, rax, ray, raz, t2x, t2y, t2z, scratch_inertia_a)
-            + angular_jacobian_contribution(ss, baseB, rbx, rby, rbz, t2x, t2y, t2z, scratch_inertia_b);
-
-        const k_n_eff = k_n + spook_eps;
-        pre[pre_off + 18] = k_n_eff > 0 ? 1 / k_n_eff : 0;
-        pre[pre_off + 19] = k_t1 > 0 ? 1 / k_t1 : 0;
-        pre[pre_off + 20] = k_t2 > 0 ? 1 / k_t2 : 0;
+        build_tangents(pre, pre_off + 12, data, off + 6);
+
+        // The levers were just detected at the substep's pose, so the row's
+        // orientations are taken at that pose too: the mass and every impulse
+        // until the next re-detect go through the configuration the levers
+        // belong to. Fresh levers at the step's prepared orientation pair a
+        // contact point with an inertia frame the body no longer has, and that
+        // gained energy (a plank spinning flat on a mesh floor, 8 % at 60 rad/s).
+        const qAx = ss[baseA + SBS_QX], qAy = ss[baseA + SBS_QY], qAz = ss[baseA + SBS_QZ], qAw = ss[baseA + SBS_QW];
+        const qBx = ss[baseB + SBS_QX], qBy = ss[baseB + SBS_QY], qBz = ss[baseB + SBS_QZ], qBw = ss[baseB + SBS_QW];
+        pre[pre_off + PRE_QA] = qAx;
+        pre[pre_off + PRE_QA + 1] = qAy;
+        pre[pre_off + PRE_QA + 2] = qAz;
+        pre[pre_off + PRE_QA + 3] = qAw;
+        pre[pre_off + PRE_QB] = qBx;
+        pre[pre_off + PRE_QB + 1] = qBy;
+        pre[pre_off + PRE_QB + 2] = qBz;
+        pre[pre_off + PRE_QB + 3] = qBw;
+
+        prepare_row_masses(pre, pre_off, ss, baseA, baseB, data, off + 6);
 
         if (g_contacts_soft) {
             // Soft mode: lane 22 carries separation (see refresh_contacts).
@@ -1080,7 +1251,7 @@ export function redetect_concave_contacts(manifolds, system) {
 /**
  * Stage 3 (per substep) — velocity iterations enforcing pure
  * non-penetration (`vn → 0`) plus Coulomb-disk friction. No bias: depth
- * correction is the position pass, restitution is the one-shot pass.
+ * correction is the position pass, restitution is {@link apply_restitution}'s.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
@@ -1095,6 +1266,14 @@ export function solve_velocity(manifolds, system, iters, use_bias = true) {
     const idx = scratch_idx;
     const mus = scratch_mu;
     const ss = system.__solver_state.data;
+    const impulse = scratch_impulse;
+
+    // The restitution compression measure takes the impulse each substep ends
+    // on, once: at the last iteration of the call that closes the substep's
+    // velocity work — the relax pass when contacts are soft, this solve when
+    // they are hard (see scratch_total_jn).
+    const counts_compression = !use_bias || !g_contacts_soft;
+    const last_iter = iters - 1;
 
     for (let iter = 0; iter < iters; iter++) {
         for (let ci = 0; ci < contact_count; ci++) {
@@ -1105,9 +1284,6 @@ export function solve_velocity(manifolds, system, iters, use_bias = true) {
             const baseA = idx[ci * INDEX_STRIDE + 2] * SBS_STRIDE;
             const baseB = idx[ci * INDEX_STRIDE + 3] * SBS_STRIDE;
 
-            const invMA = ss[baseA + SBS_INV_MASS];
-            const invMB = ss[baseB + SBS_INV_MASS];
-
             const pre_off = ci * PRE_STRIDE;
 
             const rax = pre[pre_off + 6], ray = pre[pre_off + 7], raz = pre[pre_off + 8];
@@ -1171,17 +1347,17 @@ export function solve_velocity(manifolds, system, iters, use_bias = true) {
             const delta_j_n = new_j_n - j_n_accum;
             data[off + 10] = new_j_n;
 
-            if (new_j_n > scratch_max_jn[ci]) {
-                scratch_max_jn[ci] = new_j_n;
+            if (counts_compression && iter === last_iter) {
+                scratch_total_jn[ci] += new_j_n;
             }
 
             if (delta_j_n !== 0) {
-                const Pnx = nx * delta_j_n;
-                const Pny = ny * delta_j_n;
-                const Pnz = nz * delta_j_n;
+                impulse[0] = nx * delta_j_n;
+                impulse[1] = ny * delta_j_n;
+                impulse[2] = nz * delta_j_n;
 
-                apply_impulse_to_body(ss, baseA, invMA, rax, ray, raz, Pnx, Pny, Pnz, +1, scratch_inertia_a);
-                apply_impulse_to_body(ss, baseB, invMB, rbx, rby, rbz, Pnx, Pny, Pnz, -1, scratch_inertia_b);
+                apply_impulse_to_body_oriented(ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, impulse, 0, +1, scratch_inertia_a);
+                apply_impulse_to_body_oriented(ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, impulse, 0, -1, scratch_inertia_b);
             }
 
             // --- Friction impulse (Coulomb disk in tangent plane) ---
@@ -1226,12 +1402,12 @@ export function solve_velocity(manifolds, system, iters, use_bias = true) {
 
             if (delta_t1 !== 0 || delta_t2 !== 0) {
 
-                const Ptx = t1x * delta_t1 + t2x * delta_t2;
-                const Pty = t1y * delta_t1 + t2y * delta_t2;
-                const Ptz = t1z * delta_t1 + t2z * delta_t2;
+                impulse[0] = t1x * delta_t1 + t2x * delta_t2;
+                impulse[1] = t1y * delta_t1 + t2y * delta_t2;
+                impulse[2] = t1z * delta_t1 + t2z * delta_t2;
 
-                apply_impulse_to_body(ss, baseA, invMA, rax, ray, raz, Ptx, Pty, Ptz, +1, scratch_inertia_a);
-                apply_impulse_to_body(ss, baseB, invMB, rbx, rby, rbz, Ptx, Pty, Ptz, -1, scratch_inertia_b);
+                apply_impulse_to_body_oriented(ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, impulse, 0, +1, scratch_inertia_a);
+                apply_impulse_to_body_oriented(ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, impulse, 0, -1, scratch_inertia_b);
 
             }
         }
@@ -1239,18 +1415,36 @@ export function solve_velocity(manifolds, system, iters, use_bias = true) {
 }
 
 /**
- * Stage 4 (once, after the substep loop) — one-shot restitution
- * (Box2D-v3 `b2ApplyRestitution`, Catto 2018). Drives `vn → -e · vn_approach`
- * exactly once per closing contact, gated on (a) the contact having been
- * closing faster than the threshold at prepare, and (b) a compressive
- * normal impulse having formed during the velocity solve. The added impulse
- * accumulates into the same normal-impulse slot so it composes with
- * warm-start next frame.
+ * Stage 4 (after the substep loop) — restitution (Box3D `b3ApplyRestitution`,
+ * Catto). `iterations` Gauss-Seidel passes over every contact whose combined
+ * restitution is non-zero, each driving an ARMED contact's normal velocity
+ * toward `-e · vn_approach` and holding the rest of those contacts to plain
+ * non-penetration, so a bounce at one point does not drive another into the
+ * ground. A contact is armed when (a) it was closing faster than
+ * `system.restitutionThreshold` at prepare and (b) it pressed with a compressive
+ * normal impulse during the velocity solve. The impulses accumulate into the
+ * same normal-impulse slot so they compose with warm-start next frame.
+ *
+ * Why passes: a body striking at several points at once — a cube landing flat
+ * — is a coupled problem, and one sweep leaves it unconverged. The row solved
+ * first takes more than its share of the bounce, through the body's rotation
+ * as well as its translation, and the body leaves the ground spinning: a cube
+ * dropped flat on frictionless ground at e = 0.8 left at 5.2 rad/s, rebounding
+ * at 0.77 of its impact speed.
+ *
+ * Why the cap: a pass that has not converged overshoots — the row solved first
+ * sends its contact apart faster than `e` times its approach, and the body
+ * leaves with more energy than it struck with. So each contact may return at
+ * most `e` times the impulse it pressed with (Poisson's kinetic restitution),
+ * measured by {@link scratch_total_jn} as the impulse it delivered. Ported
+ * from Box3D's contact_solver.c (MIT, Erin Catto), which counts that impulse
+ * twice per substep; see there for why this counts it once.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
+ * @param {number} iterations passes over the contacts; 0 applies no restitution
  */
-export function apply_restitution(manifolds, system) {
+export function apply_restitution(manifolds, system, iterations) {
     const contact_count = g_contact_count;
     if (contact_count === 0) return;
 
@@ -1258,51 +1452,77 @@ export function apply_restitution(manifolds, system) {
     const pre = scratch_pre;
     const idx = scratch_idx;
     const ss = system.__solver_state.data;
+    const total_jn = scratch_total_jn;
+    const rest_jn = scratch_rest_jn;
 
     for (let ci = 0; ci < contact_count; ci++) {
-        const pre_off = ci * PRE_STRIDE;
-        const rest_bias = pre[pre_off + 21];
-        if (rest_bias === 0) continue;
+        rest_jn[ci] = 0;
+    }
 
-        const slot = idx[ci * INDEX_STRIDE];
-        const cidx = idx[ci * INDEX_STRIDE + 1];
-        // Gate on the running max normal impulse, not the end-of-loop value:
-        // a transient collision relaxes back to j_n ≈ 0 under per-substep
-        // warm-start, but it WAS compressive, so it should still bounce.
-        if (scratch_max_jn[ci] <= 0) continue;
+    for (let pass = 0; pass < iterations; pass++) {
+        for (let ci = 0; ci < contact_count; ci++) {
+            const slot = idx[ci * INDEX_STRIDE];
+            const cidx = idx[ci * INDEX_STRIDE + 1];
 
-        const slot_off = manifolds.slot_data_offset(slot);
-        const off = slot_off + cidx * CONTACT_STRIDE;
+            const slot_off = manifolds.slot_data_offset(slot);
+            const off = slot_off + cidx * CONTACT_STRIDE;
 
-        const j_n_accum = data[off + 10];
+            const restitution = data[off + 15];
+            if (restitution === 0) continue;
 
-        const baseA = idx[ci * INDEX_STRIDE + 2] * SBS_STRIDE;
-        const baseB = idx[ci * INDEX_STRIDE + 3] * SBS_STRIDE;
-        const invMA = ss[baseA + SBS_INV_MASS];
-        const invMB = ss[baseB + SBS_INV_MASS];
+            const pre_off = ci * PRE_STRIDE;
+            const rest_bias = pre[pre_off + 21];
 
-        const rax = pre[pre_off + 6], ray = pre[pre_off + 7], raz = pre[pre_off + 8];
-        const rbx = pre[pre_off + 9], rby = pre[pre_off + 10], rbz = pre[pre_off + 11];
-        const m_eff_n = pre[pre_off + 18];
-        const nx = data[off + 6], ny = data[off + 7], nz = data[off + 8];
+            // Armed only if the contact pressed at some point in the step, not
+            // by its end-of-loop impulse: a transient collision relaxes back to
+            // j_n ≈ 0 under per-substep warm-start, but it WAS compressive.
+            const compression = total_jn[ci] - rest_jn[ci];
+            const armed = rest_bias !== 0 && compression > 0;
+
+            const baseA = idx[ci * INDEX_STRIDE + 2] * SBS_STRIDE;
+            const baseB = idx[ci * INDEX_STRIDE + 3] * SBS_STRIDE;
+
+            const rax = pre[pre_off + 6], ray = pre[pre_off + 7], raz = pre[pre_off + 8];
+            const rbx = pre[pre_off + 9], rby = pre[pre_off + 10], rbz = pre[pre_off + 11];
+            const m_eff_n = pre[pre_off + 18];
+            const nx = data[off + 6], ny = data[off + 7], nz = data[off + 8];
 
-        const vAx_at = ss[baseA + SBS_LV_X] + ss[baseA + SBS_AV_Y] * raz - ss[baseA + SBS_AV_Z] * ray;
-        const vAy_at = ss[baseA + SBS_LV_Y] + ss[baseA + SBS_AV_Z] * rax - ss[baseA + SBS_AV_X] * raz;
-        const vAz_at = ss[baseA + SBS_LV_Z] + ss[baseA + SBS_AV_X] * ray - ss[baseA + SBS_AV_Y] * rax;
-        const vBx_at = ss[baseB + SBS_LV_X] + ss[baseB + SBS_AV_Y] * rbz - ss[baseB + SBS_AV_Z] * rby;
-        const vBy_at = ss[baseB + SBS_LV_Y] + ss[baseB + SBS_AV_Z] * rbx - ss[baseB + SBS_AV_X] * rbz;
-        const vBz_at = ss[baseB + SBS_LV_Z] + ss[baseB + SBS_AV_X] * rby - ss[baseB + SBS_AV_Y] * rbx;
-        const vn = (vAx_at - vBx_at) * nx + (vAy_at - vBy_at) * ny + (vAz_at - vBz_at) * nz;
-
-        const lambda = -m_eff_n * (vn + rest_bias);
-        const new_j_n = (j_n_accum + lambda) > 0 ? (j_n_accum + lambda) : 0;
-        const delta = new_j_n - j_n_accum;
-        data[off + 10] = new_j_n;
-
-        if (delta !== 0) {
-            const Px = nx * delta, Py = ny * delta, Pz = nz * delta;
-            apply_impulse_to_body(ss, baseA, invMA, rax, ray, raz, Px, Py, Pz, +1, scratch_inertia_a);
-            apply_impulse_to_body(ss, baseB, invMB, rbx, rby, rbz, Px, Py, Pz, -1, scratch_inertia_b);
+            const vAx_at = ss[baseA + SBS_LV_X] + ss[baseA + SBS_AV_Y] * raz - ss[baseA + SBS_AV_Z] * ray;
+            const vAy_at = ss[baseA + SBS_LV_Y] + ss[baseA + SBS_AV_Z] * rax - ss[baseA + SBS_AV_X] * raz;
+            const vAz_at = ss[baseA + SBS_LV_Z] + ss[baseA + SBS_AV_X] * ray - ss[baseA + SBS_AV_Y] * rax;
+            const vBx_at = ss[baseB + SBS_LV_X] + ss[baseB + SBS_AV_Y] * rbz - ss[baseB + SBS_AV_Z] * rby;
+            const vBy_at = ss[baseB + SBS_LV_Y] + ss[baseB + SBS_AV_Z] * rbx - ss[baseB + SBS_AV_X] * rbz;
+            const vBz_at = ss[baseB + SBS_LV_Z] + ss[baseB + SBS_AV_X] * rby - ss[baseB + SBS_AV_Y] * rbx;
+            const vn = (vAx_at - vBx_at) * nx + (vAy_at - vBy_at) * ny + (vAz_at - vBz_at) * nz;
+
+            const j_n_accum = data[off + 10];
+            const lambda = -m_eff_n * (vn + (armed ? rest_bias : 0));
+            const new_j_n = (j_n_accum + lambda) > 0 ? (j_n_accum + lambda) : 0;
+            let delta = new_j_n - j_n_accum;
+
+            // The part of this impulse that only stops what is left of the approach.
+            const stop = -m_eff_n * vn;
+            const approach = Math.min(stop > 0 ? stop : 0, delta > 0 ? delta : 0);
+
+            if (armed) {
+                // Poisson: what goes past stopping may total at most e times the compression.
+                const allowance = restitution * (compression + approach) - rest_jn[ci];
+                const cap = approach + (allowance > 0 ? allowance : 0);
+                if (delta > cap) delta = cap;
+            }
+
+            data[off + 10] = j_n_accum + delta;
+            rest_jn[ci] += delta - approach;
+            total_jn[ci] += delta;
+
+            if (delta !== 0) {
+                const impulse = scratch_impulse;
+                impulse[0] = nx * delta;
+                impulse[1] = ny * delta;
+                impulse[2] = nz * delta;
+                apply_impulse_to_body_oriented(ss, baseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, impulse, 0, +1, scratch_inertia_a);
+                apply_impulse_to_body_oriented(ss, baseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, impulse, 0, -1, scratch_inertia_b);
+            }
         }
     }
 }
@@ -1348,8 +1568,6 @@ export function solve_position(manifolds, system, pos_iters) {
             const idxB = idx[ci * INDEX_STRIDE + 3];
             const sbaseA = idxA * SBS_STRIDE;
             const sbaseB = idxB * SBS_STRIDE;
-            const invMA = ss[sbaseA + SBS_INV_MASS];
-            const invMB = ss[sbaseB + SBS_INV_MASS];
 
             const rax = pre[pre_off + 6], ray = pre[pre_off + 7], raz = pre[pre_off + 8];
             const rbx = pre[pre_off + 9], rby = pre[pre_off + 10], rbz = pre[pre_off + 11];
@@ -1387,11 +1605,12 @@ export function solve_position(manifolds, system, pos_iters) {
             pos_jn[ci] = new_jn;
 
             if (delta !== 0) {
-                const Px = nx * delta;
-                const Py = ny * delta;
-                const Pz = nz * delta;
-                apply_impulse_to_pseudo(pseudoVel, baseA, ss, sbaseA, invMA, rax, ray, raz, Px, Py, Pz, +1, scratch_inertia_a);
-                apply_impulse_to_pseudo(pseudoVel, baseB, ss, sbaseB, invMB, rbx, rby, rbz, Px, Py, Pz, -1, scratch_inertia_b);
+                const impulse = scratch_impulse;
+                impulse[0] = nx * delta;
+                impulse[1] = ny * delta;
+                impulse[2] = nz * delta;
+                apply_impulse_to_pseudo(pseudoVel, baseA, ss, sbaseA, pre, pre_off + PRE_QA, pre, pre_off + PRE_RA, impulse, 0, +1, scratch_inertia_a);
+                apply_impulse_to_pseudo(pseudoVel, baseB, ss, sbaseB, pre, pre_off + PRE_QB, pre, pre_off + PRE_RB, impulse, 0, -1, scratch_inertia_b);
             }
         }
     }
@@ -1415,8 +1634,12 @@ export function solve_position(manifolds, system, pos_iters) {
  * pseudo-velocity, restitution writes real velocity — so the order is
  * consistency, not behaviour.)
  *
- * The position pass writes `system.__pseudo_velocity`; the caller must zero
- * that buffer before this call and fold it into the pose afterwards.
+ * With hard contacts the position pass writes `system.__pseudo_velocity`, a
+ * correction for the caller to fold into the pose or drop. It accumulates onto
+ * the buffer, which must hold zeros where the pass writes: it does after a
+ * soft-contact `fixedUpdate`, or after `system.__reset_pseudo_velocity()`.
+ * The driver marks the buffer written, so the system's next step zeroes it
+ * before it integrates rather than applying the correction again.
  *
  * @param {ManifoldStore} manifolds
  * @param {PhysicsSystem} system
@@ -1467,8 +1690,9 @@ export function solve_contacts(manifolds, system, dt,
             solve_velocity(manifolds, system, 1, false);
         } else {
             solve_position(manifolds, system, pos_iters);
+            system.__pseudo_velocity_dirty = system.storage.high_water_mark * PSEUDO_STRIDE;
         }
-        apply_restitution(manifolds, system);
+        apply_restitution(manifolds, system, system.restitutionIterations);
     }
 
     solver_state.scatter(bodies);