@woosh/meep-engine 3.38.0 → 3.40.0

package/src/core/geom/3d/shape/ConvexHullShape3D.js

@@ -9,20 +9,24 @@ import { compute_signed_distance_gradient_by_sampling } from "./util/compute_sig
 /**
  * Convex polyhedron collider.
  *
- * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and the
- * derived face half-spaces. Because it is convex (`is_convex === true`, the
- * default), it routes straight through the narrowphase's GJK + EPA path via
- * {@link support} — no tetrahedralisation, no per-triangle decomposition, no
- * BVH. This is the right shape for authored convex geometry (props, crates,
- * gems, low-poly rocks, an icosphere) and is far cheaper to construct than
- * {@link MeshShape3D}, which tetrahedralises its interior.
+ * Holds a convex triangle surface (`vertices` + outward-CCW `indices`) and what
+ * is derived from it: the per-triangle half-spaces, and the polygon faces (one
+ * per flat side) with their planes. Because it is convex (`is_convex === true`,
+ * the default), the narrowphase collides it through {@link support} (GJK + EPA)
+ * and its polygon faces (face clipping) — no tetrahedralisation, no per-triangle
+ * decomposition, no BVH. This is the right shape for authored convex geometry
+ * (props, crates, gems, low-poly rocks, an icosphere) and is far cheaper to
+ * construct than {@link MeshShape3D}, which tetrahedralises its interior.
  *
  * Contract:
  *   - `support` is exact for any convex point set (deepest vertex along the
  *     direction) — the precondition GJK relies on.
  *   - `contains_point` is the convex half-space test (behind every face plane).
  *   - `signed_distance` / `nearest_point_on_surface` scan the surface triangles
- *     (O(F)); these are query-path helpers, not on the collision hot path.
+ *     (O(F)). `nearest_point_on_surface` is on the collision path: the
+ *     hull/sphere contact calls it for a sphere outside the hull whose centre
+ *     is not over the face it is furthest in front of (near an edge or a
+ *     corner), so such a pair costs O(F) triangle tests.
  *
  * The input is assumed convex with outward-facing CCW winding — build it via
  * {@link ConvexHullShape3D.from}. A genuine non-convex mesh belongs in
@@ -51,8 +55,10 @@ export class ConvexHullShape3D extends AbstractShape3D {
     /**
      * Polygon-face representation for the contact clipper (CSR): face `f`'s
      * vertex loop is `face_loops[face_offsets[f] .. face_offsets[f+1]]`,
-     * ordered CCW (outward). Currently one triangle per face; a coplanar-merge
-     * pass will collapse coplanar triangles into larger polygon faces.
+     * ordered CCW (outward), indexing {@link vertices}. Derived in
+     * {@link recompute}: each side of the hull is ONE convex polygon however
+     * many coplanar triangles {@link indices} spends on it (a box has six
+     * quads), so a face-on-face contact clips to the whole patch.
      * @type {Uint32Array}
      */
     face_offsets = new Uint32Array(0);
@@ -60,6 +66,15 @@ export class ConvexHullShape3D extends AbstractShape3D {
     /** @type {Uint32Array} */
     face_loops = new Uint32Array(0);
 
+    /**
+     * The plane of each polygon face of {@link face_loops}, four doubles per face `(nx, ny, nz, d)`
+     * with unit outward normal and `d = n · v`; all zero for a face with no area. Derived in
+     * {@link recompute}, alongside the loops, so contact code that looks for the face facing a
+     * direction reads one plane per side rather than re-deriving each loop's normal per query.
+     * @type {Float64Array}
+     */
+    face_loop_planes = new Float64Array(0);
+
     /**
      * Face half-spaces, four doubles per face `(nx, ny, nz, d)` with unit
      * outward normal and `d = n · v` — point is inside iff `n · p − d ≤ 0`
@@ -174,12 +189,8 @@ export class ConvexHullShape3D extends AbstractShape3D {
         this.__surface_area = area;
         this.__volume = Math.abs(vol6) / 6;
 
-        // Polygon faces for the clipper. v1: one triangle per face (the contact
-        // clipper consumes polygon loops; a tetrahedral piece is exactly this).
-        const fo = new Uint32Array(tri + 1);
-        for (let f = 0; f <= tri; f++) fo[f] = f * 3;
-        this.face_offsets = fo;
-        this.face_loops = idx;
+        // Polygon faces for the contact clipper: coplanar triangles merged into one polygon per side.
+        build_polygon_faces(this, v, idx, planes);
     }
 
     get volume() {
@@ -206,12 +217,10 @@ export class ConvexHullShape3D extends AbstractShape3D {
      * vertex counts of authored hulls; a hill-climb over vertex adjacency is
      * the acceleration for very large hulls.
      */
-    support(
-        result, result_offset,
-        direction_x,
-        direction_y,
-        direction_z
-    ) {
+    support(result, result_offset, direction, direction_offset) {
+        const direction_x = direction[direction_offset];
+        const direction_y = direction[direction_offset + 1];
+        const direction_z = direction[direction_offset + 2];
 
         const v = this.vertices;
         const vertex_array_length = v.length;
@@ -402,3 +411,364 @@ ConvexHullShape3D.prototype.isConvexHullShape3D = true;
 
 // closest-point-on-triangle output for the surface-scan query helpers
 const scratch_closest = new Float64Array(3);
+
+/**
+ * float32 machine epsilon — the vertices are stored as float32.
+ * @type {number}
+ */
+const FLT_EPSILON = 1.1920928955078125e-7;
+
+/**
+ * How far off a side's plane a vertex may sit and still lie on that side: four float32 roundings of
+ * the hull's largest coordinate. This is Box3D's quickhull tolerance (hull.c,
+ * b3HullBuilder_ComputeTolerance; its `minRadius` is the coplanarity test of
+ * b3HullBuilder_MergeCoplanar) — Box3D, Erin Catto, MIT licence. The corners of one flat side of a
+ * hull that was rotated or moved before its vertices were rounded to float32 are coplanar only to
+ * within that rounding, which scales with the coordinates, not with the hull's size.
+ *
+ * @param {Float64Array} b the hull's bounding box `(min x, y, z, max x, y, z)`
+ * @returns {number}
+ */
+function coplanar_tolerance(b) {
+    const ax = Math.max(Math.abs(b[0]), Math.abs(b[3]));
+    const ay = Math.max(Math.abs(b[1]), Math.abs(b[4]));
+    const az = Math.max(Math.abs(b[2]), Math.abs(b[5]));
+
+    const max_coord = Math.max(ax, ay, az);
+    const max_distance = Math.min(Math.sqrt(3) * max_coord, ax + ay + az);
+
+    return 4 * (3 * max_distance * 1.01 + max_coord) * FLT_EPSILON;
+}
+
+/**
+ * Derive the hull's polygon faces — {@link ConvexHullShape3D#face_offsets} /
+ * {@link ConvexHullShape3D#face_loops} — from its triangles: every edge-connected run of triangles
+ * lying in one plane becomes a single loop, traced along the run's boundary edges, so it keeps the
+ * triangles' outward CCW winding and indexes the same vertices. A vertex inside a side (a fan
+ * centre) is on no boundary edge and drops out.
+ *
+ * The contact clipper needs this. With one triangle per face, a body resting on the half of a flat
+ * side the clipper did not pick as the reference face clipped to nothing, and the single fallback
+ * contact sat at a far corner of the side: a hull cube on a hull floor fell through in five of
+ * seven poses.
+ *
+ * Each run grows from its first triangle and tests candidates against THAT triangle's plane, so a
+ * finely tessellated curved surface cannot creep into one face a pair of neighbours at a time. A
+ * run whose boundary is not a single convex loop — which a convex, closed, consistently wound
+ * surface never produces — keeps its triangles as separate faces, as every face used to be.
+ * Degenerate (zero-area) triangles seed nothing; one lying in a side's plane joins that side.
+ *
+ * Adjacency is by POSITION, not by index: vertices within the tolerance of one another are welded
+ * first ({@link weld_vertices}), and the loops index each weld's first vertex. A hull stored as
+ * unwelded triangles — every triangle with its own three vertices, as an exporter writing unindexed
+ * triangles leaves it — has no shared indices at all, and kept every triangle as its own face.
+ *
+ * @param {ConvexHullShape3D} shape receives `face_offsets` / `face_loops`
+ * @param {Float32Array} v vertices
+ * @param {Uint32Array} input_idx triangle indices
+ * @param {Float64Array} planes per-triangle `(nx, ny, nz, d)`, unit normal or zero if degenerate
+ */
+function build_polygon_faces(shape, v, input_idx, planes) {
+    const tri = input_idx.length / 3;
+    const vc = v.length / 3;
+    const tol = coplanar_tolerance(shape.__bbox);
+
+    const welded = weld_vertices(v, vc, tol);
+    const idx = new Uint32Array(input_idx.length);
+    for (let i = 0; i < input_idx.length; i++) {
+        idx[i] = welded[input_idx[i]];
+    }
+
+    // directed edge a → b, keyed a · vc + b, to the triangle that has it; its twin is b → a
+    const edge_owner = new Map();
+    for (let t = 0; t < tri; t++) {
+        for (let k = 0; k < 3; k++) {
+            edge_owner.set(idx[t * 3 + k] * vc + idx[t * 3 + (k + 1) % 3], t);
+        }
+    }
+
+    const group = new Int32Array(tri).fill(-1);
+    const group_seed = [];
+    const stack = [];
+
+    for (let seed = 0; seed < tri; seed++) {
+        if (group[seed] !== -1) continue;
+
+        const so = seed * 4;
+        const nx = planes[so], ny = planes[so + 1], nz = planes[so + 2], d = planes[so + 3];
+
+        if (nx * nx + ny * ny + nz * nz < 0.5) continue; // degenerate: no plane to grow from
+
+        const g = group_seed.length;
+        group_seed.push(seed);
+        group[seed] = g;
+        stack.push(seed);
+
+        while (stack.length > 0) {
+            const t = stack.pop();
+
+            for (let k = 0; k < 3; k++) {
+                const a = idx[t * 3 + k];
+                const b = idx[t * 3 + (k + 1) % 3];
+                const u = edge_owner.get(b * vc + a);
+
+                if (u === undefined || group[u] !== -1) continue;
+
+                const uo = u * 4;
+                // facing the same way (a degenerate triangle faces no way, and may join)
+                if (planes[uo] * nx + planes[uo + 1] * ny + planes[uo + 2] * nz < 0) continue;
+
+                let on_plane = true;
+                for (let j = 0; j < 3; j++) {
+                    const p = idx[u * 3 + j] * 3;
+                    if (Math.abs(nx * v[p] + ny * v[p + 1] + nz * v[p + 2] - d) > tol) {
+                        on_plane = false;
+                        break;
+                    }
+                }
+                if (!on_plane) continue;
+
+                group[u] = g;
+                stack.push(u);
+            }
+        }
+    }
+
+    // degenerate triangles no side took stay faces of their own
+    for (let t = 0; t < tri; t++) {
+        if (group[t] === -1) {
+            group[t] = group_seed.length;
+            group_seed.push(t);
+        }
+    }
+
+    const group_count = group_seed.length;
+
+    // members of each group, in triangle order (CSR)
+    const member_offsets = new Uint32Array(group_count + 1);
+    for (let t = 0; t < tri; t++) member_offsets[group[t] + 1]++;
+    for (let g = 0; g < group_count; g++) member_offsets[g + 1] += member_offsets[g];
+    const members = new Uint32Array(tri);
+    const fill = member_offsets.slice(0, group_count);
+    for (let t = 0; t < tri; t++) members[fill[group[t]]++] = t;
+
+    const offsets = [0];
+    const loops = [];
+    // 0 = not reached yet, 1 = emitted as one polygon, 2 = emitted triangle by triangle
+    const state = new Uint8Array(group_count);
+    const next = new Map();
+    const loop = [];
+
+    for (let t = 0; t < tri; t++) {
+        const g = group[t];
+
+        if (state[g] === 0) {
+            state[g] = 2;
+
+            const m0 = member_offsets[g], m1 = member_offsets[g + 1];
+
+            if (m1 - m0 > 1 && trace_boundary(loop, next, g, group, members, m0, m1, idx, vc, edge_owner)
+                && is_convex_loop(loop, v, planes, group_seed[g] * 4, tol)) {
+
+                for (let i = 0; i < loop.length; i++) loops.push(loop[i]);
+                offsets.push(loops.length);
+                state[g] = 1;
+            }
+        }
+
+        if (state[g] === 2) {
+            loops.push(idx[t * 3], idx[t * 3 + 1], idx[t * 3 + 2]);
+            offsets.push(loops.length);
+        }
+    }
+
+    shape.face_offsets = Uint32Array.from(offsets);
+    shape.face_loops = Uint32Array.from(loops);
+    shape.face_loop_planes = loop_planes(v, shape.face_offsets, shape.face_loops);
+}
+
+/**
+ * The plane of each loop: its Newell normal, unit, and `d = n · v` at its first vertex; zero for a
+ * loop with no area.
+ *
+ * @param {Float32Array} v
+ * @param {Uint32Array} fo face offsets
+ * @param {Uint32Array} fl face loops
+ * @returns {Float64Array}
+ */
+function loop_planes(v, fo, fl) {
+    const face_count = fo.length - 1;
+    const planes = new Float64Array(face_count * 4);
+
+    for (let f = 0; f < face_count; f++) {
+        const s = fo[f], e = fo[f + 1];
+        let nx = 0, ny = 0, nz = 0;
+
+        for (let i = s; i < e; i++) {
+            const a = fl[i] * 3, b = fl[i + 1 < e ? i + 1 : s] * 3;
+            nx += (v[a + 1] - v[b + 1]) * (v[a + 2] + v[b + 2]);
+            ny += (v[a + 2] - v[b + 2]) * (v[a] + v[b]);
+            nz += (v[a] - v[b]) * (v[a + 1] + v[b + 1]);
+        }
+
+        const l = Math.sqrt(nx * nx + ny * ny + nz * nz);
+        if (!(l > 0)) continue;
+
+        nx /= l; ny /= l; nz /= l;
+
+        const a = fl[s] * 3;
+        const o = f * 4;
+        planes[o] = nx;
+        planes[o + 1] = ny;
+        planes[o + 2] = nz;
+        planes[o + 3] = nx * v[a] + ny * v[a + 1] + nz * v[a + 2];
+    }
+
+    return planes;
+}
+
+/**
+ * Weld vertices by position: each vertex's representative is the first vertex within `tol` of it
+ * (itself, if none came before). Only representatives are matched against, so a run of vertices each
+ * just within the tolerance of the next does not chain into one.
+ *
+ * @param {Float32Array} v
+ * @param {number} vc vertex count
+ * @param {number} tol
+ * @returns {Uint32Array} representative of each vertex
+ */
+function weld_vertices(v, vc, tol) {
+    const representative = new Uint32Array(vc);
+
+    // a grid of cells as wide as the tolerance: a match is in the vertex's cell or a neighbouring one
+    const h = tol > 0 ? tol : 1;
+    const tol2 = tol * tol;
+    const cells = new Map();
+
+    for (let i = 0; i < vc; i++) {
+        const x = v[i * 3], y = v[i * 3 + 1], z = v[i * 3 + 2];
+        const cx = Math.floor(x / h), cy = Math.floor(y / h), cz = Math.floor(z / h);
+
+        let found = -1;
+
+        for (let dx = -1; dx <= 1 && found === -1; dx++) {
+            for (let dy = -1; dy <= 1 && found === -1; dy++) {
+                for (let dz = -1; dz <= 1 && found === -1; dz++) {
+                    const list = cells.get((cx + dx) + "," + (cy + dy) + "," + (cz + dz));
+                    if (list === undefined) continue;
+
+                    for (let k = 0; k < list.length; k++) {
+                        const j = list[k] * 3;
+                        const ex = v[j] - x, ey = v[j + 1] - y, ez = v[j + 2] - z;
+
+                        if (ex * ex + ey * ey + ez * ez <= tol2) {
+                            found = list[k];
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+
+        if (found !== -1) {
+            representative[i] = found;
+            continue;
+        }
+
+        representative[i] = i;
+
+        const key = cx + "," + cy + "," + cz;
+        const list = cells.get(key);
+
+        if (list === undefined) {
+            cells.set(key, [i]);
+        } else {
+            list.push(i);
+        }
+    }
+
+    return representative;
+}
+
+/**
+ * Trace the boundary of one group of triangles — its directed edges whose twin is outside the
+ * group — into `loop`, in the triangles' winding. False unless the boundary is exactly one simple
+ * loop.
+ *
+ * @param {number[]} loop receives the loop's vertex indices
+ * @param {Map<number, number>} next scratch, origin → destination of a boundary edge
+ * @param {number} g group id
+ * @param {Int32Array} group group of each triangle
+ * @param {Uint32Array} members triangles by group
+ * @param {number} m0 first member slot of `g`
+ * @param {number} m1 one past its last
+ * @param {Uint32Array} idx triangle indices
+ * @param {number} vc vertex count
+ * @param {Map<number, number>} edge_owner directed edge → triangle
+ * @returns {boolean}
+ */
+function trace_boundary(loop, next, g, group, members, m0, m1, idx, vc, edge_owner) {
+    next.clear();
+    loop.length = 0;
+
+    let edge_count = 0;
+    let start = -1;
+
+    for (let m = m0; m < m1; m++) {
+        const t = members[m];
+
+        for (let k = 0; k < 3; k++) {
+            const a = idx[t * 3 + k];
+            const b = idx[t * 3 + (k + 1) % 3];
+            const u = edge_owner.get(b * vc + a);
+
+            if (u !== undefined && group[u] === g) continue; // interior edge
+
+            if (next.has(a)) return false; // the boundary touches itself
+
+            next.set(a, b);
+            edge_count++;
+
+            if (start === -1) start = a;
+        }
+    }
+
+    let cur = start;
+    do {
+        loop.push(cur);
+        cur = next.get(cur);
+        if (cur === undefined || loop.length > edge_count) return false;
+    } while (cur !== start);
+
+    return loop.length === edge_count && loop.length >= 3;
+}
+
+/**
+ * Whether a planar loop turns the same way at every vertex (collinear vertices allowed) about the
+ * plane normal at `planes[po]`.
+ *
+ * @param {number[]} loop
+ * @param {Float32Array} v
+ * @param {Float64Array} planes
+ * @param {number} po offset of the group's plane in `planes`
+ * @param {number} tol length tolerance
+ * @returns {boolean}
+ */
+function is_convex_loop(loop, v, planes, po, tol) {
+    const nx = planes[po], ny = planes[po + 1], nz = planes[po + 2];
+    const n = loop.length;
+
+    for (let i = 0; i < n; i++) {
+        const p0 = loop[(i + n - 1) % n] * 3, p1 = loop[i] * 3, p2 = loop[(i + 1) % n] * 3;
+
+        const ax = v[p1] - v[p0], ay = v[p1 + 1] - v[p0 + 1], az = v[p1 + 2] - v[p0 + 2];
+        const bx = v[p2] - v[p1], by = v[p2 + 1] - v[p1 + 1], bz = v[p2 + 2] - v[p1 + 2];
+
+        const turn = (ay * bz - az * by) * nx + (az * bx - ax * bz) * ny + (ax * by - ay * bx) * nz;
+        const reach = Math.hypot(ax, ay, az) + Math.hypot(bx, by, bz);
+
+        if (turn < -tol * reach) return false;
+    }
+
+    return true;
+}

package/src/core/geom/3d/shape/CylinderShape3D.d.ts

@@ -5,9 +5,11 @@
  * flat-cap sibling — same radius/height parametrisation, hemispherical caps
  * replaced by disks).
  *
- * Convex, so the physics narrowphase handles it through the GJK + EPA fallback
- * via {@link support} — there is no closed-form cylinder-vs-X contact path yet
- * (a future refinement; the curved side is the usual smooth-support EPA case).
+ * Convex, so the physics narrowphase finds the penetration axis and depth with
+ * GJK + EPA via {@link support}, and the contact points from its supporting
+ * features: the cap's rim when a cap faces the other body, the side line when
+ * the side does, else the support point. There is no closed-form cylinder-vs-X
+ * routine.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -32,7 +34,7 @@ export class CylinderShape3D extends AbstractShape3D {
     height: number;
     raycast(hit: any, ray: any): boolean;
     compute_bounding_box(result: any): void;
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     signed_distance_at_point(point: any): number;
     signed_distance_gradient_at_point(result: any, point: any): number;
     contains_point(point: any): boolean;
@@ -45,9 +47,8 @@ export class CylinderShape3D extends AbstractShape3D {
     equals(other: CylinderShape3D): boolean;
     /**
      * Fast type-check marker, mirroring `isSphereShape3D` / `isBoxShape3D` /
-     * `isCapsuleShape3D`. Reserved for a future closed-form cylinder narrowphase
-     * dispatch; until then the cylinder routes through GJK + EPA like any other
-     * convex shape (no marker check needed for that path).
+     * `isCapsuleShape3D`. The narrowphase's supporting-feature pass reads it to
+     * give a cylinder its cap and side-line features.
      * @readonly
      * @type {boolean}
      */

package/src/core/geom/3d/shape/CylinderShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CylinderShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CylinderShape3D.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;GAaG;AACH;IAcI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,eAAe,CAa3B;IA7BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,QAFU,MAAM,CAEL;IA+BX,qCAkBC;IAED,wCAUC;IAED,qGAqBC;IAED,6CAEC;IAED,mEAEC;IAED,oCASC;IAED,4DA0CC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAMnB;IAUL;;;;;;;OAOG;IACH,4BAFU,OAAO,CAE0B;CAV1C;gCA9M+B,sBAAsB"}
+{"version":3,"file":"CylinderShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/CylinderShape3D.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;GAeG;AACH;IAcI;;;;OAIG;IACH,oBAJW,MAAM,UACN,MAAM,GACJ,eAAe,CAa3B;IA7BD;;;OAGG;IACH,QAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,QAFU,MAAM,CAEL;IA+BX,qCAkBC;IAED,wCAUC;IAED,sFAyBC;IAED,6CAEC;IAED,mEAEC;IAED,oCASC;IAED,4DA0CC;IAED,kFAOC;IAED;;;OAGG;IACH,cAHW,eAAe,GACb,OAAO,CAMnB;IAUL;;;;;;OAMG;IACH,4BAFU,OAAO,CAE0B;CAT1C;gCApN+B,sBAAsB"}

package/src/core/geom/3d/shape/CylinderShape3D.js

@@ -17,9 +17,11 @@ const scratch_v3 = [0, 0, 0];
  * flat-cap sibling — same radius/height parametrisation, hemispherical caps
  * replaced by disks).
  *
- * Convex, so the physics narrowphase handles it through the GJK + EPA fallback
- * via {@link support} — there is no closed-form cylinder-vs-X contact path yet
- * (a future refinement; the curved side is the usual smooth-support EPA case).
+ * Convex, so the physics narrowphase finds the penetration axis and depth with
+ * GJK + EPA via {@link support}, and the contact points from its supporting
+ * features: the cap's rim when a cap faces the other body, the side line when
+ * the side does, else the support point. There is no closed-form cylinder-vs-X
+ * routine.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -99,7 +101,11 @@ export class CylinderShape3D extends AbstractShape3D {
         result[5] = r;
     }
 
-    support(result, result_offset, direction_x, direction_y, direction_z) {
+    support(result, result_offset, direction, direction_offset) {
+        const direction_x = direction[direction_offset];
+        const direction_y = direction[direction_offset + 1];
+        const direction_z = direction[direction_offset + 2];
+
         const r = this.radius;
         const half_h = this.height / 2;
 
@@ -214,9 +220,8 @@ export class CylinderShape3D extends AbstractShape3D {
 
 /**
  * Fast type-check marker, mirroring `isSphereShape3D` / `isBoxShape3D` /
- * `isCapsuleShape3D`. Reserved for a future closed-form cylinder narrowphase
- * dispatch; until then the cylinder routes through GJK + EPA like any other
- * convex shape (no marker check needed for that path).
+ * `isCapsuleShape3D`. The narrowphase's supporting-feature pass reads it to
+ * give a cylinder its cap and side-line features.
  * @readonly
  * @type {boolean}
  */

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts

@@ -25,8 +25,16 @@
  *     `sampler.sampleChannelCatmullRomUV(u01, v01, 0)`.
  *   - The solid volume occupies `h ∈ [0, sampledHeight(u01, v01)]` along the
  *     orientation axis, with `0` being the floor at body-local origin.
- *   - `size.y` is the maximum height value of the heightfield (used for the
- *     bounding box). Sampler values are NOT clamped to it.
+ *   - `size.y` is the maximum height value of the heightfield. Sampler values
+ *     are NOT clamped to it; the bounding box takes in whatever the samples, and
+ *     the cubic between them, reach beyond [0, size.y] (see
+ *     {@link compute_bounding_box}).
+ *   - Editing the samples of a collider already attached to a physics body: the
+ *     box follows the sampler's version, but a static body's broadphase leaf is
+ *     set when the collider is attached and never refit. An edit that raises the
+ *     surface past the box it was attached with stays out of sight until the
+ *     collider is detached and attached again — a ball dropped onto a field raised
+ *     from 1 m to 3 m fell through it; re-attached, the field held it.
  *
  * NON-CONVEX. {@link support} throws — GJK/EPA cannot be run against a
  * heightmap directly. The physics narrowphase must dispatch a dedicated
@@ -100,6 +108,25 @@ export class HeightMapShape3D extends AbstractShape3D {
     _basis_orientation_x: number;
     _basis_orientation_y: number;
     _basis_orientation_z: number;
+    /**
+     * Lowest and highest the surface can stand, along {@link orientation}: each 4 × 4 window of the
+     * sampler's finite channel-0 values widened by the Catmull-Rom overshoot ({@link CATMULL_ROM_OVERSHOOT})
+     * of its own range, the widest of those ({@link height_range_by_window}). Updated
+     * lazily by {@link _ensure_height_range}, keyed on the sampler, its data array, its version and its
+     * dimensions — so a write straight into `sampler.data` must bump `sampler.version`, as every other
+     * reader of a sampler's version expects. That moves this box; it does not move a static body's
+     * broadphase leaf, which only re-attaching the collider does (see the class notes).
+     * @private
+     * @type {number}
+     */
+    private _height_lo;
+    _height_hi: number;
+    _height_range_sampler: any;
+    _height_range_data: any;
+    _height_range_version: number;
+    _height_range_width: number;
+    _height_range_height: number;
+    _height_range_item_size: number;
     /**
      * Recompute the orthonormal basis (u, v, n) if {@link orientation} changed.
      *
@@ -129,7 +156,23 @@ export class HeightMapShape3D extends AbstractShape3D {
      * @returns {number}
      */
     sample_height_at_position(px: number, py: number, pz: number): number;
-    compute_bounding_box(result: any): void;
+    /**
+     * The box holds the solid from its floor (h = 0) to `size.y`, and the surface wherever it stands
+     * outside that: the Catmull-Rom cubic overshoots the samples it is drawn through, so a ridge whose
+     * every sample is within `size.y` still rises above it (an eighth of its height for a ridge two
+     * samples wide). A box short of the surface hid it from the broadphase and from the compound
+     * narrowphase's box test: a ball on such a ridge sank and bobbed.
+     *
+     * @param {number[]|Float64Array} result
+     */
+    compute_bounding_box(result: number[] | Float64Array): void;
+    /**
+     * Bring {@link _height_lo} / {@link _height_hi} up to date with the sampler: one pass over its
+     * channel-0 values when the sampler, its data array, its version or its dimensions changed since the
+     * last (3 ms for 513 × 513 samples, 12-16 ms for 1025 × 1025).
+     * @private
+     */
+    private _ensure_height_range;
     contains_point(point: any): boolean;
     /**
      * Approximate signed distance: difference between the point's height
@@ -157,7 +200,7 @@ export class HeightMapShape3D extends AbstractShape3D {
      * This throws rather than returning a degenerate result so the call
      * site is forced to handle heightmaps explicitly.
      */
-    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    support(result: any, result_offset: any, direction: any, direction_offset: any): void;
     /**
      * Nearest ray hit against the height-field SURFACE, in the shape's body-local
      * frame. Writes `[px, py, pz, nx, ny, nz]` into `hit` and returns true; a miss
@@ -199,10 +242,10 @@ export class HeightMapShape3D extends AbstractShape3D {
      * Measure-zero, and called out because it is the only place the two answers
      * part company.
      *
-     * `size.y` does NOT bound the query. Sampler values are not clamped to it (see
-     * the class docstring), so clipping the ray to the height range that
-     * {@link compute_bounding_box} reports could reject real surface standing above
-     * it; only the footprint is clipped against.
+     * `size.y` does NOT bound the query: sampler values are not clamped to it, and
+     * the cubic overshoots them. Only the footprint is clipped against — the
+     * height range {@link compute_bounding_box} reports follows the samples only as
+     * far as the sampler's version does.
      *
      * ## Cost
      *

package/src/core/geom/3d/shape/HeightMapShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IA4DI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IA1FD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAmC3B;;;;;;;;;OASG;IACH,sBA8CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED,wCA6BC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,qGAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgEG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,cAEnB,OAAO,CA0NnB;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCAluB+B,sBAAsB;wBAD9B,kBAAkB"}
+{"version":3,"file":"HeightMapShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/HeightMapShape3D.js"],"names":[],"mappings":"AA0KA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAkFI;;;;;;;;;;;OAWG;IACH,wCATW,MAAM,UACN,MAAM,UACN,MAAM,gBACN,OAAO,iBACP,MAAM,GAGJ,gBAAgB,CAqB5B;IAhHD;;;;;OAKG;IACH,sBAFU,OAAO,CAEkB;IAEnC;;;;;;;OAOG;IACH,eAFU,OAAO,CAEW;IAE5B;;;;;OAKG;IACH,SAFU,YAAY,IAAI,CAEX;IAEf;;;;;;;;;;;;;;;;OAgBG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;OAKG;IACH,eAA6B;IAG7B,6BAA2B;IAE3B,6BAA2B;IAC3B,6BAA2B;IAE3B;;;;;;;;;;OAUG;IACH,mBAAe;IACf,mBAAe;IAGf,2BAA6B;IAC7B,wBAA0B;IAC1B,8BAA2B;IAC3B,4BAAyB;IACzB,6BAA0B;IAC1B,gCAA6B;IAmC7B;;;;;;;;;OASG;IACH,sBA8CC;IAED;;;;;;OAMG;IACH,yBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;OAQG;IACH,8BALW,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAelB;IAED;;;;;;;;OAQG;IACH,6BAFW,MAAM,EAAE,GAAC,YAAY,QAoC/B;IAED;;;;;OAKG;IACH,6BA+CC;IAED,oCA2BC;IAED;;;;;;;;OAQG;IACH,6CAmBC;IAED;;;;OAIG;IACH,4DA2BC;IAED;;;;;;;;;OASG;IACH,sFAEC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgEG;IACH,aAJW,YAAY,GAAC,MAAM,EAAE,cAEnB,OAAO,CA0NnB;IAED,kFAiBC;IA6CD;;;OAGG;IACH,cAHW,gBAAgB,GACd,OAAO,CAUnB;IAWL;;;;;;OAMG;IACH,6BAFU,OAAO,CAE4B;CAT5C;gCAx9B+B,sBAAsB;wBAD9B,kBAAkB"}