@woosh/meep-engine 3.4.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.4.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/Engine.js

@@ -10,7 +10,7 @@ import ObservedBoolean from "../core/model/ObservedBoolean.js";
 import ConcurrentExecutor from '../core/process/executor/ConcurrentExecutor.js';
 import EmptyView from "../view/elements/EmptyView.js";
 import { ViewStack } from "../view/elements/navigation/ViewStack.js";
-import { WebGLContextFailureView } from "../view/graphics/WebGLContextFailureView.js";
+import { GraphicsContextFailureView } from "../view/graphics/GraphicsContextFailureView.js";
 
 import { AssetManager } from './asset/AssetManager.js';
 import { AssetPreloader } from "./asset/preloader/AssetPreloader.js";
@@ -416,7 +416,7 @@ class Engine {
         // Application state is left intact, which keeps a save-on-failure handler viable.
         this.#pause_simulation_for_context_loss();
 
-        this.viewStack.addChild(new WebGLContextFailureView());
+        this.viewStack.addChild(new GraphicsContextFailureView());
     }
 
     #initialize_audio() {

package/src/engine/graphics/CONTEXT_LOSS_RECOVERY_PLAN.md

@@ -203,7 +203,7 @@ already paused is left alone, and never resumed by us — hence the new `Ticker.
 accessors, since `pause()`/`resume()` throw when the loop is not cycling.
 
 On `Failed`: the simulation is paused, application state is left intact (so a save-on-failure handler
-stays viable), and `WebGLContextFailureView` explains the situation with a reload button, instead of
+stays viable), and `GraphicsContextFailureView` explains the situation with a reload button, instead of
 leaving the player looking at a black canvas.
 
 ---

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

@@ -31,6 +31,12 @@ export class GraphicsEngine3 {
      * @returns {boolean}
      */
     get isGraphicsEngine(): boolean;
+    /**
+     * Danger zone.
+     * Be careful with what you do, with great Renderer comes great responsibility.
+     * @returns {Renderer|null}
+     */
+    get renderer(): Renderer;
     /**
      * The camera, in the shape the engine's existing consumers read it — `projectionMatrix` and
      * `matrixWorldInverse`, which is what `HeadsUpDisplaySystem` multiplies together. The real
@@ -317,6 +323,7 @@ export class GraphicsEngine3 {
     render(time_delta_seconds?: number): boolean;
     #private;
 }
+import { Renderer } from "../../shade/renderer/Renderer.js";
 import { ShadeCameraAdapter } from "./ShadeCameraAdapter.js";
 import Signal from "../../core/events/signal/Signal.js";
 import Vector1 from "../../core/geom/Vector1.js";

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;IAkEG;;;;;;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;mCAzvBkC,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;;;;;;;;;;;;;;;;;;;;;;;;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"}

package/src/engine/graphics3/GraphicsEngine3.js

@@ -92,6 +92,15 @@ export class GraphicsEngine3 {
      */
     #renderer = null;
 
+    /**
+     * Danger zone.
+     * Be careful with what you do, with great Renderer comes great responsibility.
+     * @returns {Renderer|null}
+     */
+    get renderer(){
+        return this.#renderer;
+    }
+
     /**
      * Trades internal resolution for frame time — see {@link dynamic_resolution}.
      *

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#350@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#349@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#350@#clear_field"(fluid: FluidComponent): void;
+    static "__#349@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#350@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#349@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#350@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#349@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

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/playground/skinned_blas_refit/README.md

@@ -68,36 +68,59 @@ union, and each clone at its own arena address on a uniform stride.
 ## Assets
 
 `/test_assets/Michelle.glb`, which is gitignored and unpublished — see `test_assets/README.md`.
-
-## What the floor disagreement turned out to be
-
-For a while the two images disagreed about where the floor ends: a smooth band along its far edge
-that the rasterizer drew and the tracer did not, several thousand pixels at an ordinary camera and
-growing as the camera approached the edge. It read like a hole in a tree, and it was not one.
-
-The slab was placed by writing `Node3D.transform_global`, which is **derived** — the doc comment on
-it says so. Its two consumers take placement from opposite ends: `Mesh.updateBoundsBasic` reads
-`transform_global` and publishes the result as the mesh's `meshes` row, and the GPU's `transforms`
-row carries the node's *local* TRS for the hierarchy pass to compose `node.global` from. Writing
-only the first left the second at identity, 0.208 m away:
-
-- the rasterizer multiplied positions by `node.global` and drew the slab at the geometry's own
-  origin, its far edge ten rows higher up the screen than the floor actually ends;
-- the tracer tested each ray against the *translated* published box before traversing the
-  *untranslated* geometry, so rays that would have struck the slab near its far edge were turned
-  away by a box that was not around it.
-
-Neither renderer was wrong about the data it was given. Padding the published box shrank the band
-because it widened the interval the TLAS test allows — not because anything was tangent, which is
-why a few per cent of pad did what a rounding-scale slack could not.
-
-The invariant is in `add_floor.spec.js` and needs no device: published bounds must survive
-`updateMatrices`, because that is the walk which recomputes `transform_global` from the local
-transform. `chunk_ray_query_nearest.spec.js` holds the traversal itself against closed-form slab
-arithmetic in the emulator, including the case where the instance box and the node transform
-disagree.
-
-**`?count=N` still places its dancers the old way**, so they stack at the origin rather than
-spreading over a grid. That one is self-consistent — box and transform both say "at the origin" —
-so the two renderers agree about it, and unpicking it means separating the grid offset from the
-transform the glTF gave the mesh node.
+
+## What the floor disagreement turned out to be
+
+For a while the two images disagreed about where the floor ends: a smooth band along its far edge
+that the rasterizer drew and the tracer did not, several thousand pixels at an ordinary camera and
+growing as the camera approached the edge. It read like a hole in a tree, and it was not one.
+
+The slab was placed by writing `Node3D.transform_global`, which is **derived** — the doc comment on
+it says so. Its two consumers take placement from opposite ends: `Mesh.updateBoundsBasic` reads
+`transform_global` and publishes the result as the mesh's `meshes` row, and the GPU's `transforms`
+row carries the node's *local* TRS for the hierarchy pass to compose `node.global` from. Writing
+only the first left the second at identity, 0.208 m away:
+
+- the rasterizer multiplied positions by `node.global` and drew the slab at the geometry's own
+  origin, its far edge ten rows higher up the screen than the floor actually ends;
+- the tracer tested each ray against the *translated* published box before traversing the
+  *untranslated* geometry, so rays that would have struck the slab near its far edge were turned
+  away by a box that was not around it.
+
+Neither renderer was wrong about the data it was given. Padding the published box shrank the band
+because it widened the interval the TLAS test allows — not because anything was tangent, which is
+why a few per cent of pad did what a rounding-scale slack could not.
+
+The invariant is in `add_floor.spec.js` and needs no device: published bounds must survive
+`updateMatrices`, because that is the walk which recomputes `transform_global` from the local
+transform. `chunk_ray_query_nearest.spec.js` holds the traversal itself against closed-form slab
+arithmetic in the emulator, including the case where the instance box and the node transform
+disagree.
+
+## The quieter version of the same bug: `?count=N`
+
+The dancers were placed the same way — by writing `transform_global` — and stacked at the origin
+rather than spreading over a grid. Both renderers agreed about it, so there was no picture to look
+at; the only symptom was that the characters did not go where they were put.
+
+They also could not have been fixed by copying the floor's fix, because a skinned mesh's own node
+is not its placement point at all. A skinned vertex lands at
+
+```
+mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v
+```
+
+— `chunk_skin_blend_mesh_local` folds the leftmost inverse into each joint matrix and the rasterizer
+re-applies `mesh.global`, so the mesh node's transform **cancels exactly**, and
+`compute_skin_world_bounds` composes the published box out of joints without reading it either.
+Michelle's file makes the point structurally: her mesh node `Ch03` carries no local transform, the
+0.01 centimetre scale and the up-axis rotation sit on the root above it, and the joint root
+`mixamorig:Hips` is the mesh node's *sibling*. Nothing under `Ch03` drives a joint.
+
+`place_character` therefore hangs each character's roots under a fresh parent whose whole transform
+is the grid offset. That reaches the joints, leaves the file's own transform untouched below it, and
+— because the offset is a *local* transform — survives the walk that recomputes `transform_global`.
+
+`place_character.spec.js` holds the invariant the floor's cannot see: **published bounds must move
+by the offset the character was placed at.** Its negative control is the bug itself — writing either
+transform on the mesh node and watching the box not move.

package/src/shade/playground/skinned_blas_refit/place_character.d.ts

@@ -19,7 +19,8 @@
  * actually sit under.
  *
  * Michelle is the shape that makes this concrete. Her file is one root carrying the centimetre
- * scale and the Z-up rotation, with the mesh node and the joint root as *siblings* beneath it:
+ * scale and the up-axis rotation (+90° about x, the file's Z-up into the renderer's Y-up), with the
+ * mesh node and the joint root as *siblings* beneath it:
  *
  * ```
  * "Character"            R=(0.70711, 0, 0, 0.70711)  S=(0.01, 0.01, 0.01)