@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/physics/narrowphase/decomposition/heightmap_triangle_edge_flags.js

@@ -0,0 +1,250 @@
+import { tri3_classify_shared_edge_array } from "../../../../core/geom/3d/triangle/tri3_classify_shared_edge.js";
+import { TriangleEdgeFlags } from "../../../../core/geom/3d/triangle/TriangleEdgeFlags.js";
+import { TRIANGLE_FEATURE_ID_OFFSET } from "./triangle_buffer_layout.js";
+
+// The class of an edge of one height-field triangle comes from the slopes of it and of its neighbour
+// across the edge: `0`, {@link TriangleEdgeFlags.FlatAB} or {@link TriangleEdgeFlags.ConcaveAB}. In the
+// heightmap's (u, v, h) frame a triangle with slopes (gu, gv) has the outward normal (-gu, -gv, 1); the
+// frame is orthonormal, so the angles and sides the classes compare are the body frame's.
+//
+// The classifier's inputs are staged in `edge`: the triangle's normal at EDGE_OWN, the neighbour's at
+// EDGE_NEIGHBOUR, and at EDGE_FAR the neighbour's far corner less a corner of the edge. Handed over as
+// numbers they were boxed, nine a classification: the four samples of the height field leave no
+// inlining budget for the call.
+const EDGE_OWN = 0;
+const EDGE_NEIGHBOUR = 3;
+const EDGE_FAR = 6;
+const edge = new Float64Array(9);
+
+/**
+ * Classify the edge staged in {@link edge}.
+ * @returns {number}
+ */
+function classify_staged() {
+    return tri3_classify_shared_edge_array(edge, EDGE_OWN, edge, EDGE_NEIGHBOUR, edge, EDGE_FAR);
+}
+
+/**
+ * {@link TriangleEdgeFlags} of the edges of one triangle {@link heightmap_enumerate_triangles} wrote into
+ * a triangle buffer (its corners: {@link heightmap_triangle_vertex_flat}): for each of its edges, whether the triangle across — the other half of its sub-cell across
+ * the diagonal, a neighbouring sub-cell's across a grid line — lies in its plane (FLAT), bends up
+ * (CONCAVE), or neither, a real edge; the rim of the footprint has no neighbour and is real. The
+ * classes are {@link tri3_classify_shared_edge}'s, as {@link MeshShape3D#get_triangle_edge_flags} gives
+ * a mesh.
+ *
+ * Nothing is stored. The triangle's own three corners are in the buffer; the far corner of each
+ * neighbour — three of them — is sampled exactly as the enumerator samples corners (the same
+ * Catmull-Rom filter, the same `i / seg_u`, `j / seg_v` products). A contact pays for this only on the
+ * triangles whose contacts the narrowphase has to judge, never per enumerated triangle.
+ *
+ * The edges are numbered as the enumerator winds the triangle: of `(A, D, B)`, A→D (the sub-cell's
+ * low-u side), D→B (the diagonal) and B→A (its low-v side); of `(D, C, B)`, D→C (high v), C→B
+ * (high u) and B→D (the diagonal).
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {Float64Array} triangles a triangle buffer the enumerator wrote
+ * @param {number} offset float index of the triangle's entry
+ * @returns {number}
+ */
+export function heightmap_triangle_edge_flags(shape, triangles, offset) {
+    const sampler = shape.sampler;
+    const N = shape.tessellation;
+
+    const seg_u = (sampler.width - 1) * N;
+    const seg_v = (sampler.height - 1) * N;
+
+    // fid = (j · seg_u + i) · 2 + triangle + 1
+    const index = triangles[offset + TRIANGLE_FEATURE_ID_OFFSET] - 1;
+    const triangle = index & 1;
+    const cell = (index - triangle) / 2;
+    const j = Math.floor(cell / seg_u);
+    const i = cell - j * seg_u;
+
+    const inv_segU = 1 / seg_u;
+    const inv_segV = 1 / seg_v;
+
+    const du = shape.size[0] * inv_segU;
+    const dv = shape.size[2] * inv_segV;
+    const inv_du = 1 / du;
+    const inv_dv = 1 / dv;
+
+    // the corners' heights: the triangle's own along the height axis, the fourth sampled
+    shape._ensure_basis();
+    const b = shape._basis;
+    const nx = b[6], ny = b[7], nz = b[8];
+
+    const h0 = nx * triangles[offset] + ny * triangles[offset + 1] + nz * triangles[offset + 2];
+    const h1 = nx * triangles[offset + 3] + ny * triangles[offset + 4] + nz * triangles[offset + 5];
+    const h2 = nx * triangles[offset + 6] + ny * triangles[offset + 7] + nz * triangles[offset + 8];
+
+    let flags;
+
+    // A neighbour with slopes (nu, nv) is staged as the normal (-nu, -nv, 1).
+    const e = edge;
+    e[EDGE_OWN + 2] = 1;
+    e[EDGE_NEIGHBOUR + 2] = 1;
+
+    if (triangle === 0) {
+        // (A, D, B)
+        const hA = h0, hD = h1, hB = h2;
+        const hC = sampler.sampleChannelCatmullRomUV((i + 1) * inv_segU, (j + 1) * inv_segV, 0);
+
+        const gu = (hB - hA) * inv_du, gv = (hD - hA) * inv_dv;
+        e[EDGE_OWN] = -gu;
+        e[EDGE_OWN + 1] = -gv;
+
+        // D→B, the diagonal, against (D, C, B), whose far corner is C
+        e[EDGE_NEIGHBOUR] = -((hC - hD) * inv_du);
+        e[EDGE_NEIGHBOUR + 1] = -((hC - hB) * inv_dv);
+        e[EDGE_FAR] = du; e[EDGE_FAR + 1] = 0; e[EDGE_FAR + 2] = hC - hD;
+        flags = classify_staged() << 1;
+
+        if (i >= 1) {
+            // A→D against (i-1, j)'s (D, C, B), far corner (i-1, j+1)
+            const h = sampler.sampleChannelCatmullRomUV((i - 1) * inv_segU, (j + 1) * inv_segV, 0);
+            e[EDGE_NEIGHBOUR] = -((hD - h) * inv_du);
+            e[EDGE_NEIGHBOUR + 1] = -((hD - hA) * inv_dv);
+            e[EDGE_FAR] = -du; e[EDGE_FAR + 1] = dv; e[EDGE_FAR + 2] = h - hA;
+            flags |= classify_staged();
+        }
+
+        if (j >= 1) {
+            // B→A against (i, j-1)'s (D, C, B), far corner (i+1, j-1)
+            const h = sampler.sampleChannelCatmullRomUV((i + 1) * inv_segU, (j - 1) * inv_segV, 0);
+            e[EDGE_NEIGHBOUR] = -((hB - hA) * inv_du);
+            e[EDGE_NEIGHBOUR + 1] = -((hB - h) * inv_dv);
+            e[EDGE_FAR] = du; e[EDGE_FAR + 1] = -dv; e[EDGE_FAR + 2] = h - hA;
+            flags |= classify_staged() << 2;
+        }
+    } else {
+        // (D, C, B)
+        const hD = h0, hC = h1, hB = h2;
+        const hA = sampler.sampleChannelCatmullRomUV(i * inv_segU, j * inv_segV, 0);
+
+        const gu = (hC - hD) * inv_du, gv = (hC - hB) * inv_dv;
+        e[EDGE_OWN] = -gu;
+        e[EDGE_OWN + 1] = -gv;
+
+        // B→D, the diagonal, against (A, D, B), whose far corner is A
+        e[EDGE_NEIGHBOUR] = -((hB - hA) * inv_du);
+        e[EDGE_NEIGHBOUR + 1] = -((hD - hA) * inv_dv);
+        e[EDGE_FAR] = -du; e[EDGE_FAR + 1] = 0; e[EDGE_FAR + 2] = hA - hB;
+        flags = classify_staged() << 2;
+
+        if (j <= seg_v - 2) {
+            // D→C against (i, j+1)'s (A, D, B), far corner (i, j+2)
+            const h = sampler.sampleChannelCatmullRomUV(i * inv_segU, (j + 2) * inv_segV, 0);
+            e[EDGE_NEIGHBOUR] = -((hC - hD) * inv_du);
+            e[EDGE_NEIGHBOUR + 1] = -((h - hD) * inv_dv);
+            e[EDGE_FAR] = 0; e[EDGE_FAR + 1] = dv; e[EDGE_FAR + 2] = h - hD;
+            flags |= classify_staged();
+        }
+
+        if (i <= seg_u - 2) {
+            // C→B against (i+1, j)'s (A, D, B), far corner (i+2, j)
+            const h = sampler.sampleChannelCatmullRomUV((i + 2) * inv_segU, j * inv_segV, 0);
+            e[EDGE_NEIGHBOUR] = -((h - hB) * inv_du);
+            e[EDGE_NEIGHBOUR + 1] = -((hC - hB) * inv_dv);
+            e[EDGE_FAR] = du; e[EDGE_FAR + 1] = 0; e[EDGE_FAR + 2] = h - hB;
+            flags |= classify_staged() << 1;
+        }
+    }
+
+    return flags;
+}
+
+/**
+ * Grid steps from a vertex to its six neighbours, counter-clockwise in (u, v): the sub-cells are cut
+ * along the D→B diagonal, (i, j+1)–(i+1, j), so the diagonal neighbours are (−1, +1) and (+1, −1).
+ * Consecutive pairs bound the six triangles around the vertex.
+ */
+const RING_DI = [1, 0, -1, -1, 0, 1];
+const RING_DJ = [0, 1, 1, 0, -1, -1];
+
+/** Scratch: the six neighbours' heights, then the six triangles' normals. */
+const ring_h = new Float64Array(6);
+const ring_n = new Float64Array(18);
+
+/** The far-vertex offset of the vertex test, which needs none. */
+const ZERO = new Float64Array(3);
+
+/**
+ * Whether corner `k` of one triangle {@link heightmap_enumerate_triangles} wrote into a triangle buffer
+ * is a FLAT vertex ({@link TriangleEdgeFlags.FlatVertexA} shifted by `k`): every one of the six edges
+ * meeting at that grid vertex is FLAT, the six triangles around it pairwise in one plane across each.
+ * A vertex on the rim of the footprint has rim edges, which are real, and is not.
+ *
+ * Corners are numbered as the enumerator winds the triangle: A, D, B of `(A, D, B)`; D, C, B of
+ * `(D, C, B)`. Nothing is stored: the six neighbours are sampled exactly as the enumerator samples
+ * corners, so a vertex has one answer from every triangle around it. Asked only for a corner a contact
+ * lies on.
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {Float64Array} triangles a triangle buffer the enumerator wrote
+ * @param {number} offset float index of the triangle's entry
+ * @param {number} k corner, 0..2
+ * @returns {boolean}
+ */
+export function heightmap_triangle_vertex_flat(shape, triangles, offset, k) {
+    const sampler = shape.sampler;
+    const N = shape.tessellation;
+
+    const seg_u = (sampler.width - 1) * N;
+    const seg_v = (sampler.height - 1) * N;
+
+    // fid = (j · seg_u + i) · 2 + triangle + 1
+    const index = triangles[offset + TRIANGLE_FEATURE_ID_OFFSET] - 1;
+    const triangle = index & 1;
+    const cell = (index - triangle) / 2;
+    const j = Math.floor(cell / seg_u);
+    const i = cell - j * seg_u;
+
+    // the corner's grid vertex: (A, D, B) = (i, j), (i, j+1), (i+1, j); (D, C, B) = (i, j+1), (i+1, j+1), (i+1, j)
+    const vi = i + (triangle === 0 ? (k === 2 ? 1 : 0) : (k === 0 ? 0 : 1));
+    const vj = j + (triangle === 0 ? (k === 1 ? 1 : 0) : (k === 2 ? 0 : 1));
+
+    if (vi <= 0 || vj <= 0 || vi >= seg_u || vj >= seg_v) {
+        return false;
+    }
+
+    const inv_segU = 1 / seg_u;
+    const inv_segV = 1 / seg_v;
+
+    const du = shape.size[0] * inv_segU;
+    const dv = shape.size[2] * inv_segV;
+
+    // the vertex's own height along the height axis, as the enumerator placed it
+    shape._ensure_basis();
+    const b = shape._basis;
+    const p = offset + k * 3;
+    const h = b[6] * triangles[p] + b[7] * triangles[p + 1] + b[8] * triangles[p + 2];
+
+    for (let r = 0; r < 6; r++) {
+        ring_h[r] = sampler.sampleChannelCatmullRomUV((vi + RING_DI[r]) * inv_segU, (vj + RING_DJ[r]) * inv_segV, 0) - h;
+    }
+
+    // the six triangles' normals in (u, v, h), all of one handedness: (r − V) × (r' − V)
+    for (let r = 0; r < 6; r++) {
+        const s = (r + 1) % 6;
+
+        const pu = RING_DI[r] * du, pv = RING_DJ[r] * dv, ph = ring_h[r];
+        const qu = RING_DI[s] * du, qv = RING_DJ[s] * dv, qh = ring_h[s];
+
+        ring_n[r * 3] = pv * qh - ph * qv;
+        ring_n[r * 3 + 1] = ph * qu - pu * qh;
+        ring_n[r * 3 + 2] = pu * qv - pv * qu;
+    }
+
+    // the edge to neighbour r + 1 lies between triangles r and r + 1
+    for (let r = 0; r < 6; r++) {
+        const s = (r + 1) % 6;
+
+        const flat = tri3_classify_shared_edge_array(ring_n, r * 3, ring_n, s * 3, ZERO, 0) === TriangleEdgeFlags.FlatAB;
+
+        if (!flat) {
+            return false;
+        }
+    }
+
+    return true;
+}

package/src/engine/physics/narrowphase/decomposition/mesh_enumerate_triangles.d.ts

@@ -13,22 +13,25 @@
  *                           warm-start matching and per-substep redetect)
  *
  * Triangles are AABB-filtered: a triangle is emitted iff its tight AABB
- * (min/max across its 3 vertices) overlaps the query AABB. This is a
- * linear O(N) scan over the mesh's surface triangles — no surface-BVH
- * yet (the existing BVH on MeshShape3D is over the *tet* decomposition
- * used by `contains_point`, with different leaf semantics). For meshes
- * up to a few thousand triangles the linear scan is comfortably faster
- * than a BVH would be after broadphase has already given us a tight
- * query AABB; we can graduate to a per-mesh surface BVH later.
+ * (min/max across its 3 vertices) overlaps the query AABB, touching
+ * included. The candidates come from the shape's surface BVH
+ * ({@link MeshShape3D#get_surface_bvh}, built on the first call), behind an
+ * early-out on the shape's bounding box, so the cost follows the triangles
+ * near the query rather than the mesh: this was a linear scan over every
+ * triangle, re-run by the concave redetect every substep — ~4.4 ns a
+ * triangle, 5 ms a step for one box resting on a 200k-triangle floor.
  *
  * Determinism: triangles are emitted in the natural index order, so
  * feature_id values inside `output` rise monotonically over a single
  * call. The narrowphase relies on this for stable contact-manifold
- * pairing across frames.
+ * pairing across frames — and the order decides which contacts the
+ * dedup and reduction keep, so the BVH's hits are sorted back into index
+ * order: the output is exactly what the linear scan wrote.
  *
- * Caller is responsible for ensuring
- *   `output.length - offset >= shape.indices.length / 3 * TRIANGLE_FLOAT_STRIDE`
- * in the worst case (every triangle overlaps).
+ * Returns the TRUE overlap count. Writes past the end of `output` are
+ * dropped (typed-array semantics), so a caller whose buffer is short of
+ * `count * TRIANGLE_FLOAT_STRIDE` floats past `offset` must grow it and
+ * call again rather than read past what fit.
  *
  * @param {Float64Array} output
  * @param {number} offset float-index into output
@@ -42,4 +45,17 @@
  * @returns {number} number of triangles written
  */
 export function mesh_enumerate_triangles(output: Float64Array, offset: number, shape: MeshShape3D, aabb_min_x: number, aabb_min_y: number, aabb_min_z: number, aabb_max_x: number, aabb_max_y: number, aabb_max_z: number): number;
+/**
+ * {@link mesh_enumerate_triangles} with the query box read from `aabb[aabb_offset ..+5]`
+ * (`[min x, min y, min z, max x, max y, max z]`, the shape's body-local frame): this is past what V8
+ * inlines, and a call that is not inlined boxes each number passed to it.
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {MeshShape3D} shape
+ * @param {Float64Array} aabb
+ * @param {number} aabb_offset
+ * @returns {number} number of triangles written
+ */
+export function mesh_enumerate_triangles_array(output: Float64Array, offset: number, shape: MeshShape3D, aabb: Float64Array, aabb_offset: number): number;
 //# sourceMappingURL=mesh_enumerate_triangles.d.ts.map

package/src/engine/physics/narrowphase/decomposition/mesh_enumerate_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mesh_enumerate_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/mesh_enumerate_triangles.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,iDAXW,YAAY,UACZ,MAAM,kCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqDlB"}
+{"version":3,"file":"mesh_enumerate_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/mesh_enumerate_triangles.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iDAXW,YAAY,UACZ,MAAM,kCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAalB;AAKD;;;;;;;;;;;GAWG;AACH,uDAPW,YAAY,UACZ,MAAM,4BAEN,YAAY,eACZ,MAAM,GACJ,MAAM,CAqElB"}

package/src/engine/physics/narrowphase/decomposition/mesh_enumerate_triangles.js

@@ -1,5 +1,92 @@
+import { COLUMN_CHILD_1, COLUMN_CHILD_2, COLUMN_USER_DATA, ELEMENT_WORD_COUNT, NULL_NODE } from "../../../../core/bvh2/bvh3/BVH.js";
 import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_buffer_layout.js";
 
+/**
+ * The BVH walk's own node stack — not SCRATCH_UINT32_TRAVERSAL_STACK, whose
+ * contract breaks when a caller that keeps its pointer in a local (as the
+ * physics raycast's broadphase walk does) reaches this from inside its walk.
+ * A depth-first walk that pushes both children holds at most one pending
+ * sibling per level, so this stays near the tree's height; grown on demand.
+ * @type {Uint32Array}
+ */
+let stack = new Uint32Array(64);
+
+/**
+ * The shape's bounding box, for the early-out.
+ * @type {Float64Array}
+ */
+const shape_bounds = new Float64Array(6);
+
+/**
+ * Triangle indices the BVH walk found, sorted before they are emitted. Grown
+ * by doubling, high-water mark kept; single-threaded narrowphase.
+ * @type {Uint32Array}
+ */
+let found_triangles = new Uint32Array(256);
+
+/**
+ * Up to this many found triangles, an insertion sort; past it, a radix sort.
+ * @type {number}
+ */
+const INSERTION_SORT_LIMIT = 64;
+
+/**
+ * The radix sort's other buffer; traded with {@link found_triangles} when a
+ * sort ends in it, so both keep the high-water length.
+ * @type {Uint32Array}
+ */
+let sort_scratch = new Uint32Array(256);
+
+/**
+ * Per-byte digit counts, then offsets, for the radix sort.
+ * @type {Int32Array}
+ */
+const radix_counts = new Int32Array(256);
+
+/**
+ * Widening applied to the query for the BVH walk only, relative to each
+ * bound's magnitude: one float32 ULP (2^-23). The BVH stores its boxes as
+ * float32, which is exact for float32 positions but rounds float64 positions
+ * to nearest — possibly inward. Rounding is monotonic, so a box rounded from
+ * a value that reaches the query still reaches the query widened by a ULP;
+ * the exact per-triangle test below then decides, so the walk can only add
+ * candidates, never lose one.
+ * @type {number}
+ */
+const F32_RELATIVE_SLACK = 1 / (1 << 23);
+
+/**
+ * The widening's floor: float32's smallest subnormal (2^-149), its ULP across
+ * the subnormal range, where a relative ULP of the bound would undershoot.
+ * @type {number}
+ */
+const F32_MIN_SUBNORMAL = Math.pow(2, -149);
+
+/**
+ * Float32's largest finite value. A position past it (±3.4e38) overflows to an
+ * infinite BVH box bound — outward for the face it is the extreme of, but a
+ * node's *nearer* bound can overflow too: a triangle wholly past +3.4e38 has a
+ * box minimum of +Infinity, beyond any finite query. A query bound at or past
+ * float32's range therefore reaches to infinity in the walk, so such nodes are
+ * still met; the exact test at the leaf decides.
+ * @type {number}
+ */
+const F32_MAX = 3.4028234663852886e38;
+
+// The two reach-to-infinity helpers overflow to ±Infinity by multiplying
+// (3.4e38 × 1e300) rather than returning the `Infinity` constant: with the
+// constant, V8 boxed the six query bounds, which cost 6–12% a query and 48 bytes.
+
+/** @param {number} max a widened query maximum @returns {number} */
+function f32_reach_up(max) {
+    return max >= F32_MAX ? max * 1e300 : max;
+}
+
+/** @param {number} min a widened query minimum @returns {number} */
+function f32_reach_down(min) {
+    return min <= -F32_MAX ? min * 1e300 : min;
+}
+
 /**
  * Write the mesh's surface triangles that may overlap the given query
  * AABB into `output`, starting at float-index `offset`.
@@ -15,22 +102,25 @@ import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_bu
  *                           warm-start matching and per-substep redetect)
  *
  * Triangles are AABB-filtered: a triangle is emitted iff its tight AABB
- * (min/max across its 3 vertices) overlaps the query AABB. This is a
- * linear O(N) scan over the mesh's surface triangles — no surface-BVH
- * yet (the existing BVH on MeshShape3D is over the *tet* decomposition
- * used by `contains_point`, with different leaf semantics). For meshes
- * up to a few thousand triangles the linear scan is comfortably faster
- * than a BVH would be after broadphase has already given us a tight
- * query AABB; we can graduate to a per-mesh surface BVH later.
+ * (min/max across its 3 vertices) overlaps the query AABB, touching
+ * included. The candidates come from the shape's surface BVH
+ * ({@link MeshShape3D#get_surface_bvh}, built on the first call), behind an
+ * early-out on the shape's bounding box, so the cost follows the triangles
+ * near the query rather than the mesh: this was a linear scan over every
+ * triangle, re-run by the concave redetect every substep — ~4.4 ns a
+ * triangle, 5 ms a step for one box resting on a 200k-triangle floor.
  *
  * Determinism: triangles are emitted in the natural index order, so
  * feature_id values inside `output` rise monotonically over a single
  * call. The narrowphase relies on this for stable contact-manifold
- * pairing across frames.
+ * pairing across frames — and the order decides which contacts the
+ * dedup and reduction keep, so the BVH's hits are sorted back into index
+ * order: the output is exactly what the linear scan wrote.
  *
- * Caller is responsible for ensuring
- *   `output.length - offset >= shape.indices.length / 3 * TRIANGLE_FLOAT_STRIDE`
- * in the worst case (every triangle overlaps).
+ * Returns the TRUE overlap count. Writes past the end of `output` are
+ * dropped (typed-array semantics), so a caller whose buffer is short of
+ * `count * TRIANGLE_FLOAT_STRIDE` floats past `offset` must grow it and
+ * call again rather than read past what fit.
  *
  * @param {Float64Array} output
  * @param {number} offset float-index into output
@@ -48,6 +138,33 @@ export function mesh_enumerate_triangles(
     aabb_min_x, aabb_min_y, aabb_min_z,
     aabb_max_x, aabb_max_y, aabb_max_z
 ) {
+    const aabb = scratch_aabb;
+
+    aabb[0] = aabb_min_x; aabb[1] = aabb_min_y; aabb[2] = aabb_min_z;
+    aabb[3] = aabb_max_x; aabb[4] = aabb_max_y; aabb[5] = aabb_max_z;
+
+    return mesh_enumerate_triangles_array(output, offset, shape, aabb, 0);
+}
+
+/** Where {@link mesh_enumerate_triangles} packs its query box. */
+const scratch_aabb = new Float64Array(6);
+
+/**
+ * {@link mesh_enumerate_triangles} with the query box read from `aabb[aabb_offset ..+5]`
+ * (`[min x, min y, min z, max x, max y, max z]`, the shape's body-local frame): this is past what V8
+ * inlines, and a call that is not inlined boxes each number passed to it.
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {MeshShape3D} shape
+ * @param {Float64Array} aabb
+ * @param {number} aabb_offset
+ * @returns {number} number of triangles written
+ */
+export function mesh_enumerate_triangles_array(output, offset, shape, aabb, aabb_offset) {
+    const aabb_min_x = aabb[aabb_offset], aabb_min_y = aabb[aabb_offset + 1], aabb_min_z = aabb[aabb_offset + 2];
+    const aabb_max_x = aabb[aabb_offset + 3], aabb_max_y = aabb[aabb_offset + 4], aabb_max_z = aabb[aabb_offset + 5];
+
     const positions = shape.positions;
     const indices = shape.indices;
 
@@ -56,10 +173,27 @@ export function mesh_enumerate_triangles(
         return 0;
     }
 
+    // Early-out on the shape's bounds: every triangle lies inside them. Ahead
+    // of the BVH, so a mesh that is never approached never builds one.
+    shape.compute_bounding_box(shape_bounds);
+    if (
+        shape_bounds[0] > aabb_max_x || shape_bounds[3] < aabb_min_x
+        || shape_bounds[1] > aabb_max_y || shape_bounds[4] < aabb_min_y
+        || shape_bounds[2] > aabb_max_z || shape_bounds[5] < aabb_min_z
+    ) {
+        return 0;
+    }
+
+    const found = find_triangles(shape, aabb, aabb_offset);
+
+    sort_found_triangles(found, tri_count - 1);
+
     let count = 0;
     let cursor = offset;
 
-    for (let t = 0; t < tri_count; t++) {
+    for (let k = 0; k < found; k++) {
+        const t = found_triangles[k];
+
         const i_a = indices[t * 3    ] * 3;
         const i_b = indices[t * 3 + 1] * 3;
         const i_c = indices[t * 3 + 2] * 3;
@@ -95,3 +229,148 @@ export function mesh_enumerate_triangles(
 
     return count;
 }
+
+/**
+ * Walk the shape's surface BVH and collect, into {@link found_triangles}, the
+ * index of every triangle whose leaf box overlaps the query widened by
+ * {@link F32_RELATIVE_SLACK} — a superset of the triangles the exact test
+ * accepts, in traversal order.
+ *
+ * @param {MeshShape3D} shape
+ * @param {Float64Array} aabb the query box `[min x, min y, min z, max x, max y, max z]`
+ * @param {number} aabb_offset
+ * @returns {number} how many were found
+ */
+function find_triangles(shape, aabb, aabb_offset) {
+    const aabb_min_x = aabb[aabb_offset], aabb_min_y = aabb[aabb_offset + 1], aabb_min_z = aabb[aabb_offset + 2];
+    const aabb_max_x = aabb[aabb_offset + 3], aabb_max_y = aabb[aabb_offset + 4], aabb_max_z = aabb[aabb_offset + 5];
+
+    const bvh = shape.get_surface_bvh();
+    const root = bvh.root;
+
+    if (root === NULL_NODE) {
+        return 0;
+    }
+
+    const min_x = f32_reach_down(aabb_min_x - Math.max(Math.abs(aabb_min_x) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+    const min_y = f32_reach_down(aabb_min_y - Math.max(Math.abs(aabb_min_y) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+    const min_z = f32_reach_down(aabb_min_z - Math.max(Math.abs(aabb_min_z) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+    const max_x = f32_reach_up(aabb_max_x + Math.max(Math.abs(aabb_max_x) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+    const max_y = f32_reach_up(aabb_max_y + Math.max(Math.abs(aabb_max_y) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+    const max_z = f32_reach_up(aabb_max_z + Math.max(Math.abs(aabb_max_z) * F32_RELATIVE_SLACK, F32_MIN_SUBNORMAL));
+
+    // Read the node columns directly, as ebvh_geometry_query_nearest_triangle_ray does.
+    const float32 = bvh.__data_float32;
+    const uint32 = bvh.__data_uint32;
+
+    let found = 0;
+
+    let pointer = 0;
+    stack[pointer++] = root;
+
+    while (pointer > 0) {
+        const node = stack[--pointer];
+        const address = node * ELEMENT_WORD_COUNT;
+
+        if (
+            float32[address] > max_x || float32[address + 3] < min_x
+            || float32[address + 1] > max_y || float32[address + 4] < min_y
+            || float32[address + 2] > max_z || float32[address + 5] < min_z
+        ) {
+            continue;
+        }
+
+        const child_1 = uint32[address + COLUMN_CHILD_1];
+
+        if (child_1 !== NULL_NODE) {
+            if (pointer + 2 > stack.length) {
+                const grown = new Uint32Array(stack.length * 2);
+                grown.set(stack);
+                stack = grown;
+            }
+
+            stack[pointer++] = child_1;
+            stack[pointer++] = uint32[address + COLUMN_CHILD_2];
+            continue;
+        }
+
+        if (found === found_triangles.length) {
+            const grown = new Uint32Array(found * 2);
+            grown.set(found_triangles);
+            found_triangles = grown;
+        }
+
+        found_triangles[found++] = uint32[address + COLUMN_USER_DATA];
+    }
+
+    return found;
+}
+
+/**
+ * Sort the first `count` entries of {@link found_triangles} ascending — back
+ * into the mesh's index order, which is the order the linear scan emitted in.
+ * Insertion sort for a few, else a byte-wise LSD radix sort through
+ * {@link sort_scratch}: linear, and no allocation (the typed-array sort it
+ * replaced needed a subarray view per call).
+ *
+ * @param {number} count
+ * @param {number} max_value no entry exceeds it (the mesh's last triangle index)
+ */
+function sort_found_triangles(count, max_value) {
+    if (count > INSERTION_SORT_LIMIT) {
+        if (sort_scratch.length < count) {
+            sort_scratch = new Uint32Array(found_triangles.length);
+        }
+
+        let src = found_triangles;
+        let dst = sort_scratch;
+
+        // a pass per byte the largest index has
+        for (let shift = 0; shift < 32 && (max_value >>> shift) !== 0; shift += 8) {
+            radix_counts.fill(0);
+
+            for (let i = 0; i < count; i++) {
+                radix_counts[(src[i] >>> shift) & 255]++;
+            }
+
+            let sum = 0;
+            for (let d = 0; d < 256; d++) {
+                const c = radix_counts[d];
+                radix_counts[d] = sum;
+                sum += c;
+            }
+
+            for (let i = 0; i < count; i++) {
+                const v = src[i];
+                dst[radix_counts[(v >>> shift) & 255]++] = v;
+            }
+
+            const swap = src;
+            src = dst;
+            dst = swap;
+        }
+
+        // an odd number of passes leaves the sorted run in the scratch: trade the buffers
+        if (src !== found_triangles) {
+            sort_scratch = found_triangles;
+            found_triangles = src;
+        }
+
+        return;
+    }
+
+    const a = found_triangles;
+
+    for (let i = 1; i < count; i++) {
+        const v = a[i];
+
+        let j = i - 1;
+
+        while (j >= 0 && a[j] > v) {
+            a[j + 1] = a[j];
+            j--;
+        }
+
+        a[j + 1] = v;
+    }
+}

package/src/engine/physics/narrowphase/decomposition/triangle_buffer_layout.d.ts

@@ -21,7 +21,13 @@
  *
  * Stride 10 (rather than 9) is the small cost we pay for clean warm-start
  * matching; ID-based matching beats position-distance matching when shapes
- * slide along curved surfaces.
+ * slide along curved surfaces. {@link triangle_edge_flags} reads an entry
+ * to say which of the triangle's edges are real.
+ *
+ * A vertex two triangles share has the same coordinates, bit for bit, in
+ * both entries — both enumerators copy or compute each one by one expression
+ * — so a vertex or an edge can be recognised across triangles by its
+ * coordinates.
  *
  * @readonly
  * @type {number}

package/src/engine/physics/narrowphase/decomposition/triangle_buffer_layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"triangle_buffer_layout.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/triangle_buffer_layout.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,yCAFU,MAAM,CAE4B"}
+{"version":3,"file":"triangle_buffer_layout.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/triangle_buffer_layout.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,yCAFU,MAAM,CAE4B"}