@woosh/meep-engine 3.5.0 → 3.7.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.7.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/graphics3/GraphicsEngine3.d.ts

@@ -6,17 +6,22 @@
  * start(), stop(), render(), updateSize()}` — because that is what `Engine` needs in order to boot,
  * and because the facade is deliberately not allowed to grow past §4.2 (D14).
  *
- * **Two things have been let through since, each by name.** {@link add_extension} /
+ * **Three things have been let through since, each by name.** {@link add_extension} /
  * {@link remove_extension} (E9), because an extension has to survive the restart that replaces the
  * renderer holding it, and
  * {@link scene_context} (E13, D29), because the managers a system needs — animation above all —
  * hang off Shade's per-scene GPU state and there is no other door to them. Both take or return
  * something the caller already owns; neither hands out the renderer.
  *
- * What is deliberately absent, and stays absent: `renderer` / `getRenderer()` (44 callers on the
- * old engine, each of them a migration item rather than a reason to re-open the hatch), `layers`
- * (CPU visibility dies with GPU culling), `scene` (entities reach the scene through the mesh
- * system, not through the facade), and the three-shaped material manager.
+ * {@link renderer} is the third, and much the widest: it hands the renderer straight out, so
+ * everything the other two are shaped to avoid is reachable through it. It is an escape hatch for
+ * callers that have no other route, not a migration target — the old engine's 44
+ * `.renderer`/`getRenderer()` call sites are each still a migration item.
+ *
+ * What is deliberately absent, and stays absent: `getRenderer()` (the old engine's accessor, and
+ * the shape those call sites are being ported off), `layers` (CPU visibility dies with GPU
+ * culling), `scene` (entities reach the scene through the mesh system, not through the facade),
+ * and the three-shaped material manager.
  *
  * **Lifecycle differs from the old engine on purpose.** `GraphicsEngine` starts inside the `Engine`
  * constructor, which is why stopping an engine used to leave a restarted one with no renderer at

package/src/engine/graphics3/GraphicsEngine3.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphicsEngine3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine3.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IA0DG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAED;;OAEG;IACH,YAFU,OAAO,CAEe;IAEhC;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iDAOC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,2DAWC;IAED;;;;;;;;;;OAUG;IACH,oCAFa,MAAM,CAclB;IAED;;;;;;OAMG;IACH,8CAFa,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,kBAAgB,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,yBAEL,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CA4DzB;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,UAAQ,UACf,OAAO,UAAQ,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,6CAMhB;IAED;;;;;;;OAOG;IACH,mBA0BC;IAED;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,OAAO,CAoDnB;;CACJ;yBAxwBwB,kCAAkC;mCAMxB,yBAAyB;mBAbzC,oCAAoC;oBACnC,4BAA4B;wBACxB,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}
+{"version":3,"file":"GraphicsEngine3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GraphicsEngine3.js"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IACI;;;;;OAKG;IACH,gCAEC;IAUD;;;;OAIG;IACH,yBAEC;IA0DG;;;;;;OAMG;IACH,QAFU,kBAAkB,CAEsB;IAElD;QACI;;;;;;;;WAQG;mBADO,MAAM;QAIhB;;;;;WAKG;oBADO,MAAM;QAIhB;;;;WAIG;qBADO,MAAM;QAIhB;;;;;;;WAOG;;QAGH;;;;;WAKG;;MAEN;IAED;;OAEG;IACH,YAFU,OAAO,CAEe;IAEhC;;;;;OAKG;IACH,4BAFU,OAAO,CAEyB;IAE1C;;;;;;OAMG;IACH,UAFU,SAAS,CAEY;IAG/B;;OAEG;IACH,YAFU,iBAAiB,GAAC,IAAI,CAEV;IAEtB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;;;;OAKG;IACH,UAFU,OAAO,CAEG;IAEpB;;OAEG;IACH,YAFU,MAAM,CAEG;IAoBvB;;;;;;;;;;;;OAYG;IACH,mDAEC;IAED;;;;;;;;OAQG;IACH,iBAFW,KAAK,QAoBf;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iDAOC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,2DAWC;IAED;;;;;;;;;;OAUG;IACH,oCAFa,MAAM,CAclB;IAED;;;;;;OAMG;IACH,8CAFa,OAAO,CAgBnB;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBALW,KAAK,GACH,kBAAgB,IAAI,CAehC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,yBARW,KAAK,yBAEL,MAAM,UACN,MAAM,GACJ,QAAQ,SAAS,CAAC,CAwD9B;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;;;;;;;OAUG;IACH,SAFa,QAAQ,IAAI,CAAC,CA4DzB;IAED;;;;;OAKG;IACH,aAiBC;IASD;;;;;;;;OAQG;IACH,8BAHW,OAAO,UAAQ,UACf,OAAO,UAAQ,QAQzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,yBALW,MAAM,KACN,MAAM,6CAMhB;IAED;;;;;;;OAOG;IACH,mBA0BC;IAED;;;;;OAKG;IACH,4BAHW,MAAM,GACJ,OAAO,CAoDnB;;CACJ;yBA7wBwB,kCAAkC;mCAMxB,yBAAyB;mBAbzC,oCAAoC;oBACnC,4BAA4B;wBACxB,4BAA4B;sBAQ9B,kCAAkC;yCAJf,kDAAkD;sBAErE,qCAAqC;0BACjC,0CAA0C"}

package/src/engine/graphics3/GraphicsEngine3.js

@@ -56,17 +56,22 @@ const TARGET_FRAME_RATE = 30;
  * start(), stop(), render(), updateSize()}` — because that is what `Engine` needs in order to boot,
  * and because the facade is deliberately not allowed to grow past §4.2 (D14).
  *
- * **Two things have been let through since, each by name.** {@link add_extension} /
+ * **Three things have been let through since, each by name.** {@link add_extension} /
  * {@link remove_extension} (E9), because an extension has to survive the restart that replaces the
  * renderer holding it, and
  * {@link scene_context} (E13, D29), because the managers a system needs — animation above all —
  * hang off Shade's per-scene GPU state and there is no other door to them. Both take or return
  * something the caller already owns; neither hands out the renderer.
  *
- * What is deliberately absent, and stays absent: `renderer` / `getRenderer()` (44 callers on the
- * old engine, each of them a migration item rather than a reason to re-open the hatch), `layers`
- * (CPU visibility dies with GPU culling), `scene` (entities reach the scene through the mesh
- * system, not through the facade), and the three-shaped material manager.
+ * {@link renderer} is the third, and much the widest: it hands the renderer straight out, so
+ * everything the other two are shaped to avoid is reachable through it. It is an escape hatch for
+ * callers that have no other route, not a migration target — the old engine's 44
+ * `.renderer`/`getRenderer()` call sites are each still a migration item.
+ *
+ * What is deliberately absent, and stays absent: `getRenderer()` (the old engine's accessor, and
+ * the shape those call sites are being ported off), `layers` (CPU visibility dies with GPU
+ * culling), `scene` (entities reach the scene through the mesh system, not through the facade),
+ * and the three-shaped material manager.
  *
  * **Lifecycle differs from the old engine on purpose.** `GraphicsEngine` starts inside the `Engine`
  * constructor, which is why stopping an engine used to leave a restarted one with no renderer at

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/engine/physics/queries/shape_cast.d.ts

@@ -30,10 +30,12 @@
  *     refinement which the broadphase-only architecture doesn't have
  *     wired up yet.
  *   - `result.normal` — target surface's outward normal at the kiss
- *     point (unit length), computed by running GJK + EPA against the
- *     just-overlapping configuration at the TOI. Falls back to
- *     `-ray.direction` on the rare case EPA degenerates (NaN / zero
- *     depth) — see comment near the EPA call.
+ *     point (unit length), recovered by running MPR against the
+ *     just-overlapping configuration at the TOI. A pair that is exactly
+ *     tangent there carries no MTV to read, so a second probe nudged
+ *     toward the target's centre supplies one; `-ray.direction` remains
+ *     the last-resort fallback if both degenerate. See the
+ *     contact-normal recovery block near the end of the function.
  *   - `result.entity` / `result.body_id` — the hit body.
  *
  * Output on miss: untouched; same convention as `raycast`.
@@ -52,12 +54,15 @@
  *   distinguishes bodies when colliders live on child entities)
  * @param {boolean} [skip_initial_overlaps=false] how a candidate ALREADY
  *   overlapping the swept shape at `t = 0` is treated. `false` (kinematic
- *   "can I move?" semantics): the cast is blocked where it stands — report a
- *   hit at `t = 0`. `true` (CCD semantics): such a candidate is a resting /
- *   sliding contact the discrete solver already owns, NOT a tunnelling
- *   threat — skip it and keep scanning the remaining candidates for real
- *   blockers along the sweep. Without the skip, one resting contact at the
- *   start of the sweep would blind the cast to every other obstacle.
+ *   "can I move?" semantics): targets are solid, so the cast is blocked where
+ *   it stands — report a hit at `t = 0`. The one exception is a convex target
+ *   the shape merely TOUCHES (no depth beyond {@link CONTACT_EPSILON}): a
+ *   tangency blocks only a sweep driving into it, and otherwise steps aside so
+ *   the scan can reach real blockers. `true` (CCD semantics): such a candidate
+ *   is a resting / sliding contact the discrete solver already owns, NOT a
+ *   tunnelling threat — skip it and keep scanning the remaining candidates for
+ *   real blockers along the sweep. Either way, one contact at the start of the
+ *   sweep must never blind the cast to every other obstacle.
  * @returns {boolean}
  */
 export function shape_cast(system: PhysicsSystem, ray: any, shape: AbstractShape3D, rotation: {

package/src/engine/physics/queries/shape_cast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape_cast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/shape_cast.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,8FAhBW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iDAE7B,MAAM,+BAA6B,MAAM,KAAG,OAAO,0BAI3D,OAAO,GAQL,OAAO,CA2RnB"}
+{"version":3,"file":"shape_cast.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/queries/shape_cast.js"],"names":[],"mappings":"AAoPA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,8FAnBW;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,iDAE7B,MAAM,+BAA6B,MAAM,KAAG,OAAO,0BAI3D,OAAO,GAWL,OAAO,CAsTnB"}