@woosh/meep-engine 2.156.0 → 2.157.0

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

@@ -22,11 +22,14 @@
  *
  * The collision grid therefore has `seg_u = (W − 1)·N` segments along u and
  * `seg_v = (H − 1)·N` along v. The feature_id encodes
- * `(sub_y · seg_u + sub_x) · 2 + tri_idx`, where (sub_x, sub_y) is the
+ * `(sub_y · seg_u + sub_x) · 2 + tri_idx + 1`, where (sub_x, sub_y) is the
  * sub-cell and tri_idx ∈ {0, 1}: a unique, frame-stable key per sub-cell
  * triangle (`seg_u · seg_v · 2` stays well under 2^53 for any realistic
- * sampler × N). Two triangles per sub-cell, lower-left-diagonal split
- * (matches the existing {@link build_height_field_geometry} winding).
+ * sampler × N). The `+ 1` keeps the corner cell's first triangle off fid 0 —
+ * the narrowphase's "no feature info" sentinel, which would cost its
+ * contacts fid warm-start matching and per-substep redetect. Two triangles
+ * per sub-cell, lower-left-diagonal split (matches the existing
+ * {@link build_height_field_geometry} winding).
  *
  * The query AABB is filtered against the footprint *and* against the
  * cell grid; triangles outside the query AABB along the height axis are

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

@@ -1 +1 @@
-{"version":3,"file":"heightmap_enumerate_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/heightmap_enumerate_triangles.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,sDAXW,YAAY,UACZ,MAAM,uCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CA+KlB"}
+{"version":3,"file":"heightmap_enumerate_triangles.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/narrowphase/decomposition/heightmap_enumerate_triangles.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,sDAXW,YAAY,UACZ,MAAM,uCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CA+MlB"}

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

@@ -1,5 +1,26 @@
 import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_buffer_layout.js";
 
+/**
+ * Corner-height row cache (D5). The emit loop reads 4 corner heights per
+ * sub-cell, but every interior corner is shared by 4 sub-cells — and the
+ * Catmull-Rom evaluation behind each height is ~9 bilinear taps, re-paid by
+ * the concave redetect every substep. Sampling each corner of the query
+ * rect ONCE — a row of corners at a time, rolled as `j` advances — cuts CR
+ * evaluations ~4× on interior rects.
+ *
+ * Exactness: corner k of row j is sampled at
+ * `u01 = (i_first + k) * inv_segU`, `v01 = j * inv_segV` — the SAME float
+ * expressions the per-cell code used (cell i's `u01_hi` and cell i+1's
+ * `u01_lo` are the identical product), so the cached values are
+ * bit-identical to the uncached ones and the emitted triangles do not
+ * change by a single bit.
+ *
+ * Module scratch, grown on demand; single-threaded narrowphase.
+ * @type {Float64Array}
+ */
+let row_corner_lo = new Float64Array(64);
+let row_corner_hi = new Float64Array(64);
+
 /**
  * Write the heightmap's triangles that may overlap the given body-local
  * query AABB into `output`, starting at float-index `offset`.
@@ -24,11 +45,14 @@ import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_bu
  *
  * The collision grid therefore has `seg_u = (W − 1)·N` segments along u and
  * `seg_v = (H − 1)·N` along v. The feature_id encodes
- * `(sub_y · seg_u + sub_x) · 2 + tri_idx`, where (sub_x, sub_y) is the
+ * `(sub_y · seg_u + sub_x) · 2 + tri_idx + 1`, where (sub_x, sub_y) is the
  * sub-cell and tri_idx ∈ {0, 1}: a unique, frame-stable key per sub-cell
  * triangle (`seg_u · seg_v · 2` stays well under 2^53 for any realistic
- * sampler × N). Two triangles per sub-cell, lower-left-diagonal split
- * (matches the existing {@link build_height_field_geometry} winding).
+ * sampler × N). The `+ 1` keeps the corner cell's first triangle off fid 0 —
+ * the narrowphase's "no feature info" sentinel, which would cost its
+ * contacts fid warm-start matching and per-substep redetect. Two triangles
+ * per sub-cell, lower-left-diagonal split (matches the existing
+ * {@link build_height_field_geometry} winding).
  *
  * The query AABB is filtered against the footprint *and* against the
  * cell grid; triangles outside the query AABB along the height axis are
@@ -177,22 +201,48 @@ export function heightmap_enumerate_triangles(
     let count = 0;
     let cursor = offset;
 
+    // Corner-row cache (see the D5 note at the top): `row_corner_lo` holds
+    // the heights along the sub-cell row's lower grid line, `row_corner_hi`
+    // the upper; rolled (swapped) as `j` advances since row j's upper line
+    // IS row j+1's lower line — the same `(j+1) * inv_segV` float.
+    const corners_per_row = i_last - i_first + 2;
+    if (row_corner_lo.length < corners_per_row) {
+        let cap = row_corner_lo.length;
+        while (cap < corners_per_row) cap <<= 1;
+        row_corner_lo = new Float64Array(cap);
+        row_corner_hi = new Float64Array(cap);
+    }
+
+    // Prime the first row's lower grid line.
+    {
+        const v01 = j_first * inv_segV;
+        for (let k = 0; k < corners_per_row; k++) {
+            row_corner_lo[k] = sampler.sampleChannelCatmullRomUV((i_first + k) * inv_segU, v01, 0);
+        }
+    }
+
     for (let j = j_first; j <= j_last; j++) {
         const v01_lo = j * inv_segV;
         const v01_hi = (j + 1) * inv_segV;
         const v_lo_coord = -half_v + size_z * v01_lo;
         const v_hi_coord = -half_v + size_z * v01_hi;
 
+        // Sample the row's upper grid line; the lower line is already cached.
+        for (let k = 0; k < corners_per_row; k++) {
+            row_corner_hi[k] = sampler.sampleChannelCatmullRomUV((i_first + k) * inv_segU, v01_hi, 0);
+        }
+
         for (let i = i_first; i <= i_last; i++) {
             const u01_lo = i * inv_segU;
             const u01_hi = (i + 1) * inv_segU;
             const u_lo_coord = -half_u + size_x * u01_lo;
             const u_hi_coord = -half_u + size_x * u01_hi;
 
-            const hA = sampler.sampleChannelCatmullRomUV(u01_lo, v01_lo, 0);
-            const hB = sampler.sampleChannelCatmullRomUV(u01_hi, v01_lo, 0);
-            const hC = sampler.sampleChannelCatmullRomUV(u01_hi, v01_hi, 0);
-            const hD = sampler.sampleChannelCatmullRomUV(u01_lo, v01_hi, 0);
+            const k = i - i_first;
+            const hA = row_corner_lo[k];
+            const hB = row_corner_lo[k + 1];
+            const hC = row_corner_hi[k + 1];
+            const hD = row_corner_hi[k];
 
             const Ax = ux * u_lo_coord + vx * v_lo_coord + nx * hA;
             const Ay = uy * u_lo_coord + vy * v_lo_coord + ny * hA;
@@ -213,11 +263,11 @@ export function heightmap_enumerate_triangles(
             const cell_idx = j * seg_u + i;
             const fid_base = cell_idx * 2;
 
-            // triangle 0: (A, D, B)
+            // triangle 0: (A, D, B). fid is offset by 1 — 0 is the "no fid" sentinel.
             output[cursor    ] = Ax; output[cursor + 1] = Ay; output[cursor + 2] = Az;
             output[cursor + 3] = Dx; output[cursor + 4] = Dy; output[cursor + 5] = Dz;
             output[cursor + 6] = Bx; output[cursor + 7] = By; output[cursor + 8] = Bz;
-            output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = fid_base;
+            output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = fid_base + 1;
             cursor += TRIANGLE_FLOAT_STRIDE;
             count++;
 
@@ -225,10 +275,16 @@ export function heightmap_enumerate_triangles(
             output[cursor    ] = Dx; output[cursor + 1] = Dy; output[cursor + 2] = Dz;
             output[cursor + 3] = Cx; output[cursor + 4] = Cy; output[cursor + 5] = Cz;
             output[cursor + 6] = Bx; output[cursor + 7] = By; output[cursor + 8] = Bz;
-            output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = fid_base + 1;
+            output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = fid_base + 2;
             cursor += TRIANGLE_FLOAT_STRIDE;
             count++;
         }
+
+        // Roll the corner rows: this row's upper line is the next row's
+        // lower line.
+        const roll = row_corner_lo;
+        row_corner_lo = row_corner_hi;
+        row_corner_hi = roll;
     }
 
     return count;

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

@@ -7,7 +7,10 @@
  *                       {@link MeshShape3D#positions})
  *   [+3..+5]  vB.xyz
  *   [+6..+8]  vC.xyz
- *   [+9]      feature_id   (the surface triangle's index)
+ *   [+9]      feature_id   (the surface triangle's index + 1 — fid 0 is the
+ *                           narrowphase's "no feature info" sentinel, which
+ *                           would cost triangle 0's contacts their fid
+ *                           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

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,iDAXW,YAAY,UACZ,MAAM,kCAEN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,cACN,MAAM,GACJ,MAAM,CAqDlB"}

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

@@ -1,94 +1,97 @@
-import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_buffer_layout.js";
-
-/**
- * Write the mesh's surface triangles that may overlap the given query
- * AABB into `output`, starting at float-index `offset`.
- *
- * Each triangle occupies {@link TRIANGLE_FLOAT_STRIDE} consecutive floats:
- *   [+0..+2]  vA.xyz   (shape's body-local frame, i.e. read directly from
- *                       {@link MeshShape3D#positions})
- *   [+3..+5]  vB.xyz
- *   [+6..+8]  vC.xyz
- *   [+9]      feature_id   (the surface triangle's index)
- *
- * 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.
- *
- * 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.
- *
- * Caller is responsible for ensuring
- *   `output.length - offset >= shape.indices.length / 3 * TRIANGLE_FLOAT_STRIDE`
- * in the worst case (every triangle overlaps).
- *
- * @param {Float64Array} output
- * @param {number} offset float-index into output
- * @param {MeshShape3D} shape
- * @param {number} aabb_min_x  query AABB in shape's body-local frame
- * @param {number} aabb_min_y
- * @param {number} aabb_min_z
- * @param {number} aabb_max_x
- * @param {number} aabb_max_y
- * @param {number} aabb_max_z
- * @returns {number} number of triangles written
- */
-export function mesh_enumerate_triangles(
-    output, offset, shape,
-    aabb_min_x, aabb_min_y, aabb_min_z,
-    aabb_max_x, aabb_max_y, aabb_max_z
-) {
-    const positions = shape.positions;
-    const indices = shape.indices;
-
-    const tri_count = (indices.length / 3) | 0;
-    if (tri_count === 0) {
-        return 0;
-    }
-
-    let count = 0;
-    let cursor = offset;
-
-    for (let t = 0; t < tri_count; t++) {
-        const i_a = indices[t * 3    ] * 3;
-        const i_b = indices[t * 3 + 1] * 3;
-        const i_c = indices[t * 3 + 2] * 3;
-
-        const ax = positions[i_a    ]; const ay = positions[i_a + 1]; const az = positions[i_a + 2];
-        const bx = positions[i_b    ]; const by = positions[i_b + 1]; const bz = positions[i_b + 2];
-        const cx = positions[i_c    ]; const cy = positions[i_c + 1]; const cz = positions[i_c + 2];
-
-        // tight per-triangle AABB
-        const tri_min_x = ax < bx ? (ax < cx ? ax : cx) : (bx < cx ? bx : cx);
-        if (tri_min_x > aabb_max_x) continue;
-        const tri_max_x = ax > bx ? (ax > cx ? ax : cx) : (bx > cx ? bx : cx);
-        if (tri_max_x < aabb_min_x) continue;
-
-        const tri_min_y = ay < by ? (ay < cy ? ay : cy) : (by < cy ? by : cy);
-        if (tri_min_y > aabb_max_y) continue;
-        const tri_max_y = ay > by ? (ay > cy ? ay : cy) : (by > cy ? by : cy);
-        if (tri_max_y < aabb_min_y) continue;
-
-        const tri_min_z = az < bz ? (az < cz ? az : cz) : (bz < cz ? bz : cz);
-        if (tri_min_z > aabb_max_z) continue;
-        const tri_max_z = az > bz ? (az > cz ? az : cz) : (bz > cz ? bz : cz);
-        if (tri_max_z < aabb_min_z) continue;
-
-        output[cursor    ] = ax; output[cursor + 1] = ay; output[cursor + 2] = az;
-        output[cursor + 3] = bx; output[cursor + 4] = by; output[cursor + 5] = bz;
-        output[cursor + 6] = cx; output[cursor + 7] = cy; output[cursor + 8] = cz;
-        output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = t;
-
-        cursor += TRIANGLE_FLOAT_STRIDE;
-        count++;
-    }
-
-    return count;
-}
+import { TRIANGLE_FEATURE_ID_OFFSET, TRIANGLE_FLOAT_STRIDE } from "./triangle_buffer_layout.js";
+
+/**
+ * Write the mesh's surface triangles that may overlap the given query
+ * AABB into `output`, starting at float-index `offset`.
+ *
+ * Each triangle occupies {@link TRIANGLE_FLOAT_STRIDE} consecutive floats:
+ *   [+0..+2]  vA.xyz   (shape's body-local frame, i.e. read directly from
+ *                       {@link MeshShape3D#positions})
+ *   [+3..+5]  vB.xyz
+ *   [+6..+8]  vC.xyz
+ *   [+9]      feature_id   (the surface triangle's index + 1 — fid 0 is the
+ *                           narrowphase's "no feature info" sentinel, which
+ *                           would cost triangle 0's contacts their fid
+ *                           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.
+ *
+ * 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.
+ *
+ * Caller is responsible for ensuring
+ *   `output.length - offset >= shape.indices.length / 3 * TRIANGLE_FLOAT_STRIDE`
+ * in the worst case (every triangle overlaps).
+ *
+ * @param {Float64Array} output
+ * @param {number} offset float-index into output
+ * @param {MeshShape3D} shape
+ * @param {number} aabb_min_x  query AABB in shape's body-local frame
+ * @param {number} aabb_min_y
+ * @param {number} aabb_min_z
+ * @param {number} aabb_max_x
+ * @param {number} aabb_max_y
+ * @param {number} aabb_max_z
+ * @returns {number} number of triangles written
+ */
+export function mesh_enumerate_triangles(
+    output, offset, shape,
+    aabb_min_x, aabb_min_y, aabb_min_z,
+    aabb_max_x, aabb_max_y, aabb_max_z
+) {
+    const positions = shape.positions;
+    const indices = shape.indices;
+
+    const tri_count = (indices.length / 3) | 0;
+    if (tri_count === 0) {
+        return 0;
+    }
+
+    let count = 0;
+    let cursor = offset;
+
+    for (let t = 0; t < tri_count; t++) {
+        const i_a = indices[t * 3    ] * 3;
+        const i_b = indices[t * 3 + 1] * 3;
+        const i_c = indices[t * 3 + 2] * 3;
+
+        const ax = positions[i_a    ]; const ay = positions[i_a + 1]; const az = positions[i_a + 2];
+        const bx = positions[i_b    ]; const by = positions[i_b + 1]; const bz = positions[i_b + 2];
+        const cx = positions[i_c    ]; const cy = positions[i_c + 1]; const cz = positions[i_c + 2];
+
+        // tight per-triangle AABB
+        const tri_min_x = ax < bx ? (ax < cx ? ax : cx) : (bx < cx ? bx : cx);
+        if (tri_min_x > aabb_max_x) continue;
+        const tri_max_x = ax > bx ? (ax > cx ? ax : cx) : (bx > cx ? bx : cx);
+        if (tri_max_x < aabb_min_x) continue;
+
+        const tri_min_y = ay < by ? (ay < cy ? ay : cy) : (by < cy ? by : cy);
+        if (tri_min_y > aabb_max_y) continue;
+        const tri_max_y = ay > by ? (ay > cy ? ay : cy) : (by > cy ? by : cy);
+        if (tri_max_y < aabb_min_y) continue;
+
+        const tri_min_z = az < bz ? (az < cz ? az : cz) : (bz < cz ? bz : cz);
+        if (tri_min_z > aabb_max_z) continue;
+        const tri_max_z = az > bz ? (az > cz ? az : cz) : (bz > cz ? bz : cz);
+        if (tri_max_z < aabb_min_z) continue;
+
+        output[cursor    ] = ax; output[cursor + 1] = ay; output[cursor + 2] = az;
+        output[cursor + 3] = bx; output[cursor + 4] = by; output[cursor + 5] = bz;
+        output[cursor + 6] = cx; output[cursor + 7] = cy; output[cursor + 8] = cz;
+        output[cursor + TRIANGLE_FEATURE_ID_OFFSET] = t + 1; // 0 is the "no fid" sentinel
+
+        cursor += TRIANGLE_FLOAT_STRIDE;
+        count++;
+    }
+
+    return count;
+}

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

@@ -1,117 +1,117 @@
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
-import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
-import { aabb_world_to_local } from "./decomposition/aabb_world_to_local.js";
-import { build_convex_decomposition } from "./convex_decomposition.js";
-import { convex_convex_manifold, CONVEX_CONVEX_OUT_LENGTH } from "./convex_convex_manifold.js";
-
-/**
- * Contact generation between two triangulated meshes, each treated as the union
- * of its CONVEX PIECES (from greedy tet-merge — see {@link build_convex_decomposition}).
- * Concave-vs-concave reduced to convex piece-vs-piece, the standard
- * convex-decomposition approach.
- *
- * Only piece pairs whose AABBs overlap reach the SAT + face-clip manifold:
- * project mesh B's world AABB into A's local frame and query A's piece BVH; for
- * each candidate piece of A, project its world AABB into B's local frame and
- * query B's piece BVH. One top-level broadphase leaf per body; the per-shape
- * piece BVHs do the culling. Merging keeps the piece count (and the per-pair
- * SAT cost) far below the raw tet count — the path to large tet counts.
- *
- * The decomposition is built once per shape and cached (shapes are immutable,
- * shared, and the decomposition is in the shape's local frame). Per-frame, no
- * cross-frame state → reset-and-resimulate determinism preserved.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/** Stop emitting once the candidate buffer is nearly full (capped at 4
- *  downstream); a localised resting contact never approaches this. */
-const MAX_EMIT = 60;
-
-const piece_out = new Float64Array(CONVEX_CONVEX_OUT_LENGTH);
-let cand_a = new Uint32Array(4096);
-let cand_b = new Uint32Array(4096);
-const local_bbox = new Float64Array(6);
-const world_aabb = new Float64Array(6);
-const query_aabb = new Float64Array(6);
-
-/** Build + cache the convex decomposition on the (immutable, shared) shape. */
-function get_decomposition(shape) {
-    let d = shape.__convex_decomposition;
-    if (d === undefined) {
-        d = build_convex_decomposition(shape);
-        shape.__convex_decomposition = d;
-    }
-    return d;
-}
-
-function ensure(buf, n) { return buf.length >= n ? buf : new Uint32Array(n); }
-
-/**
- * Append the mesh-vs-mesh contacts via `append`, the narrowphase's
- * `append_contact(count, wax,way,waz, wbx,wby,wbz, nx,ny,nz, depth, fid) → newCount`.
- *
- * @returns {number} new candidate count
- */
-export function mesh_mesh_tet_contacts(count, shapeA, trA, shapeB, trB, append) {
-    const decompA = get_decomposition(shapeA);
-    const decompB = get_decomposition(shapeB);
-    const piecesA = decompA.pieces;
-    const piecesB = decompB.pieces;
-
-    // Candidate pieces of A: those whose AABB overlaps B's world AABB (in A-local).
-    shapeB.compute_bounding_box(local_bbox);
-    aabb3_transform_oriented(
-        world_aabb, 0,
-        local_bbox[0], local_bbox[1], local_bbox[2], local_bbox[3], local_bbox[4], local_bbox[5],
-        trB.position.x, trB.position.y, trB.position.z,
-        trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w
-    );
-    aabb_world_to_local(
-        query_aabb, 0, world_aabb,
-        trA.position.x, trA.position.y, trA.position.z,
-        trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w
-    );
-
-    cand_a = ensure(cand_a, piecesA.length);
-    const nA = bvh_query_user_data_overlaps_aabb(cand_a, 0, decompA.bvh, query_aabb);
-
-    for (let i = 0; i < nA; i++) {
-        const pieceA = piecesA[cand_a[i]];
-
-        // Candidate pieces of B near this piece of A.
-        const ab = pieceA.aabb;
-        aabb3_transform_oriented(
-            world_aabb, 0,
-            ab[0], ab[1], ab[2], ab[3], ab[4], ab[5],
-            trA.position.x, trA.position.y, trA.position.z,
-            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w
-        );
-        aabb_world_to_local(
-            query_aabb, 0, world_aabb,
-            trB.position.x, trB.position.y, trB.position.z,
-            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w
-        );
-        cand_b = ensure(cand_b, piecesB.length);
-        const nB = bvh_query_user_data_overlaps_aabb(cand_b, 0, decompB.bvh, query_aabb);
-
-        for (let j = 0; j < nB; j++) {
-            const pieceB = piecesB[cand_b[j]];
-            if (!convex_convex_manifold(piece_out, pieceA, trA.position, trA.rotation, pieceB, trB.position, trB.rotation)) {
-                continue;
-            }
-            const cc = piece_out[3] | 0;
-            const nx = piece_out[0], ny = piece_out[1], nz = piece_out[2];
-            for (let k = 0; k < cc; k++) {
-                const base = 4 + k * 7;
-                count = append(count,
-                    piece_out[base], piece_out[base + 1], piece_out[base + 2],
-                    piece_out[base + 3], piece_out[base + 4], piece_out[base + 5],
-                    nx, ny, nz, piece_out[base + 6], 0);
-            }
-            if (count >= MAX_EMIT) return count;
-        }
-    }
-    return count;
-}
+import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { aabb3_transform_oriented_inverse } from "../../../core/geom/3d/aabb/aabb3_transform_oriented_inverse.js";
+import { build_convex_decomposition } from "./convex_decomposition.js";
+import { convex_convex_manifold, CONVEX_CONVEX_OUT_LENGTH } from "./convex_convex_manifold.js";
+
+/**
+ * Contact generation between two triangulated meshes, each treated as the union
+ * of its CONVEX PIECES (from greedy tet-merge — see {@link build_convex_decomposition}).
+ * Concave-vs-concave reduced to convex piece-vs-piece, the standard
+ * convex-decomposition approach.
+ *
+ * Only piece pairs whose AABBs overlap reach the SAT + face-clip manifold:
+ * project mesh B's world AABB into A's local frame and query A's piece BVH; for
+ * each candidate piece of A, project its world AABB into B's local frame and
+ * query B's piece BVH. One top-level broadphase leaf per body; the per-shape
+ * piece BVHs do the culling. Merging keeps the piece count (and the per-pair
+ * SAT cost) far below the raw tet count — the path to large tet counts.
+ *
+ * The decomposition is built once per shape and cached (shapes are immutable,
+ * shared, and the decomposition is in the shape's local frame). Per-frame, no
+ * cross-frame state → reset-and-resimulate determinism preserved.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** Stop emitting once the candidate buffer is nearly full (capped at 4
+ *  downstream); a localised resting contact never approaches this. */
+const MAX_EMIT = 60;
+
+const piece_out = new Float64Array(CONVEX_CONVEX_OUT_LENGTH);
+let cand_a = new Uint32Array(4096);
+let cand_b = new Uint32Array(4096);
+const local_bbox = new Float64Array(6);
+const world_aabb = new Float64Array(6);
+const query_aabb = new Float64Array(6);
+
+/** Build + cache the convex decomposition on the (immutable, shared) shape. */
+function get_decomposition(shape) {
+    let d = shape.__convex_decomposition;
+    if (d === undefined) {
+        d = build_convex_decomposition(shape);
+        shape.__convex_decomposition = d;
+    }
+    return d;
+}
+
+function ensure(buf, n) { return buf.length >= n ? buf : new Uint32Array(n); }
+
+/**
+ * Append the mesh-vs-mesh contacts via `append`, the narrowphase's
+ * `append_contact(count, wax,way,waz, wbx,wby,wbz, nx,ny,nz, depth, fid) → newCount`.
+ *
+ * @returns {number} new candidate count
+ */
+export function mesh_mesh_tet_contacts(count, shapeA, trA, shapeB, trB, append) {
+    const decompA = get_decomposition(shapeA);
+    const decompB = get_decomposition(shapeB);
+    const piecesA = decompA.pieces;
+    const piecesB = decompB.pieces;
+
+    // Candidate pieces of A: those whose AABB overlaps B's world AABB (in A-local).
+    shapeB.compute_bounding_box(local_bbox);
+    aabb3_transform_oriented(
+        world_aabb, 0,
+        local_bbox[0], local_bbox[1], local_bbox[2], local_bbox[3], local_bbox[4], local_bbox[5],
+        trB.position.x, trB.position.y, trB.position.z,
+        trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w
+    );
+    aabb3_transform_oriented_inverse(
+        query_aabb, 0, world_aabb,
+        trA.position.x, trA.position.y, trA.position.z,
+        trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w
+    );
+
+    cand_a = ensure(cand_a, piecesA.length);
+    const nA = bvh_query_user_data_overlaps_aabb(cand_a, 0, decompA.bvh, query_aabb);
+
+    for (let i = 0; i < nA; i++) {
+        const pieceA = piecesA[cand_a[i]];
+
+        // Candidate pieces of B near this piece of A.
+        const ab = pieceA.aabb;
+        aabb3_transform_oriented(
+            world_aabb, 0,
+            ab[0], ab[1], ab[2], ab[3], ab[4], ab[5],
+            trA.position.x, trA.position.y, trA.position.z,
+            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w
+        );
+        aabb3_transform_oriented_inverse(
+            query_aabb, 0, world_aabb,
+            trB.position.x, trB.position.y, trB.position.z,
+            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w
+        );
+        cand_b = ensure(cand_b, piecesB.length);
+        const nB = bvh_query_user_data_overlaps_aabb(cand_b, 0, decompB.bvh, query_aabb);
+
+        for (let j = 0; j < nB; j++) {
+            const pieceB = piecesB[cand_b[j]];
+            if (!convex_convex_manifold(piece_out, pieceA, trA.position, trA.rotation, pieceB, trB.position, trB.rotation)) {
+                continue;
+            }
+            const cc = piece_out[3] | 0;
+            const nx = piece_out[0], ny = piece_out[1], nz = piece_out[2];
+            for (let k = 0; k < cc; k++) {
+                const base = 4 + k * 7;
+                count = append(count,
+                    piece_out[base], piece_out[base + 1], piece_out[base + 2],
+                    piece_out[base + 3], piece_out[base + 4], piece_out[base + 5],
+                    nx, ny, nz, piece_out[base + 6], 0);
+            }
+            if (count >= MAX_EMIT) return count;
+        }
+    }
+    return count;
+}

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":"AAk1CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,QAiKlE;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,QA8G3D"}
+{"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"}