@woosh/meep-engine 2.153.0 → 2.154.0

package/src/engine/physics/events/ContactEventBuffer.js

@@ -1,83 +1,84 @@
-/**
- * Event kinds emitted by the manifold diff pass.
- * @readonly
- * @enum {number}
- */
-export const ContactEventKind = {
-    Begin: 0,
-    Stay: 1,
-    End: 2,
-};
-
-const DEFAULT_INITIAL_CAPACITY = 32;
-
-/**
- * Per-event stride in the Uint32 backing array:
- *   0 : kind (ContactEventKind)
- *   1 : entityA
- *   2 : entityB
- *   3 : slot
- * @type {number}
- */
-const EVENT_STRIDE = 4;
-
-/**
- * Append-only buffer of contact events produced during one fixedUpdate, ready
- * to be dispatched (and then cleared) at end-of-step.
- *
- * Storage is flat Uint32Array — keeping the metadata side allocation-free; the
- * actual contact payload (normal, depth, world point) is read on demand from
- * the {@link ManifoldStore} by the dispatch code.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class ContactEventBuffer {
-    /**
-     * @param {number} [initial_capacity] events
-     */
-    constructor(initial_capacity = DEFAULT_INITIAL_CAPACITY) {
-        this.__capacity = Math.max(1, initial_capacity);
-        this.__count = 0;
-        // Int32 so entity ids may legitimately store -1 (stale body after free).
-        this.__data = new Int32Array(this.__capacity * EVENT_STRIDE);
-    }
-
-    /**
-     * @returns {number}
-     */
-    get count() {
-        return this.__count;
-    }
-
-    clear() {
-        this.__count = 0;
-    }
-
-    /**
-     * @param {ContactEventKind|number} kind
-     * @param {number} entityA
-     * @param {number} entityB
-     * @param {number} slot manifold slot id
-     */
-    push(kind, entityA, entityB, slot) {
-        if (this.__count === this.__capacity) {
-            const new_cap = this.__capacity << 1;
-            const next = new Int32Array(new_cap * EVENT_STRIDE);
-            next.set(this.__data);
-            this.__data = next;
-            this.__capacity = new_cap;
-        }
-        const off = this.__count * EVENT_STRIDE;
-        this.__data[off] = kind;
-        this.__data[off + 1] = entityA;
-        this.__data[off + 2] = entityB;
-        this.__data[off + 3] = slot;
-        this.__count++;
-    }
-
-    kind_at(i) { return this.__data[i * EVENT_STRIDE]; }
-    entityA_at(i) { return this.__data[i * EVENT_STRIDE + 1]; }
-    entityB_at(i) { return this.__data[i * EVENT_STRIDE + 2]; }
-    slot_at(i) { return this.__data[i * EVENT_STRIDE + 3]; }
-}
+/**
+ * Event kinds emitted by the manifold diff pass.
+ * @readonly
+ * @enum {number}
+ */
+export const ContactEventKind = {
+    Begin: 0,
+    Stay: 1,
+    End: 2,
+};
+
+const DEFAULT_INITIAL_CAPACITY = 32;
+
+/**
+ * Per-event stride in the Int32 backing array:
+ *   0 : kind (ContactEventKind)
+ *   1 : entityA
+ *   2 : entityB
+ *   3 : slot
+ * @type {number}
+ */
+const EVENT_STRIDE = 4;
+
+/**
+ * Append-only buffer of contact events produced during one fixedUpdate, ready
+ * to be dispatched (and then cleared) at end-of-step.
+ *
+ * Storage is flat Int32Array (signed: entity ids may legitimately be -1 for a
+ * stale body after free) — keeping the metadata side allocation-free; the
+ * actual contact payload (normal, depth, world point) is read on demand from
+ * the {@link ManifoldStore} by the dispatch code.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ContactEventBuffer {
+    /**
+     * @param {number} [initial_capacity] events
+     */
+    constructor(initial_capacity = DEFAULT_INITIAL_CAPACITY) {
+        this.__capacity = Math.max(1, initial_capacity);
+        this.__count = 0;
+        // Int32 so entity ids may legitimately store -1 (stale body after free).
+        this.__data = new Int32Array(this.__capacity * EVENT_STRIDE);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get count() {
+        return this.__count;
+    }
+
+    clear() {
+        this.__count = 0;
+    }
+
+    /**
+     * @param {ContactEventKind|number} kind
+     * @param {number} entityA
+     * @param {number} entityB
+     * @param {number} slot manifold slot id
+     */
+    push(kind, entityA, entityB, slot) {
+        if (this.__count === this.__capacity) {
+            const new_cap = this.__capacity << 1;
+            const next = new Int32Array(new_cap * EVENT_STRIDE);
+            next.set(this.__data);
+            this.__data = next;
+            this.__capacity = new_cap;
+        }
+        const off = this.__count * EVENT_STRIDE;
+        this.__data[off] = kind;
+        this.__data[off + 1] = entityA;
+        this.__data[off + 2] = entityB;
+        this.__data[off + 3] = slot;
+        this.__count++;
+    }
+
+    kind_at(i) { return this.__data[i * EVENT_STRIDE]; }
+    entityA_at(i) { return this.__data[i * EVENT_STRIDE + 1]; }
+    entityB_at(i) { return this.__data[i * EVENT_STRIDE + 2]; }
+    slot_at(i) { return this.__data[i * EVENT_STRIDE + 3]; }
+}

package/src/engine/physics/gjk/gjk.d.ts

@@ -13,30 +13,4 @@
  * @returns {boolean} true if the shapes intersect
  */
 export function gjk(simplex: number[] | Float64Array, shape_a: AbstractShape3D, shape_b: AbstractShape3D): boolean;
-/**
- * Separating-axis-cached variant of {@link gjk}. The 3 floats at
- * `axis_buffer[axis_offset..+2]` are used as the initial search
- * direction (seed) AND are overwritten with the final search direction
- * on exit. The narrowphase keeps a per-manifold-slot cache of these
- * three floats so quiescent contacts converge in 1–2 iterations next
- * frame instead of ~6–10 from a cold `(1, 0, 0)` start (Bullet's
- * `m_cachedSeparatingAxis` and Jolt's `ioV` use the same pattern).
- *
- * The same primitive doubles as a separating-axis cache for the
- * "no-overlap" path: when GJK returns false, the final direction is
- * roughly the separating axis, and next frame's first iteration
- * detects separation immediately.
- *
- * Writeback is automatic — `gjk_core` mutates a `subarray` view of
- * `axis_buffer`, so on return `axis_buffer[axis_offset..+2]` holds the
- * final direction. No try/finally needed.
- *
- * @param {number[]|Float64Array} simplex
- * @param {AbstractShape3D} shape_a
- * @param {AbstractShape3D} shape_b
- * @param {Float64Array} axis_buffer
- * @param {number} axis_offset
- * @returns {boolean}
- */
-export function gjk_with_axis(simplex: number[] | Float64Array, shape_a: AbstractShape3D, shape_b: AbstractShape3D, axis_buffer: Float64Array, axis_offset: number): boolean;
 //# sourceMappingURL=gjk.d.ts.map

package/src/engine/physics/gjk/gjk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/gjk.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAWnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,uCAPW,MAAM,EAAE,GAAC,YAAY,mEAGrB,YAAY,eACZ,MAAM,GACJ,OAAO,CAqBnB"}
+{"version":3,"file":"gjk.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/gjk.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;GAaG;AACH,6BALW,MAAM,EAAE,GAAC,YAAY,uDAGnB,OAAO,CAWnB"}

package/src/engine/physics/gjk/gjk.js

@@ -40,60 +40,11 @@ export function gjk(simplex, shape_a, shape_b) {
     return gjk_core(simplex, shape_a, shape_b, scratch_dir);
 }
 
-/**
- * Separating-axis-cached variant of {@link gjk}. The 3 floats at
- * `axis_buffer[axis_offset..+2]` are used as the initial search
- * direction (seed) AND are overwritten with the final search direction
- * on exit. The narrowphase keeps a per-manifold-slot cache of these
- * three floats so quiescent contacts converge in 1–2 iterations next
- * frame instead of ~6–10 from a cold `(1, 0, 0)` start (Bullet's
- * `m_cachedSeparatingAxis` and Jolt's `ioV` use the same pattern).
- *
- * The same primitive doubles as a separating-axis cache for the
- * "no-overlap" path: when GJK returns false, the final direction is
- * roughly the separating axis, and next frame's first iteration
- * detects separation immediately.
- *
- * Writeback is automatic — `gjk_core` mutates a `subarray` view of
- * `axis_buffer`, so on return `axis_buffer[axis_offset..+2]` holds the
- * final direction. No try/finally needed.
- *
- * @param {number[]|Float64Array} simplex
- * @param {AbstractShape3D} shape_a
- * @param {AbstractShape3D} shape_b
- * @param {Float64Array} axis_buffer
- * @param {number} axis_offset
- * @returns {boolean}
- */
-export function gjk_with_axis(simplex, shape_a, shape_b, axis_buffer, axis_offset) {
-    // Subarray view: zero-copy in V8 once the JIT realises both views
-    // back the same buffer; the in-place writes inside gjk_core
-    // propagate to axis_buffer automatically.
-    const dir_view = axis_buffer.subarray(axis_offset, axis_offset + 3);
-
-    // Guard against a stale or degenerate cached axis. A zero vector
-    // (first-frame initial state, or a stuck cache) and NaN / Inf
-    // would crash the first support-point query; the (1, 0, 0)
-    // fallback is the cold-start default.
-    const x = dir_view[0], y = dir_view[1], z = dir_view[2];
-    if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)
-        || (x === 0 && y === 0 && z === 0)) {
-        dir_view[0] = 1;
-        dir_view[1] = 0;
-        dir_view[2] = 0;
-    }
-
-    return gjk_core(simplex, shape_a, shape_b, dir_view);
-}
-
 /**
  * Core GJK routine — parameterised on the search-direction buffer.
- * The caller seeds `dir[0..2]` with an initial direction (typically
- * `(1, 0, 0)` for cold starts or a cached separating axis from a
- * previous frame), and on return `dir` holds the FINAL search
- * direction the algorithm settled on. The narrowphase separating-
- * axis cache (P2.1) uses this to thread per-manifold axes through
- * `gjk_with_axis` without a try/finally writeback dance.
+ * The caller seeds `dir[0..2]` with an initial direction (`(1, 0, 0)`
+ * for the {@link gjk} cold-start wrapper), and on return `dir` holds the
+ * FINAL search direction the algorithm settled on.
  *
  * @param {number[]|Float64Array} simplex
  * @param {AbstractShape3D} shape_a

package/src/engine/physics/gjk/gjk_epa_penetration.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Penetration depth + normal between two convex support providers at world pose.
+ * Writes the unit separation normal (B→A) into `out` and returns the depth
+ * (positive on overlap, 0 if separated — `out` untouched on 0).
+ *
+ * @param {Float64Array|number[]} out length ≥ 3
+ * @param {{support:Function}} A  world-space support provider (e.g. PosedShape)
+ * @param {{support:Function}} B
+ * @returns {number} penetration depth, or 0 if separated
+ */
+export function gjk_epa_penetration(out: Float64Array | number[], A: {
+    support: Function;
+}, B: {
+    support: Function;
+}): number;
+//# sourceMappingURL=gjk_epa_penetration.d.ts.map

package/src/engine/physics/gjk/gjk_epa_penetration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gjk_epa_penetration.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/gjk_epa_penetration.js"],"names":[],"mappings":"AA+OA;;;;;;;;;GASG;AACH,yCALW,YAAY,GAAC,MAAM,EAAE,KACrB;IAAC,OAAO,WAAS;CAAC,KAClB;IAAC,OAAO,WAAS;CAAC,GAChB,MAAM,CAOlB"}

package/src/engine/physics/gjk/gjk_epa_penetration.js

@@ -0,0 +1,255 @@
+/**
+ * Robust GJK + EPA penetration for convex shapes — the narrowphase's
+ * convex-fallback and concave-per-triangle penetration query. Replaced the
+ * `gjk.js` `gjk_with_axis` + `expanding_polytope_algorithm.js` pair, which
+ * returned a non-minimal axis for polytopes because its GJK handed EPA a
+ * degenerate (origin-on-face) simplex (see memory: feedback_epa_unreliable_polytopes).
+ *
+ * Structure follows Bullet's btGjkEpa2: GJK produces a rank-4 simplex that
+ * strictly encloses the origin; EPA builds outward-oriented faces from it and
+ * expands toward the closest face, rebuilding the horizon each step. Operates on
+ * any support provider with `support(out, off, dx, dy, dz)` in WORLD space (e.g.
+ * {@link PosedShape}); the penetration normal + depth come from the Minkowski
+ * difference's closest face to the origin. No cross-frame state → reset-and-
+ * resimulate determinism preserved.
+ *
+ * Even with per-call allocation (plain arrays) it measured ~2.1× FASTER than the
+ * replaced pair, which wasted all 64 iterations diverging on the degenerate
+ * simplex. KNOWN FOLLOW-UP: port the hot path to typed-array pools to remove the
+ * per-call allocation; the convex/concave EPA fallbacks are rarely hit today
+ * (closed-form solvers + SAT cover the common pairs), so it has not been urgent.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const GJK_MAX_ITER = 64;
+const EPA_MAX_ITER = 64;
+const EPA_EPS = 1e-8;
+
+const _sA = new Float64Array(3);
+const _sB = new Float64Array(3);
+
+function sub(a, b) { return [a[0] - b[0], a[1] - b[1], a[2] - b[2]]; }
+function dot(a, b) { return a[0] * b[0] + a[1] * b[1] + a[2] * b[2]; }
+function cross(a, b) {
+    return [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+}
+function neg(a) { return [-a[0], -a[1], -a[2]]; }
+function lensq(a) { return a[0] * a[0] + a[1] * a[1] + a[2] * a[2]; }
+// triple product (a×b)×c = b(a·c) − a(b·c)
+function tripleProduct(a, b, c) {
+    const ac = dot(a, c), bc = dot(b, c);
+    return [b[0] * ac - a[0] * bc, b[1] * ac - a[1] * bc, b[2] * ac - a[2] * bc];
+}
+
+/**
+ * Minkowski-difference support: support_A(d) − support_B(−d), world space.
+ *
+ * The direction is normalised first: the support contract assumes a UNIT vector
+ * — `SphereShape3D`/`CapsuleShape3D` scale the raw direction by their radius
+ * with no internal renormalisation — but GJK/EPA hand us arbitrary-magnitude
+ * search directions (the seed `−s` and the cross/triple products from the
+ * simplex evolution). Polytope supports are scale-invariant (vertex argmax), so
+ * this only matters for curved providers, but it must hold for them. Matches the
+ * sibling `minkowski_support.js`, which normalises for the same reason.
+ */
+function csoSupport(A, B, d) {
+    let dx = d[0], dy = d[1], dz = d[2];
+    const len2 = dx * dx + dy * dy + dz * dz;
+    if (len2 > 1e-30) {
+        const inv = 1 / Math.sqrt(len2);
+        dx *= inv; dy *= inv; dz *= inv;
+    }
+    A.support(_sA, 0, dx, dy, dz);
+    B.support(_sB, 0, -dx, -dy, -dz);
+    return [_sA[0] - _sB[0], _sA[1] - _sB[1], _sA[2] - _sB[2]];
+}
+
+/**
+ * GJK intersection. Returns a rank-4 simplex (array of 4 CSO points) enclosing
+ * the origin on overlap, or null if separated. `simplex[0]` is the most-recent
+ * point throughout (Muratori convention).
+ */
+function gjk(A, B) {
+    let d = [1, 0, 0];
+    let s = csoSupport(A, B, d);
+    if (lensq(s) < 1e-18) { d = [0, 1, 0]; s = csoSupport(A, B, d); }
+    const simplex = [s];
+    d = neg(s);
+
+    for (let iter = 0; iter < GJK_MAX_ITER; iter++) {
+        if (lensq(d) < 1e-18) return null; // search direction collapsed → touching/sep
+        const a = csoSupport(A, B, d);
+        if (dot(a, d) < 0) return null;    // farthest point short of origin → separated
+        simplex.unshift(a);
+        if (doSimplex(simplex, d)) return simplex.slice(0, 4);
+    }
+    return null;
+}
+
+/**
+ * Evolve the simplex toward the origin. Mutates `simplex` (in place) and writes
+ * the next search direction into `dOut`. Returns true when a tetrahedron
+ * encloses the origin.
+ */
+function doSimplex(simplex, dOut) {
+    if (simplex.length === 2) return lineCase(simplex, dOut);
+    if (simplex.length === 3) return triangleCase(simplex, dOut);
+    return tetraCase(simplex, dOut);
+}
+
+function setDir(dOut, v) { dOut[0] = v[0]; dOut[1] = v[1]; dOut[2] = v[2]; }
+
+function lineCase(simplex, dOut) {
+    const a = simplex[0], b = simplex[1];
+    const ab = sub(b, a), ao = neg(a);
+    if (dot(ab, ao) > 0) {
+        const perp = tripleProduct(ab, ao, ab);
+        if (lensq(perp) < 1e-18) {
+            // origin on the line — pick any perpendicular
+            const ref = Math.abs(ab[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0];
+            setDir(dOut, cross(ab, ref));
+        } else setDir(dOut, perp);
+    } else {
+        simplex.length = 1; // keep [a]
+        setDir(dOut, ao);
+    }
+    return false;
+}
+
+function triangleCase(simplex, dOut) {
+    const a = simplex[0], b = simplex[1], c = simplex[2];
+    const ab = sub(b, a), ac = sub(c, a), ao = neg(a);
+    const abc = cross(ab, ac);
+
+    if (dot(cross(abc, ac), ao) > 0) {
+        if (dot(ac, ao) > 0) { // outside edge ac
+            simplex.length = 0; simplex.push(a, c);
+            setDir(dOut, tripleProduct(ac, ao, ac));
+            return false;
+        }
+        return starCase(simplex, a, b, ao, dOut);
+    }
+    if (dot(cross(ab, abc), ao) > 0) return starCase(simplex, a, b, ao, dOut);
+
+    // origin within the triangle's prism — above or below
+    if (dot(abc, ao) > 0) { simplex.length = 0; simplex.push(a, b, c); setDir(dOut, abc); }
+    else { simplex.length = 0; simplex.push(a, c, b); setDir(dOut, neg(abc)); }
+    return false;
+}
+
+function starCase(simplex, a, b, ao, dOut) {
+    const ab = sub(b, a);
+    if (dot(ab, ao) > 0) {
+        simplex.length = 0; simplex.push(a, b);
+        setDir(dOut, tripleProduct(ab, ao, ab));
+    } else {
+        simplex.length = 0; simplex.push(a);
+        setDir(dOut, ao);
+    }
+    return false;
+}
+
+function tetraCase(simplex, dOut) {
+    const a = simplex[0], b = simplex[1], c = simplex[2], d = simplex[3];
+    const ab = sub(b, a), ac = sub(c, a), ad = sub(d, a), ao = neg(a);
+    const abc = cross(ab, ac);
+    const acd = cross(ac, ad);
+    const adb = cross(ad, ab);
+
+    if (dot(abc, ao) > 0) { simplex.length = 0; simplex.push(a, b, c); return triangleCase(simplex, dOut); }
+    if (dot(acd, ao) > 0) { simplex.length = 0; simplex.push(a, c, d); return triangleCase(simplex, dOut); }
+    if (dot(adb, ao) > 0) { simplex.length = 0; simplex.push(a, d, b); return triangleCase(simplex, dOut); }
+    return true; // origin inside the tetrahedron
+}
+
+/**
+ * EPA over the Minkowski difference, seeded by a rank-4 enclosing simplex.
+ * Writes the unit penetration normal (B→A) into `out` and returns the depth.
+ */
+function epa(A, B, simplex, out) {
+    const verts = simplex.map((p) => [p[0], p[1], p[2]]);
+    // centroid for outward orientation of the initial faces
+    const cen = [(verts[0][0] + verts[1][0] + verts[2][0] + verts[3][0]) / 4,
+        (verts[0][1] + verts[1][1] + verts[2][1] + verts[3][1]) / 4,
+        (verts[0][2] + verts[1][2] + verts[2][2] + verts[3][2]) / 4];
+
+    let faces = [[0, 1, 2], [0, 2, 3], [0, 3, 1], [1, 3, 2]].map((f) => makeFace(verts, f, cen));
+
+    for (let iter = 0; iter < EPA_MAX_ITER; iter++) {
+        // closest face to the origin
+        let best = faces[0];
+        for (let i = 1; i < faces.length; i++) if (faces[i].dist < best.dist) best = faces[i];
+
+        const w = csoSupport(A, B, best.n);
+        const wdist = dot(best.n, w) - best.dist;
+        if (wdist < EPA_EPS) break; // converged onto the closest face
+
+        const wi = verts.length;
+        verts.push(w);
+
+        // remove faces visible from w; collect horizon edges (those on exactly one removed face)
+        const edges = [];
+        const kept = [];
+        for (const f of faces) {
+            if (dot(f.n, w) - f.dist > EPA_EPS) {
+                addEdge(edges, f.v[0], f.v[1]);
+                addEdge(edges, f.v[1], f.v[2]);
+                addEdge(edges, f.v[2], f.v[0]);
+            } else kept.push(f);
+        }
+        faces = kept;
+        for (const [i, j] of edges) faces.push(makeFace(verts, [i, j, wi], cen));
+        if (faces.length === 0) break; // degenerate polytope (all faces visible + horizon cancelled)
+    }
+
+    // recompute the closest face (faces may have changed on the last iteration)
+    if (faces.length === 0) {
+        // Degenerate: no face survived. Report no usable axis (caller treats a
+        // non-positive depth as a miss) rather than dereferencing faces[0] and
+        // throwing a TypeError out of the narrowphase step.
+        out[0] = 0; out[1] = 0; out[2] = 0;
+        return 0;
+    }
+    let best = faces[0];
+    for (let i = 1; i < faces.length; i++) if (faces[i].dist < best.dist) best = faces[i];
+    out[0] = best.n[0]; out[1] = best.n[1]; out[2] = best.n[2];
+    return best.dist;
+}
+
+/** Build a face with an OUTWARD unit normal (away from the polytope centroid). */
+function makeFace(verts, idx, cen) {
+    const a = verts[idx[0]], b = verts[idx[1]], c = verts[idx[2]];
+    let n = cross(sub(b, a), sub(c, a));
+    const l = Math.sqrt(lensq(n)) || 1;
+    n = [n[0] / l, n[1] / l, n[2] / l];
+    // orient outward: normal should point away from the polytope interior (centroid)
+    if (dot(n, sub(a, cen)) < 0) { n = neg(n); const t = idx[1]; idx = [idx[0], idx[2], t]; }
+    return { v: idx, n, dist: dot(n, a) }; // perpendicular distance from origin (≥0 once outward)
+}
+
+/** Add an edge with horizon cancellation: if the reverse edge is present, drop both. */
+function addEdge(edges, i, j) {
+    for (let k = 0; k < edges.length; k++) {
+        if (edges[k][0] === j && edges[k][1] === i) { edges.splice(k, 1); return; }
+    }
+    edges.push([i, j]);
+}
+
+/**
+ * Penetration depth + normal between two convex support providers at world pose.
+ * Writes the unit separation normal (B→A) into `out` and returns the depth
+ * (positive on overlap, 0 if separated — `out` untouched on 0).
+ *
+ * @param {Float64Array|number[]} out length ≥ 3
+ * @param {{support:Function}} A  world-space support provider (e.g. PosedShape)
+ * @param {{support:Function}} B
+ * @returns {number} penetration depth, or 0 if separated
+ */
+export function gjk_epa_penetration(out, A, B) {
+    const simplex = gjk(A, B);
+    if (simplex === null || simplex.length < 4) return 0;
+    const depth = epa(A, B, simplex, out);
+    return depth > 0 && Number.isFinite(depth) ? depth : 0;
+}

package/src/engine/physics/gjk/minkowski_support.d.ts

@@ -15,15 +15,10 @@
  * and shape support implementations (sphere especially) don't bother
  * to renormalise internally.
  *
- * NOTE: EPA (`expanding_polytope_algorithm.js`) computes the Minkowski
- * support inline rather than calling this. Its convention is the
- * opposite sign (B−A rather than A−B), and it skips the normalisation
- * because the search directions it constructs from face normals are
- * already unit-length. The narrowphase consumer of EPA's output then
- * negates the result to get the contact normal in the "B → A" stored
- * convention. Folding EPA onto this helper would require both flipping
- * its sign convention and changing the narrowphase call site — not
- * worth the churn for one call site.
+ * NOTE: the robust penetration query (`gjk_epa_penetration.js`) computes
+ * its own Minkowski-difference support inline rather than calling this
+ * helper — it is self-contained (its own GJK + EPA) and works on world-
+ * space support providers, so it does not share this body-space path.
  *
  * @param {Float64Array|number[]} result  3-vector destination
  * @param {number} result_offset

package/src/engine/physics/gjk/minkowski_support.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"minkowski_support.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/minkowski_support.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,0CARW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,6DAGN,MAAM,SACN,MAAM,SACN,MAAM,QA2BhB"}
+{"version":3,"file":"minkowski_support.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/gjk/minkowski_support.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,0CARW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,6DAGN,MAAM,SACN,MAAM,SACN,MAAM,QA2BhB"}