@woosh/meep-engine 2.155.0 → 2.157.0

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

@@ -1,13 +1,19 @@
-export function face_key(a: any, b: any, c: any): string;
 /**
- * @param {{tet_mesh, tet_positions, compute_bounding_box}} meshShape
+ * Exact, collision-free, order-independent key for a triangle's vertex triple:
+ * the three indices sorted ascending and joined with commas, so two faces with
+ * the same vertex set (any winding) map to the same key.
+ *
+ * @param {number} a first vertex index
+ * @param {number} b second vertex index
+ * @param {number} c third vertex index
+ * @returns {string} canonical `"x,y,z"` key with x ≤ y ≤ z
+ */
+export function face_key(a: number, b: number, c: number): string;
+/**
+ * @param {MeshShape3D} meshShape
  * @returns {{pieces: Array<{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array, aabb:Float64Array}>, bvh: BVH}}
  */
-export function build_convex_decomposition(meshShape: {
-    tet_mesh;
-    tet_positions;
-    compute_bounding_box;
-}): {
+export function build_convex_decomposition(meshShape: MeshShape3D): {
     pieces: Array<{
         vertices: Float32Array;
         face_offsets: Uint32Array;
@@ -16,12 +22,25 @@ export function build_convex_decomposition(meshShape: {
     }>;
     bvh: 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: any, boundary: any): {
+/**
+ * Build a clippable piece from its boundary triangles: coplanar-merge them into
+ * polygon faces and localise the vertex indices. Orientation is re-derived from
+ * the piece centroid, so the `boundary` triples may have any winding. Exported
+ * so the convex-mesh fast path ({@link mesh_convex_hull}) can build a single
+ * coplanar-merged hull from a whole mesh's boundary.
+ *
+ * @param {Float32Array|Float64Array|number[]} tp tet positions: flat `(x, y, z)`
+ *   per vertex, indexed by global vertex index
+ * @param {Map<string, {a:number, b:number, c:number}>} boundary boundary faces
+ *   keyed by {@link face_key}; each value is a vertex triple (any winding)
+ * @returns {{vertices: Float32Array, face_offsets: Uint32Array, face_loops: Uint32Array, aabb: Float64Array}}
+ *   a clippable convex piece — local vertices, CSR polygon-face loops, and local AABB
+ */
+export function build_piece(tp: Float32Array | Float64Array | number[], boundary: Map<string, {
+    a: number;
+    b: number;
+    c: number;
+}>): {
     vertices: Float32Array;
     face_offsets: Uint32Array;
     face_loops: Uint32Array;

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

@@ -1 +1 @@
-{"version":3,"file":"convex_decomposition.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/convex_decomposition.js"],"names":[],"mappings":"AAsCA,yDAOC;AAED;;;GAGG;AACH,sDAHW;IAAC,QAAQ,CAAC;IAAC,aAAa,CAAC;IAAC,oBAAoB,CAAA;CAAC;YACpC,MAAM;QAAC,QAAQ,EAAC,YAAY,CAAC;QAAC,YAAY,EAAC,WAAW,CAAC;QAAC,UAAU,EAAC,WAAW,CAAC;QAAC,IAAI,EAAC,YAAY,CAAA;KAAC,CAAC;SAAO,GAAG;EA+IlI;AAED;;;;yDAIyD;AACzD;;;;;EA6FC;AAhQD,kCAAiF;oBApC7D,gCAAgC"}
+{"version":3,"file":"convex_decomposition.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/convex_decomposition.js"],"names":[],"mappings":"AA4CA;;;;;;;;;GASG;AACH,4BALW,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAQlB;AAED;;;GAGG;AACH;YAFsB,MAAM;QAAC,QAAQ,EAAC,YAAY,CAAC;QAAC,YAAY,EAAC,WAAW,CAAC;QAAC,UAAU,EAAC,WAAW,CAAC;QAAC,IAAI,EAAC,YAAY,CAAA;KAAC,CAAC;SAAO,GAAG;EAmHlI;AAED;;;;;;;;;;;;;GAaG;AACH,gCAPW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,YAElC,IAAI,MAAM,EAAE;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,CAAC;cAE9B,YAAY;kBAAgB,WAAW;gBAAc,WAAW;UAAQ,YAAY;EAgG3G;AAzPD,kCAAiF;oBAvC7D,gCAAgC"}

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

@@ -1,4 +1,7 @@
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+import { v3_compute_triangle_normal } from "../../../core/geom/3d/triangle/v3_compute_triangle_normal.js";
+import { tetrahedral_mesh_tet_get_neighbours } from "../../../core/geom/3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js";
+import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
 
 /**
  * Greedy convex decomposition of a tetrahedralised mesh into a small set of
@@ -36,8 +39,20 @@ const PLANE_OFFSET_TOL = 1e-4;
 // 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]];
 
+// Reusable scratch for v3_compute_triangle_normal (writes a unit normal as 3 floats).
+const _face_normal = new Float64Array(3);
+
+/**
+ * Exact, collision-free, order-independent key for a triangle's vertex triple:
+ * the three indices sorted ascending and joined with commas, so two faces with
+ * the same vertex set (any winding) map to the same key.
+ *
+ * @param {number} a first vertex index
+ * @param {number} b second vertex index
+ * @param {number} c third vertex index
+ * @returns {string} canonical `"x,y,z"` key with x ≤ y ≤ z
+ */
 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; }
@@ -46,7 +61,7 @@ export function face_key(a, b, c) {
 }
 
 /**
- * @param {{tet_mesh, tet_positions, compute_bounding_box}} meshShape
+ * @param {MeshShape3D} meshShape
  * @returns {{pieces: Array<{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array, aabb:Float64Array}>, bvh: BVH}}
  */
 export function build_convex_decomposition(meshShape) {
@@ -60,49 +75,20 @@ export function build_convex_decomposition(meshShape) {
     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 = [];
 
+    // Per-tet face neighbours are read straight from the mesh's stored adjacency
+    // via tetrahedral_mesh_tet_get_neighbours; this is its reusable output scratch
+    // (a tet has at most 4 face neighbours).
+    const tet_neighbours = new Int32Array(4);
+
     // 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
@@ -110,13 +96,13 @@ export function build_convex_decomposition(meshShape) {
         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 a = tm.getVertexIndex(t, o[0]), b = tm.getVertexIndex(t, o[1]), c = tm.getVertexIndex(t, 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]); };
+        const add_verts = (t) => { for (let i = 0; i < 4; i++) pieceVerts.add(tm.getVertexIndex(t, 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
@@ -124,20 +110,20 @@ export function build_convex_decomposition(meshShape) {
         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;
+                v3_compute_triangle_normal(_face_normal, 0,
+                    ax, ay, az,
+                    tp[fc.b * 3], tp[fc.b * 3 + 1], tp[fc.b * 3 + 2],
+                    tp[fc.c * 3], tp[fc.c * 3 + 1], tp[fc.c * 3 + 2]);
+                const nx = _face_normal[0], ny = _face_normal[1], nz = _face_normal[2];
                 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);
+                    const d = v3_dot(nx, ny, nz, tp[v * 3] - ax, tp[v * 3 + 1] - ay, 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);
+                    const d = v3_dot(nx, ny, nz, tp[v * 3] - ax, tp[v * 3 + 1] - ay, tp[v * 3 + 2] - az);
                     if (d > EPS) pos = true; else if (d < -EPS) neg = true;
                     if (pos && neg) return false;
                 }
@@ -146,13 +132,13 @@ export function build_convex_decomposition(meshShape) {
         };
 
         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);
+        const frontier = [];
+        const seed_nbr_count = tetrahedral_mesh_tet_get_neighbours(tm, tet_neighbours, 0, seed);
+        for (let i = 0; i < seed_nbr_count; i++) { frontier.push(tet_neighbours[i]); tried.add(tet_neighbours[i]); }
 
         while (frontier.length > 0) {
             const t = frontier.pop();
@@ -160,13 +146,14 @@ export function build_convex_decomposition(meshShape) {
 
             // 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]];
+            const cand = [tm.getVertexIndex(t, 0), tm.getVertexIndex(t, 1), tm.getVertexIndex(t, 2), tm.getVertexIndex(t, 3)];
             toggle_tet_faces(t);
             if (convex_with(cand)) {
                 visited[t] = 1;
-                pieceTets.push(t);
                 add_verts(t);
-                for (const n of neighbours(t)) {
+                const nbr_count = tetrahedral_mesh_tet_get_neighbours(tm, tet_neighbours, 0, t);
+                for (let i = 0; i < nbr_count; i++) {
+                    const n = tet_neighbours[i];
                     if (!visited[n] && !tried.has(n)) { tried.add(n); frontier.push(n); }
                 }
             } else {
@@ -192,11 +179,20 @@ export function build_convex_decomposition(meshShape) {
     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. */
+/**
+ * Build a clippable piece from its boundary triangles: coplanar-merge them into
+ * polygon faces and localise the vertex indices. Orientation is re-derived from
+ * the piece centroid, so the `boundary` triples may have any winding. Exported
+ * so the convex-mesh fast path ({@link mesh_convex_hull}) can build a single
+ * coplanar-merged hull from a whole mesh's boundary.
+ *
+ * @param {Float32Array|Float64Array|number[]} tp tet positions: flat `(x, y, z)`
+ *   per vertex, indexed by global vertex index
+ * @param {Map<string, {a:number, b:number, c:number}>} boundary boundary faces
+ *   keyed by {@link face_key}; each value is a vertex triple (any winding)
+ * @returns {{vertices: Float32Array, face_offsets: Uint32Array, face_loops: Uint32Array, aabb: Float64Array}}
+ *   a clippable convex piece — local vertices, CSR polygon-face loops, and local AABB
+ */
 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.
@@ -210,16 +206,16 @@ export function build_piece(tp, boundary) {
     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;
+        v3_compute_triangle_normal(_face_normal, 0,
+            ax, ay, az,
+            tp[fc.b * 3], tp[fc.b * 3 + 1], tp[fc.b * 3 + 2],
+            tp[fc.c * 3], tp[fc.c * 3 + 1], tp[fc.c * 3 + 2]);
+        let nx = _face_normal[0], ny = _face_normal[1], nz = _face_normal[2];
+        if (v3_dot(nx, ny, nz, ax - pcx, ay - pcy, az - pcz) < 0) { nx = -nx; ny = -ny; nz = -nz; }
+        const off = v3_dot(nx, ny, nz, ax, ay, 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
+            if (Math.abs(v3_dot(cand.nx, cand.ny, cand.nz, nx, ny, 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); }
@@ -252,7 +248,7 @@ export function build_piece(tp, boundary) {
 
         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) };
+            return { gv, ang: Math.atan2(v3_dot(dx, dy, dz, vx, vy, vz), v3_dot(dx, dy, dz, ux, uy, uz)) };
         });
         items.sort((p, q) => p.ang - q.ang);
         loops.push(items.map((it) => it.gv));

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"}