@woosh/meep-engine 3.38.0 → 3.40.0

package/src/core/geom/3d/shape/HeightMapShape3D.js

@@ -14,13 +14,160 @@ import { AbstractShape3D } from "./AbstractShape3D.js";
 
 /**
  * Below this, a ray's footprint-plane velocity component counts as zero in
- * {@link HeightMapShape3D#raycast}'s slab clip — the reciprocal a smaller value
- * would produce is not a usable slab distance. Matches the concave narrowphase's
- * `refine_ray_concave`, so the two agree on rays that graze the footprint edge.
+ * {@link HeightMapShape3D#raycast}'s slab clip, and the ray is held to its
+ * origin's slab on that axis — the reciprocal a smaller value would produce is
+ * not a usable slab distance. This method's own rule, not the physics ray
+ * query's: `refine_ray_concave` holds only an axis the ray does not move along at
+ * all and divides by any other component, however small. So the two can differ
+ * on a ray that drifts across the footprint's edge at under this rate: one
+ * starting 1e-14 outside it and drifting in at 1e-12 misses here and hits there.
  * @type {number}
  */
 const RAY_SLAB_EPSILON = 1e-12;
 
+/**
+ * How far outside the range of the samples it is drawn through the Catmull-Rom surface can stand, as a
+ * fraction of that range. Along one axis the cubic's two negative weights sum to −t(1 − t)/2, at most
+ * 1/8 in size (t = 1/2), so its positive ones to at most 9/8; the 2-D filter is the product of two such
+ * weight sets, whose positive products sum to at most (9/8)² + (1/8)² = 41/32 — and a value is at most
+ * `max + (41/32 − 1)·(max − min)`, at least `min − 9/32·(max − min)`. Sampler2D's nine-tap form of the
+ * filter, clamped at the edges, takes the same weights over values of the same samples.
+ *
+ * A ridge two samples wide rises an eighth of its height above them, and a checkerboard 0.159 of it
+ * (where the edge clamps it); a ring — each 4 × 4 block's corners and middle 2 × 2 high, the rest of
+ * its rim low — reaches the bound at the block's centre.
+ * @type {number}
+ */
+const CATMULL_ROM_OVERSHOOT = 9 / 32;
+
+/**
+ * Lowest and highest the surface can stand, as the range functions below leave them: [lo, hi], lo > hi
+ * when there is no finite sample.
+ * @type {Float64Array}
+ */
+const height_range = new Float64Array(2);
+
+/**
+ * The 4-wide row maxima and minima of the last four sample rows, for {@link height_range_by_window}.
+ * Grown with the widest sampler seen.
+ * @type {Float64Array}
+ */
+let window_row_hi = new Float64Array(4 * 64);
+let window_row_lo = new Float64Array(4 * 64);
+
+/**
+ * {@link height_range} over `count` samples taken together: their finite range, widened by
+ * {@link CATMULL_ROM_OVERSHOOT} of it. For a sampler narrower than the filter's 4 × 4 window, whose
+ * every value may draw on every sample.
+ *
+ * @param {ArrayLike<number>} data
+ * @param {number} count
+ * @param {number} item_size
+ */
+function height_range_whole(data, count, item_size) {
+    let lo = Infinity;
+    let hi = -Infinity;
+
+    const end = count * item_size;
+
+    for (let i = 0; i < end; i += item_size) {
+        const v = data[i];
+
+        // finite samples only: an infinite one made an infinite range, and 0 × Infinity on the axes
+        // the orientation does not touch made the box NaN, which no body overlaps
+        if (v - v !== 0) continue;
+
+        if (v < lo) lo = v;
+        if (v > hi) hi = v;
+    }
+
+    const overshoot = hi >= lo ? (hi - lo) * CATMULL_ROM_OVERSHOOT : 0;
+
+    height_range[0] = lo - overshoot;
+    height_range[1] = hi + overshoot;
+}
+
+/**
+ * {@link height_range} window by window: every value of the surface is a combination of one 4 × 4 window
+ * of samples (edge-clamped windows repeat samples of a window inside), so it stands within
+ * {@link CATMULL_ROM_OVERSHOOT} of that window's own range outside it. The surface's range is the widest
+ * of those over every window — on a smooth terrain barely past its samples, where the whole samples'
+ * range would have put a band 28 % of the terrain's height above and below it. Finite samples only.
+ *
+ * One pass: each row's 4-wide maxima and minima, kept for the last four rows, then combined down the
+ * columns.
+ *
+ * @param {ArrayLike<number>} data
+ * @param {number} width at least 4
+ * @param {number} height at least 4
+ * @param {number} item_size
+ */
+function height_range_by_window(data, width, height, item_size) {
+    const windows = width - 3;
+
+    if (window_row_hi.length < 4 * windows) {
+        window_row_hi = new Float64Array(4 * windows);
+        window_row_lo = new Float64Array(4 * windows);
+    }
+
+    const row_hi = window_row_hi;
+    const row_lo = window_row_lo;
+
+    let lo = Infinity;
+    let hi = -Infinity;
+
+    for (let j = 0; j < height; j++) {
+        const ring = (j & 3) * windows;
+        const row = j * width;
+
+        for (let i = 0; i < windows; i++) {
+            let w_lo = Infinity;
+            let w_hi = -Infinity;
+
+            for (let q = 0; q < 4; q++) {
+                const v = data[(row + i + q) * item_size];
+
+                if (v - v !== 0) continue;
+
+                if (v < w_lo) w_lo = v;
+                if (v > w_hi) w_hi = v;
+            }
+
+            row_lo[ring + i] = w_lo;
+            row_hi[ring + i] = w_hi;
+        }
+
+        if (j < 3) {
+            continue;
+        }
+
+        for (let i = 0; i < windows; i++) {
+            let w_lo = row_lo[i];
+            let w_hi = row_hi[i];
+
+            for (let r = 1; r < 4; r++) {
+                const k = r * windows + i;
+
+                if (row_lo[k] < w_lo) w_lo = row_lo[k];
+                if (row_hi[k] > w_hi) w_hi = row_hi[k];
+            }
+
+            if (w_lo > w_hi) {
+                // no finite sample in this window
+                continue;
+            }
+
+            const overshoot = (w_hi - w_lo) * CATMULL_ROM_OVERSHOOT;
+
+            if (w_lo - overshoot < lo) lo = w_lo - overshoot;
+            if (w_hi + overshoot > hi) hi = w_hi + overshoot;
+        }
+    }
+
+    height_range[0] = lo;
+    height_range[1] = hi;
+}
+
 /**
  * Heightmap shape, intended primarily for terrain.
  *
@@ -48,8 +195,16 @@ const RAY_SLAB_EPSILON = 1e-12;
  *     `sampler.sampleChannelCatmullRomUV(u01, v01, 0)`.
  *   - The solid volume occupies `h ∈ [0, sampledHeight(u01, v01)]` along the
  *     orientation axis, with `0` being the floor at body-local origin.
- *   - `size.y` is the maximum height value of the heightfield (used for the
- *     bounding box). Sampler values are NOT clamped to it.
+ *   - `size.y` is the maximum height value of the heightfield. Sampler values
+ *     are NOT clamped to it; the bounding box takes in whatever the samples, and
+ *     the cubic between them, reach beyond [0, size.y] (see
+ *     {@link compute_bounding_box}).
+ *   - Editing the samples of a collider already attached to a physics body: the
+ *     box follows the sampler's version, but a static body's broadphase leaf is
+ *     set when the collider is attached and never refit. An edit that raises the
+ *     surface past the box it was attached with stays out of sight until the
+ *     collider is detached and attached again — a ball dropped onto a field raised
+ *     from 1 m to 3 m fell through it; re-attached, the field held it.
  *
  * NON-CONVEX. {@link support} throws — GJK/EPA cannot be run against a
  * heightmap directly. The physics narrowphase must dispatch a dedicated
@@ -118,6 +273,28 @@ export class HeightMapShape3D extends AbstractShape3D {
     _basis_orientation_y = NaN;
     _basis_orientation_z = NaN;
 
+    /**
+     * Lowest and highest the surface can stand, along {@link orientation}: each 4 × 4 window of the
+     * sampler's finite channel-0 values widened by the Catmull-Rom overshoot ({@link CATMULL_ROM_OVERSHOOT})
+     * of its own range, the widest of those ({@link height_range_by_window}). Updated
+     * lazily by {@link _ensure_height_range}, keyed on the sampler, its data array, its version and its
+     * dimensions — so a write straight into `sampler.data` must bump `sampler.version`, as every other
+     * reader of a sampler's version expects. That moves this box; it does not move a static body's
+     * broadphase leaf, which only re-attaching the collider does (see the class notes).
+     * @private
+     * @type {number}
+     */
+    _height_lo = 0;
+    _height_hi = 0;
+
+    // what the height range was taken from
+    _height_range_sampler = null;
+    _height_range_data = null;
+    _height_range_version = -1;
+    _height_range_width = -1;
+    _height_range_height = -1;
+    _height_range_item_size = -1;
+
     /**
      * Convenience constructor.
      * @param {Sampler2D} sampler
@@ -244,8 +421,18 @@ export class HeightMapShape3D extends AbstractShape3D {
         return this.sample_height_at_uv(u01, v01);
     }
 
+    /**
+     * The box holds the solid from its floor (h = 0) to `size.y`, and the surface wherever it stands
+     * outside that: the Catmull-Rom cubic overshoots the samples it is drawn through, so a ridge whose
+     * every sample is within `size.y` still rises above it (an eighth of its height for a ridge two
+     * samples wide). A box short of the surface hid it from the broadphase and from the compound
+     * narrowphase's box test: a ball on such a ridge sank and bobbed.
+     *
+     * @param {number[]|Float64Array} result
+     */
     compute_bounding_box(result) {
         this._ensure_basis();
+        this._ensure_height_range();
 
         const b = this._basis;
 
@@ -256,11 +443,14 @@ export class HeightMapShape3D extends AbstractShape3D {
         const half_u = sx * 0.5;
         const half_v = sz * 0.5;
 
+        const h_lo = this._height_lo < 0 ? this._height_lo : 0;
+        const h_hi = this._height_hi > sy ? this._height_hi : sy;
+
         // For each body axis k (0=x, 1=y, 2=z):
         //   body[k] = b[0+k]*u + b[3+k]*v + b[6+k]*h
         //
         // The (u,v) footprint contribution is symmetric (u ∈ [-half_u, +half_u], v ∈ [-half_v, +half_v])
-        // The height contribution is asymmetric (h ∈ [0, sy])
+        // The height contribution is asymmetric (h ∈ [h_lo, h_hi])
         for (let k = 0; k < 3; k++) {
             const cu = b[k];
             const cv = b[3 + k];
@@ -268,13 +458,69 @@ export class HeightMapShape3D extends AbstractShape3D {
 
             const uv_extent = Math.abs(cu) * half_u + Math.abs(cv) * half_v;
 
-            const h_extent = ch * sy;
+            const h_extent_lo = ch * h_lo;
+            const h_extent_hi = ch * h_hi;
 
-            result[k] = -uv_extent + Math.min(h_extent, 0);
-            result[k + 3] = uv_extent + Math.max(h_extent, 0);
+            result[k] = -uv_extent + Math.min(h_extent_lo, h_extent_hi);
+            result[k + 3] = uv_extent + Math.max(h_extent_lo, h_extent_hi);
         }
     }
 
+    /**
+     * Bring {@link _height_lo} / {@link _height_hi} up to date with the sampler: one pass over its
+     * channel-0 values when the sampler, its data array, its version or its dimensions changed since the
+     * last (3 ms for 513 × 513 samples, 12-16 ms for 1025 × 1025).
+     * @private
+     */
+    _ensure_height_range() {
+        const sampler = this.sampler;
+
+        if (sampler === null) {
+            this._height_lo = 0;
+            this._height_hi = 0;
+            this._height_range_sampler = null;
+            return;
+        }
+
+        const data = sampler.data;
+        const width = sampler.width;
+        const height = sampler.height;
+        const item_size = sampler.itemSize;
+
+        if (
+            sampler === this._height_range_sampler
+            && data === this._height_range_data
+            && sampler.version === this._height_range_version
+            && width === this._height_range_width
+            && height === this._height_range_height
+            && item_size === this._height_range_item_size
+        ) {
+            return;
+        }
+
+        if (width < 4 || height < 4) {
+            height_range_whole(data, width * height, item_size);
+        } else {
+            height_range_by_window(data, width, height, item_size);
+        }
+
+        if (height_range[0] > height_range[1]) {
+            // no finite samples: no surface beyond the solid's own range
+            this._height_lo = 0;
+            this._height_hi = 0;
+        } else {
+            this._height_lo = height_range[0];
+            this._height_hi = height_range[1];
+        }
+
+        this._height_range_sampler = sampler;
+        this._height_range_data = data;
+        this._height_range_version = sampler.version;
+        this._height_range_width = width;
+        this._height_range_height = height;
+        this._height_range_item_size = item_size;
+    }
+
     contains_point(point) {
         const px = point[0];
         const py = point[1];
@@ -378,7 +624,7 @@ export class HeightMapShape3D extends AbstractShape3D {
      * This throws rather than returning a degenerate result so the call
      * site is forced to handle heightmaps explicitly.
      */
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
         throw new Error("HeightMapShape3D.support: heightmaps are non-convex; the narrowphase must dispatch grid-traversal instead.");
     }
 
@@ -423,10 +669,10 @@ export class HeightMapShape3D extends AbstractShape3D {
      * Measure-zero, and called out because it is the only place the two answers
      * part company.
      *
-     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
-     * the class docstring), so clipping the ray to the height range that
-     * {@link compute_bounding_box} reports could reject real surface standing above
-     * it; only the footprint is clipped against.
+     * `size.y` does NOT bound the query: sampler values are not clamped to it, and
+     * the cubic overshoots them. Only the footprint is clipped against — the
+     * height range {@link compute_bounding_box} reports follows the samples only as
+     * far as the sampler's version does.
      *
      * ## Cost
      *

package/src/core/geom/3d/shape/MeshShape3D.d.ts

@@ -24,6 +24,12 @@
  * MeshShape3D()` directly — the factory compacts the tet mesh, builds
  * the BVH, and caches the bbox / volume / surface area.
  *
+ * A third structure, a BVH over the surface triangles, is built lazily the
+ * first time a body or a ray comes near the mesh (contacts and raycasts walk
+ * it instead of every triangle). It costs 80 bytes per triangle and 25–40 ms
+ * per 100k triangles to build, in the step that first needs it; call
+ * {@link get_surface_bvh} at load time to pay that up front.
+ *
  * Narrowphase routing:
  *   - GJK + EPA for the general case, using {@link support}.
  *   - The support function currently returns the deepest tet-mesh
@@ -101,14 +107,63 @@ export class MeshShape3D extends AbstractShape3D {
      */
     private __surface_area;
     /**
-     * Lazily-built surface-triangle BVH for {@link raycast} (distinct from {@link tet_bvh}, which
-     * keys the interior tets). Built on the first ray query from `positions` / `indices`; null until
-     * then. Mutating the surface invalidates it (set back to null to rebuild).
+     * Lazily-built surface-triangle BVH, see {@link get_surface_bvh} (distinct from
+     * {@link tet_bvh}, which keys the interior tets). Null until first asked for; mutating the
+     * surface invalidates it ({@link recompute_cached} sets it back to null).
      * @private
      * @type {BVH|null}
      */
     private __raycast_blas;
+    /**
+     * Lazily-computed per-triangle edge and corner classes, see {@link get_triangle_edge_flags}.
+     * Null until first asked for; {@link recompute_cached} sets it back to null.
+     * @private
+     * @type {Uint16Array|null}
+     */
+    private __triangle_edge_flags;
     compute_bounding_box(result: any): void;
+    /**
+     * BVH over the surface triangles: one leaf per triangle, whose user data is the triangle's
+     * index into {@link indices} (triangle `t` is `indices[3t .. 3t + 2]`) and whose box is the
+     * triangle's tight bounds. Node boxes are float32, so they are exact for float32
+     * {@link positions} and may round inward by up to half a float32 ULP for float64 ones;
+     * the walks over it widen their queries to match. Float64 positions past float32's range
+     * (±3.4e38) overflow their boxes to ±Infinity; the narrowphase's triangle enumeration and
+     * the physics raycast's walk reach to infinity for them.
+     *
+     * Shared by {@link raycast}, the physics narrowphase's triangle enumeration and the physics
+     * raycast, so every mesh a body or a ray comes near builds one. {@link recompute_cached}
+     * drops it, so it is rebuilt against a mutated surface.
+     *
+     * ## Cost
+     *
+     * - Memory: 80 bytes per triangle (two 40-byte nodes per triangle), kept for the shape's
+     *   life — 16 MB for a 200k-triangle floor, over four times its own 3.6 MB of positions and
+     *   indices.
+     * - Time: built lazily, by the first caller — a Morton build of 25–40 ms per 100k triangles
+     *   (measured 30–57 ms for 100k and 45–65 ms for 200k; a first step of 105 ms against a
+     *   23 ms one on a busy machine), paid inside whatever physics step first brings a body or a
+     *   ray to the mesh. Call this once while loading the mesh to move that hitch out of the
+     *   simulation.
+     *
+     * @returns {BVH}
+     */
+    get_surface_bvh(): BVH;
+    /**
+     * How each surface triangle meets its neighbours: one {@link TriangleEdgeFlags} word per triangle
+     * of {@link indices}, marking which of its edges are FLAT (the neighbour lies in its plane — an
+     * edge of the triangulation, not of the surface) and which CONCAVE, the rest being real convex
+     * edges, the rim included; and which of its corners are FLAT, met by no real edge. Neighbours
+     * are matched by vertex position, so a buffer that splits vertices for normals or UVs still has
+     * them. See {@link mesh_compute_triangle_edge_flags}.
+     *
+     * Cooked by {@link shape3_mesh_from_geometry}; otherwise computed on first use. Linear in the
+     * triangles, and cached on the shape; {@link recompute_cached} drops it, so it is recomputed for a
+     * mutated surface.
+     *
+     * @returns {Uint16Array}
+     */
+    get_triangle_edge_flags(): Uint16Array;
     /**
      * Nearest surface hit of `ray` (local frame) within `ray[6]` (tMax), writing
      * `[px,py,pz, nx,ny,nz]` into `hit`. Two intentional divergences from the
@@ -161,11 +216,10 @@ export class MeshShape3D extends AbstractShape3D {
      *
      * @param {number[]|Float32Array} result
      * @param {number} result_offset
-     * @param {number} direction_x
-     * @param {number} direction_y
-     * @param {number} direction_z
+     * @param {number[]|Float32Array|Float64Array} direction unit direction, at `direction_offset`
+     * @param {number} direction_offset
      */
-    support(result: number[] | Float32Array, result_offset: number, direction_x: number, direction_y: number, direction_z: number): void;
+    support(result: number[] | Float32Array, result_offset: number, direction: number[] | Float32Array | Float64Array, direction_offset: number): void;
     /**
      * Inside test via the tet mesh. Queries the tet BVH for the leaves
      * whose AABB contains the point, then runs an `orient3d`-based

package/src/core/geom/3d/shape/MeshShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/MeshShape3D.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IAEI;;;;;OAKG;IACH,WAFU,YAAY,CAEU;IAEhC;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;;OAOG;IACH,UAFU,eAAe,CAEQ;IAEjC;;;;;;;;OAQG;IACH,eAFU,YAAY,CAEc;IAEpC;;;;;;OAMG;IACH,SAFU,GAAG,CAEO;IAEpB;;;;;OAKG;IACH,eAA8C;IAE9C;;;;;OAKG;IACH,iBAAa;IAEb;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;;OAMG;IACH,uBAAsB;IAUtB,wCAIC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAJW,YAAY,cAEV,OAAO,CA+DnB;IAED;;;;;;;OAOG;IACH,yBAiDC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,QA0BhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAyCnB;IAED;;;;;;;;;OASG;IACH,iCAHW,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,EAAE,GAAC,YAAY,QAmC/B;IAED;;;;;;;;OAQG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CA8BlB;IAGD;;;;;;OAMG;IACH,0CAJW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,cAHW,WAAW,GACT,OAAO,CAanB;IAkBL;;;;OAIG;IACH,wBAFU,OAAO,CAEkB;CAPlC;gCA3gB+B,sBAAsB;gCADtB,kCAAkC;oBAN9C,2BAA2B"}
+{"version":3,"file":"MeshShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/MeshShape3D.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IAEI;;;;;OAKG;IACH,WAFU,YAAY,CAEU;IAEhC;;;;OAIG;IACH,SAFU,WAAW,CAEQ;IAE7B;;;;;;;OAOG;IACH,UAFU,eAAe,CAEQ;IAEjC;;;;;;;;OAQG;IACH,eAFU,YAAY,CAEc;IAEpC;;;;;;OAMG;IACH,SAFU,GAAG,CAEO;IAEpB;;;;;OAKG;IACH,eAA8C;IAE9C;;;;;OAKG;IACH,iBAAa;IAEb;;;;OAIG;IACH,uBAAmB;IAEnB;;;;;;OAMG;IACH,uBAAsB;IAEtB;;;;;OAKG;IACH,8BAA6B;IAU7B,wCAIC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,mBAFa,GAAG,CAYf;IAED;;;;;;;;;;;;;OAaG;IACH,2BAFa,WAAW,CAWvB;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAJW,YAAY,cAEV,OAAO,CAyDnB;IAED;;;;;;;OAOG;IACH,yBAkEC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBALW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,oBAClC,MAAM,QA8BhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAyCnB;IAED;;;;;;;;;OASG;IACH,iCAHW,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,EAAE,GAAC,YAAY,QAmC/B;IAED;;;;;;;;OAQG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CA8BlB;IAGD;;;;;;OAMG;IACH,0CAJW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,cAHW,WAAW,GACT,OAAO,CAanB;IAkBL;;;;OAIG;IACH,wBAFU,OAAO,CAEkB;CAPlC;gCAtmB+B,sBAAsB;gCADtB,kCAAkC;oBAN9C,2BAA2B"}

package/src/core/geom/3d/shape/MeshShape3D.js

@@ -9,7 +9,7 @@ import { tetrahedral_mesh_compute_tet_volume } from "../tetrahedra/tetrahedral_m
 import { TetrahedralMesh } from "../tetrahedra/TetrahedralMesh.js";
 import { AbstractShape3D } from "./AbstractShape3D.js";
 import { compute_signed_distance_gradient_by_sampling } from "./util/compute_signed_distance_gradient_by_sampling.js";
-import { aabb3_from_v3_array } from "../aabb/aabb3_from_v3_array.js";
+import { mesh_compute_triangle_edge_flags } from "./util/mesh_compute_triangle_edge_flags.js";
 
 // module-static scratch for the surface-raycast query [triangleIndex, u, v, t]
 const MESH_QUERY_OUT = [0, 0, 0, 0];
@@ -40,6 +40,12 @@ const MESH_QUERY_OUT = [0, 0, 0, 0];
  * MeshShape3D()` directly — the factory compacts the tet mesh, builds
  * the BVH, and caches the bbox / volume / surface area.
  *
+ * A third structure, a BVH over the surface triangles, is built lazily the
+ * first time a body or a ray comes near the mesh (contacts and raycasts walk
+ * it instead of every triangle). It costs 80 bytes per triangle and 25–40 ms
+ * per 100k triangles to build, in the step that first needs it; call
+ * {@link get_surface_bvh} at load time to pay that up front.
+ *
  * Narrowphase routing:
  *   - GJK + EPA for the general case, using {@link support}.
  *   - The support function currently returns the deepest tet-mesh
@@ -126,14 +132,22 @@ export class MeshShape3D extends AbstractShape3D {
     __surface_area = 0;
 
     /**
-     * Lazily-built surface-triangle BVH for {@link raycast} (distinct from {@link tet_bvh}, which
-     * keys the interior tets). Built on the first ray query from `positions` / `indices`; null until
-     * then. Mutating the surface invalidates it (set back to null to rebuild).
+     * Lazily-built surface-triangle BVH, see {@link get_surface_bvh} (distinct from
+     * {@link tet_bvh}, which keys the interior tets). Null until first asked for; mutating the
+     * surface invalidates it ({@link recompute_cached} sets it back to null).
      * @private
      * @type {BVH|null}
      */
     __raycast_blas = null;
 
+    /**
+     * Lazily-computed per-triangle edge and corner classes, see {@link get_triangle_edge_flags}.
+     * Null until first asked for; {@link recompute_cached} sets it back to null.
+     * @private
+     * @type {Uint16Array|null}
+     */
+    __triangle_edge_flags = null;
+
     get volume() {
         return this.__volume;
     }
@@ -148,6 +162,69 @@ export class MeshShape3D extends AbstractShape3D {
         result[3] = b[3]; result[4] = b[4]; result[5] = b[5];
     }
 
+    /**
+     * BVH over the surface triangles: one leaf per triangle, whose user data is the triangle's
+     * index into {@link indices} (triangle `t` is `indices[3t .. 3t + 2]`) and whose box is the
+     * triangle's tight bounds. Node boxes are float32, so they are exact for float32
+     * {@link positions} and may round inward by up to half a float32 ULP for float64 ones;
+     * the walks over it widen their queries to match. Float64 positions past float32's range
+     * (±3.4e38) overflow their boxes to ±Infinity; the narrowphase's triangle enumeration and
+     * the physics raycast's walk reach to infinity for them.
+     *
+     * Shared by {@link raycast}, the physics narrowphase's triangle enumeration and the physics
+     * raycast, so every mesh a body or a ray comes near builds one. {@link recompute_cached}
+     * drops it, so it is rebuilt against a mutated surface.
+     *
+     * ## Cost
+     *
+     * - Memory: 80 bytes per triangle (two 40-byte nodes per triangle), kept for the shape's
+     *   life — 16 MB for a 200k-triangle floor, over four times its own 3.6 MB of positions and
+     *   indices.
+     * - Time: built lazily, by the first caller — a Morton build of 25–40 ms per 100k triangles
+     *   (measured 30–57 ms for 100k and 45–65 ms for 200k; a first step of 105 ms against a
+     *   23 ms one on a busy machine), paid inside whatever physics step first brings a body or a
+     *   ray to the mesh. Call this once while loading the mesh to move that hitch out of the
+     *   simulation.
+     *
+     * @returns {BVH}
+     */
+    get_surface_bvh() {
+        let blas = this.__raycast_blas;
+
+        if (blas === null) {
+            blas = new BVH();
+            ebvh_build_for_geometry_morton(blas, this.indices, this.positions);
+            this.__raycast_blas = blas;
+        }
+
+        return blas;
+    }
+
+    /**
+     * How each surface triangle meets its neighbours: one {@link TriangleEdgeFlags} word per triangle
+     * of {@link indices}, marking which of its edges are FLAT (the neighbour lies in its plane — an
+     * edge of the triangulation, not of the surface) and which CONCAVE, the rest being real convex
+     * edges, the rim included; and which of its corners are FLAT, met by no real edge. Neighbours
+     * are matched by vertex position, so a buffer that splits vertices for normals or UVs still has
+     * them. See {@link mesh_compute_triangle_edge_flags}.
+     *
+     * Cooked by {@link shape3_mesh_from_geometry}; otherwise computed on first use. Linear in the
+     * triangles, and cached on the shape; {@link recompute_cached} drops it, so it is recomputed for a
+     * mutated surface.
+     *
+     * @returns {Uint16Array}
+     */
+    get_triangle_edge_flags() {
+        let flags = this.__triangle_edge_flags;
+
+        if (flags === null) {
+            flags = mesh_compute_triangle_edge_flags(this.positions, this.indices);
+            this.__triangle_edge_flags = flags;
+        }
+
+        return flags;
+    }
+
     /**
      * Nearest surface hit of `ray` (local frame) within `ray[6]` (tMax), writing
      * `[px,py,pz, nx,ny,nz]` into `hit`. Two intentional divergences from the
@@ -179,13 +256,7 @@ export class MeshShape3D extends AbstractShape3D {
             return false;
         }
 
-        if (this.__raycast_blas === null) {
-            const blas = new BVH();
-            ebvh_build_for_geometry_morton(blas, indices, this.positions);
-            this.__raycast_blas = blas;
-        }
-
-        const blas = this.__raycast_blas;
+        const blas = this.get_surface_bvh();
 
         const found = ebvh_geometry_query_nearest_triangle_ray(
             MESH_QUERY_OUT, 0, blas, blas.root, ray, 0, ray[6], indices, this.positions
@@ -248,12 +319,26 @@ export class MeshShape3D extends AbstractShape3D {
         const indices = this.indices;
         const bbox = this.__bbox;
 
-        const v_count = positions.length / 3;
-
-        aabb3_from_v3_array(bbox, positions, positions.length);
+        // The box of the vertices the triangles use: a vertex no triangle uses is no part of the surface,
+        // and one left in the buffer at Infinity made the box infinite, and the mesh invisible to the
+        // broadphase — bodies fell through it.
+        bbox[0] = bbox[1] = bbox[2] = Infinity;
+        bbox[3] = bbox[4] = bbox[5] = -Infinity;
+
+        for (let i = 0; i < indices.length; i++) {
+            const v = indices[i] * 3;
+            const x = positions[v], y = positions[v + 1], z = positions[v + 2];
+
+            if (x < bbox[0]) bbox[0] = x;
+            if (y < bbox[1]) bbox[1] = y;
+            if (z < bbox[2]) bbox[2] = z;
+            if (x > bbox[3]) bbox[3] = x;
+            if (y > bbox[4]) bbox[4] = y;
+            if (z > bbox[5]) bbox[5] = z;
+        }
 
-        if (v_count === 0) {
-            // empty surface collapses to a degenerate box at the origin; the reduction leaves ±Infinity
+        if (!(bbox[0] <= bbox[3])) {
+            // no triangles: a degenerate box at the origin
             bbox[0] = bbox[1] = bbox[2] = bbox[3] = bbox[4] = bbox[5] = 0;
         }
 
@@ -292,6 +377,9 @@ export class MeshShape3D extends AbstractShape3D {
         // were snapshotted from the old surface and would otherwise prune valid
         // hits). Matches the invalidation of __bbox / __volume / __surface_area.
         this.__raycast_blas = null;
+
+        // and the edge classes, which the new surface's adjacency and angles decide
+        this.__triangle_edge_flags = null;
     }
 
     /**
@@ -312,11 +400,14 @@ export class MeshShape3D extends AbstractShape3D {
      *
      * @param {number[]|Float32Array} result
      * @param {number} result_offset
-     * @param {number} direction_x
-     * @param {number} direction_y
-     * @param {number} direction_z
+     * @param {number[]|Float32Array|Float64Array} direction unit direction, at `direction_offset`
+     * @param {number} direction_offset
      */
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
+        const direction_x = direction[direction_offset];
+        const direction_y = direction[direction_offset + 1];
+        const direction_z = direction[direction_offset + 2];
+
         const positions = this.tet_positions;
         const v_count = positions.length / 3;
         if (v_count === 0) {

package/src/core/geom/3d/shape/PointShape3D.d.ts

@@ -9,7 +9,7 @@ export class PointShape3D extends AbstractShape3D {
     nearest_point_on_surface(result: any, reference: any): void;
     sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
     raycast(hit: any, ray: any): boolean;
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     equals(other: any): boolean;
     /**
      * Fast type-check marker, mirroring `SphereShape3D.prototype.isSphereShape3D` and friends.

package/src/core/geom/3d/shape/PointShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAwEI,8BAAqC;IA/DrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qCAeC;IAED,qGAIC;IAED,4BAGC;IAWL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CAPpC;gCA/E+B,sBAAsB"}
+{"version":3,"file":"PointShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/PointShape3D.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IAwEI,8BAAqC;IA/DrC,wCAOC;IAED,6CAEC;IAED,oCAEC;IAED,4DAIC;IAED,kFAIC;IAED,qCAeC;IAED,sFAIC;IAED,4BAGC;IAWL;;;;OAIG;IACH,yBAFU,OAAO,CAEoB;CAPpC;gCA/E+B,sBAAsB"}

package/src/core/geom/3d/shape/PointShape3D.js

@@ -60,7 +60,7 @@ export class PointShape3D extends AbstractShape3D {
         return true;
     }
 
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
         result[result_offset] = 0;
         result[result_offset + 1] = 0;
         result[result_offset + 2] = 0;