@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -12,13 +12,14 @@
  * is reordered in place and the caller reads the first `maxKept` records.
  *
  * Shared by {@link box_box_manifold} / {@link convex_convex_manifold} (stride 4,
- * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and the
- * narrowphase dispatcher's pair-candidate buffer (stride 13, depth lane 9 —
- * lanes 10..12 are feature id / friction / restitution). Each previously
- * carried its own byte-identical copy.
+ * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and,
+ * through {@link reduce_manifold_contacts_by_plane} when its candidates lie on
+ * one plane, the narrowphase dispatcher's pair-candidate buffer (stride 14,
+ * depth lane 9 — lanes 10..13 are feature id / friction / restitution / flags).
+ * Each previously carried its own byte-identical copy.
  *
  * `depth_lane` is deliberately REQUIRED, not defaulted to `stride - 1`: the
- * candidate layouts genuinely differ (the dispatcher's lane 12 is RESTITUTION),
+ * candidate layouts genuinely differ (the dispatcher's last lane is FLAGS),
  * and a stride-derived default is exactly the trap that would silently rank
  * contacts by the wrong lane (REVIEW_003 E2).
  *
@@ -33,4 +34,54 @@
  * @copyright Company Named Limited (c) 2026
  */
 export function reduce_manifold_contacts(buf: Float64Array, n: number, stride: number, maxKept: number, depth_lane: number): number;
+/**
+ * In-place reduction of a body pair's contact candidates to at most `maxKept`, sharing the slots
+ * between the planes the contacts lie on.
+ *
+ * One body pair's candidates can lie on several surfaces at once: a floor and a wall, a floor and a
+ * ramp, the faces of two colliders. {@link reduce_manifold_contacts} keeps the deepest and then the
+ * widest spread, blind to the normals, so one surface could take every slot and leave another none. A
+ * cube sliding along a floor and a wall cut from one mesh had no floor contact in 40 of 240 frames, and
+ * a box meeting a 45° flank square along its leading edge kept one contact on the flank, turned about
+ * it and sank twice the step that carried it in (107 mm at 3 m/s, where the step is 50 mm).
+ *
+ * Here the candidates are grouped into planes by normal (cosine above {@link PLANE_COS}), and
+ *   1. each plane's deepest candidate takes a slot, the deepest planes first — slot 0 is the deepest
+ *      of all, as before;
+ *   2. the planes then take turns adding the candidate farthest from the points they already keep (the
+ *      far end of an edge, the opposite corner of a face) until the slots are full.
+ * Candidates on one plane — every box resting on a floor — are reduced by
+ * {@link reduce_manifold_contacts} itself, unchanged.
+ *
+ * Box3D keeps up to four points for every plane, each its own manifold (mesh_contact.c,
+ * `b3ComputeMeshManifolds`, MIT, Erin Catto). Here the planes share {@link MAX_CONTACTS_PER_MANIFOLD}
+ * slots, so a cube pressed into a corner gets two contacts on the floor and two on the wall where Box3D,
+ * or two separate bodies, would give it four and four — and still rocks as it slides along the corner.
+ *
+ * A candidate founds no plane when a deeper candidate at the same point already pushes it out: when
+ * moving the body that deeper depth along the deeper normal clears it too
+ * (`depth ≤ deeper_depth · (normal · deeper_normal)`). A flat face resting on a sharp convex edge of a
+ * mesh gets, beside its own contacts, contacts on the planes of the edge's two faces, each the face's
+ * depth projected on that plane; given slots of their own they pushed a box resting on two knife-edged
+ * rails sideways off them. A wall's contact at the bottom corner of a box in a corner is not like that:
+ * the wall's push does nothing for the floor's.
+ *
+ * Nor does a plane that is a curb under another ({@link is_curb_under}): a wall met only within the
+ * depth a body has sunk into the floor beside it, as the far rim of a slot is. Its contacts are left out
+ * altogether — lifting the body out of the floor clears them.
+ *
+ * Planes are told apart by normal alone, not by which collider pair made them: a compound slab of six
+ * boxes resting on a floor is one plane whose four slots span the slab. Told apart, its colliders were
+ * six planes, four of them got one corner each, and the slab never slept and sank 11 mm (a 4×4 slab:
+ * 35 to 67 mm).
+ *
+ * @param {Float64Array} buf  strided candidate buffer, position at lanes 0..2
+ * @param {number} n          input candidate count
+ * @param {number} stride     floats per candidate
+ * @param {number} maxKept    maximum candidates to keep
+ * @param {number} depth_lane lane holding penetration depth
+ * @param {number} normal_lane first of the three lanes holding the unit normal
+ * @returns {number} kept count, at most min(n, maxKept); the kept candidates are the first records
+ */
+export function reduce_manifold_contacts_by_plane(buf: Float64Array, n: number, stride: number, maxKept: number, depth_lane: number, normal_lane: number): number;
 //# sourceMappingURL=reduce_manifold_contacts.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"reduce_manifold_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/reduce_manifold_contacts.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,8CAVW,YAAY,KACZ,MAAM,UACN,MAAM,WACN,MAAM,cACN,MAAM,GACJ,MAAM,CAmClB"}
+{"version":3,"file":"reduce_manifold_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/reduce_manifold_contacts.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8CAVW,YAAY,KACZ,MAAM,UACN,MAAM,WACN,MAAM,cACN,MAAM,GACJ,MAAM,CAmClB;AAmED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,uDARW,YAAY,KACZ,MAAM,UACN,MAAM,WACN,MAAM,cACN,MAAM,eACN,MAAM,GACJ,MAAM,CAyKlB"}

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

@@ -12,13 +12,14 @@
  * is reordered in place and the caller reads the first `maxKept` records.
  *
  * Shared by {@link box_box_manifold} / {@link convex_convex_manifold} (stride 4,
- * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and the
- * narrowphase dispatcher's pair-candidate buffer (stride 13, depth lane 9 —
- * lanes 10..12 are feature id / friction / restitution). Each previously
- * carried its own byte-identical copy.
+ * depth lane 3), {@link box_triangle_contact} (stride 7, depth lane 6) and,
+ * through {@link reduce_manifold_contacts_by_plane} when its candidates lie on
+ * one plane, the narrowphase dispatcher's pair-candidate buffer (stride 14,
+ * depth lane 9 — lanes 10..13 are feature id / friction / restitution / flags).
+ * Each previously carried its own byte-identical copy.
  *
  * `depth_lane` is deliberately REQUIRED, not defaulted to `stride - 1`: the
- * candidate layouts genuinely differ (the dispatcher's lane 12 is RESTITUTION),
+ * candidate layouts genuinely differ (the dispatcher's last lane is FLAGS),
  * and a stride-derived default is exactly the trap that would silently rank
  * contacts by the wrong lane (REVIEW_003 E2).
  *
@@ -64,6 +65,546 @@ export function reduce_manifold_contacts(buf, n, stride, maxKept, depth_lane) {
     return maxKept;
 }
 
+/**
+ * Two contact normals whose cosine is at most this lie on different planes: Box3D's cluster tolerance
+ * for mesh manifolds (mesh_contact.c, `b3ComputeMeshManifolds`), about 5°.
+ * @type {number}
+ */
+const PLANE_COS = 0.996;
+
+/**
+ * How many candidates the search for a further plane passes over as already pushed out, or planes it
+ * drops as curbs (see {@link reduce_manifold_contacts_by_plane}), before it settles for the planes it has.
+ * A bound on the cost — each pass scans the candidates — not a tolerance.
+ * @type {number}
+ */
+const MAX_PUSHED_OUT_SKIPS = 8;
+
+/**
+ * Two contacts are at one point when they lie within the deeper one's depth plus this, m. Two
+ * surfaces' contacts at one corner of a body sit up to about that depth apart, each on its own surface.
+ * @type {number}
+ */
+const SAME_POINT_SLACK = 0.001;
+
+/**
+ * Depth slack of "already pushed out", m: rounding only.
+ * @type {number}
+ */
+const PUSHED_OUT_SLACK = 1e-6;
+
+/**
+ * A further point of a plane must lie farther than this (squared, m²: 1 mm) from the points the plane
+ * already keeps; a nearer one adds nothing.
+ * @type {number}
+ */
+const SPREAD_MIN_D2 = 1e-6;
+
+/** Candidate index of each plane's deepest candidate, in the order the planes were found. */
+let plane_seed = new Int32Array(4);
+
+/**
+ * A curb's slab may be this fraction of the support's depth wider on either side: the support's deepest
+ * point is where its depth is measured, and a body pitched a hair nose-down meets the curb a little lower.
+ * @type {number}
+ */
+const CURB_SLAB_SLACK = 0.25;
+
+/**
+ * A curb's contacts span at least this fraction of the support's depth along its normal: they run from
+ * the support's surface down to the body's — a contact patch confined to one corner of the slab is a
+ * body touching a surface with one corner, not a curb.
+ * @type {number}
+ */
+const CURB_MIN_SPAN = 0.5;
+
+/** {@link settled}: a plane's deepest, or passed over as already pushed out. */
+const SETTLED = 1;
+
+/** {@link settled}: on a curb (see {@link is_curb_under}); left out of the reduction. */
+const CURB = 2;
+
+/** Per-candidate: 0, {@link SETTLED} or {@link CURB}. */
+let settled = new Uint8Array(64);
+
+/** Per-candidate: the plane (slot of its deepest candidate) the candidate lies on, -1 for none kept. */
+let plane_of = new Int32Array(64);
+
+/**
+ * In-place reduction of a body pair's contact candidates to at most `maxKept`, sharing the slots
+ * between the planes the contacts lie on.
+ *
+ * One body pair's candidates can lie on several surfaces at once: a floor and a wall, a floor and a
+ * ramp, the faces of two colliders. {@link reduce_manifold_contacts} keeps the deepest and then the
+ * widest spread, blind to the normals, so one surface could take every slot and leave another none. A
+ * cube sliding along a floor and a wall cut from one mesh had no floor contact in 40 of 240 frames, and
+ * a box meeting a 45° flank square along its leading edge kept one contact on the flank, turned about
+ * it and sank twice the step that carried it in (107 mm at 3 m/s, where the step is 50 mm).
+ *
+ * Here the candidates are grouped into planes by normal (cosine above {@link PLANE_COS}), and
+ *   1. each plane's deepest candidate takes a slot, the deepest planes first — slot 0 is the deepest
+ *      of all, as before;
+ *   2. the planes then take turns adding the candidate farthest from the points they already keep (the
+ *      far end of an edge, the opposite corner of a face) until the slots are full.
+ * Candidates on one plane — every box resting on a floor — are reduced by
+ * {@link reduce_manifold_contacts} itself, unchanged.
+ *
+ * Box3D keeps up to four points for every plane, each its own manifold (mesh_contact.c,
+ * `b3ComputeMeshManifolds`, MIT, Erin Catto). Here the planes share {@link MAX_CONTACTS_PER_MANIFOLD}
+ * slots, so a cube pressed into a corner gets two contacts on the floor and two on the wall where Box3D,
+ * or two separate bodies, would give it four and four — and still rocks as it slides along the corner.
+ *
+ * A candidate founds no plane when a deeper candidate at the same point already pushes it out: when
+ * moving the body that deeper depth along the deeper normal clears it too
+ * (`depth ≤ deeper_depth · (normal · deeper_normal)`). A flat face resting on a sharp convex edge of a
+ * mesh gets, beside its own contacts, contacts on the planes of the edge's two faces, each the face's
+ * depth projected on that plane; given slots of their own they pushed a box resting on two knife-edged
+ * rails sideways off them. A wall's contact at the bottom corner of a box in a corner is not like that:
+ * the wall's push does nothing for the floor's.
+ *
+ * Nor does a plane that is a curb under another ({@link is_curb_under}): a wall met only within the
+ * depth a body has sunk into the floor beside it, as the far rim of a slot is. Its contacts are left out
+ * altogether — lifting the body out of the floor clears them.
+ *
+ * Planes are told apart by normal alone, not by which collider pair made them: a compound slab of six
+ * boxes resting on a floor is one plane whose four slots span the slab. Told apart, its colliders were
+ * six planes, four of them got one corner each, and the slab never slept and sank 11 mm (a 4×4 slab:
+ * 35 to 67 mm).
+ *
+ * @param {Float64Array} buf  strided candidate buffer, position at lanes 0..2
+ * @param {number} n          input candidate count
+ * @param {number} stride     floats per candidate
+ * @param {number} maxKept    maximum candidates to keep
+ * @param {number} depth_lane lane holding penetration depth
+ * @param {number} normal_lane first of the three lanes holding the unit normal
+ * @returns {number} kept count, at most min(n, maxKept); the kept candidates are the first records
+ */
+export function reduce_manifold_contacts_by_plane(buf, n, stride, maxKept, depth_lane, normal_lane) {
+    if (n <= maxKept) return n;
+
+    if (settled.length < n) {
+        settled = new Uint8Array(n * 2);
+        plane_of = new Int32Array(n * 2);
+    }
+
+    if (plane_seed.length < maxKept) {
+        plane_seed = new Int32Array(maxKept);
+    }
+
+    settled.fill(0, 0, n);
+
+    // 1. Each plane's deepest candidate, deepest planes first. Nothing moves yet, so that one plane
+    //    falls through to reduce_manifold_contacts with the buffer as it came.
+    let planes = 0;
+    let skips = 0;
+    let curbs = 0;
+
+    while (planes < maxKept) {
+        const seed = deepest_off_planes(buf, n, stride, depth_lane, normal_lane, planes);
+
+        if (seed === -1) {
+            break;
+        }
+
+        settled[seed] = SETTLED;
+
+        if (planes > 0 && is_pushed_out(buf, n, stride, depth_lane, normal_lane, seed)) {
+            if (++skips === MAX_PUSHED_OUT_SKIPS) {
+                break;
+            }
+
+            continue;
+        }
+
+        if (planes > 0 && is_curb_under_any(buf, n, stride, depth_lane, normal_lane, seed, planes)) {
+            drop_plane(buf, n, stride, normal_lane, seed);
+            curbs++;
+
+            if (++skips === MAX_PUSHED_OUT_SKIPS) {
+                break;
+            }
+
+            continue;
+        }
+
+        // a plane found earlier may be a curb under this one: deeper than it, but no step at all
+        for (let p = 0; p < planes; p++) {
+            const earlier = plane_seed[p];
+
+            if (!is_curb_under(buf, n, stride, depth_lane, normal_lane, earlier, seed)) {
+                continue;
+            }
+
+            drop_plane(buf, n, stride, normal_lane, earlier);
+            curbs++;
+            skips++;
+
+            for (let q = p; q < planes - 1; q++) {
+                plane_seed[q] = plane_seed[q + 1];
+            }
+
+            planes--;
+            p--;
+        }
+
+        plane_seed[planes++] = seed;
+
+        if (skips >= MAX_PUSHED_OUT_SKIPS) {
+            break;
+        }
+    }
+
+    if (planes <= 1) {
+        // A curb's contacts are left out; the rest are reduced as one plane's.
+        return reduce_manifold_contacts(buf, curbs > 0 ? drop_curbs(buf, n, stride) : n, stride, maxKept, depth_lane);
+    }
+
+    // The deepest candidates of the planes into slots [0, planes).
+    for (let p = 0; p < planes; p++) {
+        const s = plane_seed[p];
+
+        if (s === p) {
+            continue;
+        }
+
+        swap(buf, stride, p, s);
+
+        const t = settled[p];
+        settled[p] = settled[s];
+        settled[s] = t;
+
+        // a later plane's seed that sat in slot p is where slot p's record went
+        for (let q = p + 1; q < planes; q++) {
+            if (plane_seed[q] === p) {
+                plane_seed[q] = s;
+            }
+        }
+    }
+
+    for (let i = 0; i < n; i++) {
+        if (i < planes) {
+            plane_of[i] = i;
+        } else {
+            plane_of[i] = settled[i] === CURB ? -1 : plane_matching(buf, stride, normal_lane, i, planes);
+        }
+    }
+
+    // 2. The planes take turns, each adding its candidate farthest from its kept points.
+    let kept = planes;
+    let idle = 0;
+
+    for (let p = 0; kept < maxKept && idle < planes; p = (p + 1 === planes) ? 0 : p + 1) {
+        let best = -1;
+        let best_d2 = SPREAD_MIN_D2;
+
+        for (let i = kept; i < n; i++) {
+            if (plane_of[i] !== p) {
+                continue;
+            }
+
+            const io = i * stride;
+            let min_d2 = Infinity;
+
+            for (let j = 0; j < kept; j++) {
+                if (plane_of[j] !== p) {
+                    continue;
+                }
+
+                const jo = j * stride;
+                const dx = buf[io] - buf[jo];
+                const dy = buf[io + 1] - buf[jo + 1];
+                const dz = buf[io + 2] - buf[jo + 2];
+                const d2 = dx * dx + dy * dy + dz * dz;
+
+                if (d2 < min_d2) {
+                    min_d2 = d2;
+                }
+            }
+
+            if (min_d2 > best_d2) {
+                best_d2 = min_d2;
+                best = i;
+            }
+        }
+
+        if (best === -1) {
+            idle++;
+            continue;
+        }
+
+        idle = 0;
+
+        if (best !== kept) {
+            swap(buf, stride, kept, best);
+
+            const t = plane_of[kept];
+            plane_of[kept] = plane_of[best];
+            plane_of[best] = t;
+        }
+
+        kept++;
+    }
+
+    return kept;
+}
+
+/**
+ * The deepest candidate not yet {@link settled} whose normal is on none of the first `planes` planes
+ * found ({@link plane_seed}), or -1.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @param {number} depth_lane
+ * @param {number} normal_lane
+ * @param {number} planes
+ * @returns {number}
+ */
+function deepest_off_planes(buf, n, stride, depth_lane, normal_lane, planes) {
+    let best = -1;
+    let best_depth = -Infinity;
+
+    for (let i = 0; i < n; i++) {
+        if (settled[i] !== 0) {
+            continue;
+        }
+
+        const o = i * stride;
+        const depth = buf[o + depth_lane];
+
+        if (!(depth > best_depth)) {
+            continue;
+        }
+
+        const nx = buf[o + normal_lane], ny = buf[o + normal_lane + 1], nz = buf[o + normal_lane + 2];
+
+        let on_plane = false;
+
+        for (let p = 0; p < planes && !on_plane; p++) {
+            const so = plane_seed[p] * stride + normal_lane;
+
+            on_plane = buf[so] * nx + buf[so + 1] * ny + buf[so + 2] * nz > PLANE_COS;
+        }
+
+        if (!on_plane) {
+            best = i;
+            best_depth = depth;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Whether a deeper candidate at the same point as candidate `c` pushes it out: moving the body that
+ * deeper depth along the deeper normal clears `c` too.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @param {number} depth_lane
+ * @param {number} normal_lane
+ * @param {number} c
+ * @returns {boolean}
+ */
+function is_pushed_out(buf, n, stride, depth_lane, normal_lane, c) {
+    const co = c * stride;
+    const depth = buf[co + depth_lane];
+    const nx = buf[co + normal_lane], ny = buf[co + normal_lane + 1], nz = buf[co + normal_lane + 2];
+
+    for (let j = 0; j < n; j++) {
+        const jo = j * stride;
+        const deeper = buf[jo + depth_lane];
+
+        if (!(deeper > depth)) {
+            continue;
+        }
+
+        const dx = buf[jo] - buf[co];
+        const dy = buf[jo + 1] - buf[co + 1];
+        const dz = buf[jo + 2] - buf[co + 2];
+        const reach = deeper + SAME_POINT_SLACK;
+
+        if (dx * dx + dy * dy + dz * dz > reach * reach) {
+            continue;
+        }
+
+        const cos = buf[jo + normal_lane] * nx + buf[jo + normal_lane + 1] * ny + buf[jo + normal_lane + 2] * nz;
+
+        if (depth <= deeper * cos + PUSHED_OUT_SLACK) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Whether the plane of candidate `c` is a curb under the plane of candidate `s` (the support): all of its
+ * contacts lie in the support's penetration slab — between the support's surface and the body's, `s`'s
+ * depth apart along `s`'s normal — and run from one face of it to the other.
+ *
+ * A body resting on a floor sinks the solver's few millimetres of slop into it. Where the floor has an
+ * edge whose far side is no higher — the far rim of a slot across it — the body's leading face meets that
+ * side's wall just below the floor's top: a contact on the wall, pushing the body back, as deep as the
+ * step it took past the rim. It is a curb no higher than the body's own penetration, cleared by the
+ * floor's push lifting the body back out; given two of the four slots it stopped the body dead. A box
+ * sliding at 1 m/s across a 2 to 10 cm slot in a floor was turned back in 13 of 72 starting phases.
+ *
+ * The wall of a corner is no curb: its contacts climb the body's side, out of the floor's slab. Nor is a
+ * floor that a body pressed into a wall touches with one bottom corner: that contact sits in the wall's
+ * slab, but at one depth, not across it. The slab is measured from the support's deepest contact,
+ * widened by {@link CURB_SLAB_SLACK} of its depth for a body pitched a little; the span must be at least
+ * {@link CURB_MIN_SPAN} of the depth.
+ *
+ * A contact's two witnesses are its position `a` and `a + normal · depth` — the narrowphase's convention.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @param {number} depth_lane
+ * @param {number} normal_lane
+ * @param {number} c a candidate on the plane tested
+ * @param {number} s the support's deepest candidate
+ * @returns {boolean}
+ */
+function is_curb_under(buf, n, stride, depth_lane, normal_lane, c, s) {
+    const so = s * stride;
+    const snx = buf[so + normal_lane], sny = buf[so + normal_lane + 1], snz = buf[so + normal_lane + 2];
+
+    const depth = buf[so + depth_lane] > 0 ? buf[so + depth_lane] : 0;
+    const surface = snx * buf[so] + sny * buf[so + 1] + snz * buf[so + 2];
+    const slack = depth * CURB_SLAB_SLACK + PUSHED_OUT_SLACK;
+    const lo = surface - slack;
+    const hi = surface + depth + slack;
+
+    const co = c * stride + normal_lane;
+    const cnx = buf[co], cny = buf[co + 1], cnz = buf[co + 2];
+
+    let low = Infinity;
+    let high = -Infinity;
+
+    for (let i = 0; i < n; i++) {
+        const o = i * stride;
+        const nx = buf[o + normal_lane], ny = buf[o + normal_lane + 1], nz = buf[o + normal_lane + 2];
+
+        if (!(nx * cnx + ny * cny + nz * cnz > PLANE_COS)) {
+            continue;
+        }
+
+        // the two witnesses, along the support's normal
+        const ta = snx * buf[o] + sny * buf[o + 1] + snz * buf[o + 2];
+        const tb = ta + (snx * nx + sny * ny + snz * nz) * buf[o + depth_lane];
+
+        if (!(ta >= lo && ta <= hi && tb >= lo && tb <= hi)) {
+            return false;
+        }
+
+        const t0 = ta < tb ? ta : tb;
+        const t1 = ta < tb ? tb : ta;
+
+        if (t0 < low) low = t0;
+        if (t1 > high) high = t1;
+    }
+
+    return high - low >= depth * CURB_MIN_SPAN;
+}
+
+/**
+ * Whether the plane of candidate `c` is a curb under any of the first `planes` planes found.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @param {number} depth_lane
+ * @param {number} normal_lane
+ * @param {number} c
+ * @param {number} planes
+ * @returns {boolean}
+ */
+function is_curb_under_any(buf, n, stride, depth_lane, normal_lane, c, planes) {
+    for (let p = 0; p < planes; p++) {
+        if (is_curb_under(buf, n, stride, depth_lane, normal_lane, c, plane_seed[p])) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Mark every candidate on the plane of candidate `c` a {@link CURB}.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @param {number} normal_lane
+ * @param {number} c
+ */
+function drop_plane(buf, n, stride, normal_lane, c) {
+    const co = c * stride + normal_lane;
+    const cnx = buf[co], cny = buf[co + 1], cnz = buf[co + 2];
+
+    for (let i = 0; i < n; i++) {
+        const o = i * stride + normal_lane;
+
+        if (buf[o] * cnx + buf[o + 1] * cny + buf[o + 2] * cnz > PLANE_COS) {
+            settled[i] = CURB;
+        }
+    }
+}
+
+/**
+ * Move every candidate not on a curb to the front, in order, and return how many there are.
+ *
+ * @param {Float64Array} buf
+ * @param {number} n
+ * @param {number} stride
+ * @returns {number}
+ */
+function drop_curbs(buf, n, stride) {
+    let kept = 0;
+
+    for (let i = 0; i < n; i++) {
+        if (settled[i] === CURB) {
+            continue;
+        }
+
+        if (kept !== i) {
+            buf.copyWithin(kept * stride, i * stride, i * stride + stride);
+        }
+
+        kept++;
+    }
+
+    return kept;
+}
+
+/**
+ * The first of the planes in slots [0, planes) whose normal candidate `i`'s is on, or -1.
+ *
+ * @param {Float64Array} buf
+ * @param {number} stride
+ * @param {number} normal_lane
+ * @param {number} i
+ * @param {number} planes
+ * @returns {number}
+ */
+function plane_matching(buf, stride, normal_lane, i, planes) {
+    const o = i * stride + normal_lane;
+    const nx = buf[o], ny = buf[o + 1], nz = buf[o + 2];
+
+    for (let p = 0; p < planes; p++) {
+        const so = p * stride + normal_lane;
+
+        if (buf[so] * nx + buf[so + 1] * ny + buf[so + 2] * nz > PLANE_COS) {
+            return p;
+        }
+    }
+
+    return -1;
+}
+
 function swap(buf, stride, a, b) {
     const ao = a * stride, bo = b * stride;
     for (let k = 0; k < stride; k++) {

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

@@ -2,7 +2,7 @@
  * @param {AbstractShape3D} shape  a concave shape (`is_convex === false`)
  * @param {ArrayLike<number>} position  body world position, indexed as
  *   [x, y, z] — read by index like `rotation`, so an `{x, y, z}` object
- *   sends a NaN ray into the decomposition and returns NaN
+ *   makes a NaN ray, which misses (`Infinity`)
  * @param {ArrayLike<number>} rotation  body rotation quaternion (x,y,z,w)
  * @param {number} ox  ray origin x (world)
  * @param {number} oy  ray origin y (world)
@@ -10,9 +10,36 @@
  * @param {number} dx  ray dir x (world, unit)
  * @param {number} dy  ray dir y (world, unit)
  * @param {number} dz  ray dir z (world, unit)
- * @param {number} tMax
+ * @param {number} tMax  reach; NaN reaches nothing (a miss)
  * @param {Float64Array|Vector3} outNormal  world surface normal, written on hit
  * @returns {number} hit distance, or `Infinity` on miss
  */
 export function refine_ray_concave(shape: AbstractShape3D, position: ArrayLike<number>, rotation: ArrayLike<number>, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, outNormal: Float64Array | Vector3): number;
+/**
+ * The feature id of the triangle the most recent {@link refine_ray_concave}
+ * that returned a hit struck — the enumerators' id, the triangle's index in
+ * its shape's triangulation plus one. Read straight after that call: a later
+ * hit overwrites it, a miss leaves it alone.
+ *
+ * @returns {number}
+ */
+export function refine_ray_concave_hit_feature(): number;
+/**
+ * How many triangles {@link heightmap_enumerate_triangles} emits for a query box
+ * in the heightmap's own frame, in O(1): the enumerator's own cell-range
+ * arithmetic, expression for expression, without the emitting — so the same
+ * number for the same box. For sizing a walk's pieces before enumerating any
+ * (this one's, and `shape_cast`'s over a heightmap): enumerating an over-full
+ * box only to learn that it was samples every height in it.
+ *
+ * @param {HeightMapShape3D} shape
+ * @param {number} aabb_min_x query box in the heightmap's 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}
+ */
+export function heightmap_box_triangles(shape: HeightMapShape3D, 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;
 //# sourceMappingURL=refine_ray_concave.d.ts.map