@woosh/meep-engine 3.5.0 → 3.6.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/gjk/gjk_epa_penetration.d.ts

@@ -3,15 +3,42 @@
  * Writes the unit separation normal (A→B: the direction A must move along
  * NEGATED to separate — equivalently, negate `out` for the B→A push axis;
  * the narrowphase sign-check sites canonicalise it against the body centres)
- * into `out` and returns the depth (positive on overlap, 0 if separated —
- * `out` untouched on 0).
+ * into `out` and returns the depth. `out` is untouched unless the return is
+ * positive.
  *
  * @param {Float64Array|number[]} out destination for the unit normal, length ≥ 3
  * @param {SupportProvider} A world-space support provider (e.g. PosedShape3D)
  * @param {SupportProvider} B world-space support provider (e.g. PosedShape3D)
- * @returns {number} penetration depth, or 0 if separated
+ * @returns {number} the penetration depth (> 0) on overlap;
+ *   {@link GJK_SEPARATED} when GJK PROVED the shapes apart; `0` for no usable
+ *   axis — EPA degenerated on an established overlap, or GJK reached no
+ *   verdict at all. `0` is not a separation and callers with a fallback
+ *   should still run it
  */
 export function gjk_epa_penetration(out: Float64Array | number[], A: SupportProvider, B: SupportProvider): number;
+/**
+ * Sentinel returned by {@link gjk_epa_penetration} when GJK PROVED the shapes
+ * apart — {@link GJK_APART}, a support plane with the whole Minkowski
+ * difference on the far side of the origin — as distinct from `0`, "no usable
+ * axis": a degenerate EPA, or a GJK that reached no verdict at all.
+ *
+ * The two need separate values because callers act on them differently. A
+ * proof of separation is the final answer and the pair is done; the rest is a
+ * gap in this query that a fallback (MPR) may still be able to fill. Note the
+ * asymmetry — this is claimed ONLY from the proof, never from GJK's other two
+ * non-overlap exits, which are inconclusive rather than negative.
+ * Collapsing both to `0`, as this function used to, sent every non-touching
+ * pair the broadphase produced into that fallback — where MPR, whose portal
+ * argument assumes an overlap it was never told to doubt, answered a question
+ * GJK had already settled and reported the gap as a penetration of its own
+ * size (see the separating-plane certificate in {@link mpr}).
+ *
+ * Negative so that the existing `depth > 0` guard at every call site keeps
+ * rejecting it unchanged.
+ *
+ * @type {number}
+ */
+export const GJK_SEPARATED: number;
 /**
  * A convex shape exposing a world-space support mapping: `support(out, off, dx,
  * dy, dz)` writes the farthest point of the shape in direction `(dx, dy, dz)`

package/src/core/geom/3d/gjk/gjk_epa_penetration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gjk_epa_penetration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk_epa_penetration.js"],"names":[],"mappings":"AAofA;;;;;;;;;;;;GAYG;AACH,yCALW,YAAY,GAAC,MAAM,EAAE,KACrB,eAAe,KACf,eAAe,GACb,MAAM,CAQlB;;;;;;8BAvbY;IAAE,OAAO,SAAW,YAAY,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,IAAI,CAAA;CAAE"}
+{"version":3,"file":"gjk_epa_penetration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/gjk_epa_penetration.js"],"names":[],"mappings":"AA2iBA;;;;;;;;;;;;;;;;GAgBG;AACH,yCATW,YAAY,GAAC,MAAM,EAAE,KACrB,eAAe,KACf,eAAe,GACb,MAAM,CA0BlB;AA7DD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4BAFU,MAAM,CAEgB;;;;;;8BAzdnB;IAAE,OAAO,SAAW,YAAY,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,IAAI,CAAA;CAAE"}

package/src/core/geom/3d/gjk/gjk_epa_penetration.js

@@ -81,14 +81,45 @@ const CEN = new Float64Array(3); // polytope centroid (for outward orientation)
  * @typedef {{ support: function(Float64Array, number, number, number, number): void }} SupportProvider
  */
 
+/**
+ * {@link gjk} enclosed the origin: the shapes overlap and {@link SIMPLEX} holds
+ * a rank-4 simplex EPA can expand from.
+ * @type {number}
+ */
+const GJK_ENCLOSED = 4;
+
+/**
+ * {@link gjk} found a support plane with the whole Minkowski difference on the
+ * far side of the origin. That is a proof of separation, and the only one of
+ * this function's non-overlap exits that is.
+ * @type {number}
+ */
+const GJK_APART = -1;
+
+/**
+ * {@link gjk} ran out of road: the search direction collapsed, or the iteration
+ * cap hit. Neither says the shapes are apart — the direction collapses when the
+ * origin lands exactly ON a simplex feature, which is a TOUCH (two spheres at
+ * exactly 2r do this), and the cap is just non-convergence on a smooth support.
+ * Callers must treat it as "no answer" and keep whatever fallback they have.
+ * @type {number}
+ */
+const GJK_INCONCLUSIVE = 0;
+
 /**
  * GJK intersection. Fills {@link SIMPLEX} with a rank-4 simplex enclosing the
- * origin and returns 4 on overlap; returns 0 if the shapes are separated.
+ * origin and returns {@link GJK_ENCLOSED} on overlap.
  * `SIMPLEX` slot 0 is the most-recent point throughout (Muratori convention).
  *
+ * The two non-overlap verdicts are deliberately distinct: only
+ * {@link GJK_APART} is a proof, and collapsing it together with
+ * {@link GJK_INCONCLUSIVE} silently converts "I could not tell" into "they are
+ * not touching" — which drops touching contacts.
+ *
  * @param {SupportProvider} A first support provider
  * @param {SupportProvider} B second support provider
- * @returns {number} 4 if the origin is enclosed (shapes overlap), 0 if separated
+ * @returns {number} {@link GJK_ENCLOSED}, {@link GJK_APART}, or
+ *   {@link GJK_INCONCLUSIVE}
  */
 function gjk(A, B) {
     minkowski_support(SIMPLEX, 0, A, B, 1, 0, 0);
@@ -102,11 +133,11 @@ function gjk(A, B) {
 
     for (let iter = 0; iter < GJK_MAX_ITER; iter++) {
         if (v3_length_sqr(DIR[0], DIR[1], DIR[2]) < DIR_EPS) {
-            return 0; // search direction collapsed → touching/separated
+            return GJK_INCONCLUSIVE; // direction collapsed → touching, or apart; unknown
         }
         minkowski_support(_w, 0, A, B, DIR[0], DIR[1], DIR[2]);
         if (v3_dot(_w[0], _w[1], _w[2], DIR[0], DIR[1], DIR[2]) < 0) {
-            return 0; // farthest point short of the origin → separated
+            return GJK_APART; // farthest point short of the origin → proven separated
         }
         // push the new point to slot 0, shifting the existing points down one slot
         // (copyWithin is memmove-style: the overlapping forward copy is well-defined)
@@ -118,10 +149,10 @@ function gjk(A, B) {
 
         count = do_simplex(count);
         if (count === 0) {
-            return 4; // origin enclosed by the tetrahedron
+            return GJK_ENCLOSED; // origin enclosed by the tetrahedron
         }
     }
-    return 0;
+    return GJK_INCONCLUSIVE; // iteration cap → non-convergent, not a separation
 }
 
 /**
@@ -498,23 +529,65 @@ function epa(A, B, out) {
     return FACE_DIST[best];
 }
 
+/**
+ * Sentinel returned by {@link gjk_epa_penetration} when GJK PROVED the shapes
+ * apart — {@link GJK_APART}, a support plane with the whole Minkowski
+ * difference on the far side of the origin — as distinct from `0`, "no usable
+ * axis": a degenerate EPA, or a GJK that reached no verdict at all.
+ *
+ * The two need separate values because callers act on them differently. A
+ * proof of separation is the final answer and the pair is done; the rest is a
+ * gap in this query that a fallback (MPR) may still be able to fill. Note the
+ * asymmetry — this is claimed ONLY from the proof, never from GJK's other two
+ * non-overlap exits, which are inconclusive rather than negative.
+ * Collapsing both to `0`, as this function used to, sent every non-touching
+ * pair the broadphase produced into that fallback — where MPR, whose portal
+ * argument assumes an overlap it was never told to doubt, answered a question
+ * GJK had already settled and reported the gap as a penetration of its own
+ * size (see the separating-plane certificate in {@link mpr}).
+ *
+ * Negative so that the existing `depth > 0` guard at every call site keeps
+ * rejecting it unchanged.
+ *
+ * @type {number}
+ */
+export const GJK_SEPARATED = -1;
+
 /**
  * Penetration depth + normal between two convex support providers at world pose.
  * Writes the unit separation normal (A→B: the direction A must move along
  * NEGATED to separate — equivalently, negate `out` for the B→A push axis;
  * the narrowphase sign-check sites canonicalise it against the body centres)
- * into `out` and returns the depth (positive on overlap, 0 if separated —
- * `out` untouched on 0).
+ * into `out` and returns the depth. `out` is untouched unless the return is
+ * positive.
  *
  * @param {Float64Array|number[]} out destination for the unit normal, length ≥ 3
  * @param {SupportProvider} A world-space support provider (e.g. PosedShape3D)
  * @param {SupportProvider} B world-space support provider (e.g. PosedShape3D)
- * @returns {number} penetration depth, or 0 if separated
+ * @returns {number} the penetration depth (> 0) on overlap;
+ *   {@link GJK_SEPARATED} when GJK PROVED the shapes apart; `0` for no usable
+ *   axis — EPA degenerated on an established overlap, or GJK reached no
+ *   verdict at all. `0` is not a separation and callers with a fallback
+ *   should still run it
  */
 export function gjk_epa_penetration(out, A, B) {
-    if (gjk(A, B) < 4) {
+    const verdict = gjk(A, B);
+
+    if (verdict === GJK_APART) {
+        return GJK_SEPARATED;
+    }
+
+    if (verdict !== GJK_ENCLOSED) {
+        // GJK_INCONCLUSIVE — no simplex to expand and no proof of separation
+        // either, so this reports the same "no usable axis" as a degenerate
+        // EPA and leaves the caller's fallback in play. Reporting it as
+        // GJK_SEPARATED would be an overclaim, and an expensive one: the
+        // collapse exit fires on EXACTLY touching pairs (two spheres at 2r),
+        // whose resting contact would then be dropped without anything ever
+        // looking at the geometry.
         return 0;
     }
+
     const depth = epa(A, B, out);
     return depth > 0 && Number.isFinite(depth) ? depth : 0;
 }

package/src/core/geom/3d/gjk/mpr.d.ts

@@ -39,7 +39,13 @@
  *   any narrowphase call site.
  *
  * On failure modes:
- *   - Returns `false` if the shapes don't overlap.
+ *   - Returns `false` if the shapes don't overlap, decided by a
+ *     separating-plane certificate — the support of the Mink-diff along
+ *     the portal normal fails to reach the origin — which is one exact
+ *     evaluation carrying none of the refinement's error. A miss leaves
+ *     `result` untouched: the separation distance is deliberately NOT
+ *     written, because every caller reads the depth as |MTV| and cannot
+ *     tell a gap from a penetration once the sign is gone.
  *   - On a degenerate Mink-diff (shapes touching at a point, perfectly
  *     coincident centres with collinear support points), returns
  *     `true` with a small fallback MTV — same approach as EPA's

package/src/core/geom/3d/gjk/mpr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mpr.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/mpr.js"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,4BANW,YAAY,iBACZ,MAAM,iDAGJ,OAAO,CAqQnB"}
+{"version":3,"file":"mpr.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/gjk/mpr.js"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,4BANW,YAAY,iBACZ,MAAM,iDAGJ,OAAO,CA8TnB"}

package/src/core/geom/3d/gjk/mpr.js

@@ -93,7 +93,13 @@ const V4 = new Float64Array(3);
  *   any narrowphase call site.
  *
  * On failure modes:
- *   - Returns `false` if the shapes don't overlap.
+ *   - Returns `false` if the shapes don't overlap, decided by a
+ *     separating-plane certificate — the support of the Mink-diff along
+ *     the portal normal fails to reach the origin — which is one exact
+ *     evaluation carrying none of the refinement's error. A miss leaves
+ *     `result` untouched: the separation distance is deliberately NOT
+ *     written, because every caller reads the depth as |MTV| and cannot
+ *     tell a gap from a penetration once the sign is gone.
  *   - On a degenerate Mink-diff (shapes touching at a point, perfectly
  *     coincident centres with collinear support points), returns
  *     `true` with a small fallback MTV — same approach as EPA's
@@ -116,6 +122,17 @@ export function mpr(result, result_offset, shape_a, shape_b) {
     // origins are interior to their geometry — true for spheres,
     // boxes, capsules, and any closed mesh whose bounding box contains
     // its centroid.
+    //
+    // This is a PRECONDITION, not a preference, and nothing here can
+    // check it: every argument below assumes the ray V0→origin starts
+    // inside. An authored ConvexHullShape3D whose vertices sit far from
+    // its own local origin (a level brush keeping map coordinates under
+    // an identity collider transform, say) violates it, and MPR then
+    // returns a confidently wrong MTV — measured at 17.8 m, the slab's
+    // half-width, for a 0.05 m overlap. Callers that can answer overlap
+    // some other way should do so and reach for MPR only when that
+    // answer is genuinely unavailable; {@link narrowphase_step} keeps it
+    // behind a GJK verdict for exactly this reason.
     V0[0] = shape_a.px - shape_b.px;
     V0[1] = shape_a.py - shape_b.py;
     V0[2] = shape_a.pz - shape_b.pz;
@@ -281,10 +298,22 @@ export function mpr(result, result_offset, shape_a, shape_b) {
         const inv_pn = 1 / Math.sqrt(pn_len_sqr);
         pn_x *= inv_pn; pn_y *= inv_pn; pn_z *= inv_pn;
 
-        // Perpendicular distance from the origin to the portal plane,
-        // = dot(V1, portal_normal). This is the candidate depth on
-        // every iteration; we accept it once V4 fails to push the
-        // portal further.
+        // Signed offset of the portal plane from the origin along the
+        // outward normal, = dot(V1, portal_normal), and the depth this
+        // returns once the portal settles. In exact arithmetic its sign
+        // would also BE the overlap test — V0 is interior and the ray
+        // V0→origin pierces the portal, so the origin is inside the
+        // Mink-diff exactly when it lies on V0's side of that plane —
+        // and a negative value would mean the ray left the Mink-diff
+        // before reaching the origin, making |portal_dist| a SEPARATION
+        // rather than a depth.
+        //
+        // It is not the test used, because this is an iterate: near zero
+        // its sign is refinement noise, not geometry. The certificate
+        // below decides instead, and getting a magnitude out of a
+        // separated pair — which every caller then reads as a depth,
+        // |MTV| having thrown the sign away — is the failure that made
+        // this loop worth re-deriving.
         const portal_dist = V1[0] * pn_x + V1[1] * pn_y + V1[2] * pn_z;
 
         // New support V4 in the portal normal direction.
@@ -292,8 +321,41 @@ export function mpr(result, result_offset, shape_a, shape_b) {
 
         const v4_dist = V4[0] * pn_x + V4[1] * pn_y + V4[2] * pn_z;
 
+        // Separating-plane certificate — and it has to be tested BEFORE
+        // the convergence branch below. If the farthest point of the
+        // Mink-diff along pn does not reach the origin, the plane
+        // through the origin with normal pn separates the two shapes,
+        // which is a proof of a miss. It can never reject a true
+        // overlap: the origin is then inside the Mink-diff, whose
+        // support is ≥ 0 in EVERY direction.
+        //
+        // The order is the whole point. A small shape near a large flat
+        // face seeds a portal already within MPR_TOLERANCE of the
+        // support plane, so the convergence test succeeds on the first
+        // iteration and this proof was never reached — the old order
+        // returned `true` with a negative portal_dist, and callers
+        // (which read the depth as |MTV|) saw the gap as a penetration
+        // of exactly its own size.
+        if (v4_dist < 0) {
+            return false;
+        }
+
         // Convergence: V4 doesn't extend the portal beyond the current
-        // face (within tolerance). Emit MTV = normal × depth.
+        // face (within tolerance), so the portal face is the closest
+        // face of the Mink-diff and its offset is the depth.
+        //
+        // Note what does NOT appear here: a `portal_dist <= 0` gate. It
+        // is tempting — a negative offset is exactly what a miss looks
+        // like — but portal_dist is the one quantity in this loop that
+        // carries the refinement's error, and near zero that error is
+        // the whole signal. A capsule resting exactly on a floor
+        // converges at portal_dist ≈ −3e-6 with v4_dist ≈ +2.5e-6: a
+        // real touching contact whose sign is pure noise, which such a
+        // gate drops, taking the resting contact with it. The certificate
+        // above is error-free (one exact support evaluation) and is the
+        // right arbiter; by the time it passes, convergence bounds
+        // portal_dist below at −MPR_TOLERANCE, which is the same
+        // accuracy the depth itself is quoted to.
         if (v4_dist - portal_dist < MPR_TOLERANCE) {
             result[result_offset]     = pn_x * portal_dist;
             result[result_offset + 1] = pn_y * portal_dist;
@@ -301,13 +363,6 @@ export function mpr(result, result_offset, shape_a, shape_b) {
             return true;
         }
 
-        // V4 didn't pass the origin along the portal normal — the
-        // shapes aren't actually overlapping (shouldn't happen after
-        // successful portal discovery, but defensive).
-        if (v4_dist < 0) {
-            return false;
-        }
-
         // Replace one of V1, V2, V3 with V4 such that the new portal
         // still contains the V0→origin ray. The split is determined by
         // three cross-product / dot tests against V4 × V0: signs of
@@ -360,6 +415,14 @@ export function mpr(result, result_offset, shape_a, shape_b) {
     }
     const inv_pn = 1 / Math.sqrt(pn_len_sqr);
     pn_x *= inv_pn; pn_y *= inv_pn; pn_z *= inv_pn;
+    // The portal never settled, so this face is a guess — but the
+    // separating-plane certificate costs one support call and holds
+    // regardless of how the refinement terminated. Apply the same rule
+    // both exits use rather than emitting an unexamined MTV.
+    minkowski_support(V4, 0, shape_a, shape_b, pn_x, pn_y, pn_z);
+    if (V4[0] * pn_x + V4[1] * pn_y + V4[2] * pn_z < 0) {
+        return false;
+    }
     const portal_dist = V1[0] * pn_x + V1[1] * pn_y + V1[2] * pn_z;
     result[result_offset]     = pn_x * portal_dist;
     result[result_offset + 1] = pn_y * portal_dist;

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":"AAyyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAuClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QA4LlE;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,QA2H3D"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA2zCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAuClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QA4LlE;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,QA2H3D"}

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

@@ -3,7 +3,7 @@ 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 { gjk_epa_penetration } from "../../../core/geom/3d/gjk/gjk_epa_penetration.js";
+import { GJK_SEPARATED, gjk_epa_penetration } from "../../../core/geom/3d/gjk/gjk_epa_penetration.js";
 import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
 import { mpr } from "../../../core/geom/3d/gjk/mpr.js";
 import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
@@ -1124,12 +1124,15 @@ function dispatch_pair(count, colA, trA, colB, trB) {
             // 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.
+            // safety net for the case EPA degenerates on a real overlap, or
+            // GJK reaches no verdict — never for a triangle GJK proved clear.
             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 (pen_depth === GJK_SEPARATED) {
+                continue;
             } else {
                 if (!mpr(epa_result, 0, posed_a, posed_b)) continue;
                 ex = epa_result[0]; ey = epa_result[1]; ez = epa_result[2];
@@ -1247,7 +1250,22 @@ function dispatch_pair(count, colA, trA, colB, trB) {
     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 (pen_depth === GJK_SEPARATED) {
+        // GJK proved the pair apart — the answer, not a gap in the query, so
+        // the safety net below has nothing to add and must not be consulted.
+        // This branch is the common case on this path, not an edge: the
+        // broadphase hands over every pair whose fat AABBs touch, and most of
+        // them are near misses. Asking MPR about them is what turned a clear
+        // gap into a ContactBegin carrying a positive depth equal to the gap
+        // — for a sphere near a large ConvexHullShape3D face, which is every
+        // projectile in a brush-built level (mpr.js's separating-plane
+        // certificate now refuses that answer at the source too).
+        return count;
     } else {
+        // No usable axis: EPA degenerated on a real overlap, or GJK itself
+        // reached no verdict (its search direction collapses on an EXACTLY
+        // touching pair). Neither is a separation, so the net still gets to
+        // look. THIS is what it is for.
         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);

package/src/shade/renderer/scene/bvh/StaticSceneBVH.js

@@ -390,10 +390,10 @@ export class StaticSceneBVH {
         let nearest_distance = ray.tMax;
 
         const hit_count = bvh_query_user_data_ray(
-            bvh,
-            bvh.root,
             scratch_instance_hits,
             0,
+            bvh,
+            bvh.root,
             ray.origin_x, ray.origin_y, ray.origin_z,
             ray.direction_x, ray.direction_y, ray.direction_z
         );
@@ -501,10 +501,10 @@ export class StaticSceneBVH {
         const bvh = this.instance_bvh;
 
         const hit_count = bvh_query_user_data_ray(
-            bvh,
-            bvh.root,
             scratch_instance_hits,
             0,
+            bvh,
+            bvh.root,
             ray.origin_x, ray.origin_y, ray.origin_z,
             ray.direction_x, ray.direction_y, ray.direction_z
         );

package/src/engine/graphics/sh3/build_injected_shader.d.ts

@@ -1,51 +0,0 @@
-/**
- * Prepend a preamble to a three.js-generated shader and splice a chunk in after
- * a named anchor.
- *
- * WHY THIS EXISTS
- *
- * The LPV/GI and LPG material paths have eight shader builders between them
- * (`space_fragment` and `space_vertex`, vertex and fragment, times two
- * subsystems) and every one of them was the same three statements: concatenate
- * the preambles ahead of the source, `insert_after` an anchor, return. What
- * actually differs is data — which preamble, which anchor, which chunk.
- *
- * More importantly the two anchors were spelled out in eight separate string
- * literals. They are three.js's own chunk include lines, and a mismatch fails
- * *quietly* (a console warning and an unmodified shader), so having one
- * definition each is worth more than the lines it saves.
- *
- * Shader assembly happens once per material compile, not per frame.
- *
- * @param {string} source shader source three.js handed to `onBeforeCompile`
- * @param {string} preamble prepended verbatim, ahead of the source
- * @param {string} anchor see {@link GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN} / {@link GLSL_ANCHOR_FOG_VERTEX}
- * @param {string} chunk GLSL spliced in directly after `anchor`
- * @returns {string}
- */
-export function build_injected_shader(source: string, preamble: string, anchor: string, chunk: string): string;
-/**
- * three.js chunk marker after which a probe-field contribution is added to
- * `irradiance` in the fragment stage.
- *
- * `<lights_fragment_begin>` is where three declares `irradiance` and has not yet
- * consumed it, so anything added immediately after it participates in the
- * lighting equations normally. The literal must match three's include line
- * exactly — `insert_after` warns and silently returns the source unchanged when
- * it does not find the term, which shows up as GI simply not appearing.
- *
- * @type {string}
- */
-export const GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN: string;
-/**
- * three.js chunk marker after which per-vertex probe work is injected.
- *
- * `<fog_vertex>` is the last chunk in the standard vertex `main()`, so by that
- * point `worldPosition` (when declared), `position` and `normal` are all
- * available. Same exact-match requirement as
- * {@link GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN}.
- *
- * @type {string}
- */
-export const GLSL_ANCHOR_FOG_VERTEX: string;
-//# sourceMappingURL=build_injected_shader.d.ts.map

package/src/engine/graphics/sh3/build_injected_shader.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"build_injected_shader.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/sh3/build_injected_shader.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,8CANW,MAAM,YACN,MAAM,UACN,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AArDD;;;;;;;;;;;GAWG;AACH,gDAFU,MAAM,CAEoE;AAEpF;;;;;;;;;GASG;AACH,qCAFU,MAAM,CAE8C"}

package/src/engine/graphics/sh3/build_injected_shader.js

@@ -1,56 +0,0 @@
-import { insert_after } from "../../../core/primitives/strings/insert_after.js";
-
-/**
- * three.js chunk marker after which a probe-field contribution is added to
- * `irradiance` in the fragment stage.
- *
- * `<lights_fragment_begin>` is where three declares `irradiance` and has not yet
- * consumed it, so anything added immediately after it participates in the
- * lighting equations normally. The literal must match three's include line
- * exactly — `insert_after` warns and silently returns the source unchanged when
- * it does not find the term, which shows up as GI simply not appearing.
- *
- * @type {string}
- */
-export const GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN = '#include <lights_fragment_begin>';
-
-/**
- * three.js chunk marker after which per-vertex probe work is injected.
- *
- * `<fog_vertex>` is the last chunk in the standard vertex `main()`, so by that
- * point `worldPosition` (when declared), `position` and `normal` are all
- * available. Same exact-match requirement as
- * {@link GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN}.
- *
- * @type {string}
- */
-export const GLSL_ANCHOR_FOG_VERTEX = '#include <fog_vertex>';
-
-/**
- * Prepend a preamble to a three.js-generated shader and splice a chunk in after
- * a named anchor.
- *
- * WHY THIS EXISTS
- *
- * The LPV/GI and LPG material paths have eight shader builders between them
- * (`space_fragment` and `space_vertex`, vertex and fragment, times two
- * subsystems) and every one of them was the same three statements: concatenate
- * the preambles ahead of the source, `insert_after` an anchor, return. What
- * actually differs is data — which preamble, which anchor, which chunk.
- *
- * More importantly the two anchors were spelled out in eight separate string
- * literals. They are three.js's own chunk include lines, and a mismatch fails
- * *quietly* (a console warning and an unmodified shader), so having one
- * definition each is worth more than the lines it saves.
- *
- * Shader assembly happens once per material compile, not per frame.
- *
- * @param {string} source shader source three.js handed to `onBeforeCompile`
- * @param {string} preamble prepended verbatim, ahead of the source
- * @param {string} anchor see {@link GLSL_ANCHOR_LIGHTS_FRAGMENT_BEGIN} / {@link GLSL_ANCHOR_FOG_VERTEX}
- * @param {string} chunk GLSL spliced in directly after `anchor`
- * @returns {string}
- */
-export function build_injected_shader(source, preamble, anchor, chunk) {
-    return insert_after(preamble + source, anchor, chunk);
-}

package/src/engine/graphics/sh3/fromCubeRenderTarget.d.ts

@@ -1,9 +0,0 @@
-/**
- *
- * @param {Uint8Array} data
- * @param {THREE.WebGLRenderer} renderer
- * @param {THREE.WebGLCubeRenderTarget} cubeRenderTarget
- * @return {Float64Array}
- */
-export function fromCubeRenderTarget(data: Uint8Array, renderer: THREE.WebGLRenderer, cubeRenderTarget: THREE.WebGLCubeRenderTarget): Float64Array;
-//# sourceMappingURL=fromCubeRenderTarget.d.ts.map

package/src/engine/graphics/sh3/fromCubeRenderTarget.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"fromCubeRenderTarget.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics/sh3/fromCubeRenderTarget.js"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,2CALW,UAAU,iFAGT,YAAY,CAgIvB"}

package/src/engine/graphics/sh3/fromCubeRenderTarget.js

@@ -1,142 +0,0 @@
-import { sh3_basis_at } from "../../../core/geom/3d/sphere/harmonics/sh3_basis_at.js";
-import { sh3_dering_optimize_positive } from "../../../core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js";
-import { sh3_vector_accumulate } from "../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
-import { vector_scale_offset } from "../../../core/geom/vec/vector_scale_offset.js";
-import { v3_length_sqr } from "../../../core/geom/vec3/v3_length_sqr.js";
-
-const scratch_color = new Float32Array(3);
-
-/**
- *
- * @param {Uint8Array} data
- * @param {THREE.WebGLRenderer} renderer
- * @param {THREE.WebGLCubeRenderTarget} cubeRenderTarget
- * @return {Float64Array}
- */
-export function fromCubeRenderTarget(
-    data,
-    renderer,
-    cubeRenderTarget
-) {
-
-    // The renderTarget must be set to RGBA in order to make readRenderTargetPixels works
-    let total_weight = 0;
-
-    const __shared_buffer = new ArrayBuffer((27 + 9) * 8);
-
-    const sh_basis = new Float64Array(__shared_buffer, 0, 9);
-    const coefficients = new Float64Array(__shared_buffer, 9 * 8, 27);
-
-    const image_size = cubeRenderTarget.width;
-
-    const pixel_size = 2 / image_size;
-
-    let normal_x = 0, normal_y = 0, normal_z = 0;
-
-    for (let faceIndex = 0; faceIndex < 6; faceIndex++) {
-
-        renderer.readRenderTargetPixels(cubeRenderTarget, 0, 0, image_size, image_size, data, faceIndex);
-
-        // RGBA assumed
-
-        for (let i = 0, il = data.length; i < il; i += 4) {
-
-
-            // pixel coordinate on unit cube
-
-            const pixelIndex = i / 4;
-
-            const col = -1 + (pixelIndex % image_size + 0.5) * pixel_size;
-
-            const row = 1 - (Math.floor(pixelIndex / image_size) + 0.5) * pixel_size;
-
-
-            switch (faceIndex) {
-
-                case 0:
-                    normal_x = 1;
-                    normal_y = row;
-                    normal_z = -col;
-                    break;
-
-                case 1:
-                    normal_x = -1;
-                    normal_y = row;
-                    normal_z = col;
-                    break;
-
-                case 2:
-                    normal_x = col;
-                    normal_y = 1;
-                    normal_z = -row;
-                    break;
-
-                case 3:
-                    normal_x = col;
-                    normal_y = -1;
-                    normal_z = row;
-                    break;
-
-                case 4:
-                    normal_x = col;
-                    normal_y = row;
-                    normal_z = 1;
-                    break;
-
-                case 5:
-                    normal_x = -col;
-                    normal_y = row;
-                    normal_z = -1;
-                    break;
-
-            }
-
-            // weight assigned to this pixel
-
-            const length_squared = v3_length_sqr(normal_x, normal_y, normal_z);
-
-            const length = Math.sqrt(length_squared);
-
-            const weight = 4 / (length * length_squared);
-
-            total_weight += weight;
-
-            // direction vector to this pixel
-            normal_x /= length;
-            normal_y /= length;
-            normal_z /= length;
-
-            // evaluate SH basis functions in direction dir
-            sh3_basis_at(normal_x, normal_y, normal_z, sh_basis);
-
-            // pixel color, already in linear space so no sRGB->Linear conversion necessary
-
-            // 0.003921 constant value is 1/255, a conversion value from UINT8 to normalized float
-            const weight_conv = weight * 0.00392156862745098;
-
-            scratch_color[0] = data[i] * weight_conv;
-            scratch_color[1] = data[i + 1] * weight_conv;
-            scratch_color[2] = data[i + 2] * weight_conv;
-
-            // accumulate
-            sh3_vector_accumulate(
-                coefficients, 0,
-                sh_basis, 0,
-                scratch_color, 0,
-                3
-            );
-
-        }
-
-    }
-
-    // normalize
-    const norm = (4 * Math.PI) / total_weight;
-
-    vector_scale_offset(coefficients, 0, coefficients, 0, 27, norm);
-
-    sh3_dering_optimize_positive(coefficients, 0, coefficients, 0, 3);
-
-    return coefficients;
-
-}

package/src/engine/graphics/sh3/shader/visualize.frag.d.ts

@@ -1,3 +0,0 @@
-declare const _default: "\n#define RECIPROCAL_PI 0.318309886\n\nvec3 inverseTransformDirection( in vec3 normal, in mat4 matrix ) {\n    // matrix is assumed to be orthogonal\n    return normalize( ( vec4( normal, 0.0 ) * matrix ).xyz );\n}\n\n// source: https://graphics.stanford.edu/papers/envmap/envmap.pdf\n//\n// SIGN CONVENTION: coefficients 1, 3, 5 and 7 are SUBTRACTED here, matching\n// three.js's SphericalHarmonics3 and the JS reference\n// core/geom/3d/sphere/harmonics/sh3_sample_irradiance_by_direction.js. The LPV\n// and LPG shader chunks (sh3/{gi,lpg}/material/chunk_*_get_irradiance_at.js)\n// ADD them instead — see the note in chunk_lpv_get_irradiance_at.js. The\n// constants are the same in all four; only these signs differ.\nvec3 shGetIrradianceAt( in vec3 normal, in vec3 shCoefficients[ 9 ] ) {\n    // normal is assumed to have unit length\n    float x = normal.x, y = normal.y, z = normal.z;\n\n    // band 0\n    vec3 result = shCoefficients[ 0 ] * 0.8862269254527579;\n\n    // band 1\n    result -= shCoefficients[ 1 ] * 1.0233267079464885 * y;\n    result += shCoefficients[ 2 ] * 1.0233267079464885 * z;\n    result -= shCoefficients[ 3 ] * 1.0233267079464885 * x;\n\n    // band 2\n    result += shCoefficients[ 4 ] * 0.8580855308097834 * x * y;\n    result -= shCoefficients[ 5 ] * 0.8580855308097834 * y * z;\n    result += shCoefficients[ 6 ] * ( 0.7431238683011272 * z * z - 0.24770795610037571 );\n    result -= shCoefficients[ 7 ] * 0.8580855308097834 * x * z;\n    result += shCoefficients[ 8 ] * 0.4290427654048917 * ( x * x - y * y );\n\n    return result;\n}\n\nuniform vec3 sh[ 9 ]; // sh coefficients\nuniform float intensity; // light probe intensity\nvarying vec3 vNormal;\n\nvoid main() {\n    vec3 normal = normalize( vNormal );\n    vec3 worldNormal = normalize(inverseTransformDirection( normal, viewMatrix ));\n    vec3 irradiance = shGetIrradianceAt( worldNormal, sh );\n    vec3 outgoingLight = 1.0  * irradiance * intensity;\n    gl_FragColor = linearToOutputTexel( vec4( outgoingLight, 1.0 ) );\n}\n";
-export default _default;
-//# sourceMappingURL=visualize.frag.d.ts.map

package/src/engine/graphics/sh3/shader/visualize.frag.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"visualize.frag.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/shader/visualize.frag.js"],"names":[],"mappings":""}

package/src/engine/graphics/sh3/shader/visualize.frag.js

@@ -1,51 +0,0 @@
-// language=GLSL
-export default `
-#define RECIPROCAL_PI 0.318309886
-
-vec3 inverseTransformDirection( in vec3 normal, in mat4 matrix ) {
-    // matrix is assumed to be orthogonal
-    return normalize( ( vec4( normal, 0.0 ) * matrix ).xyz );
-}
-
-// source: https://graphics.stanford.edu/papers/envmap/envmap.pdf
-//
-// SIGN CONVENTION: coefficients 1, 3, 5 and 7 are SUBTRACTED here, matching
-// three.js's SphericalHarmonics3 and the JS reference
-// core/geom/3d/sphere/harmonics/sh3_sample_irradiance_by_direction.js. The LPV
-// and LPG shader chunks (sh3/{gi,lpg}/material/chunk_*_get_irradiance_at.js)
-// ADD them instead — see the note in chunk_lpv_get_irradiance_at.js. The
-// constants are the same in all four; only these signs differ.
-vec3 shGetIrradianceAt( in vec3 normal, in vec3 shCoefficients[ 9 ] ) {
-    // normal is assumed to have unit length
-    float x = normal.x, y = normal.y, z = normal.z;
-
-    // band 0
-    vec3 result = shCoefficients[ 0 ] * 0.8862269254527579;
-
-    // band 1
-    result -= shCoefficients[ 1 ] * 1.0233267079464885 * y;
-    result += shCoefficients[ 2 ] * 1.0233267079464885 * z;
-    result -= shCoefficients[ 3 ] * 1.0233267079464885 * x;
-
-    // band 2
-    result += shCoefficients[ 4 ] * 0.8580855308097834 * x * y;
-    result -= shCoefficients[ 5 ] * 0.8580855308097834 * y * z;
-    result += shCoefficients[ 6 ] * ( 0.7431238683011272 * z * z - 0.24770795610037571 );
-    result -= shCoefficients[ 7 ] * 0.8580855308097834 * x * z;
-    result += shCoefficients[ 8 ] * 0.4290427654048917 * ( x * x - y * y );
-
-    return result;
-}
-
-uniform vec3 sh[ 9 ]; // sh coefficients
-uniform float intensity; // light probe intensity
-varying vec3 vNormal;
-
-void main() {
-    vec3 normal = normalize( vNormal );
-    vec3 worldNormal = normalize(inverseTransformDirection( normal, viewMatrix ));
-    vec3 irradiance = shGetIrradianceAt( worldNormal, sh );
-    vec3 outgoingLight = 1.0  * irradiance * intensity;
-    gl_FragColor = linearToOutputTexel( vec4( outgoingLight, 1.0 ) );
-}
-`

package/src/engine/graphics/sh3/shader/visualize.vert.d.ts

@@ -1,3 +0,0 @@
-declare const _default: "\nvarying vec3 vNormal;\n\nvoid main() {\n\n    vNormal = normalize( normalMatrix * normal );\n\n    gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );\n\n}\n";
-export default _default;
-//# sourceMappingURL=visualize.vert.d.ts.map

package/src/engine/graphics/sh3/shader/visualize.vert.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"visualize.vert.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/shader/visualize.vert.js"],"names":[],"mappings":""}

package/src/engine/graphics/sh3/shader/visualize.vert.js

@@ -1,12 +0,0 @@
-// language=GLSL
-export default `
-varying vec3 vNormal;
-
-void main() {
-
-    vNormal = normalize( normalMatrix * normal );
-
-    gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
-
-}
-`