@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/physics/ccd/linear_sweep.js

@@ -4,8 +4,11 @@ import { combine_friction, combine_restitution } from "../contact/combine_materi
 import { BodyKind } from "../ecs/BodyKind.js";
 import { is_sensor } from "../ecs/is_sensor.js";
 import { RigidBodyFlags } from "../ecs/RigidBodyFlags.js";
+import { SleepState } from "../ecs/SleepState.js";
+import { angular_effective_mass_raw, world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
 import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
-import { shape_cast } from "../queries/shape_cast.js";
+import { shape_cast, shape_cast_struck_support } from "../queries/shape_cast.js";
+import { PENETRATION_SLOP } from "../solver/solve_contacts.js";
 
 /**
  * Continuous collision detection — linear shape-cast.
@@ -21,11 +24,19 @@ import { shape_cast } from "../queries/shape_cast.js";
  * the substep solver has produced each body's final pose, sweep a CCD-flagged
  * fast mover's primary collider along its NET step translation
  * (start-of-step → final pose) using the existing {@link shape_cast} TOI engine.
- * On the first blocker, clamp the body to the contact pose, remove the inbound
- * normal component of its velocity (an inelastic stop), and RECORD the impact
- * on the pair's manifold ({@link record_ccd_contact}) so this step's event diff
- * reports it — the next discrete step then resolves the now-touching contact
- * with the real material / restitution.
+ * On the first blocker, clamp the body to the contact pose, RESPOND to the
+ * impact there and then ({@link ccd_respond}: the pair's restitution, and an
+ * impulse shared with a dynamic blocker), and RECORD the impact on the pair's
+ * manifold ({@link record_ccd_contact}) so this step's event diff reports it.
+ *
+ * The response cannot be left to the next discrete step. The clamp leaves the
+ * body clear of what it struck — {@link shape_cast} parks it 1e-5 to 1.25e-5 m
+ * short of a convex blocker, and on a triangle's face to within 5e-16 m either
+ * side — and the narrowphase reports only strictly positive penetration, so
+ * the next step sees no contact to respond with — and restitution arms only on
+ * an approach faster than `PhysicsSystem.restitutionThreshold`, which a stopped
+ * body no longer has. The sweep is the only part of the pipeline that saw the
+ * impact, so it is the part that answers it.
  *
  * Scope (v1, deliberate):
  *   - LINEAR sweep only: the orientation is held fixed through the sweep (the
@@ -37,8 +48,11 @@ import { shape_cast } from "../queries/shape_cast.js";
  *     leaves); APPROXIMATE against other dynamic bodies (they have moved this
  *     step too, but the sweep sees their start-of-step broadphase AABBs) — the
  *     speculative-margin floor for the dynamic-vs-dynamic case.
- *   - The CCD stop itself is inelastic; the impact does not bounce. Restitution
- *     applies on the next discrete contact.
+ *   - One impact per body per step, answered by one normal impulse and one
+ *     Coulomb friction impulse ({@link ccd_friction}) at the contact point. The
+ *     normal impulse against an immovable blocker is linear only (see
+ *     {@link ccd_respond}); friction turns the body as well, which is how a
+ *     ball spinning into a wall comes off it rolling.
  */
 
 /**
@@ -59,6 +73,39 @@ import { shape_cast } from "../queries/shape_cast.js";
  */
 export const CCD_MIN_SWEEP_DISTANCE = 1e-3;
 
+/**
+ * How far past the contact pose, along the contact normal, a body that STARTED
+ * its step touching what the sweep struck (within
+ * {@link CCD_MIN_SWEEP_DISTANCE} of it) may end the step and be left where the
+ * step put it: the solver's {@link PENETRATION_SLOP}. Such a body is resting
+ * on or sliding along the surface, and overlaps it at the end by no more than
+ * the solver lets a resting contact sink, so the next discrete step resolves
+ * it like any contact, with friction. A body whose centre would end on the
+ * surface's far side is clamped all the same: one thinner than the slop
+ * crosses a mesh triangle whole within it.
+ *
+ * It is that one COLLIDER the body is left to the discrete step for, not its
+ * whole sweep: the sweep steps past it ({@link step_past_slid_along}) and goes
+ * on to whatever else is in the path, as Box3D's continuous pass rejects a
+ * hit at a time of impact of zero shape by shape and continues its query.
+ * Skipping the whole sweep instead let a ball sliding on a floor it touched
+ * through a 1 cm or 2 mm wall in 8 of 48 cases, a 60 m/s one ending 30 m on.
+ *
+ * Clamping a body that started the step touching the surface put it back
+ * where it started, because the sweep found the contact at the start. Exactly
+ * touching, it then had no discrete contact either, so the next step did the
+ * same. A ball landing on a μ 0.5 floor while moving at 5 to 42 m/s stood
+ * still for 43 of its first 60 steps with its speed untouched, and a missile
+ * stopped at a box's corner stood there for good with the metre a second the
+ * corner's normal left it.
+ *
+ * Only a body that starts touching. Leaving every end pose this shallow to the
+ * discrete step also took over slow bounces from the sweep's exact response:
+ * bounces at 240 Hz lost up to 20% of their energy.
+ * @type {number}
+ */
+const CCD_CONTACT_SLOP = PENETRATION_SLOP;
+
 // ── Module scratch ──────────────────────────────────────────────────────────
 // CCD runs inside the step loop; reuse buffers so the pass allocates nothing.
 
@@ -79,6 +126,13 @@ const _ray = {
 /** Sweep result reused across bodies inside {@link ccd_resolve}. */
 const _hit = new PhysicsSurfacePoint();
 
+/**
+ * The swept body's orientation as the array {@link ccd_sweep_segment} takes, copied out of its
+ * transform once per body inside {@link ccd_resolve}: reading a Transform64's `rotation` builds a
+ * fresh view on every read. The sweep only translates, so it holds for every re-sweep of that body.
+ */
+const _sweep_rotation = new Float64Array(4);
+
 /**
  * The swept shape held at its CLAMPED pose, for the contact-witness support
  * query in {@link record_ccd_contact}.
@@ -86,9 +140,63 @@ const _hit = new PhysicsSurfacePoint();
  */
 const _clamped = new PosedShape3D();
 
-/** Contact witness written by {@link _clamped}'s support query. */
+/**
+ * The impact's contact point, written by {@link ccd_contact}: the centre of the
+ * swept shape's own surface feature facing the blocker at the clamped pose.
+ */
 const _witness = new Float64Array(3);
 
+/**
+ * The direction each witness support is asked along.
+ */
+const _witness_direction = new Float64Array(3);
+
+/**
+ * How many supports {@link ccd_contact} averages for the contact point, the
+ * tilt of their directions off the contact normal, and the phase of the first
+ * one. Eight directions 45° apart give each corner of a facing box face two
+ * of them, and each end of a facing edge four; the phase keeps the set off the
+ * axis-aligned directions, where two of a face's corners would tie. The tilt
+ * is the flatness a facing feature is allowed: corners within ~1% of its
+ * extent of the plane closest to the blocker count as touching it.
+ * @type {number}
+ */
+const WITNESS_SAMPLES = 8;
+const WITNESS_TILT = 0.01;
+const WITNESS_PHASE = 0.3;
+
+/**
+ * How spread across their thinnest direction, against their widest, the
+ * struck feature's samples must be to span an AREA — a triangle met on its
+ * face, rather than on an edge (two points) or a vertex (one), whose spread
+ * across is nothing but rounding.
+ * @type {number}
+ */
+const FACE_SPREAD = 1e-6;
+
+/** The pair's combined friction and restitution, written by {@link ccd_contact}. */
+let _friction = 0;
+let _restitution = 0;
+
+/**
+ * How far the clamped body's stored velocity lags its actual motion along the
+ * contact normal at the impact, relative to the blocker's (a falling blocker
+ * lags as much as the body), written by {@link ccd_velocity_at_impact}.
+ * @type {number}
+ */
+let _impact_lag = 0;
+
+/**
+ * The impulse {@link ccd_respond} applies, and scratch for its effective mass:
+ * a `LockRot*`-masked inverse-inertia diagonal and a world-space product.
+ */
+const _impulse = new Float64Array(3);
+const _masked_inertia = new Float64Array(3);
+const _inertia_scratch = new Float64Array(3);
+
+/** A collider's local bounding box, for {@link body_extent}. */
+const _local_box = new Float64Array(6);
+
 /**
  * Slots {@link record_ccd_contact} wrote this step, as `(slot, idA, idB)`
  * triples, for {@link ccd_release_contacts} to take back out again. Grows by
@@ -100,6 +208,14 @@ let _written = new Uint32Array(3 * 16);
 /** Number of triples currently in {@link _written}. */
 let _written_count = 0;
 
+/**
+ * Storage indices of the bodies the current pass clamped, in the order it
+ * clamped them; {@link ccd_resolve} returns how many. Grows by doubling;
+ * module-scoped so the pass allocates nothing in steady state.
+ * @type {Uint32Array}
+ */
+let _clamped_bodies = new Uint32Array(16);
+
 /**
  * CCD-eligible body indices of the current pass, ordered by ENTITY id.
  * Grows by doubling; module-scoped so the pass allocates nothing in steady
@@ -122,6 +238,25 @@ let _system = null;
  */
 let _self_body_id = -1;
 
+/**
+ * How many convex colliders one body's sweep may step past as surfaces it is
+ * sliding along ({@link CCD_CONTACT_SLOP}) before it is clamped at the next
+ * one anyway: a floor, a wall it runs along, and the like, each its own
+ * collider.
+ * @type {number}
+ */
+const CCD_MAX_SLID_ALONG = 4;
+
+/**
+ * Colliders the current body's sweep steps past, the first
+ * {@link _slid_along_count} of them; {@link _ccd_filter} rejects them.
+ * @type {Array<Collider|null>}
+ */
+const _slid_along = new Array(CCD_MAX_SLID_ALONG).fill(null);
+
+/** Number of live entries in {@link _slid_along}. */
+let _slid_along_count = 0;
+
 /**
  * Sweep filter, mirroring the discrete pipeline's pair acceptance:
  *   - never the swept body itself. BODY-id exclusion: every collider of a
@@ -138,7 +273,9 @@ let _self_body_id = -1;
  *     asking in sweep order let a filter accept for CCD what the broadphase
  *     had rejected. The sweep then clamped the body onto geometry the discrete
  *     pipeline had no pair for — and, once the sweep began reporting its own
- *     impacts ({@link record_ccd_contact}), raised contact events for it.
+ *     impacts ({@link record_ccd_contact}), raised contact events for it;
+ *   - not a collider the body is sliding along ({@link _slid_along}): that
+ *     contact is the discrete step's, and the sweep goes on past it.
  *
  * @param {number} entity candidate body's entity
  * @param {Collider} collider candidate body's primary collider
@@ -147,6 +284,9 @@ let _self_body_id = -1;
  */
 function _ccd_filter(entity, collider, body_id) {
     if (body_id === _self_body_id) return false;
+    for (let i = 0; i < _slid_along_count; i++) {
+        if (_slid_along[i] === collider) return false;
+    }
     if (is_sensor(_system.__bodies[body_id_index(body_id)], collider)) return false;
     if (_self_body_id !== -1) {
         const self_entity = _system.storage.entity_at(body_id_index(_self_body_id));
@@ -222,25 +362,838 @@ export function ccd_sweep_segment(
     }
 
     // result.t is the impact distance along the unit direction; normalise to a
-    // segment fraction. shape_cast reports the just-SEPARATING side of its
-    // bisection, so the swept shape at `result.t` is provably not overlapping —
-    // safe to place the body there.
+    // segment fraction. The swept shape at `result.t` is clear of the blocker
+    // or touching it, never in it by more than rounding: a convex blocker's
+    // conservative advancement parks it 1e-5 m short, and a triangle face's
+    // closed-form time leaves it ON the face — within 5e-16 m of it, on either
+    // side, measured over mesh and heightmap floors.
     const frac = result.t * inv;
     return frac < 1 ? frac : 1;
 }
 
+/**
+ * Take the gravity of the part of the step a clamped body did not travel back
+ * out of `lv`, its end-of-step linear velocity; and record in
+ * {@link _impact_lag} how far the stored velocity lags the body's actual
+ * motion along the contact normal.
+ *
+ * The clamp puts the body back where it struck, part-way through the step, but
+ * the velocity it carries out of the solver is the END-of-step one: it has had
+ * the whole step's gravity while the body only travelled the part of the step
+ * before the impact. Reflected, that velocity hands the bounce the rest of the
+ * step's gravity as free energy — an e = 1 ball dropped from 2 m came back to
+ * 2.059 m, every bounce, and from 0.5 m to 0.538 m.
+ *
+ * Gravity is the only thing taken back: `v ← v − g·(dt − τ)`, `τ` the time of
+ * impact and `g` the body's own gravity (`gravityScale` applied), as Box3D
+ * does. The body is then where its own free flight had it at `τ`, in pose and
+ * in velocity, and its free-flight energy is what it was. Gravity acts on the
+ * body alone, so taking the lost time's share back from the body alone is
+ * exact. ALL of it: taken out along the normal only, a ball falling into a
+ * vertical wall kept the vertical gravity of the time it did not fall
+ * through, and the integrator's free-flight energy rose by 0.11% to 0.35% a
+ * strike (and fell as much for a rising ball). And its OWN gravity, whatever
+ * it struck: what a falling blocker did enters the impulse, not the rewind
+ * (see {@link blocker_fall}). Taking back
+ * the step's WHOLE velocity change, `v_end − v_start`, also took back what the
+ * step's contacts had done — from this body only, never from the body on the
+ * other side of the contact, and never from its spin. In zero gravity a ball
+ * glancing off a free box changed the pair's momentum by up to 15% of itself,
+ * and a cloud of CCD bodies drifted by up to 4.7% of its bodies' summed |m·v|;
+ * a ball rolling along a wall it was pressed into had the floor's friction
+ * taken out of its velocity every step but left in its spin, and reached 1.38
+ * times the energy it started with.
+ *
+ * Under gravity the integrator's substeps (`h` long; velocity first, then
+ * position) put the body on the parabola whose velocity is the STORED velocity
+ * plus `½·g·h` — the stored one is the average over the substep just taken,
+ * half a substep behind the motion. Along the normal the body covered
+ * `d_n = (contact pose − start pose)·n` before it struck, starting with the
+ * normal motion `w0_n = v_n − g_n·dt + ½·g_n·h`; that fixes its normal motion
+ * at impact through `w_n² = w0_n² + 2·g_n·d_n` — the energy relation, so the
+ * impact neither gains nor loses — and the time of impact through
+ * `d_n = ½·(w0_n + w_n)·τ`.
+ *
+ * The response works on the normal MOTION of the body relative to the
+ * blocker's, which {@link _impact_lag} records: the body's lag `½·g_n·h`, less
+ * the blocker's own, `½·f_n·h` for a blocker falling at `f_n`
+ * ({@link blocker_fall}). Both lags differ from what the stored velocities
+ * say, and an elastic impulse that reverses the relative motion keeps the
+ * pair's free-flight energy, each body's on its own trajectory.
+ *
+ * The rest of the step, `dt − τ`, is lost: the body ends the step at the impact
+ * pose with the velocity it had there, which is what Box3D does too (its
+ * continuous solver takes the lost time's gravity back out of the velocity).
+ * Losing that time costs no energy; spending the lost time's gravity on a body
+ * that did not move would.
+ *
+ * @param {Float64Array} lv the body's linear velocity, rewritten in place
+ * @param {number} gx the body's gravity, `gravityScale` applied
+ * @param {number} gy
+ * @param {number} gz
+ * @param {number} fn the blocker's fall along `n` ({@link blocker_fall}), for
+ *   the relative lag
+ * @param {number} cx displacement from the start-of-step pose to the contact pose
+ * @param {number} cy
+ * @param {number} cz
+ * @param {ArrayLike<number>} n the blocker's unit outward normal, toward the body
+ * @param {number} frac the sweep's fraction of the step at impact — the time
+ *   of impact where the normal motion cannot say (it never closed on the blocker)
+ * @param {number} dt the step's length
+ * @param {number} h the integrator's substep length
+ */
+function ccd_velocity_at_impact(lv, gx, gy, gz, fn, cx, cy, cz, n, frac, dt, h) {
+    _impact_lag = 0;
+    if (!(dt > 0)) return;
+
+    const nx = n[0], ny = n[1], nz = n[2];
+    const gn = gx * nx + gy * ny + gz * nz;
+    const dn = cx * nx + cy * ny + cz * nz;
+    const lag = 0.5 * gn * h;
+    const w0n = lv[0] * nx + lv[1] * ny + lv[2] * nz - gn * dt + lag;
+
+    // Approaching at impact, by construction: the root on the closing side.
+    const disc = w0n * w0n + 2 * gn * dn;
+    const wn = -Math.sqrt(disc > 0 ? disc : 0);
+
+    const closing = w0n + wn;
+    let tau = closing < 0 ? 2 * dn / closing : frac * dt;
+    if (!Number.isFinite(tau)) tau = frac * dt;
+    if (tau < 0) tau = 0;
+    else if (tau > dt) tau = dt;
+
+    const lost = dt - tau;
+    lv[0] -= gx * lost;
+    lv[1] -= gy * lost;
+    lv[2] -= gz * lost;
+
+    _impact_lag = lag - 0.5 * fn * h;
+}
+
+/**
+ * How fast the body the sweep struck fell along the contact normal through
+ * the step: its acceleration along `n` over the solve, from the velocity
+ * change {@link ccd_resolve} read off before its first impulse, kept between
+ * none and its own gravity's. Zero for a static or kinematic blocker, and for
+ * a body that was not awake when the step began.
+ *
+ * A blocker in free flight runs half a substep of its gravity ahead of its
+ * stored velocity, as the mover does; one resting on something does not. So
+ * the fall decides how much of the blocker's lag the impulse takes off the
+ * mover's ({@link ccd_velocity_at_impact}): with each body's own, an elastic
+ * impulse keeps the pair's free-flight energy. With the mover's lag alone, a
+ * ball striking a falling box raised the pair's energy by up to 2.3% at 30 Hz
+ * with one substep.
+ *
+ * It decides no more than that. afc18e2b1 also took it off the mover's rewind,
+ * so that two bodies falling together collided as they would with gravity off.
+ * That left the mover at the pose of the impact with the velocity of the end
+ * of the step, and the pair's free-flight energy rose by 0.19% to 0.78% a
+ * strike. The mover is rewound by its own gravity instead, as Box3D does, and
+ * loses the rest of the step: the pair, now half a step apart in time, comes
+ * out of an elastic impact with 0.953 to 1.014 times the energy it had about
+ * its centre of mass, never more in all. A crate resting on the floor still
+ * does not fall: a ball bouncing on it comes back to 0.994 to 0.996 of its
+ * height.
+ *
+ * The rest of the blocker's velocity change is its contacts', which act on it
+ * and on something else, never on the mover: hence the clamp. The impulses of
+ * this pass are left out altogether: a ball that struck a box earlier in the
+ * pass set it moving, it did not make it fall.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {PhysicsSurfacePoint} hit the sweep result that produced the clamp
+ * @param {number} dt the step's length
+ * @param {number} captured how many of the awake set's first positions the
+ *   step captured a start-of-step velocity for
+ * @returns {number}
+ */
+function blocker_fall(system, hit, dt, captured) {
+    const blocker_id = hit.body_id;
+    const storage = system.storage;
+    if (blocker_id < 0 || !storage.is_valid(blocker_id) || !(dt > 0)) return 0;
+
+    const idx = body_id_index(blocker_id);
+    const blocker = system.__bodies[idx];
+    if (blocker === undefined || blocker.kind !== BodyKind.Dynamic) return 0;
+
+    // A body woken after the step began — by an impulse earlier in this
+    // pass, say — kept still until then, and its velocity change was never
+    // read.
+    const position = storage.awake_position_of(idx);
+    if (position === BODY_INDEX_ABSENT || position >= captured) return 0;
+
+    const nx = hit.normal[0], ny = hit.normal[1], nz = hit.normal[2];
+    const g = system.gravity;
+    const gn = (g[0] * nx + g[1] * ny + g[2] * nz) * blocker.gravityScale;
+
+    const change = system.__ccd_start_vel;
+    const b = idx * 3;
+    const an = (change[b] * nx + change[b + 1] * ny + change[b + 2] * nz) / dt;
+
+    const lo = gn < 0 ? gn : 0;
+    const hi = gn < 0 ? 0 : gn;
+    return an < lo ? lo : (an > hi ? hi : an);
+}
+
+/**
+ * How far the swept collider reaches from its centre toward what it struck,
+ * along the contact normal `n`: the height of its centre over the struck
+ * surface where they touch. A body that ends its step this far past the
+ * contact pose has its centre on the surface's far side.
+ *
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape
+ * @param {Transform64} tr the collider's transform
+ * @param {ArrayLike<number>} n the blocker's unit outward normal, toward the body
+ * @returns {number}
+ */
+function contact_depth_reach(shape, tr, n) {
+    _clamped.setup_components(
+        shape,
+        tr.translation_x, tr.translation_y, tr.translation_z,
+        tr.rotation_x, tr.rotation_y, tr.rotation_z, tr.rotation_w
+    );
+    _witness_direction[0] = -n[0];
+    _witness_direction[1] = -n[1];
+    _witness_direction[2] = -n[2];
+    _clamped.support(_witness, 0, _witness_direction, 0);
+    return (tr.translation_x - _witness[0]) * n[0]
+        + (tr.translation_y - _witness[1]) * n[1]
+        + (tr.translation_z - _witness[2]) * n[2];
+}
+
+/**
+ * If the sweep's hit is a CONVEX collider the swept body is sliding along —
+ * the body started the step within {@link CCD_MIN_SWEEP_DISTANCE} of it, ends
+ * the step no more than {@link CCD_CONTACT_SLOP} past it, and keeps its centre
+ * on its own side — add that collider to {@link _slid_along}, so the next
+ * sweep of the body steps past it, and say so.
+ *
+ * A convex collider is safe to step past: it lies wholly on the far side of
+ * the plane the body slides along, which the body crosses by no more than the
+ * slop. A concave one is not — the triangle the body slides on shares its
+ * collider with the walls it may run into — and {@link shape_cast} already
+ * steps past such triangles one by one.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {PhysicsSurfacePoint} hit the sweep's result
+ * @param {import("../../../core/geom/3d/shape/AbstractShape3D.js").AbstractShape3D} shape the swept shape
+ * @param {Transform64} tr the swept collider's transform, at the end pose
+ * @param {number} sx start of the sweep
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} ex end of the sweep
+ * @param {number} ey
+ * @param {number} ez
+ * @returns {boolean} true when a collider was added, and the body should be swept again
+ */
+function step_past_slid_along(system, hit, shape, tr, sx, sy, sz, ex, ey, ez) {
+    const hp = hit.position;
+    const n = hit.normal;
+    const overshoot = (hp[0] - ex) * n[0] + (hp[1] - ey) * n[1] + (hp[2] - ez) * n[2];
+    const closed = (sx - hp[0]) * n[0] + (sy - hp[1]) * n[1] + (sz - hp[2]) * n[2];
+    if (!(closed <= CCD_MIN_SWEEP_DISTANCE && overshoot <= CCD_CONTACT_SLOP)) return false;
+    if (!(overshoot < contact_depth_reach(shape, tr, n))) return false;
+
+    const blocker_id = hit.body_id;
+    if (blocker_id < 0 || !system.storage.is_valid(blocker_id)) return false;
+    const list = system.__body_collider_lists[body_id_index(blocker_id)];
+    if (list === undefined) return false;
+
+    const before = _slid_along_count;
+    for (let i = 0; i < list.length && _slid_along_count < CCD_MAX_SLID_ALONG; i++) {
+        const entry = list[i];
+        if (entry.entity === hit.collider_entity && entry.collider.shape.is_convex !== false) {
+            _slid_along[_slid_along_count++] = entry.collider;
+        }
+    }
+    return _slid_along_count > before;
+}
+
+/**
+ * Empty {@link _slid_along}, releasing the colliders it held.
+ */
+function clear_slid_along() {
+    for (let i = 0; i < _slid_along_count; i++) _slid_along[i] = null;
+    _slid_along_count = 0;
+}
+
+/**
+ * Whether the collider the sweep struck is concave — a mesh, a heightmap —
+ * which {@link shape_cast} sweeps triangle by triangle, so that what it struck
+ * is one triangle of a larger surface. The struck collider is the one on the
+ * entity the hit names (`collider_entity`). Asked of the whole body instead, a
+ * body with a mesh anywhere on it took the mesh rule for its convex parts too:
+ * a box face striking a 0.2 m cube that shared its body with a mesh put the
+ * impulse beside the cube, which spun off at 502 rad/s.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {PhysicsSurfacePoint} hit the sweep result that produced the clamp
+ * @returns {boolean}
+ */
+function struck_collider_is_concave(system, hit) {
+    const blocker_id = hit.body_id;
+    if (blocker_id < 0 || !system.storage.is_valid(blocker_id)) return false;
+
+    const list = system.__body_collider_lists[body_id_index(blocker_id)];
+    if (list === undefined) return false;
+
+    const entity = hit.collider_entity;
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        if (entry.entity === entity && entry.collider.shape.is_convex === false) return true;
+    }
+    return false;
+}
+
+/**
+ * The contact the sweep just found, as the response and the report both use
+ * it: its point into {@link _witness}, the pair's combined friction and
+ * restitution into {@link _friction} / {@link _restitution}.
+ *
+ * The point is the middle of where the two FEATURES facing each other overlap
+ * in the contact plane: the mover's around −normal at its clamped pose (a
+ * sphere's near pole, a box's leading corner, edge or face) and the struck
+ * surface's around +normal ({@link shape_cast_struck_support}). Each feature
+ * is sampled by {@link WITNESS_SAMPLES} supports along directions tilted
+ * {@link WITNESS_TILT} off the normal all round it — every one lands on an
+ * extreme point of the feature, so a vertex stays a vertex while an edge or a
+ * face spreads to its extent — and the point is the middle of the overlap of
+ * the two extents. A vertex against a face is the vertex; a small face against
+ * a large one is the small face's middle.
+ *
+ * A single support along −normal is a corner of whatever feature faces the
+ * blocker, and the impulse went in at that point: a box striking a box face to
+ * face took it at a corner of its face and spun off at 95 rad/s about two axes,
+ * keeping 52 of 60 m/s where the even split leaves 30. The mover's feature
+ * alone is not enough either: a box face striking a small ball 0.15 off the
+ * face's middle put the impulse at the face's middle, beside the ball, which
+ * spun off at 380 rad/s while the box kept straight on.
+ *
+ * Except on the FACE of a concave collider's triangle
+ * ({@link struck_collider_is_concave}): the struck feature is then the one
+ * triangle the sweep met, a fragment of a surface its neighbouring triangles
+ * continue, and the mover's feature alone places the contact. Overlapped with
+ * the triangle, a box's face striking a free plate of 0.1 m mesh cells flat and
+ * centred took the impulse under the triangle's middle, 0.25 off on both axes:
+ * box and plate spun at 228 rad/s between them and the box kept 93.75 of its
+ * 120 m/s, where the centred impulse leaves 40. A triangle met on an edge or a
+ * vertex keeps the overlap: a box's face striking the apex of a mesh pyramid
+ * 0.15 off its middle, placed by the box's face alone, put the impulse beside
+ * the apex — the pyramid spun at 54 rad/s and the box not at all, where the
+ * apex turns the box at 206 rad/s and leaves the pyramid still.
+ *
+ * Materials are combined exactly as `dispatch_pair` does, from the blocker's
+ * primary collider; an invalid blocker has none, and gets zero.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {Collider} collider the swept (primary) collider
+ * @param {Transform64} tr the swept collider's transform, already clamped to
+ *   the contact pose
+ * @param {PhysicsSurfacePoint} hit the sweep result that produced the clamp
+ */
+function ccd_contact(system, collider, tr, hit) {
+    const n = hit.normal;
+    const nx = n[0], ny = n[1], nz = n[2];
+    _clamped.setup_components(
+        collider.shape,
+        tr.translation_x, tr.translation_y, tr.translation_z,
+        tr.rotation_x, tr.rotation_y, tr.rotation_z, tr.rotation_w
+    );
+
+    // A tangent basis (t1, t2) of the contact plane: t1 from the world axis
+    // least aligned with n.
+    const ax = Math.abs(nx), ay = Math.abs(ny), az = Math.abs(nz);
+    let t1x, t1y, t1z;
+    if (ax <= ay && ax <= az) { t1x = 0; t1y = nz; t1z = -ny; }
+    else if (ay <= az) { t1x = -nz; t1y = 0; t1z = nx; }
+    else { t1x = ny; t1y = -nx; t1z = 0; }
+    const t1_inv = 1 / Math.sqrt(t1x * t1x + t1y * t1y + t1z * t1z);
+    t1x *= t1_inv; t1y *= t1_inv; t1z *= t1_inv;
+    const t2x = ny * t1z - nz * t1y;
+    const t2y = nz * t1x - nx * t1z;
+    const t2z = nx * t1y - ny * t1x;
+
+    // Both facing features, sampled, in contact-plane coordinates (u, v) and
+    // height h along n: the mover's around −n, the struck surface's around +n.
+    // Of the struck one also the spread, taken about its first sample so that
+    // coordinates far from the origin do not cancel it away.
+    let ua0 = Infinity, ua1 = -Infinity, va0 = Infinity, va1 = -Infinity, ha = 0;
+    let ub0 = Infinity, ub1 = -Infinity, vb0 = Infinity, vb1 = -Infinity;
+    let bu_ref = 0, bv_ref = 0, su = 0, sv = 0, suu = 0, svv = 0, suv = 0;
+    for (let k = 0; k < WITNESS_SAMPLES; k++) {
+        const angle = WITNESS_PHASE + k * (2 * Math.PI / WITNESS_SAMPLES);
+        const c = Math.cos(angle) * WITNESS_TILT;
+        const s = Math.sin(angle) * WITNESS_TILT;
+        const ox = c * t1x + s * t2x, oy = c * t1y + s * t2y, oz = c * t1z + s * t2z;
+
+        _witness_direction[0] = -nx + ox;
+        _witness_direction[1] = -ny + oy;
+        _witness_direction[2] = -nz + oz;
+        _clamped.support(_witness, 0, _witness_direction, 0);
+        const au = _witness[0] * t1x + _witness[1] * t1y + _witness[2] * t1z;
+        const av = _witness[0] * t2x + _witness[1] * t2y + _witness[2] * t2z;
+        if (au < ua0) ua0 = au;
+        if (au > ua1) ua1 = au;
+        if (av < va0) va0 = av;
+        if (av > va1) va1 = av;
+        ha += _witness[0] * nx + _witness[1] * ny + _witness[2] * nz;
+
+        _witness_direction[0] = nx + ox;
+        _witness_direction[1] = ny + oy;
+        _witness_direction[2] = nz + oz;
+        shape_cast_struck_support(_witness, 0, _witness_direction, 0);
+        const bu = _witness[0] * t1x + _witness[1] * t1y + _witness[2] * t1z;
+        const bv = _witness[0] * t2x + _witness[1] * t2y + _witness[2] * t2z;
+        if (bu < ub0) ub0 = bu;
+        if (bu > ub1) ub1 = bu;
+        if (bv < vb0) vb0 = bv;
+        if (bv > vb1) vb1 = bv;
+
+        if (k === 0) {
+            bu_ref = bu;
+            bv_ref = bv;
+        }
+        const du = bu - bu_ref, dv = bv - bv_ref;
+        su += du;
+        sv += dv;
+        suu += du * du;
+        svv += dv * dv;
+        suv += du * dv;
+    }
+    ha /= WITNESS_SAMPLES;
+
+    // A concave collider's struck feature is one triangle. Met on its FACE, it
+    // is a fragment of a surface its neighbours continue, and the mover's
+    // feature alone places the contact; met on an edge or a vertex, it is a
+    // feature in its own right, and the overlap below places it as on a convex
+    // body. The samples span an area only on the face: the spread across their
+    // thinnest direction is nothing for an edge or a vertex.
+    if (struck_collider_is_concave(system, hit)) {
+        const inv = 1 / WITNESS_SAMPLES;
+        const mu = su * inv, mv = sv * inv;
+        const cuu = suu * inv - mu * mu;
+        const cvv = svv * inv - mv * mv;
+        const cuv = suv * inv - mu * mv;
+        const mean = 0.5 * (cuu + cvv);
+        const dev = Math.sqrt(0.25 * (cuu - cvv) * (cuu - cvv) + cuv * cuv);
+        if (mean - dev > FACE_SPREAD * (mean + dev)) {
+            ub0 = vb0 = -Infinity;
+            ub1 = vb1 = Infinity;
+        }
+    }
+
+    // The middle of where the two features' extents overlap (or of the gap
+    // between them, the same expression): a vertex against a face is the
+    // vertex, a small face against a large one the small face's middle.
+    const u = 0.5 * ((ua0 > ub0 ? ua0 : ub0) + (ua1 < ub1 ? ua1 : ub1));
+    const v = 0.5 * ((va0 > vb0 ? va0 : vb0) + (va1 < vb1 ? va1 : vb1));
+    _witness[0] = u * t1x + v * t2x + ha * nx;
+    _witness[1] = u * t1y + v * t2y + ha * ny;
+    _witness[2] = u * t1z + v * t2z + ha * nz;
+
+    _friction = 0;
+    _restitution = 0;
+
+    const blocker_id = hit.body_id;
+    if (blocker_id < 0 || !system.storage.is_valid(blocker_id)) return;
+
+    const blocker_collider = system.__primary_collider(body_id_index(blocker_id));
+    if (blocker_collider !== null
+        && collider.friction !== undefined
+        && blocker_collider.friction !== undefined
+    ) {
+        _friction = combine_friction(collider.friction, blocker_collider.friction);
+        _restitution = combine_restitution(collider.restitution, blocker_collider.restitution);
+    }
+}
+
+/**
+ * Respond to the impact the sweep just resolved, at the moment of impact: one
+ * normal impulse at the contact point {@link ccd_contact} found, along the
+ * sweep's normal, and Coulomb friction against the contact point's slide
+ * ({@link ccd_friction}). The mover's velocity has already been rewound to the
+ * time of impact ({@link ccd_velocity_at_impact}).
+ *
+ * The normal velocity the response works on is the body's MOTION, the stored
+ * velocity plus {@link _impact_lag}: the stored velocity runs half a substep
+ * behind the motion, and the bounce has to send the motion away at `e` times
+ * its approach for the integrator's next substeps to retrace it. Reflecting the
+ * stored velocity drops the lag on the way in and again on the way out: an
+ * e = 1 ball lost 1.3% of its height every bounce from 2 m, and 13% from 7 cm
+ * at 30 Hz.
+ *
+ * Only an APPROACH is answered — a pair already separating along the normal
+ * (the solver's own restitution got there first, say) is left alone, so the
+ * response never doubles one the discrete step already gave. The approach must
+ * be faster than `PhysicsSystem.restitutionThreshold` to bounce, the rule
+ * `prepare_contacts` applies, so a slow impact comes to rest instead of
+ * buzzing.
+ *
+ * Against a DYNAMIC blocker the impulse is shared ({@link ccd_respond_shared}):
+ * stopping the mover alone, as the pass did, left the blocker where it was and
+ * threw the mover's momentum away — a 1 kg ball into a resting 1 kg box
+ * stopped at its face and the box never moved.
+ *
+ * Against an immovable blocker — static, kinematic, a sleeper the impact is too
+ * weak to wake, or one the sweep can no longer name — only the mover's
+ * velocity changes, and only linearly: its centre's normal motion relative to
+ * the blocker's surface becomes `−e` times what it was. That is the rigid-body
+ * answer for a sphere and for a body that cannot rotate. For a box struck on a
+ * corner it is not — the impulse there would also turn it — and that answer
+ * was measured and declined: a 60 m/s box flung into up to 330 rad/s of spin
+ * by a corner strike on a 2 cm wall turned through it within the next steps in
+ * 7 of 18 cases, the linear sweep holding its orientation fixed; with the
+ * linear response, 0 of 18. Friction does turn it, bounded by what stops the
+ * contact point's slide: tilted, spinning boxes fired obliquely at 60 m/s into
+ * a 2 cm wall of μ 0.5 or 1 reached 128 rad/s and turned through it in 0 of
+ * 162 cases.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {RigidBody} rb the swept body
+ * @param {Transform64} body_tr the swept body's own transform (its centre of
+ *   mass), already clamped
+ * @param {PhysicsSurfacePoint} hit the sweep result that produced the clamp
+ */
+function ccd_respond(system, rb, body_tr, hit) {
+    const n = hit.normal;
+    const nx = n[0], ny = n[1], nz = n[2];
+
+    const blocker_id = hit.body_id;
+    const valid = blocker_id >= 0 && system.storage.is_valid(blocker_id);
+    const blocker_idx = valid ? body_id_index(blocker_id) : -1;
+    const blocker = valid ? system.__bodies[blocker_idx] : undefined;
+    const blocker_tr = valid ? system.__transforms[blocker_idx] : undefined;
+    const known = blocker !== undefined && blocker_tr !== undefined;
+
+    if (known && blocker.kind === BodyKind.Dynamic
+        && ccd_respond_shared(system, rb, body_tr, blocker, blocker_idx, blocker_tr, nx, ny, nz)) {
+        return;
+    }
+
+    // The blocker's surface velocity at the contact point: a kinematic body's
+    // own motion; none for a static body, nor for a sleeper (at rest by the
+    // sleep invariant).
+    const px = _witness[0], py = _witness[1], pz = _witness[2];
+    let vbx = 0, vby = 0, vbz = 0;
+    if (known && (blocker.kind === BodyKind.KinematicVelocity || blocker.kind === BodyKind.KinematicPosition)) {
+        const bl = blocker.linearVelocity;
+        const ba = blocker.angularVelocity;
+        const rx = px - blocker_tr.translation_x;
+        const ry = py - blocker_tr.translation_y;
+        const rz = pz - blocker_tr.translation_z;
+        vbx = bl[0] + ba[1] * rz - ba[2] * ry;
+        vby = bl[1] + ba[2] * rx - ba[0] * rz;
+        vbz = bl[2] + ba[0] * ry - ba[1] * rx;
+    }
+
+    const lv = rb.linearVelocity;
+    const wn = (lv[0] - vbx) * nx + (lv[1] - vby) * ny + (lv[2] - vbz) * nz + _impact_lag;
+    if (!(wn < 0)) return;
+
+    const e = wn < -system.restitutionThreshold ? _restitution : 0;
+    const dv = -(1 + e) * wn;
+    lv[0] += dv * nx;
+    lv[1] += dv * ny;
+    lv[2] += dv * nz;
+
+    const inv_m = inverse_mass(rb);
+    if (inv_m > 0) {
+        ccd_friction(system, rb, body_tr, null, null, vbx, vby, vbz, dv / inv_m, nx, ny, nz);
+    }
+}
+
+/**
+ * Coulomb friction at the impact: a tangential impulse at the contact point
+ * {@link ccd_contact} found, against the slide of the mover's contact point
+ * over the blocker's surface, of at most `μ·j_n` — `μ` the pair's combined
+ * friction ({@link _friction}), `j_n` the normal impulse just applied. Within
+ * that bound it stops the slide: `j_t = s / K_t`, `s` the slide's speed and
+ * `K_t` the effective mass along it, `1/m_A + (r_A × t)·I_A⁻¹(r_A × t)` plus
+ * the blocker's own two terms when it is free. Applied at the contact point,
+ * linear and angular, to the mover and (oppositely) to a free blocker.
+ *
+ * The slide is the contact points' relative velocity after the normal impulse,
+ * spin included, less its normal part; the blocker's surface moves with a
+ * kinematic body's own motion and with a free body's.
+ *
+ * An impulse that at most stops the slide takes energy and never adds it, and
+ * one with its opposite on the other body keeps momentum about any point. With
+ * the normal impulse alone, whatever ran along the surface ran on: a ball shot
+ * straight down at 150 m/s onto a μ 0.5 slope of 5° or 10° kept its 13 or
+ * 26 m/s along it and went 11 or 23 m in a second, and a ball spinning at 20
+ * rad/s into a μ 0.5 wall left with all of it.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {RigidBody} rb the swept body
+ * @param {Transform64} body_tr its transform, already clamped
+ * @param {RigidBody|null} other a free blocker sharing the impulse, or null
+ * @param {Transform64|null} other_tr its transform
+ * @param {number} vbx the surface's velocity at the contact point, when `other` is null
+ * @param {number} vby
+ * @param {number} vbz
+ * @param {number} jn the normal impulse, ≥ 0
+ * @param {number} nx the blocker's outward normal, toward the mover
+ * @param {number} ny
+ * @param {number} nz
+ */
+function ccd_friction(system, rb, body_tr, other, other_tr, vbx, vby, vbz, jn, nx, ny, nz) {
+    const limit = _friction * jn;
+    if (!(limit > 0)) return;
+
+    const px = _witness[0], py = _witness[1], pz = _witness[2];
+
+    const lv = rb.linearVelocity;
+    const av = rb.angularVelocity;
+    const rax = px - body_tr.translation_x;
+    const ray = py - body_tr.translation_y;
+    const raz = pz - body_tr.translation_z;
+
+    let rbx = 0, rby = 0, rbz = 0;
+    if (other !== null) {
+        const bl = other.linearVelocity;
+        const ba = other.angularVelocity;
+        rbx = px - other_tr.translation_x;
+        rby = py - other_tr.translation_y;
+        rbz = pz - other_tr.translation_z;
+        vbx = bl[0] + ba[1] * rbz - ba[2] * rby;
+        vby = bl[1] + ba[2] * rbx - ba[0] * rbz;
+        vbz = bl[2] + ba[0] * rby - ba[1] * rbx;
+    }
+
+    // The contact points' relative velocity, and its part along the surface.
+    let ux = lv[0] + av[1] * raz - av[2] * ray - vbx;
+    let uy = lv[1] + av[2] * rax - av[0] * raz - vby;
+    let uz = lv[2] + av[0] * ray - av[1] * rax - vbz;
+    const un = ux * nx + uy * ny + uz * nz;
+    ux -= un * nx;
+    uy -= un * ny;
+    uz -= un * nz;
+
+    const slide = Math.sqrt(ux * ux + uy * uy + uz * uz);
+    if (!(slide > 0)) return;
+    const tx = ux / slide, ty = uy / slide, tz = uz / slide;
+
+    let k = inverse_mass(rb) + angular_term(rb, body_tr, rax, ray, raz, tx, ty, tz);
+    if (other !== null) {
+        k += inverse_mass(other) + angular_term(other, other_tr, rbx, rby, rbz, tx, ty, tz);
+    }
+    if (!(k > 0)) return;
+
+    const stop = slide / k;
+    const jt = stop < limit ? stop : limit;
+
+    _impulse[0] = -tx * jt;
+    _impulse[1] = -ty * jt;
+    _impulse[2] = -tz * jt;
+    system.applyImpulseAt(rb, body_tr, _impulse, _witness);
+
+    if (other !== null) {
+        _impulse[0] = -_impulse[0];
+        _impulse[1] = -_impulse[1];
+        _impulse[2] = -_impulse[2];
+        system.applyImpulseAt(other, other_tr, _impulse, _witness);
+    }
+}
+
+/**
+ * The impulse {@link ccd_respond} shares with a dynamic blocker:
+ * `j = −(1 + e)·w_n / K`, `w_n` the normal velocity of the contact point of the
+ * mover relative to that of the blocker (taken as their relative motion, the
+ * stored velocities plus {@link _impact_lag}, see {@link ccd_respond}), and
+ * `K = 1/m_A + 1/m_B + (r_A × n)·I_A⁻¹(r_A × n) + (r_B × n)·I_B⁻¹(r_B × n)`,
+ * applied to both bodies at the contact point, linear and angular, and then
+ * Coulomb friction between them ({@link ccd_friction}), also shared.
+ *
+ * A SLEEPING blocker is woken only by an impulse that leaves it moving faster
+ * than the sleep test lets a body sleep at ({@link PhysicsSystem#sleepVelocitySqrThreshold}),
+ * judged by the sleep test's own metric: the speed of the body's far end,
+ * `|v|² + |ω|²·max(extent, 1)²` ({@link body_extent}). A weaker one is
+ * declined — the sleeper stands as an anchor, the way the solver gathers a
+ * sleeping body — because the sleep test would only zero it again a moment
+ * later, and because a body ground against a sleeper re-strikes it every step
+ * for nothing: waking it each time left it flickering awake and asleep for as
+ * long as the grinding lasted. Judged on `|ω|²` alone, a 4 g pellet at 100 m/s
+ * into the tip of a sleeping 20 m plank read 0.0017 where the tip would move at
+ * 0.12 m/s (0.0145 against the threshold's 0.01): the plank stood, and the
+ * pellet's momentum went nowhere.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {RigidBody} rb
+ * @param {Transform64} body_tr
+ * @param {RigidBody} blocker
+ * @param {number} blocker_idx the blocker's storage index
+ * @param {Transform64} blocker_tr
+ * @param {number} nx blocker's outward normal, toward the mover
+ * @param {number} ny
+ * @param {number} nz
+ * @returns {boolean} false when declined — the caller treats the blocker as
+ *   immovable
+ */
+function ccd_respond_shared(system, rb, body_tr, blocker, blocker_idx, blocker_tr, nx, ny, nz) {
+    const px = _witness[0], py = _witness[1], pz = _witness[2];
+
+    const lv = rb.linearVelocity;
+    const av = rb.angularVelocity;
+    const rax = px - body_tr.translation_x;
+    const ray = py - body_tr.translation_y;
+    const raz = pz - body_tr.translation_z;
+
+    const bl = blocker.linearVelocity;
+    const ba = blocker.angularVelocity;
+    const rbx = px - blocker_tr.translation_x;
+    const rby = py - blocker_tr.translation_y;
+    const rbz = pz - blocker_tr.translation_z;
+
+    const wn = (lv[0] + av[1] * raz - av[2] * ray - (bl[0] + ba[1] * rbz - ba[2] * rby)) * nx
+        + (lv[1] + av[2] * rax - av[0] * raz - (bl[1] + ba[2] * rbx - ba[0] * rbz)) * ny
+        + (lv[2] + av[0] * ray - av[1] * rax - (bl[2] + ba[0] * rby - ba[1] * rbx)) * nz
+        + _impact_lag;
+    if (!(wn < 0)) return true;
+
+    const e = wn < -system.restitutionThreshold ? _restitution : 0;
+
+    const inv_mb = inverse_mass(blocker);
+    const k = inverse_mass(rb) + inv_mb
+        + angular_term(rb, body_tr, rax, ray, raz, nx, ny, nz)
+        + angular_term(blocker, blocker_tr, rbx, rby, rbz, nx, ny, nz);
+    if (!(k > 0)) return true;
+
+    const j = -(1 + e) * wn / k;
+
+    if (blocker.sleepState !== SleepState.Awake) {
+        // The blocker's velocity change: −j·n linearly, I⁻¹(r × −j·n) angularly.
+        const dv = j * inv_mb;
+        masked_inverse_inertia(blocker);
+        world_inverse_inertia_apply_raw(
+            _inertia_scratch, 0,
+            _masked_inertia[0], _masked_inertia[1], _masked_inertia[2],
+            blocker_tr.rotation_x, blocker_tr.rotation_y, blocker_tr.rotation_z, blocker_tr.rotation_w,
+            -(rby * nz - rbz * ny) * j, -(rbz * nx - rbx * nz) * j, -(rbx * ny - rby * nx) * j
+        );
+        const w = _inertia_scratch;
+        const extent = body_extent(system, blocker_idx, blocker_tr);
+        const reach = extent > 1 ? extent : 1;
+        if (dv * dv + (w[0] * w[0] + w[1] * w[1] + w[2] * w[2]) * reach * reach <= system.sleepVelocitySqrThreshold) {
+            return false;
+        }
+    }
+
+    _impulse[0] = nx * j;
+    _impulse[1] = ny * j;
+    _impulse[2] = nz * j;
+    system.applyImpulseAt(rb, body_tr, _impulse, _witness);
+
+    _impulse[0] = -_impulse[0];
+    _impulse[1] = -_impulse[1];
+    _impulse[2] = -_impulse[2];
+    system.applyImpulseAt(blocker, blocker_tr, _impulse, _witness);
+
+    ccd_friction(system, rb, body_tr, blocker, blocker_tr, 0, 0, 0, j, nx, ny, nz);
+
+    return true;
+}
+
+/**
+ * A body's extent, metres: how far from its centre any of its colliders
+ * reaches — each collider's local bounding-box corner radius plus the
+ * collider's offset from the body — exactly as stage 2 of the step records it
+ * in `PhysicsSystem.__body_extent` for the sleep test.
+ *
+ * Computed here from the colliders, not read from there: stage 2 writes the
+ * AWAKE bodies only, and a sleeper's slot is not kept. Linking twelve more
+ * bodies after a 20 m plank fell asleep grew the array, and the plank's slot
+ * then read 0; a body linked asleep never had one written.
+ *
+ * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {number} idx the body's storage index
+ * @param {Transform64} body_tr the body's transform (its centre)
+ * @returns {number}
+ */
+function body_extent(system, idx, body_tr) {
+    const list = system.__body_collider_lists[idx];
+    if (list === undefined) return 0;
+
+    let extent = 0;
+    for (let i = 0; i < list.length; i++) {
+        const entry = list[i];
+        entry.collider.shape.compute_bounding_box(_local_box);
+
+        const ex = -_local_box[0] > _local_box[3] ? -_local_box[0] : _local_box[3];
+        const ey = -_local_box[1] > _local_box[4] ? -_local_box[1] : _local_box[4];
+        const ez = -_local_box[2] > _local_box[5] ? -_local_box[2] : _local_box[5];
+        const ct = entry.transform;
+        const ox = ct.translation_x - body_tr.translation_x;
+        const oy = ct.translation_y - body_tr.translation_y;
+        const oz = ct.translation_z - body_tr.translation_z;
+        const reach = Math.sqrt(ex * ex + ey * ey + ez * ez) + Math.sqrt(ox * ox + oy * oy + oz * oz);
+
+        if (reach > extent) extent = reach;
+    }
+    return extent;
+}
+
+/**
+ * @param {RigidBody} rb a dynamic body
+ * @returns {number}
+ */
+function inverse_mass(rb) {
+    return rb.mass > 0 ? 1 / rb.mass : 0;
+}
+
+/**
+ * Write `rb`'s body-local inverse-inertia diagonal into {@link _masked_inertia}
+ * with the `LockRot*` mask `PhysicsSystem#applyImpulseAt` (which applies the
+ * impulse) and the solver gather use.
+ *
+ * @param {RigidBody} rb
+ */
+function masked_inverse_inertia(rb) {
+    const ii = rb.inverseInertiaLocal;
+    const flags = rb.flags;
+    _masked_inertia[0] = (flags & RigidBodyFlags.LockRotX) !== 0 ? 0 : ii[0];
+    _masked_inertia[1] = (flags & RigidBodyFlags.LockRotY) !== 0 ? 0 : ii[1];
+    _masked_inertia[2] = (flags & RigidBodyFlags.LockRotZ) !== 0 ? 0 : ii[2];
+}
+
+/**
+ * One body's angular share of a normal impulse's effective mass at lever arm
+ * `r`: `(r × n)·I_w⁻¹(r × n)`.
+ *
+ * @param {RigidBody} rb
+ * @param {Transform64} tr
+ * @param {number} rx
+ * @param {number} ry
+ * @param {number} rz
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz
+ * @returns {number}
+ */
+function angular_term(rb, tr, rx, ry, rz, nx, ny, nz) {
+    masked_inverse_inertia(rb);
+    return angular_effective_mass_raw(
+        _masked_inertia[0], _masked_inertia[1], _masked_inertia[2],
+        tr.rotation_x, tr.rotation_y, tr.rotation_z, tr.rotation_w,
+        rx, ry, rz,
+        nx, ny, nz,
+        _inertia_scratch
+    );
+}
+
 /**
  * Record the impact the sweep just resolved as a contact on the pair's
  * manifold, so this step's event diff reports it.
  *
  * ## Why the sweep has to report its own impacts
  *
- * The clamp parks the body on the just-SEPARATING side of the TOI bisection —
- * {@link shape_cast} reports `t_lo`, the last sample proven NOT to overlap, and
- * that is exactly the property the clamp relies on. The discrete narrowphase
- * emits a contact only for STRICTLY POSITIVE penetration. So the pose CCD
- * produces is, by construction, the one pose the narrowphase calls "not
- * touching": a body stopped dead by the sweep raised no ContactBegin, and kept
+ * The clamp parks the body clear of the surface or touching it:
+ * {@link shape_cast} stops a convex blocker's advancement 1e-5 m short, and a
+ * triangle face's closed-form time leaves the body on the face to within
+ * 5e-16 m, either side. The discrete narrowphase emits a contact only for
+ * STRICTLY POSITIVE penetration. So the pose CCD produces is one the
+ * narrowphase calls "not touching", or calls touching only as the rounding
+ * falls: a body stopped dead by the sweep raised no ContactBegin, and kept
  * raising none for as long as it sat there.
  *
  * That it ever appeared to work at all was luck about which side of tangency
@@ -263,8 +1216,10 @@ export function ccd_sweep_segment(
  *
  * ## What is written
  *
- * A single contact at depth ZERO. The sweep stopped the body ON the surface, so
- * the pair is touching and the penetration is nothing; that is the honest depth
+ * A single contact at depth ZERO. The sweep stopped the body at the surface —
+ * 1e-5 to 1.25e-5 m clear of a convex, on a triangle's face to within
+ * 5e-16 m — so the
+ * pair is touching and the penetration is nothing; that is the honest depth
  * and the one the solver's `PENETRATION_SLOP`-gated position bias ignores.
  * Both witness points are the same point — at a tangency the two surfaces meet
  * there — and `feature_id` is 0, no stable cross-frame feature, same as the
@@ -284,14 +1239,13 @@ export function ccd_sweep_segment(
  * manifold is the better one, and only an impact the discrete pass could not
  * see is this pass's to report.
  *
+ * Reads the contact point and materials {@link ccd_contact} computed.
+ *
  * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
  * @param {number} body_idx swept body's storage index
- * @param {Collider} collider the swept (primary) collider
- * @param {Transform64} tr the swept body's transform, already clamped to the
- *   contact pose
  * @param {PhysicsSurfacePoint} hit the sweep result that produced the clamp
  */
-function record_ccd_contact(system, body_idx, collider, tr, hit) {
+function record_ccd_contact(system, body_idx, hit) {
     const blocker_id = hit.body_id;
 
     const storage = system.storage;
@@ -315,33 +1269,8 @@ function record_ccd_contact(system, body_idx, collider, tr, hit) {
     // swept body.
     const n = hit.normal;
 
-    // Contact witness: the swept shape's own surface point facing the blocker,
-    // which is its support along −n (a sphere's near pole, a box's leading
-    // corner). Taking it from the MOVER rather than the blocker is what keeps it
-    // near the actual contact patch — a large blocker's support along a face
-    // axis is a corner metres away, which is why the narrowphase's EPA fallback
-    // refuses support witnesses and falls back to body centres.
-    _clamped.setup_components(
-        collider.shape,
-        tr.translation_x, tr.translation_y, tr.translation_z,
-        tr.rotation_x, tr.rotation_y, tr.rotation_z, tr.rotation_w
-    );
-    _clamped.support(_witness, 0, -n[0], -n[1], -n[2]);
-
     const wx = _witness[0], wy = _witness[1], wz = _witness[2];
 
-    // Per-contact materials, combined exactly as `dispatch_pair` does.
-    const blocker_collider = system.__primary_collider(blocker_idx);
-    let friction = 0;
-    let restitution = 0;
-    if (blocker_collider !== null
-        && collider.friction !== undefined
-        && blocker_collider.friction !== undefined
-    ) {
-        friction = combine_friction(collider.friction, blocker_collider.friction);
-        restitution = combine_restitution(collider.restitution, blocker_collider.restitution);
-    }
-
     // The stored normal points from the slot's OWN body B toward its body A.
     const s = self_is_a ? 1 : -1;
 
@@ -351,7 +1280,7 @@ function record_ccd_contact(system, body_idx, collider, tr, hit) {
         wx, wy, wz,
         n[0] * s, n[1] * s, n[2] * s,
         0, 0,
-        friction, restitution,
+        _friction, _restitution,
     );
 
     const w = _written_count * 3;
@@ -398,12 +1327,13 @@ export function ccd_release_contacts(system) {
  * Post-solve continuous-collision pass over the awake set. For each awake
  * Dynamic body flagged {@link RigidBodyFlags.CCD} that moved more than
  * {@link CCD_MIN_SWEEP_DISTANCE} this step, sweep its primary collider along the
- * step's net translation and stop it at the first blocker (clamp pose + remove
- * inbound normal velocity).
+ * step's net translation and stop it at the first blocker (clamp pose + the
+ * impact's response, {@link ccd_respond}).
  *
  * Start-of-step positions are captured into `system.__ccd_start_pos` (3 doubles
- * per body index) before the substep loop; this pass reads the final pose from
- * the live Transform64.
+ * per body index) before the substep loop, and the start-of-step velocities of
+ * the awake dynamic bodies into `system.__ccd_start_vel`; this pass reads the
+ * final pose from the live Transform64.
  *
  * Bodies are processed in ENTITY order, not awake-list order. CCD order is
  * outcome-coupled: an earlier body's clamp moves the pose a later body's
@@ -413,25 +1343,47 @@ export function ccd_release_contacts(system) {
  * state need not share; entity order is derivable from state alone — the
  * determinism contract.
  *
+ * Returns how many bodies the pass CLAMPED — moved back from the pose the step
+ * integrated them to — with their storage indices in {@link ccd_clamped_bodies}.
+ * Whatever the step already published from those poses is stale.
+ *
  * @param {import("../ecs/PhysicsSystem.js").PhysicsSystem} system
+ * @param {number} dt the step's length, seconds
+ * @param {number} h the integrator's substep length, seconds
+ * @param {number} captured how many of the awake set's first positions the
+ *   step captured start-of-step state for — the bodies awake when it began
+ * @returns {number} clamped body count
  */
-export function ccd_resolve(system) {
+export function ccd_resolve(system, dt, h, captured) {
     // Each pass owns its own report list. Dropped rather than carried if a
     // caller never got round to releasing the previous one, so a slot id can
     // never be cleared a step after it was written (or for a pair that has
     // since been reallocated onto it).
     _written_count = 0;
 
+    let clamped = 0;
+
     const storage = system.storage;
-    const count = storage.awake_count;
+    const count = captured < storage.awake_count ? captured : storage.awake_count;
     const lists = system.__body_collider_lists;
     const start = system.__ccd_start_pos;
+    const gravity = system.gravity;
     const CCD = RigidBodyFlags.CCD;
 
-    // Collect the CCD-eligible awake bodies…
+    // Collect the movers the step took a start pose for (`__ccd_movers`), as
+    // they still are: awake, dynamic, flagged, and swept by the same primary
+    // collider. A body woken, flagged or given its first collider since — by
+    // a listener on an announcement, say — has no start pose this step: its
+    // slot held whatever was there, the origin for a body never swept, and a
+    // ball 5 m out was swept from the origin and clamped 2.65 m back at a wall
+    // half way…
+    const movers = system.__ccd_movers;
+    const mover_colliders = system.__ccd_mover_colliders;
+    const mover_count = system.__ccd_mover_count;
     let n = 0;
-    for (let i = 0; i < count; i++) {
-        const idx = storage.awake_at(i);
+    for (let k = 0; k < mover_count; k++) {
+        const idx = movers[k];
+        if (!storage.is_awake(idx)) continue;
 
         const rb = system.__bodies[idx];
         if (rb === undefined) continue;
@@ -439,7 +1391,7 @@ export function ccd_resolve(system) {
         if (rb.kind !== BodyKind.Dynamic) continue;
 
         const list = lists[idx];
-        if (list === undefined || list.length === 0) continue;
+        if (list === undefined || list.length === 0 || list[0].collider !== mover_colliders[k]) continue;
 
         if (n === _ccd_order.length) {
             const next = new Uint32Array(_ccd_order.length * 2);
@@ -448,7 +1400,24 @@ export function ccd_resolve(system) {
         }
         _ccd_order[n++] = idx;
     }
-    if (n === 0) return;
+    if (n === 0) return 0;
+
+    // Each awake dynamic body's velocity change through the solve, in place of
+    // its start-of-step velocity, read now: before this pass's own impulses
+    // change any of them. See {@link blocker_fall}.
+    const change = system.__ccd_start_vel;
+    for (let i = 0; i < count; i++) {
+        const idx = storage.awake_at(i);
+
+        const rb = system.__bodies[idx];
+        if (rb === undefined || rb.kind !== BodyKind.Dynamic) continue;
+
+        const lv = rb.linearVelocity;
+        const b = idx * 3;
+        change[b] = lv[0] - change[b];
+        change[b + 1] = lv[1] - change[b + 1];
+        change[b + 2] = lv[2] - change[b + 2];
+    }
 
     // …and order them by entity (insertion sort; CCD bodies are few).
     for (let i = 1; i < n; i++) {
@@ -468,15 +1437,14 @@ export function ccd_resolve(system) {
         const list = lists[idx];
         const primary = list[0];
         const tr = primary.transform;
-        const p = tr.translation;
 
         const base = idx * 3;
         const sx = start[base];
         const sy = start[base + 1];
         const sz = start[base + 2];
-        const ex = p[0];
-        const ey = p[1];
-        const ez = p[2];
+        const ex = tr.translation_x;
+        const ey = tr.translation_y;
+        const ez = tr.translation_z;
 
         const dx = ex - sx;
         const dy = ey - sy;
@@ -497,56 +1465,122 @@ export function ccd_resolve(system) {
         // NOT primary.entity: a compound body's primary collider can live on a
         // CHILD entity, and excluding that child would leave the body's other
         // leaves visible to its own sweep (self-hit at t = 0).
-        const frac = ccd_sweep_segment(
-            system, shape, tr.rotation,
+        const entity = storage.entity_at(idx);
+
+        _sweep_rotation[0] = tr.rotation_x;
+        _sweep_rotation[1] = tr.rotation_y;
+        _sweep_rotation[2] = tr.rotation_z;
+        _sweep_rotation[3] = tr.rotation_w;
+
+        let frac = ccd_sweep_segment(
+            system, shape, _sweep_rotation,
             sx, sy, sz, ex, ey, ez,
-            storage.entity_at(idx), _hit,
+            entity, _hit,
         );
+
+        // A convex collider the body starts the step touching and slides
+        // along is in a contact for the next discrete step to resolve, not a
+        // tunnel: the sweep steps past THAT collider and sweeps again, for
+        // whatever else is in the way. See {@link CCD_CONTACT_SLOP}.
+        while (frac < 1 && step_past_slid_along(system, _hit, shape, tr, sx, sy, sz, ex, ey, ez)) {
+            frac = ccd_sweep_segment(
+                system, shape, _sweep_rotation,
+                sx, sy, sz, ex, ey, ez,
+                entity, _hit,
+            );
+        }
+        clear_slid_along();
+
         if (frac >= 1) continue; // clear path — no tunnelling this step
 
+        const hp = _hit.position;
+        const cdx = hp[0] - ex;
+        const cdy = hp[1] - ey;
+        const cdz = hp[2] - ez;
+        const n_hit = _hit.normal;
+
         // Clamp the body to the first-contact pose (swept-shape centre at the
         // TOI), so it cannot end the step on the far side of the blocker.
         //
         // The sweep is of the primary COLLIDER, whose transform is the body's
         // own only for a same-entity collider. The clamp has to land on the
-        // body — that is what integration moved and what the velocity fix
-        // below applies to — so a child collider's transform is displaced by
+        // body — that is what integration moved and what the response below
+        // applies to — so a child collider's transform is displaced by
         // the same delta rather than being assigned the swept centre, which
         // would move the child out from under the body it belongs to.
-        const hp = _hit.position;
         const body_tr = system.__transforms[idx];
-        if (body_tr === tr) {
-            p[0] = hp[0];
-            p[1] = hp[1];
-            p[2] = hp[2];
-        } else {
-            const bp = body_tr.translation;
-            bp[0] += hp[0] - ex;
-            bp[1] += hp[1] - ey;
-            bp[2] += hp[2] - ez;
-            p[0] = hp[0];
-            p[1] = hp[1];
-            p[2] = hp[2];
+        if (body_tr !== tr) {
+            body_tr.setTranslation(
+                body_tr.translation_x + cdx,
+                body_tr.translation_y + cdy,
+                body_tr.translation_z + cdz
+            );
         }
+        tr.setTranslation(hp[0], hp[1], hp[2]);
 
-        // Remove the inbound normal component of velocity (inelastic stop).
-        // `_hit.normal` is the blocker's outward surface normal; the body is
-        // moving into it (v·n < 0). Zeroing that component leaves the tangential
-        // slide intact and never adds energy. The next discrete step applies the
-        // real restitution / friction on the established contact.
-        const n = _hit.normal;
-        const lv = rb.linearVelocity;
-        const vn = lv[0] * n[0] + lv[1] * n[1] + lv[2] * n[2];
-        if (vn < 0) {
-            lv[0] -= vn * n[0];
-            lv[1] -= vn * n[1];
-            lv[2] -= vn * n[2];
+        // The body's OTHER child-entity colliders go with it too. They are
+        // re-composed only when the body is announced again, after this pass,
+        // and a CCD body swept later in this pass would meet them where the
+        // body would have tunnelled to: a ball falling past a clamped body's
+        // child collider, 0.1 to its side, swept against the child 0.1 further
+        // off and ended the step 10 cm inside it. The clamp is a translation,
+        // so every child moves by the same delta.
+        for (let c = 1; c < list.length; c++) {
+            const ct = list[c].transform;
+            if (ct === body_tr || ct === tr) continue;
+            let seen = false;
+            for (let o = 1; o < c; o++) {
+                if (list[o].transform === ct) { seen = true; break; }
+            }
+            if (seen) continue;
+            ct.setTranslation(ct.translation_x + cdx, ct.translation_y + cdy, ct.translation_z + cdz);
+        }
+
+        if (clamped === _clamped_bodies.length) {
+            const next = new Uint32Array(_clamped_bodies.length * 2);
+            next.set(_clamped_bodies);
+            _clamped_bodies = next;
         }
+        _clamped_bodies[clamped++] = idx;
+
+        // The body is now where it was at the moment of impact, so its velocity
+        // must not carry the gravity of the rest of the step, which it never
+        // travelled. See {@link ccd_velocity_at_impact}; the struck body's fall
+        // ({@link blocker_fall}) only sets the relative integrator lag.
+        ccd_velocity_at_impact(
+            rb.linearVelocity,
+            gravity[0] * rb.gravityScale, gravity[1] * rb.gravityScale, gravity[2] * rb.gravityScale,
+            blocker_fall(system, _hit, dt, captured),
+            hp[0] - sx, hp[1] - sy, hp[2] - sz,
+            n_hit, frac, dt, h
+        );
+
+        // Answer the impact where it happened: the pair's restitution, and an
+        // impulse shared with a dynamic blocker. Nothing later will — the body
+        // now rests at the surface without penetrating it (clear of a convex,
+        // on a triangle's face to rounding), where the narrowphase sees no
+        // contact. See {@link ccd_respond}.
+        ccd_contact(system, primary.collider, tr, _hit);
+        ccd_respond(system, rb, body_tr, _hit);
 
         // Tell the world it happened. The clamp above is the whole of the
         // collision — the discrete narrowphase samples step boundaries and this
         // impact was between two of them — so without this the body is stopped
         // dead and nothing is ever told. See {@link record_ccd_contact}.
-        record_ccd_contact(system, idx, primary.collider, tr, _hit);
+        record_ccd_contact(system, idx, _hit);
     }
+
+    return clamped;
+}
+
+/**
+ * Storage indices of the bodies the last {@link ccd_resolve} clamped; the
+ * first `n` entries are live, `n` being what that call returned. The array is
+ * the pass's own scratch: read it before the next pass, and do not keep it
+ * (it is replaced when it grows).
+ *
+ * @returns {Uint32Array}
+ */
+export function ccd_clamped_bodies() {
+    return _clamped_bodies;
 }