@woosh/meep-engine 2.152.0 → 2.154.0

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

@@ -0,0 +1,293 @@
+import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+
+/**
+ * Greedy convex decomposition of a tetrahedralised mesh into a small set of
+ * convex pieces, each with coplanar-merged polygon faces — the representation
+ * the contact clipper ({@link convex_convex_manifold}) consumes.
+ *
+ * Why: colliding two meshes as their raw tetrahedra means a SAT+clip per
+ * contacting tet pair. Merging adjacent tets into larger convex pieces collapses
+ * a convex sub-region (e.g. a box) to a SINGLE piece, cutting both the pair
+ * count and the per-pair work — the path to large tet counts.
+ *
+ * Pipeline:
+ *   1. Build face → tets adjacency from shared faces (sorted vertex triples).
+ *   2. Greedy region-grow: seed a piece from a tet, BFS-absorb face-neighbours
+ *      while the union stays convex. Convexity test is definitive: every vertex
+ *      of the candidate union lies behind (or on) every boundary-face plane.
+ *   3. Per piece: XOR the member tets' faces to get the boundary triangles
+ *      (outward-oriented), coplanar-merge them into polygon faces by walking the
+ *      directed boundary edges, and localise the vertex indices.
+ *   4. Build a BVH over the pieces' local AABBs for piece-pair culling.
+ *
+ * Output (cached on the MeshShape3D): `{ pieces, bvh }` where each piece is
+ * `{ vertices, face_offsets, face_loops, aabb }` — directly clippable.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+// Quantisation for grouping coplanar faces (normal + plane offset).
+const PLANE_NORMAL_TOL = 1e-4;
+const PLANE_OFFSET_TOL = 1e-4;
+
+// A tet face by index: the 3 face-vertex slots + the opposite-vertex slot.
+// Exported so the convex-mesh fast path (mesh_convex_hull.js) shares the same
+// tet-face convention rather than keeping a parallel copy.
+export const FACE_OPP = [[1, 2, 3, 0], [0, 2, 3, 1], [0, 1, 3, 2], [0, 1, 2, 3]];
+
+export function face_key(a, b, c) {
+    // Exact, collision-free order-independent key for a triangle's vertex triple.
+    let x = a, y = b, z = c, t;
+    if (x > y) { t = x; x = y; y = t; }
+    if (y > z) { t = y; y = z; z = t; }
+    if (x > y) { t = x; x = y; y = t; }
+    return x + "," + y + "," + z;
+}
+
+/**
+ * @param {{tet_mesh, tet_positions, compute_bounding_box}} meshShape
+ * @returns {{pieces: Array<{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array, aabb:Float64Array}>, bvh: BVH}}
+ */
+export function build_convex_decomposition(meshShape) {
+    const tm = meshShape.tet_mesh;
+    const tp = meshShape.tet_positions;
+    const N = tm.count;
+
+    // Scale-relative epsilon for the convexity test.
+    const bb = new Float64Array(6);
+    meshShape.compute_bounding_box(bb);
+    const diag = Math.hypot(bb[3] - bb[0], bb[4] - bb[1], bb[5] - bb[2]) || 1;
+    const EPS = 1e-6 * diag;
+
+    // Tet vertices (global indices) and the 4 faces (each: 3 face verts + the
+    // opposite vertex, for outward orientation).
+    const tetV = new Int32Array(N * 4);
+    for (let t = 0; t < N; t++) {
+        for (let i = 0; i < 4; i++) tetV[t * 4 + i] = tm.getVertexIndex(t, i);
+    }
+
+    // Adjacency: face-key → list of (tet) owners. Two tets sharing a face are
+    // neighbours. Exact triple stored alongside to resolve hash collisions.
+    const faceOwners = new Map(); // key → array of { tet, fi }
+    for (let t = 0; t < N; t++) {
+        for (let f = 0; f < 4; f++) {
+            const o = FACE_OPP[f];
+            const a = tetV[t * 4 + o[0]], b = tetV[t * 4 + o[1]], c = tetV[t * 4 + o[2]];
+            const k = face_key(a, b, c);
+            let arr = faceOwners.get(k);
+            if (arr === undefined) { arr = []; faceOwners.set(k, arr); }
+            arr.push({ tet: t, fi: f, a, b, c });
+        }
+    }
+    // tet → neighbour tets (sharing a face).
+    const neighbours = (t) => {
+        const out = [];
+        for (let f = 0; f < 4; f++) {
+            const o = FACE_OPP[f];
+            const a = tetV[t * 4 + o[0]], b = tetV[t * 4 + o[1]], c = tetV[t * 4 + o[2]];
+            const arr = faceOwners.get(face_key(a, b, c));
+            if (arr === undefined) continue;
+            for (const e of arr) if (e.tet !== t) out.push(e.tet);
+        }
+        return out;
+    };
+
+    const visited = new Uint8Array(N);
+    const pieces = [];
+
+    // Reusable boundary structure for the growing piece: key → oriented face.
+    for (let seed = 0; seed < N; seed++) {
+        if (visited[seed]) continue;
+
+        const boundary = new Map(); // key → {a,b,c (oriented), nx,ny,nz}
+        const pieceVerts = new Set();
+        const pieceTets = [];
+
+        // Toggle a tet's 4 faces against the boundary (its own inverse): a face
+        // shared with a piece tet cancels (becomes interior). Store just the
+        // triple — orientation is resolved later from the piece centroid.
+        const toggle_tet_faces = (t) => {
+            for (let f = 0; f < 4; f++) {
+                const o = FACE_OPP[f];
+                const a = tetV[t * 4 + o[0]], b = tetV[t * 4 + o[1]], c = tetV[t * 4 + o[2]];
+                const k = face_key(a, b, c);
+                if (boundary.has(k)) boundary.delete(k);
+                else boundary.set(k, { a, b, c });
+            }
+        };
+        const add_verts = (t) => { for (let i = 0; i < 4; i++) pieceVerts.add(tetV[t * 4 + i]); };
+
+        // Convex iff every boundary-face PLANE is supporting: all vertices lie
+        // on one side of it. Orientation-free — no need to know which side is
+        // outward, so it's immune to sliver/orientation issues.
+        const convex_with = (candVerts) => {
+            for (const [, fc] of boundary) {
+                const ax = tp[fc.a * 3], ay = tp[fc.a * 3 + 1], az = tp[fc.a * 3 + 2];
+                const e1x = tp[fc.b * 3] - ax, e1y = tp[fc.b * 3 + 1] - ay, e1z = tp[fc.b * 3 + 2] - az;
+                const e2x = tp[fc.c * 3] - ax, e2y = tp[fc.c * 3 + 1] - ay, e2z = tp[fc.c * 3 + 2] - az;
+                let nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
+                const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+                nx /= len; ny /= len; nz /= len;
+                let pos = false, neg = false;
+                for (const v of pieceVerts) {
+                    const d = nx * (tp[v * 3] - ax) + ny * (tp[v * 3 + 1] - ay) + nz * (tp[v * 3 + 2] - az);
+                    if (d > EPS) pos = true; else if (d < -EPS) neg = true;
+                    if (pos && neg) return false;
+                }
+                for (let i = 0; i < 4; i++) {
+                    const v = candVerts[i];
+                    const d = nx * (tp[v * 3] - ax) + ny * (tp[v * 3 + 1] - ay) + nz * (tp[v * 3 + 2] - az);
+                    if (d > EPS) pos = true; else if (d < -EPS) neg = true;
+                    if (pos && neg) return false;
+                }
+            }
+            return true;
+        };
+
+        visited[seed] = 1;
+        pieceTets.push(seed);
+        toggle_tet_faces(seed);
+        add_verts(seed);
+
+        const tried = new Set([seed]);
+        const frontier = neighbours(seed);
+        for (const n of frontier) tried.add(n);
+
+        while (frontier.length > 0) {
+            const t = frontier.pop();
+            if (visited[t]) continue;
+
+            // Tentatively add t: toggle its faces into the boundary, test
+            // convexity, then commit or revert (toggle is its own inverse).
+            const cand = [tetV[t * 4], tetV[t * 4 + 1], tetV[t * 4 + 2], tetV[t * 4 + 3]];
+            toggle_tet_faces(t);
+            if (convex_with(cand)) {
+                visited[t] = 1;
+                pieceTets.push(t);
+                add_verts(t);
+                for (const n of neighbours(t)) {
+                    if (!visited[n] && !tried.has(n)) { tried.add(n); frontier.push(n); }
+                }
+            } else {
+                toggle_tet_faces(t); // revert
+            }
+        }
+
+        pieces.push(build_piece(tp, boundary));
+    }
+
+    // BVH over piece local AABBs.
+    const bvh = new BVH();
+    bvh.release_all();
+    bvh.node_capacity = Math.max(1, pieces.length * 2 - 1);
+    for (let i = 0; i < pieces.length; i++) {
+        const node = bvh.allocate_node();
+        const a = pieces[i].aabb;
+        bvh.node_set_aabb_primitive(node, a[0], a[1], a[2], a[3], a[4], a[5]);
+        bvh.node_set_user_data(node, i);
+        bvh.insert_leaf(node);
+    }
+
+    return { pieces, bvh };
+}
+
+/** Build a clippable piece from its boundary triangles: coplanar-merge into
+ *  polygon faces and localise vertex indices. `boundary` is a Map keyed by
+ *  face_key → {a,b,c} (any winding; orientation is re-derived from the piece
+ *  centroid). Exported so the convex-mesh fast path can build a single
+ *  coplanar-merged hull from a whole mesh's boundary. */
+export function build_piece(tp, boundary) {
+    // Piece centroid (from boundary vertices) — strictly interior for a convex
+    // piece, so it orients every face normal outward unambiguously.
+    const cset = new Set();
+    for (const [, fc] of boundary) { cset.add(fc.a); cset.add(fc.b); cset.add(fc.c); }
+    let pcx = 0, pcy = 0, pcz = 0;
+    for (const v of cset) { pcx += tp[v * 3]; pcy += tp[v * 3 + 1]; pcz += tp[v * 3 + 2]; }
+    const pn = cset.size || 1; pcx /= pn; pcy /= pn; pcz /= pn;
+
+    // Group boundary triangles by plane; each normal oriented away from the centroid.
+    const groups = []; // { nx,ny,nz, off, tris: [[a,b,c], ...] }
+    for (const [, fc] of boundary) {
+        const ax = tp[fc.a * 3], ay = tp[fc.a * 3 + 1], az = tp[fc.a * 3 + 2];
+        const e1x = tp[fc.b * 3] - ax, e1y = tp[fc.b * 3 + 1] - ay, e1z = tp[fc.b * 3 + 2] - az;
+        const e2x = tp[fc.c * 3] - ax, e2y = tp[fc.c * 3 + 1] - ay, e2z = tp[fc.c * 3 + 2] - az;
+        let nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
+        const len = Math.hypot(nx, ny, nz) || 1;
+        nx /= len; ny /= len; nz /= len;
+        if (nx * (ax - pcx) + ny * (ay - pcy) + nz * (az - pcz) < 0) { nx = -nx; ny = -ny; nz = -nz; }
+        const off = nx * ax + ny * ay + nz * az;
+        let g = null;
+        for (const cand of groups) {
+            if (Math.abs(cand.nx * nx + cand.ny * ny + cand.nz * nz - 1) < PLANE_NORMAL_TOL
+                && Math.abs(cand.off - off) < PLANE_OFFSET_TOL) { g = cand; break; }
+        }
+        if (g === null) { g = { nx, ny, nz, off, tris: [] }; groups.push(g); }
+        g.tris.push([fc.a, fc.b, fc.c]);
+    }
+
+    // Per group: each face of a convex piece is a convex polygon, so order its
+    // (boundary) vertices by angle around the face centroid in the plane, CCW
+    // w.r.t. the known outward normal. Robust regardless of triangulation.
+    const loops = []; // arrays of global vertex indices, CCW outward
+    for (const g of groups) {
+        const vset = new Set();
+        for (const [a, b, c] of g.tris) { vset.add(a); vset.add(b); vset.add(c); }
+        if (vset.size < 3) continue;
+        const varr = Array.from(vset);
+
+        let cx = 0, cy = 0, cz = 0;
+        for (const gv of varr) { cx += tp[gv * 3]; cy += tp[gv * 3 + 1]; cz += tp[gv * 3 + 2]; }
+        const inv = 1 / varr.length; cx *= inv; cy *= inv; cz *= inv;
+
+        // In-plane basis (u, v=n×u) from the outward normal n.
+        const nx = g.nx, ny = g.ny, nz = g.nz;
+        let ux, uy, uz;
+        const ax = Math.abs(nx), ay = Math.abs(ny), az = Math.abs(nz);
+        if (ax <= ay && ax <= az) { ux = 0; uy = -nz; uz = ny; }
+        else if (ay <= az) { ux = -nz; uy = 0; uz = nx; }
+        else { ux = -ny; uy = nx; uz = 0; }
+        const ul = Math.hypot(ux, uy, uz) || 1; ux /= ul; uy /= ul; uz /= ul;
+        const vx = ny * uz - nz * uy, vy = nz * ux - nx * uz, vz = nx * uy - ny * ux;
+
+        const items = varr.map((gv) => {
+            const dx = tp[gv * 3] - cx, dy = tp[gv * 3 + 1] - cy, dz = tp[gv * 3 + 2] - cz;
+            return { gv, ang: Math.atan2(dx * vx + dy * vy + dz * vz, dx * ux + dy * uy + dz * uz) };
+        });
+        items.sort((p, q) => p.ang - q.ang);
+        loops.push(items.map((it) => it.gv));
+    }
+
+    // Localise vertices used by the loops.
+    const remap = new Map();
+    const verts = [];
+    const local_of = (g) => {
+        let l = remap.get(g);
+        if (l === undefined) {
+            l = verts.length / 3;
+            verts.push(tp[g * 3], tp[g * 3 + 1], tp[g * 3 + 2]);
+            remap.set(g, l);
+        }
+        return l;
+    };
+    const face_offsets = new Uint32Array(loops.length + 1);
+    const loop_flat = [];
+    for (let i = 0; i < loops.length; i++) {
+        face_offsets[i] = loop_flat.length;
+        for (const g of loops[i]) loop_flat.push(local_of(g));
+    }
+    face_offsets[loops.length] = loop_flat.length;
+
+    const vertices = new Float32Array(verts);
+    const aabb = new Float64Array(6);
+    let mnx = Infinity, mny = Infinity, mnz = Infinity, mxx = -Infinity, mxy = -Infinity, mxz = -Infinity;
+    for (let i = 0; i < vertices.length / 3; i++) {
+        const x = vertices[i * 3], y = vertices[i * 3 + 1], z = vertices[i * 3 + 2];
+        if (x < mnx) mnx = x; if (x > mxx) mxx = x;
+        if (y < mny) mny = y; if (y > mxy) mxy = y;
+        if (z < mnz) mnz = z; if (z > mxz) mxz = z;
+    }
+    aabb[0] = mnx; aabb[1] = mny; aabb[2] = mnz; aabb[3] = mxx; aabb[4] = mxy; aabb[5] = mxz;
+
+    return { vertices, face_offsets, face_loops: new Uint32Array(loop_flat), aabb };
+}

package/src/engine/physics/narrowphase/mesh_convex_hull.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Convex fast path for a triangulated {@link MeshShape3D}: if the whole mesh is
+ * convex, represent it as a single coplanar-merged convex piece so it collides
+ * via one GJK + EPA + face-clip manifold (O(support queries)) instead of being
+ * greedily decomposed into many small SAT pieces.
+ *
+ * Why this matters: the greedy convex decomposition fragments even a convex mesh
+ * (a partial union of tets is generally NOT convex, so the order-dependent grow
+ * can't reconstruct the single convex region — a curved convex surface splits
+ * into dozens of pieces). Detecting global convexity and emitting ONE piece
+ * collapses that to a single collider, the path to large convex meshes.
+ *
+ * The piece is built by {@link build_piece} from the mesh's whole boundary, so
+ * its faces are coplanar-MERGED polygons (a box → 6 quads, not 12 triangles) —
+ * essential for the clipper to produce a full face-on-face patch rather than
+ * triangle slivers. A `support()` is attached (linear scan over the piece's
+ * localised surface vertices, so it stays O(surface), not O(all tets)).
+ *
+ * Cached on the (immutable) shape as `__convex_hull`: the piece if convex, or
+ * `null` if concave. Returned verbatim on subsequent calls.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @param {{tet_mesh, tet_positions, compute_bounding_box}} meshShape
+ * @returns {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array, aabb:Float64Array, support:Function}|null}
+ *   a single coplanar-merged convex piece (with support) if the mesh is convex, else null
+ */
+export function get_mesh_convex_hull(meshShape: {
+    tet_mesh;
+    tet_positions;
+    compute_bounding_box;
+}): {
+    vertices: Float32Array;
+    face_offsets: Uint32Array;
+    face_loops: Uint32Array;
+    aabb: Float64Array;
+    support: Function;
+} | null;
+//# sourceMappingURL=mesh_convex_hull.d.ts.map

package/src/engine/physics/narrowphase/mesh_convex_hull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh_convex_hull.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/mesh_convex_hull.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,gDAJW;IAAC,QAAQ,CAAC;IAAC,aAAa,CAAC;IAAC,oBAAoB,CAAA;CAAC,GAC7C;IAAC,QAAQ,EAAC,YAAY,CAAC;IAAC,YAAY,EAAC,WAAW,CAAC;IAAC,UAAU,EAAC,WAAW,CAAC;IAAC,IAAI,EAAC,YAAY,CAAC;IAAC,OAAO,WAAS;CAAC,GAAC,IAAI,CAQ/H"}

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

@@ -0,0 +1,106 @@
+import { build_piece, face_key, FACE_OPP } from "./convex_decomposition.js";
+
+/**
+ * Convex fast path for a triangulated {@link MeshShape3D}: if the whole mesh is
+ * convex, represent it as a single coplanar-merged convex piece so it collides
+ * via one GJK + EPA + face-clip manifold (O(support queries)) instead of being
+ * greedily decomposed into many small SAT pieces.
+ *
+ * Why this matters: the greedy convex decomposition fragments even a convex mesh
+ * (a partial union of tets is generally NOT convex, so the order-dependent grow
+ * can't reconstruct the single convex region — a curved convex surface splits
+ * into dozens of pieces). Detecting global convexity and emitting ONE piece
+ * collapses that to a single collider, the path to large convex meshes.
+ *
+ * The piece is built by {@link build_piece} from the mesh's whole boundary, so
+ * its faces are coplanar-MERGED polygons (a box → 6 quads, not 12 triangles) —
+ * essential for the clipper to produce a full face-on-face patch rather than
+ * triangle slivers. A `support()` is attached (linear scan over the piece's
+ * localised surface vertices, so it stays O(surface), not O(all tets)).
+ *
+ * Cached on the (immutable) shape as `__convex_hull`: the piece if convex, or
+ * `null` if concave. Returned verbatim on subsequent calls.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @param {{tet_mesh, tet_positions, compute_bounding_box}} meshShape
+ * @returns {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array, aabb:Float64Array, support:Function}|null}
+ *   a single coplanar-merged convex piece (with support) if the mesh is convex, else null
+ */
+export function get_mesh_convex_hull(meshShape) {
+    if (meshShape.__convex_hull !== undefined) return meshShape.__convex_hull;
+    const hull = build_if_convex(meshShape);
+    meshShape.__convex_hull = hull;
+    return hull;
+}
+
+function build_if_convex(meshShape) {
+    const tm = meshShape.tet_mesh;
+    const tp = meshShape.tet_positions;
+    const N = tm.count;
+    if (N === 0) return null;
+
+    const bb = new Float64Array(6);
+    meshShape.compute_bounding_box(bb);
+    const diag = Math.hypot(bb[3] - bb[0], bb[4] - bb[1], bb[5] - bb[2]) || 1;
+    const EPS = 1e-6 * diag;
+
+    // Boundary faces = those owned by exactly one tet. Keep the owning tet's
+    // opposite vertex to orient the face outward for the convexity test.
+    const owners = new Map(); // key → { a, b, c, opp, count }
+    for (let t = 0; t < N; t++) {
+        for (let f = 0; f < 4; f++) {
+            const o = FACE_OPP[f];
+            const a = tm.getVertexIndex(t, o[0]);
+            const b = tm.getVertexIndex(t, o[1]);
+            const c = tm.getVertexIndex(t, o[2]);
+            const opp = tm.getVertexIndex(t, o[3]);
+            const k = face_key(a, b, c);
+            const e = owners.get(k);
+            if (e === undefined) owners.set(k, { a, b, c, opp, count: 1 });
+            else e.count++;
+        }
+    }
+
+    // Convexity: every vertex behind (or on) every boundary-face plane.
+    const nVerts = tp.length / 3;
+    const boundary = new Map(); // key → {a,b,c} for build_piece
+    let boundaryCount = 0;
+    for (const [k, fc] of owners) {
+        if (fc.count !== 1) continue;
+        boundaryCount++;
+        const ax = tp[fc.a * 3], ay = tp[fc.a * 3 + 1], az = tp[fc.a * 3 + 2];
+        const e1x = tp[fc.b * 3] - ax, e1y = tp[fc.b * 3 + 1] - ay, e1z = tp[fc.b * 3 + 2] - az;
+        const e2x = tp[fc.c * 3] - ax, e2y = tp[fc.c * 3 + 1] - ay, e2z = tp[fc.c * 3 + 2] - az;
+        let nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
+        const ox = tp[fc.opp * 3] - ax, oy = tp[fc.opp * 3 + 1] - ay, oz = tp[fc.opp * 3 + 2] - az;
+        if (nx * ox + ny * oy + nz * oz > 0) { nx = -nx; ny = -ny; nz = -nz; } // outward
+        const len = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1;
+        const ix = nx / len, iy = ny / len, iz = nz / len;
+        for (let v = 0; v < nVerts; v++) {
+            const d = ix * (tp[v * 3] - ax) + iy * (tp[v * 3 + 1] - ay) + iz * (tp[v * 3 + 2] - az);
+            if (d > EPS) return null; // a vertex in front of a face → concave
+        }
+        boundary.set(k, { a: fc.a, b: fc.b, c: fc.c });
+    }
+    if (boundaryCount < 4) return null; // not a closed volume
+
+    // Coplanar-merged hull piece + a linear-scan support over its local verts.
+    const piece = build_piece(tp, boundary);
+    const v = piece.vertices;
+    const vc = v.length / 3;
+    piece.support = function (result, result_offset, dx, dy, dz) {
+        let bi = 0, best = -Infinity;
+        for (let i = 0; i < vc; i++) {
+            const d = dx * v[i * 3] + dy * v[i * 3 + 1] + dz * v[i * 3 + 2];
+            if (d > best) { best = d; bi = i; }
+        }
+        result[result_offset] = v[bi * 3];
+        result[result_offset + 1] = v[bi * 3 + 1];
+        result[result_offset + 2] = v[bi * 3 + 2];
+    };
+    return piece;
+}

package/src/engine/physics/narrowphase/mesh_mesh_tet_manifold.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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: any, shapeA: any, trA: any, shapeB: any, trB: any, append: any): number;
+//# sourceMappingURL=mesh_mesh_tet_manifold.d.ts.map

package/src/engine/physics/narrowphase/mesh_mesh_tet_manifold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh_mesh_tet_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/mesh_mesh_tet_manifold.js"],"names":[],"mappings":"AAkDA;;;;;GAKG;AACH,+GAFa,MAAM,CA8DlB"}

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

@@ -0,0 +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;
+}

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":"AA8zCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CAyClB;AAED;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QA4KlE;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,QAkH3D"}
+{"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"}