@woosh/meep-engine 2.143.0 → 2.144.0

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

@@ -1,9 +1,9 @@
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
 import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
-import { mpr } from "../gjk/mpr.js";
 import { aabb_world_to_local } from "./decomposition/aabb_world_to_local.js";
 import { decompose_to_triangles } from "./decomposition/decompose_to_triangles.js";
 import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
+import { deepest_pair_penetration } from "./narrowphase_step.js";
 import { PosedShape } from "./PosedShape.js";
 
 /**
@@ -11,54 +11,45 @@ import { PosedShape } from "./PosedShape.js";
  * the other narrowphase utilities. Safe because PhysicsSystem queries
  * (and gameplay code calling this) run on the main thread.
  */
-const posed_a = new PosedShape();
 const posed_b = new PosedShape();
 
-// MPR result buffer — direction is "A's interior into B", magnitude is
-// the depth. Same convention as EPA but MPR converges reliably on
-// smooth-vs-smooth supports where EPA hits its iteration cap and
-// returns a noisy closest-face approximation.
-const mpr_result = new Float64Array(3);
+/**
+ * Scratch normal written by the primary {@link deepest_pair_penetration} query.
+ * Copied to the caller's `out_direction` only when the depth clears
+ * {@link CONTACT_EPSILON}, preserving the "untouched on no overlap" contract.
+ * @type {Float64Array}
+ */
+const primary_normal = new Float64Array(3);
 
 /**
- * Scratch buffers for the convex-vs-concave path (see
- * {@link compute_penetration_concave}).
+ * Scratch buffers for the convex-vs-concave recovery path (see
+ * {@link concave_recovery_penetration}).
  */
 const local_aabb = new Float64Array(6);
 const world_aabb = new Float64Array(6);
 const concave_query_aabb = new Float64Array(6);
 const scratch_v3 = new Float64Array(3);
-// Dedicated scratch for the per-triangle q · v · q* rotations below
-// (face normal + centroid). Distinct from `scratch_v3` (used by the
-// support-function call later in the same iteration) to keep the
-// data flow obvious.
 const scratch_rot = new Float64Array(3);
 
 /**
- * Per-pair triangle decomposition cap. Same rationale as
- * `narrowphase_step.MAX_TRIANGLES_PER_PAIR` and
- * `overlap_shape.MAX_TRIANGLES_PER_PAIR`: the query AABB is already
- * bounded by the convex shape's envelope, so a single pair typically
- * yields tens of triangles. Excess triangles are dropped by the
- * enumerator's bounds check.
+ * Per-pair triangle decomposition cap for the recovery path. Same rationale as
+ * `narrowphase_step.MAX_TRIANGLES_PER_PAIR`: the query AABB is bounded by the
+ * convex shape's envelope, so a single pair yields tens of triangles. Excess
+ * is dropped by the enumerator's bounds check.
  * @type {number}
  */
 const MAX_TRIANGLES_PER_PAIR = 1024;
 const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
 
 /**
- * Penetration depths below this are treated as no contact. GJK can
- * report tangent configurations as "overlap" — at exact tangent the
- * Minkowski difference touches the origin and the algorithm can go
- * either way; if it says overlap, EPA then returns a sub-micron depth
- * that reflects numerical noise rather than a real penetration. The
- * "0 means no overlap" contract is more useful when small-noise hits
- * are filtered out at the source.
+ * Penetration depths below this are treated as no contact. The narrowphase
+ * dispatch can report sub-micron "overlap" at exact tangent (GJK/EPA noise,
+ * or a closed-form solver returning a hair of depth on a kissing contact); the
+ * "0 means no overlap" contract is more useful when that noise is filtered out
+ * at the source.
  *
- * 1e-4 m (100 µm) chosen to be well below any practical world-scale
- * tolerance while still being larger than typical EPA convergence
- * residuals at exact tangent. Smaller values would let near-tangent
- * floating-point noise leak through as "tiny positive depth".
+ * 1e-4 m (100 µm) is well below any practical world-scale tolerance while
+ * still larger than typical convergence residuals at exact tangent.
  *
  * @type {number}
  */
@@ -76,56 +67,56 @@ const CONTACT_EPSILON = 1e-4;
  * `-out_direction * return_value` to `position_b`) is the minimum
  * translation that produces separation.
  *
- * If the shapes do not overlap (or EPA degenerates on a tangent
- * contact), the return value is `0` and `out_direction` is left
- * untouched. Callers should treat 0 as "no penetration".
+ * If the shapes do not overlap, the return value is `0` and
+ * `out_direction` is left untouched. Callers should treat 0 as "no
+ * penetration".
  *
  * Sign convention matches the narrowphase's stored contact normal:
- *   - `out_direction` ≡ "B → A" direction
- *   - Negative of cast direction in shape_cast at the kiss point
- *   - The outward normal of B's surface at the contact, pointing
- *     toward A
+ * `out_direction` ≡ the "B → A" direction (B's outward surface normal at the
+ * contact, pointing toward A).
  *
- * Built on the existing GJK + EPA + PosedShape primitives — same
- * precision characteristics (essentially exact for sign-based supports
- * like cubes; asymptotic on curved supports like spheres near tangent,
- * where the polytope iteration cap leaves a small angular residual on
- * the direction).
+ * ## How it is computed (hardened)
  *
- * ## Non-convex support
+ * The query routes through the **same narrowphase contact dispatch the solver
+ * consumes** ({@link deepest_pair_penetration} → `dispatch_pair`) and reports
+ * the deepest contact. That makes it correct — not "correct sometimes" — for
+ * every shape pair the engine can build:
  *
- * Exactly **one** of the two shapes may be non-convex (heightmap,
- * mesh). The non-convex shape is decomposed into triangles overlapping
- * the convex shape's AABB (via the same machinery the narrowphase
- * uses), and per-triangle GJK + EPA is run; the deepest contact's
- * direction and depth are reported. Concave-vs-concave throws — the
- * M×N triangle-pair cost is out of scope for this primitive (and is
- * also refused by the narrowphase for dynamic pairs).
+ *   - **sphere / box / capsule pairs** → exact closed-form solvers
+ *     (`sphere_sphere`, `sphere_box`, `box_box` via SAT, `capsule_*`). Box-box
+ *     in particular uses the true minimum-translation axis, so a small body
+ *     resting on a large box reports the few-cm overlap through the near face
+ *     rather than the metres-deep "exit through the far side" a centroid-seeded
+ *     MPR portal used to return.
+ *   - **general convex pairs** (anything without a closed form) → GJK + EPA,
+ *     which is exact for polytopes and is only ever reached by polytope-like
+ *     shapes here, since every curved primitive (sphere, capsule) has a closed
+ *     form above.
+ *   - **convex vs concave** (one of heightmap / mesh) → triangle decomposition
+ *     over the convex AABB + the closed-form per-triangle solvers
+ *     (`sphere_triangle`, `box_triangle`, `capsule_triangle`), deepest wins.
+ *     These are bounded to each triangle's true 2-D extent, so the historical
+ *     over-report on closed-mesh side faces (infinite-plane extrapolation) is
+ *     gone.
  *
- * ## Non-convex precision limits
+ * ## Convex-vs-concave recovery (fully-tunnelled bodies)
  *
- * The concave path is a per-triangle half-space test (convex's deepest
- * point along −face_normal, compared to the triangle's plane). This
- * is exact for **heightmaps** — adjacent triangles cover the
- * boundary cases, and the face normal IS the contact direction.
+ * The per-triangle closed-form solvers are intentionally one-sided: a convex
+ * shape that has crossed to the *inner* side of a surface produces no
+ * from-outside contact (the narrowphase won't shove a body deeper into the
+ * solid mid-step). For a standalone penetration / depenetration query that is
+ * the wrong answer — the shape *is* overlapping the solid and must be pushed
+ * back out. When the primary dispatch finds no contact for a convex-vs-concave
+ * pair, this function falls back to a half-space test
+ * ({@link concave_recovery_penetration}) that reports the outward push-out
+ * vector. This is exact for heightmap terrain and a valid (if not strictly
+ * minimal) recovery direction for closed meshes.
  *
- * For **closed meshes** the half-space test extrapolates each triangle
- * as an infinite plane, which can over-report depth on side faces
- * when the convex shape extends past a face's 2D extent. The
- * deepest-wins aggregation then picks a "false-deepest" face whose
- * direction may not be the geometrically optimal one. A closed-form
- * triangle-vs-X solver per primitive shape would fix this; until
- * then, the function reports *some* outward direction with positive
- * depth, which still resolves penetration over multiple iterations.
+ * Concave-vs-concave throws — the M×N triangle-pair cost is out of scope (and
+ * is also refused by the narrowphase for dynamic pairs).
  *
- * Bodies fully inside the concave solid (or below a heightmap
- * surface) are correctly recovered: every face's deepest-inward
- * support point lands on the inward side, so the half-space test
- * fires, and the deepest face wins. The reported direction pushes
- * the body outward through that face.
- *
- * @param {Float64Array|number[]} out_direction length ≥ 3; receives
- *   the unit separation direction (B → A) on penetration
+ * @param {Float64Array|number[]} out_direction length ≥ 3; receives the unit
+ *   separation direction (B → A) on penetration
  * @param {AbstractShape3D} shape_a  in shape_a's local frame; may be concave
  * @param {{x:number,y:number,z:number}} position_a  world position of A
  * @param {{x:number,y:number,z:number,w:number}} rotation_a  world rotation of A
@@ -147,121 +138,59 @@ export function compute_penetration(
         throw new Error("compute_penetration: at most one shape may be non-convex (concave-vs-concave triangle-pair cost is out of scope)");
     }
 
-    if (isConcaveA || isConcaveB) {
-        return compute_penetration_concave(
-            out_direction, isConcaveA,
-            shape_a, position_a, rotation_a,
-            shape_b, position_b, rotation_b
-        );
-    }
-
-    return compute_penetration_convex(
-        out_direction,
+    // ── Primary: the exact narrowphase dispatch, deepest contact = MTV. ──
+    const depth = deepest_pair_penetration(
+        primary_normal,
         shape_a, position_a, rotation_a,
         shape_b, position_b, rotation_b
     );
-}
 
-/**
- * Convex-vs-convex implementation — single MPR call.
- *
- * MPR (Minkowski Portal Refinement) gives an overlap-or-not answer
- * plus the MTV in one pass, with reliable convergence on smooth
- * supports where the previous GJK + EPA path struggled (sphere-vs-
- * sphere shallow overlap, sphere-vs-box near-tangent — the closest-
- * face direction would noise out by 20-30° before EPA hit its
- * iteration cap). MPR converges in 5-15 iterations on those same
- * configurations.
- * @private
- */
-function compute_penetration_convex(
-    out_direction,
-    shape_a, position_a, rotation_a,
-    shape_b, position_b, rotation_b
-) {
-    posed_a.setup(shape_a, position_a, rotation_a);
-    posed_b.setup(shape_b, position_b, rotation_b);
-
-    if (!mpr(mpr_result, 0, posed_a, posed_b)) return 0;
-
-    let ex = mpr_result[0], ey = mpr_result[1], ez = mpr_result[2];
-    const depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
-    if (!(depth > CONTACT_EPSILON) || !Number.isFinite(depth)) return 0;
-
-    // MTV direction sanity check: should point from A's centre toward
-    // B's centre. Same trick as in `narrowphase_step` — even MPR can
-    // settle on either side of the origin for symmetric configurations
-    // (axis-aligned cubes), so dot against the body-centre axis and
-    // flip if needed.
-    const ab_x = position_b.x - position_a.x;
-    const ab_y = position_b.y - position_a.y;
-    const ab_z = position_b.z - position_a.z;
-    if (ex * ab_x + ey * ab_y + ez * ab_z < 0) {
-        ex = -ex; ey = -ey; ez = -ez;
+    if (depth > CONTACT_EPSILON && Number.isFinite(depth)) {
+        out_direction[0] = primary_normal[0];
+        out_direction[1] = primary_normal[1];
+        out_direction[2] = primary_normal[2];
+        return depth;
     }
 
-    // MTV now points A → B. out_direction is B → A.
-    const inv = 1 / depth;
-    out_direction[0] = -ex * inv;
-    out_direction[1] = -ey * inv;
-    out_direction[2] = -ez * inv;
+    // ── Recovery: a convex shape fully crossed to the inner side of a concave
+    //    surface produces no from-outside contact above. Push it back out. ──
+    if (isConcaveA !== isConcaveB) {
+        return concave_recovery_penetration(
+            out_direction, isConcaveA,
+            shape_a, position_a, rotation_a,
+            shape_b, position_b, rotation_b
+        );
+    }
 
-    return depth;
+    return 0;
 }
 
 /**
- * Convex-vs-concave implementation — decompose, per-triangle half-space
- * test, deepest-wins aggregation.
- *
- * Why the half-space test instead of per-triangle GJK + EPA:
- *
- * GJK + EPA on `Triangle3D` (a flat 2D shape) has a known degeneracy.
- * `Triangle3D.support` along the triangle's face-normal axis returns
- * the SAME vertex regardless of sign (all three vertices have equal
- * projection along that axis). GJK can't converge from this degenerate
- * support and returns false positives — sphere clearly above a flat
- * surface gets reported as overlapping, with EPA producing a non-zero
- * depth in some arbitrary direction.
- *
- * The half-space test is closed-form and exact for this case:
- *
- *   1. Compute the triangle's outward face normal in world frame
- *      (winding gives outward-CCW per the enumerator's contract).
- *   2. Query `convex.support(-face_normal)` — the deepest point of the
- *      convex shape along the face-normal axis in the inward direction.
- *   3. Project that point onto the face normal relative to the
- *      triangle's centroid plane.
- *   4. If the projection is positive, the convex shape is entirely on
- *      the outward side — no penetration. Skip.
- *   5. Otherwise the magnitude is the penetration depth, and the
- *      face normal IS the contact direction.
- *
- * For continuous concave surfaces (heightmaps with adjacent triangles
- * sharing edges) the half-space test gives exact results: any penetrating
- * convex either crosses a triangle's plane within the triangle's 2D
- * extent (correct depth reported) or hits an adjacent triangle.
+ * Recovery fallback for a convex shape that has tunnelled to the inner side of
+ * a concave surface (heightmap / mesh), where the one-sided per-triangle
+ * solvers report no contact.
  *
- * For closed meshes (each face is a separate triangle, edges are shared
- * between facets at angles), the half-space test can over-report when a
- * convex is outside the triangle's 2D extent but still on the inward
- * side of its infinite plane. Deepest-wins aggregation makes this
- * harmless in practice — the dominant face's depth wins, which is the
- * geometrically meaningful answer for the kinematic-resolution use case.
+ * Per-triangle half-space test, deepest-wins:
+ *   1. Face normal of the triangle in world frame (outward by winding).
+ *   2. `convex.support(-face_normal)` — the convex's deepest point along the
+ *      inward face axis.
+ *   3. Signed distance of that point to the triangle's plane. If positive the
+ *      convex is fully outside this face → skip. If negative, its magnitude is
+ *      the depth and the face normal is the contact axis.
  *
- * One-sided rejection is built into the test itself: if the convex's
- * deepest inward point is still on the outward side, depth ≤ 0 → skip.
- * Bodies in fully-invalid states (inside a closed mesh, below a
- * heightmap surface) get rejected naturally and return 0.
+ * Exact for heightmaps (adjacent triangles cover the boundary); for closed
+ * meshes the infinite-plane extrapolation can over-report on side faces, but
+ * deepest-wins gives a valid outward push that resolves over iterations — and
+ * this path only runs once a body is already inside the solid, where any
+ * outward direction is progress.
  *
  * @private
  */
-function compute_penetration_concave(
+function concave_recovery_penetration(
     out_direction, isConcaveA,
     shape_a, position_a, rotation_a,
     shape_b, position_b, rotation_b
 ) {
-    // Internally normalise: "concave" side is what we decompose;
-    // "convex" side is wrapped in PosedShape and queried via support.
     const concave_shape = isConcaveA ? shape_a : shape_b;
     const concave_pos   = isConcaveA ? position_a : position_b;
     const concave_rot   = isConcaveA ? rotation_a : rotation_b;
@@ -376,8 +305,6 @@ function compute_penetration_concave(
     if (best_depth === 0) return 0;
 
     // ── 6. Write out_direction in the user's "B → A" convention ────
-    //
-    // The face normal points OUTWARD from the concave's solid.
     //   - isConcaveA: original A = concave. "B → A" = convex → concave
     //     = INTO the solid = −face_normal.
     //   - isConcaveB: original A = convex. "B → A" = concave → convex

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

@@ -1,3 +1,55 @@
+/**
+ * Single-pair penetration query: the depth and world normal of the DEEPEST
+ * contact the narrowphase would generate for one posed shape pair.
+ *
+ * Routes through the exact same {@link dispatch_pair} the contact solver
+ * consumes — closed-form for every sphere / box / capsule pair (box-box via
+ * SAT, so the true minimum-translation axis is found rather than the
+ * centroid-seeded portal MPR would pick), triangle decomposition + closed-form
+ * per triangle for convex-vs-concave, and GJK + EPA (+ MPR) for any other
+ * convex pair. The deepest contact's depth is the minimum-translation distance
+ * and its normal is the MTV axis, so the result is correct for every shape pair
+ * the engine can build and agrees bit-for-bit with what the solver acts on.
+ *
+ * The normal follows the narrowphase's stored convention: a unit vector
+ * pointing from B toward A — the direction to translate A to separate it.
+ *
+ * Concave-vs-concave is not dispatched (the narrowphase skips it) and returns
+ * 0; callers needing to reject that case must check `is_convex` themselves.
+ *
+ * Not re-entrant: shares the module-level candidate / scratch buffers with
+ * {@link narrowphase_step}. Intended for main-thread queries run outside a
+ * step (depenetration, overlap depth, tooling) — never from inside one.
+ *
+ * @param {Float64Array|number[]} out_normal length ≥ 3; receives the unit B→A
+ *   normal on penetration (untouched when the return value is 0)
+ * @param {AbstractShape3D} shapeA
+ * @param {{x:number,y:number,z:number}} posA
+ * @param {{x:number,y:number,z:number,w:number}} rotA
+ * @param {AbstractShape3D} shapeB
+ * @param {{x:number,y:number,z:number}} posB
+ * @param {{x:number,y:number,z:number,w:number}} rotB
+ * @returns {number} deepest penetration depth (> 0) or 0 if separated
+ */
+export function deepest_pair_penetration(out_normal: Float64Array | number[], shapeA: AbstractShape3D, posA: {
+    x: number;
+    y: number;
+    z: number;
+}, rotA: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}, shapeB: AbstractShape3D, posB: {
+    x: number;
+    y: number;
+    z: number;
+}, rotB: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}): number;
 /**
  * For every pair in `pair_list`, do a cross-product over A's collider list ×
  * B's collider list, accumulate candidate contacts, reduce to ≤4, and write

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

@@ -1 +1 @@
-{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AAovCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AAwyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qDAVW,YAAY,GAAC,MAAM,EAAE,iCAGrB;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,QAC5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iCAErC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,QAC5B;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,GACnC,MAAM,CAyClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QA0JlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}

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

@@ -1,6 +1,7 @@
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
 import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
 import { body_id_index } from "../body/BodyStorage.js";
+import { combine_friction, combine_restitution } from "../contact/combine_material.js";
 import { CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
 import { expanding_polytope_algorithm } from "../gjk/expanding_polytope_algorithm.js";
 import { gjk_with_axis } from "../gjk/gjk.js";
@@ -52,7 +53,7 @@ const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAP
 
 /**
  * Candidate-contact stride: wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth,
- * feature_id.
+ * feature_id, friction, restitution.
  *
  * The `feature_id` (offset 10) is a stable cross-frame identifier of the
  * geometric feature pair that produced this contact — used by the
@@ -61,9 +62,26 @@ const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAP
  * corresponds to the same physical contact. A value of 0 means
  * "no feature info, fall back to position matching".
  *
+ * `friction` (offset 11) and `restitution` (offset 12) are the COMBINED
+ * coefficients for the specific (colliderA, colliderB) pair that produced this
+ * contact, combined here (the only place that knows the exact source collider
+ * on each side) and carried into the manifold so a compound body's per-collider
+ * materials are honoured per-contact.
+ *
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 13;
+
+/**
+ * Combined friction / restitution for the collider pair currently being
+ * dispatched. Set once at the top of {@link dispatch_pair} (which is called
+ * per collider pair) and written into every contact that call appends, so
+ * each contact carries the material of its actual source colliders. Module
+ * scratch rather than threaded through every `append_contact` call site.
  * @type {number}
  */
-const CANDIDATE_STRIDE = 11;
+let g_pair_friction = 0;
+let g_pair_restitution = 0;
 
 /**
  * Maximum number of contacts emitted into the per-pair manifold after the
@@ -194,6 +212,8 @@ function append_contact(count, wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth,
     candidates[off + 6] = nx;  candidates[off + 7] = ny;  candidates[off + 8] = nz;
     candidates[off + 9] = depth;
     candidates[off + 10] = feature_id;
+    candidates[off + 11] = g_pair_friction;
+    candidates[off + 12] = g_pair_restitution;
 
     return count + 1;
 }
@@ -358,6 +378,20 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
     const shapeA = colA.shape;
     const shapeB = colB.shape;
 
+    // Per-contact materials: combine the two source colliders' coefficients
+    // once here (this is the only place that knows the exact collider on each
+    // side) and stamp them onto every contact this dispatch appends. The
+    // `deepest_pair_penetration` query passes bare `{shape}` adapters with no
+    // material fields — it never writes to a manifold, so 0 is fine there.
+    const fa = colA.friction, fb = colB.friction;
+    if (fa !== undefined && fb !== undefined) {
+        g_pair_friction = combine_friction(fa, fb);
+        g_pair_restitution = combine_restitution(colA.restitution, colB.restitution);
+    } else {
+        g_pair_friction = 0;
+        g_pair_restitution = 0;
+    }
+
     // isSphereShape3D covers both UnitSphereShape3D (fixed radius 1) and
     // SphereShape3D (arbitrary radius). Both expose `radius`.
     const isSphereA = shapeA.isSphereShape3D === true;
@@ -1266,6 +1300,98 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
     );
 }
 
+// Reusable single-pair adapters for the penetration query below — no per-call
+// allocation. dispatch_pair only reads `.shape` off a collider and
+// `.position` / `.rotation` off a transform, so these minimal stand-ins are
+// all it needs.
+const _pp_colA = { shape: null };
+const _pp_colB = { shape: null };
+const _pp_trA = { position: null, rotation: null };
+const _pp_trB = { position: null, rotation: null };
+
+/**
+ * Cold-start GJK seed for the one-shot penetration query. Re-zeroed before each
+ * call so every query is independent (gjk_with_axis treats a zero vector as a
+ * cold start) — no warm-start leakage between unrelated queries, which keeps
+ * the result a pure function of its inputs.
+ * @type {Float64Array}
+ */
+const _pp_axis = new Float64Array(3);
+
+/**
+ * Single-pair penetration query: the depth and world normal of the DEEPEST
+ * contact the narrowphase would generate for one posed shape pair.
+ *
+ * Routes through the exact same {@link dispatch_pair} the contact solver
+ * consumes — closed-form for every sphere / box / capsule pair (box-box via
+ * SAT, so the true minimum-translation axis is found rather than the
+ * centroid-seeded portal MPR would pick), triangle decomposition + closed-form
+ * per triangle for convex-vs-concave, and GJK + EPA (+ MPR) for any other
+ * convex pair. The deepest contact's depth is the minimum-translation distance
+ * and its normal is the MTV axis, so the result is correct for every shape pair
+ * the engine can build and agrees bit-for-bit with what the solver acts on.
+ *
+ * The normal follows the narrowphase's stored convention: a unit vector
+ * pointing from B toward A — the direction to translate A to separate it.
+ *
+ * Concave-vs-concave is not dispatched (the narrowphase skips it) and returns
+ * 0; callers needing to reject that case must check `is_convex` themselves.
+ *
+ * Not re-entrant: shares the module-level candidate / scratch buffers with
+ * {@link narrowphase_step}. Intended for main-thread queries run outside a
+ * step (depenetration, overlap depth, tooling) — never from inside one.
+ *
+ * @param {Float64Array|number[]} out_normal length ≥ 3; receives the unit B→A
+ *   normal on penetration (untouched when the return value is 0)
+ * @param {AbstractShape3D} shapeA
+ * @param {{x:number,y:number,z:number}} posA
+ * @param {{x:number,y:number,z:number,w:number}} rotA
+ * @param {AbstractShape3D} shapeB
+ * @param {{x:number,y:number,z:number}} posB
+ * @param {{x:number,y:number,z:number,w:number}} rotB
+ * @returns {number} deepest penetration depth (> 0) or 0 if separated
+ */
+export function deepest_pair_penetration(out_normal, shapeA, posA, rotA, shapeB, posB, rotB) {
+    _pp_colA.shape = shapeA;
+    _pp_trA.position = posA;
+    _pp_trA.rotation = rotA;
+    _pp_colB.shape = shapeB;
+    _pp_trB.position = posB;
+    _pp_trB.rotation = rotB;
+
+    // Cold GJK seed — one-shot query, not a warm-started per-frame manifold.
+    _pp_axis[0] = 0; _pp_axis[1] = 0; _pp_axis[2] = 0;
+    const n = dispatch_pair(0, _pp_colA, _pp_trA, _pp_colB, _pp_trB, _pp_axis, 0);
+    if (n === 0) {
+        return 0;
+    }
+
+    // Deepest contact = the minimum-translation depth; its stored normal is the
+    // separation axis. (For multi-point manifolds — box-box, capsule-box, a
+    // convex straddling several mesh triangles — every point shares the
+    // separating axis, so the max depth along it is the distance to separate.)
+    let best_depth = -1;
+    let best_off = 0;
+    for (let i = 0; i < n; i++) {
+        const off = i * CANDIDATE_STRIDE;
+        const d = candidates[off + 9];
+        if (d > best_depth) {
+            best_depth = d;
+            best_off = off;
+        }
+    }
+
+    if (!(best_depth > 0) || !Number.isFinite(best_depth)) {
+        return 0;
+    }
+
+    out_normal[0] = candidates[best_off + 6];
+    out_normal[1] = candidates[best_off + 7];
+    out_normal[2] = candidates[best_off + 8];
+
+    return best_depth;
+}
+
 /**
  * For every pair in `pair_list`, do a cross-product over A's collider list ×
  * B's collider list, accumulate candidate contacts, reduce to ≤4, and write
@@ -1408,7 +1534,8 @@ export function narrowphase_step(pair_list, manifolds, lists) {
                 candidates[off + 3], candidates[off + 4], candidates[off + 5],
                 candidates[off + 6], candidates[off + 7], candidates[off + 8],
                 candidates[off + 9],
-                candidates[off + 10]
+                candidates[off + 10],
+                candidates[off + 11], candidates[off + 12]
             );
             const prev_j = cand_to_prev[k];
             if (prev_j !== -1) {

package/src/engine/physics/solver/solve_contacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solve_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/solve_contacts.js"],"names":[],"mappings":"AAgcA;;;;;;;;;;;;;GAaG;AACH,0FAHW,MAAM,GACJ,MAAM,CA4JlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,2FAuCC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wFAgEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iGAmFC;AAED;;;;;;;;GAQG;AACH,uFAFW,MAAM,QA2GhB;AAED;;;;;;;;;;;GAWG;AACH,yFA4DC;AAED;;;;;;;;;;;;;;GAcG;AACH,2FAFW,MAAM,QA4EhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oFAJW,MAAM,UACN,MAAM,cACN,MAAM,QAahB;AAxlCD;;;;;GAKG;AACH,0CAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAEsB"}
+{"version":3,"file":"solve_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/solver/solve_contacts.js"],"names":[],"mappings":"AAkbA;;;;;;;;;;;;;GAaG;AACH,0FAHW,MAAM,GACJ,MAAM,CA+JlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,2FAuCC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wFAgEC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,iGAmFC;AAED;;;;;;;;GAQG;AACH,uFAFW,MAAM,QA2GhB;AAED;;;;;;;;;;;GAWG;AACH,yFA4DC;AAED;;;;;;;;;;;;;;GAcG;AACH,2FAFW,MAAM,QA4EhB;AAED;;;;;;;;;;;;;;;GAeG;AACH,oFAJW,MAAM,UACN,MAAM,cACN,MAAM,QAahB;AA7kCD;;;;;GAKG;AACH,0CAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,0CAFU,MAAM,CAEsB"}