@woosh/meep-engine 2.142.0 → 2.144.0

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,8 +378,24 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
     const shapeA = colA.shape;
     const shapeB = colB.shape;
 
-    const isSphereA = shapeA.isUnitSphereShape3D === true;
-    const isSphereB = shapeB.isUnitSphereShape3D === true;
+    // 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;
+    const isSphereB = shapeB.isSphereShape3D === true;
     // isBoxShape3D covers both UnitCubeShape3D (fixed 0.5) and BoxShape3D
     // (arbitrary half-extents). Both expose `half_extents` as a Vector3.
     const isBoxA    = shapeA.isBoxShape3D        === true;
@@ -369,12 +405,13 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
     // sphere-sphere
     if (isSphereA && isSphereB) {
+        const ra = shapeA.radius, rb = shapeB.radius;
 
         const ok = sphere_sphere_contact(
             sphere_result,
             trA.position.x, trA.position.y, trA.position.z,
             trB.position.x, trB.position.y, trB.position.z,
-            1, 1
+            ra, rb
         );
 
         if (!ok) return count;
@@ -383,23 +420,25 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
         // Sphere-sphere produces exactly one contact per pair; fid = 1
         // identifies it as a real feature (distinguishes from "no info" = 0)
-        // and is trivially stable across frames.
+        // and is trivially stable across frames. Witnesses are the surface
+        // points along the (unit) normal, scaled by each sphere's radius.
         return append_contact(count,
-            trA.position.x - nx, trA.position.y - ny, trA.position.z - nz,
-            trB.position.x + nx, trB.position.y + ny, trB.position.z + nz,
+            trA.position.x - nx * ra, trA.position.y - ny * ra, trA.position.z - nz * ra,
+            trB.position.x + nx * rb, trB.position.y + ny * rb, trB.position.z + nz * rb,
             nx, ny, nz, sphere_result[3], 1);
     }
 
     // sphere ↔ box
     if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
-        const sphereTr = isSphereA ? trA : trB;
+        const sphereTr    = isSphereA ? trA : trB;
+        const sphereShape = isSphereA ? shapeA : shapeB;
         const boxTr    = isSphereA ? trB : trA;
         const boxShape = isSphereA ? shapeB : shapeA;
         const bh = boxShape.half_extents;
 
         const ok = sphere_box_contact(
             closed_form_result,
-            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, sphereShape.radius,
             boxTr.position.x, boxTr.position.y, boxTr.position.z,
             boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
             bh.x, bh.y, bh.z
@@ -491,12 +530,13 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         const capsuleTr = isCapsuleA ? trA : trB;
         const capsuleShape = isCapsuleA ? colA.shape : colB.shape;
         const sphereTr    = isCapsuleA ? trB : trA;
+        const sphereShape = isCapsuleA ? colB.shape : colA.shape;
         const ok = capsule_sphere_contact(
             closed_form_result,
             capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
             capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
             capsuleShape.radius, capsuleShape.height * 0.5,
-            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, sphereShape.radius
         );
         if (!ok) return count;
         let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
@@ -639,14 +679,15 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         const c_pos_y = concave_tr.position.y;
         const c_pos_z = concave_tr.position.z;
 
-        // Sphere fast-path: when the convex side is a UnitSphereShape3D we
-        // bypass GJK+EPA entirely per triangle and use the closed-form
+        // Sphere fast-path: when the convex side is a sphere we bypass GJK+EPA
+        // entirely per triangle and use the closed-form
         // {@link sphere_triangle_contact}. This avoids the EPA precision
         // wall on Triangle3D (whose support function is degenerate along
         // the face normal — all 3 vertices project to the same value),
         // which was producing noisy depths at small penetrations and
         // letting dropped spheres tunnel through heightmaps / meshes.
-        const isSphereConvex = convex_col.shape.isUnitSphereShape3D === true;
+        const isSphereConvex = convex_col.shape.isSphereShape3D === true;
+        const sphere_radius = isSphereConvex ? convex_col.shape.radius : 0;
 
         // Box fast-path: closed-form {@link box_triangle_contact} via SAT
         // over 13 axes + polygon clipping for face-vs-face contacts.
@@ -743,7 +784,7 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
 
                 const ok = sphere_triangle_contact(
                     sphere_triangle_result,
-                    convex_wx, convex_wy, convex_wz, 1,
+                    convex_wx, convex_wy, convex_wz, sphere_radius,
                     ax_w, ay_w, az_w,
                     bx_w, by_w, bz_w,
                     cx_w, cy_w, cz_w
@@ -1259,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
@@ -1401,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/narrowphase/refine_ray_hit.js

@@ -41,10 +41,10 @@ const ln = new Float64Array(3); // surface normal in shape-local frame
  *   {@link RAY_REFINE_UNSUPPORTED} when the shape has no exact ray test here
  */
 export function refine_ray_hit(shape, position, rotation, ox, oy, oz, dx, dy, dz, tMax, outNormal) {
-    if (shape.isUnitSphereShape3D === true) {
+    if (shape.isSphereShape3D === true) {
         // Rotation-invariant: translate into the sphere's frame; the local
         // normal is already the world normal.
-        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, 1);
+        return ray_sphere_local(outNormal, ox - position.x, oy - position.y, oz - position.z, dx, dy, dz, tMax, shape.radius);
     }
 
     if (shape.isBoxShape3D === true || shape.isCapsuleShape3D === true) {

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

@@ -1,12 +1,13 @@
 /**
- * Closed-form contact generation for two unit spheres positioned in world
- * space. Returns whether the spheres overlap. On overlap, `out` is populated
- * with `[nx, ny, nz, depth]` where the normal points from B toward A and
- * `depth` is the positive penetration distance.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) points from B toward A
+ * and `depth` is the positive penetration distance.
  *
- * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
- * scaling on the body's transform is irrelevant under our "no scale on
- * physics transforms" assumption.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). Any scaling on the body's transform
+ * is irrelevant under our "no scale on physics transforms" assumption.
  *
  * Centres-coincident is a singular case for the general normal but is
  * resolved here by picking +X as a deterministic tie-break direction.

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

@@ -1 +1 @@
-{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}
+{"version":3,"file":"sphere_sphere_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/sphere_sphere_contact.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,2CAXW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,YACN,MAAM,YACN,MAAM,GACJ,OAAO,CA4BnB"}

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

@@ -1,12 +1,13 @@
 /**
- * Closed-form contact generation for two unit spheres positioned in world
- * space. Returns whether the spheres overlap. On overlap, `out` is populated
- * with `[nx, ny, nz, depth]` where the normal points from B toward A and
- * `depth` is the positive penetration distance.
+ * Closed-form contact generation for two spheres positioned in world space.
+ * Returns whether the spheres overlap. On overlap, `out` is populated with
+ * `[nx, ny, nz, depth]` where the normal (unit length) points from B toward A
+ * and `depth` is the positive penetration distance.
  *
- * Both spheres have radius 1 (the {@link UnitSphereShape3D} convention); any
- * scaling on the body's transform is irrelevant under our "no scale on
- * physics transforms" assumption.
+ * Each sphere's radius is passed explicitly (`radius_a` / `radius_b`) — the
+ * caller reads it from the shape (`SphereShape3D.radius`; 1 for the
+ * {@link UnitSphereShape3D} special case). Any scaling on the body's transform
+ * is irrelevant under our "no scale on physics transforms" assumption.
  *
  * Centres-coincident is a singular case for the general normal but is
  * resolved here by picking +X as a deterministic tie-break direction.

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"}

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

@@ -286,25 +286,11 @@ function inv_mass_of(rb) {
     return rb.mass > 0 ? 1 / rb.mass : 0;
 }
 
-/**
- * Combine two friction coefficients (geometric mean — Bullet / PhysX default).
- * @param {number} a
- * @param {number} b
- * @returns {number}
- */
-function combine_friction(a, b) {
-    return Math.sqrt(a * b);
-}
-
-/**
- * Combine two restitution coefficients (maximum — Unity / common default).
- * @param {number} a
- * @param {number} b
- * @returns {number}
- */
-function combine_restitution(a, b) {
-    return a > b ? a : b;
-}
+// Friction / restitution are no longer combined here: the narrowphase combines
+// the specific source-collider pair's coefficients per contact (so compound
+// bodies with mixed-material colliders are honoured) and stores the result in
+// the manifold (CONTACT_STRIDE offsets 14 / 15). prepare_contacts reads them
+// per contact. See engine/physics/contact/combine_material.js.
 
 const scratch_clamp = new Float64Array(2);
 const scratch_inertia_a = new Float64Array(3);
@@ -520,8 +506,6 @@ export function prepare_contacts(manifolds, system, dt_sub) {
 
         const cc = manifolds.contact_count(slot);
         const slot_off = manifolds.slot_data_offset(slot);
-        const restitution_combined = combine_restitution(colA.restitution, colB.restitution);
-        const friction_combined = combine_friction(colA.friction, colB.friction);
 
         const pAx = trA.position.x, pAy = trA.position.y, pAz = trA.position.z;
         const pBx = trB.position.x, pBy = trB.position.y, pBz = trB.position.z;
@@ -530,6 +514,11 @@ export function prepare_contacts(manifolds, system, dt_sub) {
         for (let k = 0; k < cc; k++) {
             const off = slot_off + k * CONTACT_STRIDE;
 
+            // Per-contact combined materials (stamped by the narrowphase from
+            // this contact's specific source-collider pair).
+            const friction_combined = data[off + 14];
+            const restitution_combined = data[off + 15];
+
             const wax = data[off],     way = data[off + 1], waz = data[off + 2];
             const wbx = data[off + 3], wby = data[off + 4], wbz = data[off + 5];
             const nx  = data[off + 6], ny  = data[off + 7], nz  = data[off + 8];