@woosh/meep-engine 2.152.0 → 2.154.0

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

@@ -3,10 +3,12 @@ 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";
+import { gjk_epa_penetration } from "../gjk/gjk_epa_penetration.js";
 import { mpr } from "../gjk/mpr.js";
 import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
+import { convex_hull_clip, CONVEX_CONVEX_OUT_LENGTH } from "./convex_convex_manifold.js";
+import { get_mesh_convex_hull } from "./mesh_convex_hull.js";
+import { mesh_mesh_tet_contacts } from "./mesh_mesh_tet_manifold.js";
 import { box_triangle_contact, BOX_TRIANGLE_OUT_LENGTH } from "./box_triangle_contact.js";
 import {
     CAPSULE_BOX_CONTACT_STRIDE,
@@ -31,17 +33,9 @@ import { sphere_triangle_contact } from "./sphere_triangle_contact.js";
 const posed_a = new PosedShape();
 const posed_b = new PosedShape();
 
-// Float64 simplex buffer. The simplex stores Minkowski-difference
-// support points that GJK accumulates across up to 64 iterations and
-// then hands to EPA for further refinement; precision loss here
-// compounds through every subsequent dot / cross / normal calculation
-// in the polytope expansion, so keep the full 53-bit mantissa.
-const simplex_buf = new Float64Array(12);
-const simplex_a = simplex_buf.subarray(0, 3);
-const simplex_b = simplex_buf.subarray(3, 6);
-const simplex_c = simplex_buf.subarray(6, 9);
-const simplex_d = simplex_buf.subarray(9, 12);
-
+// Penetration axis + depth from the robust GJK + EPA query
+// (gjk_epa_penetration writes a unit normal here; it owns its own simplex
+// internally, so the narrowphase no longer keeps a simplex buffer).
 const epa_result = new Float64Array(3);
 const sphere_result = new Float64Array(4);
 const closed_form_result = new Float64Array(10);
@@ -49,6 +43,7 @@ const sphere_triangle_result = new Float64Array(10);
 const box_triangle_result = new Float64Array(BOX_TRIANGLE_OUT_LENGTH);
 const capsule_triangle_result = new Float64Array(CAPSULE_TRIANGLE_MAX_CONTACTS * CAPSULE_TRIANGLE_CONTACT_STRIDE);
 const box_manifold_result = new Float64Array(BOX_BOX_OUT_LENGTH);
+const convex_manifold_result = new Float64Array(CONVEX_CONVEX_OUT_LENGTH);
 const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAPSULE_BOX_CONTACT_STRIDE);
 
 /**
@@ -369,31 +364,65 @@ function reduce_candidates(n) {
     return MAX_KEPT;
 }
 
+/**
+ * Multi-point contact manifold between two convex polytopes (authored
+ * ConvexHullShape3D, or a convex MeshShape3D represented as one hull). Robust
+ * GJK + EPA finds the separating axis in O(support queries) — face-count
+ * independent, where SAT's edge-pair term is prohibitive — then
+ * {@link convex_hull_clip} clips the reference/incident faces into a face-on-face
+ * patch around it (Bullet's clipHullAgainstHull). A single GJK+EPA contact can't
+ * resist a stack's toppling torque; the clipped patch holds it. No cross-frame
+ * state → reset-and-resimulate determinism.
+ *
+ * @param {number} count
+ * @param {{vertices,face_offsets,face_loops,support}} hullA  in A's local frame
+ * @param {Transform} trA
+ * @param {{vertices,face_offsets,face_loops,support}} hullB  in B's local frame
+ * @param {Transform} trB
+ * @param {Function} append_contact
+ * @returns {number}
+ */
+function hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact) {
+    posed_a.setup(hullA, trA.position, trA.rotation);
+    posed_b.setup(hullB, trB.position, trB.rotation);
+    const depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+    if (!(depth > 0) || !Number.isFinite(depth)) return count;
+
+    // convex_hull_clip orients the axis B→A robustly (via vertex centroids) and
+    // writes the final normal into convex_manifold_result[0..2].
+    convex_hull_clip(convex_manifold_result,
+        hullA, trA.position, trA.rotation,
+        hullB, trB.position, trB.rotation,
+        epa_result[0], epa_result[1], epa_result[2]);
+    const nx = convex_manifold_result[0], ny = convex_manifold_result[1], nz = convex_manifold_result[2];
+    const cc = convex_manifold_result[3] | 0;
+    // Clipped points migrate across features as the hulls rotate, so leave
+    // fid = 0 and let the match-and-merge pass position-match (as box-box does).
+    for (let k = 0; k < cc; k++) {
+        const base = 4 + k * 7;
+        count = append_contact(count,
+            convex_manifold_result[base],     convex_manifold_result[base + 1], convex_manifold_result[base + 2],
+            convex_manifold_result[base + 3], convex_manifold_result[base + 4], convex_manifold_result[base + 5],
+            nx, ny, nz,
+            convex_manifold_result[base + 6],
+            0);
+    }
+    return count;
+}
+
 /**
  * Run pairwise narrowphase for one (colliderA, colliderB) tuple — dispatches
  * by shape type and appends 0..K contacts to the candidate buffer. Returns
  * the new candidate count.
  *
- * The optional `gjk_axis_buf` + `gjk_axis_off` arguments thread the
- * manifold's cached separating axis through to the GJK + EPA fallback
- * paths. Closed-form paths (sphere/box/capsule × sphere/box/capsule
- * and the three concave fast-paths) don't use GJK and ignore them. As
- * of P2.1 step 4 these are plumbed but not yet activated — the GJK
- * call sites still use the cache-less `gjk(simplex, A, B)`; step 5
- * flips one of them.
- *
  * @param {number} count
  * @param {Collider} colA
  * @param {Transform} trA
  * @param {Collider} colB
  * @param {Transform} trB
- * @param {Float64Array|null} [gjk_axis_buf] per-slot cached-axis buffer
- *   (`manifolds.slot_axis_buffer`) or `null` for cold-start every call.
- * @param {number} [gjk_axis_off] offset into the buffer; pass
- *   `manifolds.slot_axis_offset(slot)`.
  * @returns {number}
  */
-function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axis_off = 0) {
+function dispatch_pair(count, colA, trA, colB, trB) {
     const shapeA = colA.shape;
     const shapeB = colB.shape;
 
@@ -616,6 +645,25 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         return count;
     }
 
+    // convex hull ↔ convex hull (multi-point clipping via GJK + EPA + face-clip).
+    if (shapeA.isConvexHullShape3D === true && shapeB.isConvexHullShape3D === true) {
+        return hull_pair_contacts(count, shapeA, trA, shapeB, trB, append_contact);
+    }
+
+    // mesh ↔ mesh. A globally-convex mesh collides as a single cached hull
+    // (one GJK + EPA + clip) — the greedy decomposition fragments even a convex
+    // mesh, so detecting convexity and routing through the hull path is the
+    // scalable fast path. When BOTH meshes are convex, use it; otherwise fall to
+    // the per-piece decomposed path (convex pieces vs convex pieces).
+    if (shapeA.isMeshShape3D === true && shapeB.isMeshShape3D === true) {
+        const hullA = get_mesh_convex_hull(shapeA);
+        const hullB = get_mesh_convex_hull(shapeB);
+        if (hullA !== null && hullB !== null) {
+            return hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact);
+        }
+        return mesh_mesh_tet_contacts(count, shapeA, trA, shapeB, trB, append_contact);
+    }
+
     // ── Concave (non-convex) path ───────────────────────────────────────
     //
     // If either shape has `is_convex === false`, GJK on the whole shape
@@ -1110,30 +1158,20 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
                 continue;
             }
 
-            // P2.1 step 6: pass the manifold's cached separating axis
-            // here too. Per-triangle iteration means the cache gets
-            // written multiple times per body-pair per frame (one per
-            // overlapping triangle); the final state reflects the
-            // last triangle's converged direction. Still a useful
-            // seed for next frame's first triangle.
-            if (!gjk_with_axis(simplex_buf, posed_a, posed_b, gjk_axis_buf, gjk_axis_off)) continue;
-            expanding_polytope_algorithm(
-                epa_result, 0,
-                simplex_a, simplex_b, simplex_c, simplex_d,
-                posed_a, posed_b
-            );
-
-            let ex = epa_result[0], ey = epa_result[1], ez = epa_result[2];
-            let depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
-            // P3.1: MPR fallback. EPA can return zero/negative/NaN
-            // depth on Triangle3D's degenerate face-normal support
-            // (the same precision pit the closed-form sphere/box/
-            // capsule paths above were added to dodge). MPR has
-            // different convergence properties and often succeeds
-            // here. Only kicks in for non-(sphere/box/capsule) convex
-            // shapes against the concave side — a narrow path now
-            // that closed-form covers the common cases.
-            if (!(depth > 0) || !Number.isFinite(depth)) {
+            // Robust GJK + EPA (see gjk/gjk_epa_penetration.js): returns the
+            // penetration depth and writes a UNIT axis into epa_result. We scale
+            // it to the MTV vector (ex,ey,ez) the tuned sign-check / one-sided
+            // rejection / dedup below already consume. The old gjk_with_axis +
+            // expanding_polytope_algorithm pair was replaced because it returned
+            // a non-minimal axis on degenerate simplices (see memory:
+            // feedback_epa_unreliable_polytopes); MPR is kept as a secondary
+            // safety net for the rare case the robust query reports no overlap.
+            let ex, ey, ez, depth;
+            const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+            if (pen_depth > 0 && Number.isFinite(pen_depth)) {
+                ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
+                depth = pen_depth;
+            } else {
                 if (!mpr(epa_result, 0, posed_a, posed_b)) continue;
                 ex = epa_result[0]; ey = epa_result[1]; ez = epa_result[2];
                 depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
@@ -1234,33 +1272,23 @@ function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axi
         return count;
     }
 
-    // GJK + EPA fallback for everything else. P2.1 step 5: pass the
-    // manifold's cached separating axis as GJK's initial search
-    // direction. Cold start (zero-axis) on first contact; subsequent
-    // frames reuse the converged direction, typically converging in
-    // 1–2 iterations instead of the ~6–10 cold-start cost.
+    // Robust GJK + EPA fallback for any convex pair without a closed form or a
+    // dedicated branch above (e.g. a primitive vs an authored ConvexHullShape3D,
+    // a cylinder/cone). gjk_epa_penetration returns the depth and writes a UNIT
+    // axis into epa_result; we scale to the MTV vector (ex,ey,ez) the body-centre
+    // sign-guard below consumes. Replaces the old gjk_with_axis +
+    // expanding_polytope_algorithm pair, which returned a non-minimal axis on the
+    // degenerate simplices its GJK produced (see memory:
+    // feedback_epa_unreliable_polytopes). MPR is kept as a secondary safety net.
     posed_a.setup(colA.shape, trA.position, trA.rotation);
     posed_b.setup(colB.shape, trB.position, trB.rotation);
 
-    if (!gjk_with_axis(simplex_buf, posed_a, posed_b, gjk_axis_buf, gjk_axis_off)){
-        return count;
-    }
-
-    expanding_polytope_algorithm(
-        epa_result, 0,
-        simplex_a, simplex_b, simplex_c, simplex_d,
-        posed_a, posed_b
-    );
-
-    let ex = epa_result[0], ey = epa_result[1], ez = epa_result[2];
-    let depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
-    // EPA can return zero-depth (touching), negative (impossible) or
-    // NaN/Inf (degenerate iteration-cap exit on smooth high-poly
-    // colliders). P3.1: fall back to MPR — different convergence
-    // properties (works portal-based rather than face-expansion), often
-    // succeeds where EPA fails on the same geometry. `shape_cast` and
-    // `compute_penetration` already use MPR for the same reason.
-    if (!(depth > 0) || !Number.isFinite(depth)) {
+    let ex, ey, ez, depth;
+    const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+    if (pen_depth > 0 && Number.isFinite(pen_depth)) {
+        ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
+        depth = pen_depth;
+    } else {
         if (!mpr(epa_result, 0, posed_a, posed_b)) return count;
         ex = epa_result[0]; ey = epa_result[1]; ez = epa_result[2];
         depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
@@ -1331,14 +1359,6 @@ 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
@@ -1381,9 +1401,7 @@ export function deepest_pair_penetration(out_normal, shapeA, posA, rotA, 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);
+    const n = dispatch_pair(0, _pp_colA, _pp_trA, _pp_colB, _pp_trB);
     if (n === 0) {
         return 0;
     }
@@ -1455,15 +1473,6 @@ export function narrowphase_step(pair_list, manifolds, lists) {
         const la_len = list_a.length;
         const lb_len = list_b.length;
 
-        // Per-manifold cached GJK separating-axis seed. Threaded into
-        // dispatch_pair for the GJK fallback paths. For single-collider
-        // bodies (the common case) there's no contention across the
-        // inner loop; for compound bodies the cache reflects whichever
-        // collider-pair invoked GJK last, which is a noisy-but-useful
-        // seed (better than a cold (1, 0, 0) restart every frame).
-        const gjk_axis_buf = manifolds.slot_axis_buffer;
-        const gjk_axis_off = manifolds.slot_axis_offset(slot);
-
         for (let a = 0; a < la_len; a++) {
             const ea = list_a[a];
 
@@ -1475,9 +1484,7 @@ export function narrowphase_step(pair_list, manifolds, lists) {
                     ea.collider,
                     ea.transform,
                     eb.collider,
-                    eb.transform,
-                    gjk_axis_buf,
-                    gjk_axis_off
+                    eb.transform
                 );
 
             }
@@ -1630,16 +1637,12 @@ export function redetect_pair_geometry(manifolds, slot, list_a, list_b) {
     const count = manifolds.contact_count(slot);
     if (count === 0) return;
 
-    const gjk_axis_buf = manifolds.slot_axis_buffer;
-    const gjk_axis_off = manifolds.slot_axis_offset(slot);
-
     let cc = 0;
     for (let a = 0; a < la_len; a++) {
         const ea = list_a[a];
         for (let b = 0; b < lb_len; b++) {
             const eb = list_b[b];
-            cc = dispatch_pair(cc, ea.collider, ea.transform, eb.collider, eb.transform,
-                gjk_axis_buf, gjk_axis_off);
+            cc = dispatch_pair(cc, ea.collider, ea.transform, eb.collider, eb.transform);
         }
     }
     if (cc === 0) return; // nothing re-detected this substep — keep frozen geometry

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

@@ -0,0 +1,29 @@
+/**
+ * In-place reduction of a strided contact-candidate buffer to at most `maxKept`
+ * points:
+ *   1. keep the deepest candidate (penetration depth at lane `stride - 1`) in
+ *      slot 0;
+ *   2. then greedily pick the candidate whose MINIMUM squared distance to the
+ *      already-kept set is largest (farthest-point sampling) — a behaviour-
+ *      preserving max-spread approximation that avoids degenerate near-coincident
+ *      manifolds.
+ *
+ * The contact position is lanes 0,1,2 of each `stride`-float record; the buffer
+ * is reordered in place and the caller reads the first `maxKept` records.
+ *
+ * Shared by {@link box_box_manifold} and {@link convex_convex_manifold} (both
+ * stride 4), which previously each carried a byte-identical copy. The stride-7
+ * (box_triangle) and stride-10 (narrowphase_step) variants differ only in stride
+ * and can adopt this too.
+ *
+ * @param {Float64Array} buf  strided candidate buffer
+ * @param {number} n          input candidate count
+ * @param {number} stride     floats per candidate (depth at lane stride-1)
+ * @param {number} maxKept    maximum candidates to keep
+ * @returns {number} kept count = min(n, maxKept)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function reduce_manifold_contacts(buf: Float64Array, n: number, stride: number, maxKept: number): number;
+//# sourceMappingURL=reduce_manifold_contacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reduce_manifold_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/reduce_manifold_contacts.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8CATW,YAAY,KACZ,MAAM,UACN,MAAM,WACN,MAAM,GACJ,MAAM,CAqClB"}

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

@@ -0,0 +1,69 @@
+/**
+ * In-place reduction of a strided contact-candidate buffer to at most `maxKept`
+ * points:
+ *   1. keep the deepest candidate (penetration depth at lane `stride - 1`) in
+ *      slot 0;
+ *   2. then greedily pick the candidate whose MINIMUM squared distance to the
+ *      already-kept set is largest (farthest-point sampling) — a behaviour-
+ *      preserving max-spread approximation that avoids degenerate near-coincident
+ *      manifolds.
+ *
+ * The contact position is lanes 0,1,2 of each `stride`-float record; the buffer
+ * is reordered in place and the caller reads the first `maxKept` records.
+ *
+ * Shared by {@link box_box_manifold} and {@link convex_convex_manifold} (both
+ * stride 4), which previously each carried a byte-identical copy. The stride-7
+ * (box_triangle) and stride-10 (narrowphase_step) variants differ only in stride
+ * and can adopt this too.
+ *
+ * @param {Float64Array} buf  strided candidate buffer
+ * @param {number} n          input candidate count
+ * @param {number} stride     floats per candidate (depth at lane stride-1)
+ * @param {number} maxKept    maximum candidates to keep
+ * @returns {number} kept count = min(n, maxKept)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function reduce_manifold_contacts(buf, n, stride, maxKept) {
+    if (n <= maxKept) return n;
+
+    const depth_lane = stride - 1;
+
+    // Deepest into slot 0.
+    let deepest_idx = 0;
+    let deepest_val = buf[depth_lane];
+    for (let i = 1; i < n; i++) {
+        const v = buf[i * stride + depth_lane];
+        if (v > deepest_val) { deepest_val = v; deepest_idx = i; }
+    }
+    if (deepest_idx !== 0) swap(buf, stride, 0, deepest_idx);
+
+    // Greedy farthest-point for the remaining slots.
+    for (let k = 1; k < maxKept; k++) {
+        let best_score = -1;
+        let best_i = -1;
+        for (let i = k; i < n; i++) {
+            let min_d2 = Infinity;
+            for (let j = 0; j < k; j++) {
+                const dx = buf[i * stride] - buf[j * stride];
+                const dy = buf[i * stride + 1] - buf[j * stride + 1];
+                const dz = buf[i * stride + 2] - buf[j * stride + 2];
+                const d2 = dx * dx + dy * dy + dz * dz;
+                if (d2 < min_d2) min_d2 = d2;
+            }
+            if (min_d2 > best_score) { best_score = min_d2; best_i = i; }
+        }
+        if (best_i !== k) swap(buf, stride, k, best_i);
+    }
+    return maxKept;
+}
+
+function swap(buf, stride, a, b) {
+    const ao = a * stride, bo = b * stride;
+    for (let k = 0; k < stride; k++) {
+        const t = buf[ao + k];
+        buf[ao + k] = buf[bo + k];
+        buf[bo + k] = t;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"refine_ray_concave.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_concave.js"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,qEARW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,aACN,YAAY,UAAQ,GAClB,MAAM,CAkGlB"}
+{"version":3,"file":"refine_ray_concave.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/refine_ray_concave.js"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,qEARW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,YAC5B,UAAU,MAAM,CAAC,MACjB,MAAM,MAAa,MAAM,MAAa,MAAM,MAC5C,MAAM,MAAa,MAAM,MAAa,MAAM,QAC5C,MAAM,aACN,YAAY,UAAQ,GAClB,MAAM,CAyGlB"}