@woosh/meep-engine 3.37.0 → 3.39.0

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

@@ -0,0 +1,949 @@
+import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { v3_quaternion_apply_inverse } from "../../../core/geom/vec3/v3_quaternion_apply_inverse.js";
+import { clip_poly } from "./convex_convex_manifold.js";
+import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
+
+/**
+ * Contact points for a convex pair the narrowphase has an axis and a depth for (GJK + EPA) but no
+ * dedicated routine: a cylinder against anything, a capsule against a hull, a hull or a cylinder
+ * against a mesh triangle, a scaled TransformedShape3D.
+ *
+ * Each side contributes its SUPPORTING FEATURE along the axis — the face, edge or point of it that
+ * faces the other body — and the two are clipped against each other, as Jolt's
+ * `ManifoldBetweenTwoFaces` and Box3D's capsule/hull face contact do: a cylinder standing on its cap
+ * gets the cap's rim, clipped to the floor face, and stands; a capsule lying on a hull face gets
+ * both ends of its segment. Where the features do not face each other squarely there is one contact,
+ * on the smaller feature, projected along the axis onto the other body — never at a body's origin,
+ * which is what this path used to report, putting the push metres from where the bodies touch.
+ *
+ * Features:
+ *   - box, convex hull (any `{vertices, face_offsets, face_loops}` polytope), triangle: the face whose
+ *     outward normal is within {@link FACE_ALIGNMENT} of the direction; otherwise the vertices tied
+ *     at the extreme (an edge, or a vertex);
+ *   - cylinder: the cap, as {@link CYLINDER_CAP_POINTS} rim points, within FACE_ALIGNMENT of its
+ *     axis; the side line, within the same angle of perpendicular; otherwise the support point;
+ *   - capsule: its segment's two hemisphere support points, within that angle of perpendicular;
+ *     otherwise the support point;
+ *   - TransformedShape3D (one that scales; rigid ones are collided as their subject): the subject's
+ *     feature along the direction mapped into it, carried through the matrix;
+ *   - anything else: the support point.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** @type {number} */
+export const FEATURE_POINT = 1;
+/** @type {number} */
+export const FEATURE_SEGMENT = 2;
+/** @type {number} */
+export const FEATURE_POLYGON = 3;
+
+/**
+ * A face is the supporting feature when its outward normal is within this cosine of the direction —
+ * Box3D's `kTolerance` for clipping a capsule against a hull face (about 3.6°).
+ * @type {number}
+ */
+const FACE_ALIGNMENT = 0.998;
+
+/**
+ * A segment (a capsule's, or a cylinder's side line) is the supporting feature when the direction is
+ * within the same angle of perpendicular to it.
+ * @type {number}
+ */
+const SEGMENT_ALIGNMENT = Math.sqrt(1 - FACE_ALIGNMENT * FACE_ALIGNMENT);
+
+/**
+ * Points on the rim standing in for a cylinder's circular cap. They lie ON the rim, so a clipped
+ * point's depth is exact; of eight, the manifold's reduction to four keeps a square inscribed in the
+ * cap for a cylinder standing square on a face, and the deepest of them when it leans.
+ * @type {number}
+ */
+const CYLINDER_CAP_POINTS = 8;
+
+/**
+ * Vertices within this fraction of a polytope's extent along the direction of the extreme one tie as
+ * one feature (an edge lying across the direction is two vertices, not one).
+ * @type {number}
+ */
+const SUPPORT_TIE_REL = 1e-3;
+
+/**
+ * The part of a convex shape that faces a direction, in world space.
+ */
+export class SupportFeature {
+    /**
+     * World points, flat `(x, y, z)`. A POLYGON's are in loop order.
+     * @type {Float64Array}
+     */
+    points = new Float64Array(16 * 3);
+
+    /** @type {number} */
+    count = 0;
+
+    /**
+     * {@link FEATURE_POINT}, {@link FEATURE_SEGMENT} or {@link FEATURE_POLYGON}.
+     * @type {number}
+     */
+    kind = FEATURE_POINT;
+
+    /**
+     * Unit outward normal of a POLYGON feature, world.
+     */
+    nx = 0;
+    ny = 0;
+    nz = 0;
+
+    /**
+     * The shape's furthest projection on the direction, `max(p · d)`: its support plane along it.
+     * @type {number}
+     */
+    extreme = 0;
+
+    /**
+     * @param {number} n points about to be written
+     */
+    reserve(n) {
+        if (this.points.length < n * 3) {
+            this.points = new Float64Array(n * 3 * 2);
+        }
+    }
+}
+
+const scratch_local = new Float64Array(3);
+const scratch_world = new Float64Array(3);
+const scratch_st = new Float64Array(2);
+
+/** The local direction a shape's generic support is asked along. */
+const scratch_direction = new Float64Array(3);
+
+/*
+ The feature builders below all work in the shape's own frame and write local points;
+ support_feature carries the finished feature into the world in one pass. (They used to carry each
+ point as they wrote it, through a helper taking the pose's seven numbers: when V8 declined to inline
+ it, every one of those numbers was boxed on the heap, per point.)
+*/
+
+/**
+ * Append one point to a feature.
+ */
+function put(f, x, y, z) {
+    const o = f.count * 3;
+    f.points[o] = x;
+    f.points[o + 1] = y;
+    f.points[o + 2] = z;
+    f.count++;
+}
+
+/**
+ * Make a feature a POLYGON with this outward normal.
+ */
+function set_polygon(f, nx, ny, nz) {
+    f.kind = FEATURE_POLYGON;
+    f.nx = nx;
+    f.ny = ny;
+    f.nz = nz;
+}
+
+/**
+ * The vertices tied at the extreme of a point set along `(dx, dy, dz)`: a POINT, or a SEGMENT for two.
+ * More than two tie only for a face lying across the direction, which the callers have already taken
+ * as a POLYGON when it is within FACE_ALIGNMENT; past that, their centroid is a POINT.
+ */
+function tied_vertices(f, v, n, dx, dy, dz) {
+    let hi = -Infinity, lo = Infinity;
+
+    for (let i = 0; i < n; i++) {
+        const d = v[i * 3] * dx + v[i * 3 + 1] * dy + v[i * 3 + 2] * dz;
+        if (d > hi) hi = d;
+        if (d < lo) lo = d;
+    }
+
+    const floor = hi - (hi - lo) * SUPPORT_TIE_REL;
+
+    let tied = 0, cx = 0, cy = 0, cz = 0;
+    f.count = 0;
+    f.kind = FEATURE_POINT;
+
+    for (let i = 0; i < n; i++) {
+        const x = v[i * 3], y = v[i * 3 + 1], z = v[i * 3 + 2];
+        if (x * dx + y * dy + z * dz < floor) continue;
+
+        if (tied < 2) {
+            put(f, x, y, z);
+        }
+
+        cx += x; cy += y; cz += z;
+        tied++;
+    }
+
+    if (tied === 2) {
+        f.kind = FEATURE_SEGMENT;
+    } else if (tied > 2) {
+        f.count = 0;
+        put(f, cx / tied, cy / tied, cz / tied);
+    }
+
+    return hi;
+}
+
+/** The eight corners of a box, local, for the tied-vertex search. */
+const box_corners = new Float64Array(24);
+
+/** Half-extents, a face corner, and a face normal of a box by axis index. */
+const box_half = new Float64Array(3);
+const box_local = new Float64Array(3);
+const box_normal = new Float64Array(3);
+
+function box_feature(f, h, dx, dy, dz) {
+    const hx = h.x, hy = h.y, hz = h.z;
+    const ax = Math.abs(dx), ay = Math.abs(dy), az = Math.abs(dz);
+
+    // the face axis k most aligned with d, and the other two (u, w) cyclically after it
+    let k = 0;
+    if (ay > ax && ay >= az) k = 1;
+    else if (az > ax && az > ay) k = 2;
+
+    const dk = k === 0 ? dx : (k === 1 ? dy : dz);
+
+    if (Math.abs(dk) >= FACE_ALIGNMENT) {
+        const s = dk >= 0 ? 1 : -1;
+        const u = (k + 1) % 3, w = (k + 2) % 3;
+
+        box_half[0] = hx; box_half[1] = hy; box_half[2] = hz;
+
+        f.count = 0;
+        f.reserve(4);
+
+        for (let i = 0; i < 4; i++) {
+            box_local[k] = s * box_half[k];
+            box_local[u] = (i === 1 || i === 2 ? 1 : -1) * box_half[u];
+            box_local[w] = (i >= 2 ? 1 : -1) * box_half[w];
+            put(f, box_local[0], box_local[1], box_local[2]);
+        }
+
+        box_normal[0] = 0; box_normal[1] = 0; box_normal[2] = 0;
+        box_normal[k] = s;
+        set_polygon(f, box_normal[0], box_normal[1], box_normal[2]);
+
+        return hx * ax + hy * ay + hz * az;
+    }
+
+    for (let i = 0; i < 8; i++) {
+        box_corners[i * 3] = (i & 1) ? hx : -hx;
+        box_corners[i * 3 + 1] = (i & 2) ? hy : -hy;
+        box_corners[i * 3 + 2] = (i & 4) ? hz : -hz;
+    }
+
+    f.reserve(2);
+    return tied_vertices(f, box_corners, 8, dx, dy, dz);
+}
+
+function polytope_feature(f, shape, dx, dy, dz) {
+    const v = shape.vertices;
+    const fo = shape.face_offsets;
+    const fl = shape.face_loops;
+    const face_count = fo.length - 1;
+
+    // the face most aligned with d
+    let best = -Infinity, best_face = -1, bnx = 0, bny = 0, bnz = 0;
+
+    const planes = shape.face_loop_planes;
+
+    if (planes !== undefined) {
+        // stored, one per side (ConvexHullShape3D); a face with no area has a zero plane
+        for (let face = 0; face < face_count; face++) {
+            const o = face * 4;
+            const nx = planes[o], ny = planes[o + 1], nz = planes[o + 2];
+
+            if (nx * nx + ny * ny + nz * nz < 0.5) continue;
+
+            const align = nx * dx + ny * dy + nz * dz;
+
+            if (align > best) {
+                best = align;
+                best_face = face;
+                bnx = nx; bny = ny; bnz = nz;
+            }
+        }
+    } else {
+        // any other face-loop polytope: the Newell normal of each loop
+        for (let face = 0; face < face_count; face++) {
+            const s = fo[face], e = fo[face + 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;
+
+            const align = (nx * dx + ny * dy + nz * dz) / l;
+
+            if (align > best) {
+                best = align;
+                best_face = face;
+                bnx = nx / l; bny = ny / l; bnz = nz / l;
+            }
+        }
+    }
+
+    const n = v.length / 3;
+
+    if (best >= FACE_ALIGNMENT) {
+        const s = fo[best_face], e = fo[best_face + 1];
+
+        f.count = 0;
+        f.reserve(e - s);
+
+        for (let i = s; i < e; i++) {
+            const a = fl[i] * 3;
+            put(f, v[a], v[a + 1], v[a + 2]);
+        }
+
+        set_polygon(f, bnx, bny, bnz);
+
+        let hi = -Infinity;
+        for (let i = 0; i < n; i++) {
+            const d = v[i * 3] * dx + v[i * 3 + 1] * dy + v[i * 3 + 2] * dz;
+            if (d > hi) hi = d;
+        }
+        return hi;
+    }
+
+    f.reserve(2);
+    return tied_vertices(f, v, n, dx, dy, dz);
+}
+
+/** The cap's rim points, as angles round the axis. */
+const cap_cos = new Float64Array(CYLINDER_CAP_POINTS);
+const cap_sin = new Float64Array(CYLINDER_CAP_POINTS);
+
+for (let i = 0; i < CYLINDER_CAP_POINTS; i++) {
+    const a = (i / CYLINDER_CAP_POINTS) * Math.PI * 2;
+    cap_cos[i] = Math.cos(a);
+    cap_sin[i] = Math.sin(a);
+}
+
+function cylinder_feature(f, r, h, dx, dy, dz) {
+    const rl = Math.sqrt(dx * dx + dz * dz);
+    const ay = Math.abs(dy);
+
+    f.count = 0;
+
+    if (ay >= FACE_ALIGNMENT) {
+        const cap = dy >= 0 ? h : -h;
+
+        f.reserve(CYLINDER_CAP_POINTS);
+
+        for (let i = 0; i < CYLINDER_CAP_POINTS; i++) {
+            put(f, cap_cos[i] * r, cap, cap_sin[i] * r);
+        }
+
+        set_polygon(f, 0, dy >= 0 ? 1 : -1, 0);
+    } else {
+        const ux = dx / rl, uz = dz / rl;
+
+        f.reserve(2);
+
+        if (ay <= SEGMENT_ALIGNMENT) {
+            put(f, ux * r, -h, uz * r);
+            put(f, ux * r, h, uz * r);
+            f.kind = FEATURE_SEGMENT;
+        } else {
+            put(f, ux * r, dy >= 0 ? h : -h, uz * r);
+            f.kind = FEATURE_POINT;
+        }
+    }
+
+    return ay * h + rl * r;
+}
+
+function capsule_feature(f, r, h, dx, dy, dz) {
+    f.count = 0;
+    f.reserve(2);
+
+    if (Math.abs(dy) <= SEGMENT_ALIGNMENT) {
+        put(f, dx * r, -h + dy * r, dz * r);
+        put(f, dx * r, h + dy * r, dz * r);
+        f.kind = FEATURE_SEGMENT;
+    } else {
+        put(f, dx * r, (dy >= 0 ? h : -h) + dy * r, dz * r);
+        f.kind = FEATURE_POINT;
+    }
+
+    return Math.abs(dy) * h + r;
+}
+
+/**
+ * The feature of a {@link TransformedShape3D} — a subject under an affine matrix `M = [L | t]`, which
+ * may scale it: the subject's own feature along `normalise(Lᵀ·d)`, its points carried by `M`. That is
+ * the support mapping of an affine image — the support of `M(S)` along `d` is `M` applied to the
+ * support of `S` along `Lᵀ·d` — so a stretched box's long face is still a face, and its feature still
+ * four corners; a polygon's normal maps by `(L⁻¹)ᵀ`, which keeps it perpendicular to the face.
+ *
+ * Rigid wrappers never get here (the narrowphase collides them as their subject); one that scales
+ * used to be a single support point, and a stretched box rocked on it and never slept.
+ *
+ * @returns {number} the wrapper-local extreme along `(dx, dy, dz)`
+ */
+function transformed_feature(f, shape, dx, dy, dz) {
+    const m = shape.transform;
+
+    // the subject's direction, Lᵀ·d
+    let sx = m[0] * dx + m[1] * dy + m[2] * dz;
+    let sy = m[4] * dx + m[5] * dy + m[6] * dz;
+    let sz = m[8] * dx + m[9] * dy + m[10] * dz;
+
+    const sl = Math.sqrt(sx * sx + sy * sy + sz * sz);
+    if (sl > 0) {
+        sx /= sl; sy /= sl; sz /= sl;
+    }
+
+    // the subject's feature, in its own frame
+    local_feature(f, shape.subject, sx, sy, sz);
+
+    // carried through M, into the wrapper's frame
+    const p = f.points;
+    let extreme = -Infinity;
+
+    for (let i = 0; i < f.count; i++) {
+        const o = i * 3;
+        const x = p[o], y = p[o + 1], z = p[o + 2];
+
+        const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
+        const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
+        const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
+
+        const e = wx * dx + wy * dy + wz * dz;
+        if (e > extreme) extreme = e;
+
+        p[o] = wx;
+        p[o + 1] = wy;
+        p[o + 2] = wz;
+    }
+
+    if (f.kind === FEATURE_POLYGON) {
+        // normal by the inverse transpose: n'ᵢ = Σⱼ (M⁻¹)ⱼᵢ nⱼ
+        const inv = shape.inverse_transform;
+        const nx = f.nx, ny = f.ny, nz = f.nz;
+
+        const wx = inv[0] * nx + inv[1] * ny + inv[2] * nz;
+        const wy = inv[4] * nx + inv[5] * ny + inv[6] * nz;
+        const wz = inv[8] * nx + inv[9] * ny + inv[10] * nz;
+
+        const wl = Math.sqrt(wx * wx + wy * wy + wz * wz);
+
+        f.nx = wx / wl;
+        f.ny = wy / wl;
+        f.nz = wz / wl;
+    }
+
+    return extreme;
+}
+
+/**
+ * The supporting feature of a shape along a direction, both in the shape's own frame.
+ *
+ * @returns {number} the shape's extreme projection on the direction
+ */
+function local_feature(f, shape, lx, ly, lz) {
+    if (shape.isBoxShape3D === true) {
+        return box_feature(f, shape.half_extents, lx, ly, lz);
+    }
+
+    if (shape.face_loops !== undefined && shape.face_offsets !== undefined) {
+        return polytope_feature(f, shape, lx, ly, lz);
+    }
+
+    if (shape.isCylinderShape3D === true) {
+        return cylinder_feature(f, shape.radius, shape.height * 0.5, lx, ly, lz);
+    }
+
+    if (shape.isCapsuleShape3D === true) {
+        return capsule_feature(f, shape.radius, shape.height * 0.5, lx, ly, lz);
+    }
+
+    if (shape.isTransformedShape3D === true && shape.subject !== null) {
+        return transformed_feature(f, shape, lx, ly, lz);
+    }
+
+    scratch_direction[0] = lx;
+    scratch_direction[1] = ly;
+    scratch_direction[2] = lz;
+    shape.support(scratch_local, 0, scratch_direction, 0);
+    const sx = scratch_local[0], sy = scratch_local[1], sz = scratch_local[2];
+
+    f.count = 0;
+    f.kind = FEATURE_POINT;
+    put(f, sx, sy, sz);
+
+    return sx * lx + sy * ly + sz * lz;
+}
+
+/**
+ * The supporting feature of a posed convex shape along a world direction — see the module notes.
+ *
+ * @param {SupportFeature} f receives the feature
+ * @param {AbstractShape3D|{vertices, face_offsets, face_loops, support}} shape
+ * @param {number} px shape position x
+ * @param {number} py
+ * @param {number} pz
+ * @param {number} qx shape rotation quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} dx unit world direction, toward the other body
+ * @param {number} dy
+ * @param {number} dz
+ */
+export function support_feature(f, shape, px, py, pz, qx, qy, qz, qw, dx, dy, dz) {
+    v3_quaternion_apply_inverse(scratch_local, 0, dx, dy, dz, qx, qy, qz, qw);
+    const lx = scratch_local[0], ly = scratch_local[1], lz = scratch_local[2];
+
+    const extreme = local_feature(f, shape, lx, ly, lz);
+
+    // into the world: p_world = q · p · q* + position (v3_quaternion_apply, written out)
+    const p = f.points;
+
+    for (let i = 0; i < f.count; i++) {
+        const o = i * 3;
+        const vx = p[o], vy = p[o + 1], vz = p[o + 2];
+
+        const tx = qw * vx + qy * vz - qz * vy;
+        const ty = qw * vy + qz * vx - qx * vz;
+        const tz = qw * vz + qx * vy - qy * vx;
+        const tw = -qx * vx - qy * vy - qz * vz;
+
+        p[o] = tx * qw - tw * qx - ty * qz + tz * qy + px;
+        p[o + 1] = ty * qw - tw * qy - tz * qx + tx * qz + py;
+        p[o + 2] = tz * qw - tw * qz - tx * qy + ty * qx + pz;
+    }
+
+    if (f.kind === FEATURE_POLYGON) {
+        v3_quaternion_apply(scratch_world, 0, f.nx, f.ny, f.nz, qx, qy, qz, qw);
+        f.nx = scratch_world[0];
+        f.ny = scratch_world[1];
+        f.nz = scratch_world[2];
+    }
+
+    // local extreme to world: (q·v + p) · d = v · (q*·d) + p · d
+    f.extreme = extreme + px * dx + py * dy + pz * dz;
+}
+
+/**
+ * The supporting feature of a world triangle along a direction: the triangle itself when its outward
+ * normal is within {@link FACE_ALIGNMENT} of the direction, else the vertices tied at the extreme.
+ *
+ * @param {SupportFeature} f
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} cz
+ * @param {number} nx unit outward normal of the triangle
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} dx unit direction, toward the other body
+ * @param {number} dy
+ * @param {number} dz
+ */
+export function triangle_feature(f, ax, ay, az, bx, by, bz, cx, cy, cz, nx, ny, nz, dx, dy, dz) {
+    f.reserve(3);
+
+    triangle_vertices[0] = ax; triangle_vertices[1] = ay; triangle_vertices[2] = az;
+    triangle_vertices[3] = bx; triangle_vertices[4] = by; triangle_vertices[5] = bz;
+    triangle_vertices[6] = cx; triangle_vertices[7] = cy; triangle_vertices[8] = cz;
+
+    if (nx * dx + ny * dy + nz * dz >= FACE_ALIGNMENT) {
+        f.count = 3;
+        f.points.set(triangle_vertices);
+        f.kind = FEATURE_POLYGON;
+        f.nx = nx; f.ny = ny; f.nz = nz;
+
+        f.extreme = Math.max(
+            ax * dx + ay * dy + az * dz,
+            bx * dx + by * dy + bz * dz,
+            cx * dx + cy * dy + cz * dz
+        );
+        return;
+    }
+
+    // the triangle is given in the world already
+    f.extreme = tied_vertices(f, triangle_vertices, 3, dx, dy, dz);
+}
+
+const triangle_vertices = new Float64Array(9);
+
+/** Clip scratch, grown to fit. */
+let clip_a = new Float64Array(32 * 3);
+let clip_b = new Float64Array(32 * 3);
+let candidates = new Float64Array(32 * 4);
+
+/** Centroid and largest squared distance from it of a feature's points: `[cx, cy, cz, spread²]`. */
+const centroid_a = new Float64Array(4);
+const centroid_b = new Float64Array(4);
+
+function feature_centroid(out, f) {
+    const p = f.points, n = f.count;
+    let cx = 0, cy = 0, cz = 0;
+
+    for (let i = 0; i < n; i++) {
+        cx += p[i * 3]; cy += p[i * 3 + 1]; cz += p[i * 3 + 2];
+    }
+
+    cx /= n; cy /= n; cz /= n;
+
+    let spread = 0;
+
+    for (let i = 0; i < n; i++) {
+        const ex = p[i * 3] - cx, ey = p[i * 3 + 1] - cy, ez = p[i * 3 + 2] - cz;
+        const s = ex * ex + ey * ey + ez * ez;
+        if (s > spread) spread = s;
+    }
+
+    out[0] = cx; out[1] = cy; out[2] = cz; out[3] = spread;
+}
+
+/**
+ * Clip the incident feature to the reference polygon's prism and keep the points that reach behind
+ * its plane. Writes `(x, y, z, depth)` candidates; returns their count.
+ */
+function clip_to_reference(ref, inc) {
+    const rp = ref.points, rn = ref.count;
+    const nx = ref.nx, ny = ref.ny, nz = ref.nz;
+
+    const cap = inc.count + rn + 2;
+    if (clip_a.length < cap * 3) {
+        clip_a = new Float64Array(cap * 3);
+        clip_b = new Float64Array(cap * 3);
+        candidates = new Float64Array(cap * 4);
+    }
+
+    // reference centroid: orients each side plane outward
+    let rcx = 0, rcy = 0, rcz = 0;
+    for (let i = 0; i < rn; i++) {
+        rcx += rp[i * 3]; rcy += rp[i * 3 + 1]; rcz += rp[i * 3 + 2];
+    }
+    rcx /= rn; rcy /= rn; rcz /= rn;
+
+    let src = clip_a, dst = clip_b;
+    let n = inc.count;
+
+    const ip = inc.points;
+    for (let i = 0; i < n * 3; i++) {
+        src[i] = ip[i];
+    }
+
+    // a segment clips as a parametric interval, so it never sprouts duplicate crossings
+    let t0 = 0, t1 = 1;
+    const segment = inc.kind === FEATURE_SEGMENT;
+
+    for (let e = 0; e < rn && n > 0; e++) {
+        const a = e * 3, b = ((e + 1) % rn) * 3;
+        const ex = rp[b] - rp[a], ey = rp[b + 1] - rp[a + 1], ez = rp[b + 2] - rp[a + 2];
+
+        // side plane through the edge, normal pointing out of the polygon
+        let sx = ey * nz - ez * ny, sy = ez * nx - ex * nz, sz = ex * ny - ey * nx;
+        if ((rcx - rp[a]) * sx + (rcy - rp[a + 1]) * sy + (rcz - rp[a + 2]) * sz > 0) {
+            sx = -sx; sy = -sy; sz = -sz;
+        }
+
+        if (segment) {
+            const d0 = (src[0] - rp[a]) * sx + (src[1] - rp[a + 1]) * sy + (src[2] - rp[a + 2]) * sz;
+            const d1 = (src[3] - rp[a]) * sx + (src[4] - rp[a + 1]) * sy + (src[5] - rp[a + 2]) * sz;
+
+            if (d0 > 0 && d1 > 0) {
+                n = 0;
+            } else if (d0 > 0) {
+                t0 = Math.max(t0, d0 / (d0 - d1));
+            } else if (d1 > 0) {
+                t1 = Math.min(t1, d0 / (d0 - d1));
+            }
+        } else {
+            n = clip_poly(src, n, dst, sx, sy, sz, rp[a], rp[a + 1], rp[a + 2]);
+            const t = src; src = dst; dst = t;
+        }
+    }
+
+    if (segment && n > 0) {
+        if (t0 > t1) {
+            n = 0;
+        } else {
+            const x0 = src[0], y0 = src[1], z0 = src[2];
+            const lx = src[3] - x0, ly = src[4] - y0, lz = src[5] - z0;
+
+            dst[0] = x0 + lx * t0; dst[1] = y0 + ly * t0; dst[2] = z0 + lz * t0;
+            dst[3] = x0 + lx * t1; dst[4] = y0 + ly * t1; dst[5] = z0 + lz * t1;
+            n = t1 > t0 ? 2 : 1;
+
+            const t = src; src = dst; dst = t;
+        }
+    }
+
+    let kept = 0;
+
+    for (let i = 0; i < n; i++) {
+        const x = src[i * 3], y = src[i * 3 + 1], z = src[i * 3 + 2];
+        const depth = -((x - rp[0]) * nx + (y - rp[1]) * ny + (z - rp[2]) * nz);
+
+        if (depth < 0) continue;
+
+        candidates[kept * 4] = x;
+        candidates[kept * 4 + 1] = y;
+        candidates[kept * 4 + 2] = z;
+        candidates[kept * 4 + 3] = depth;
+        kept++;
+    }
+
+    return kept;
+}
+
+/**
+ * Squared sine of the angle below which two segment features count as parallel — the threshold
+ * `capsule_capsule_multi_contacts` uses for capsule axes (about 2.6°).
+ * @type {number}
+ */
+const SEGMENT_PARALLEL_SIN_SQR = 0.002;
+
+/**
+ * Two parallel segment features — two logs lying along each other, a capsule along a cylinder's side —
+ * touch along the stretch of line they share, and one point of it is a pivot the upper body pitches
+ * and rolls about: a pile of cylinders sank 15 cm into its groove and never slept. Writes a contact at
+ * each end of the shared stretch, at the depth along `n` it reaches there.
+ *
+ * @returns {boolean} false when the segments are not parallel, share no stretch, or neither end of
+ *   it reaches the other segment; the caller then takes the closest points
+ */
+function parallel_segments(out, fa, fb, nx, ny, nz) {
+    const pa = fa.points, pb = fb.points;
+
+    const d1x = pa[3] - pa[0], d1y = pa[4] - pa[1], d1z = pa[5] - pa[2];
+    const d2x = pb[3] - pb[0], d2y = pb[4] - pb[1], d2z = pb[5] - pb[2];
+
+    const len1_sqr = d1x * d1x + d1y * d1y + d1z * d1z;
+    const len2_sqr = d2x * d2x + d2y * d2y + d2z * d2z;
+
+    if (!(len1_sqr > 0) || !(len2_sqr > 0)) return false;
+
+    const cx = d1y * d2z - d1z * d2y, cy = d1z * d2x - d1x * d2z, cz = d1x * d2y - d1y * d2x;
+
+    if (cx * cx + cy * cy + cz * cz >= SEGMENT_PARALLEL_SIN_SQR * len1_sqr * len2_sqr) return false;
+
+    // B's ends along A's line, from A's first end
+    const len1 = Math.sqrt(len1_sqr);
+    const ux = d1x / len1, uy = d1y / len1, uz = d1z / len1;
+
+    const t0 = (pb[0] - pa[0]) * ux + (pb[1] - pa[1]) * uy + (pb[2] - pa[2]) * uz;
+    const t1 = (pb[3] - pa[0]) * ux + (pb[4] - pa[1]) * uy + (pb[5] - pa[2]) * uz;
+
+    const lo = Math.max(0, Math.min(t0, t1));
+    const hi = Math.min(len1, Math.max(t0, t1));
+
+    if (!(hi > lo)) return false;
+
+    let count = 0;
+
+    for (let e = 0; e < 2; e++) {
+        const s = e === 0 ? lo : hi;
+        const ax = pa[0] + ux * s, ay = pa[1] + uy * s, az = pa[2] + uz * s;
+
+        // the closest point of B's segment
+        let t = ((ax - pb[0]) * d2x + (ay - pb[1]) * d2y + (az - pb[2]) * d2z) / len2_sqr;
+        t = t < 0 ? 0 : (t > 1 ? 1 : t);
+        const bx = pb[0] + d2x * t, by = pb[1] + d2y * t, bz = pb[2] + d2z * t;
+
+        // A is on the +n side: B's point past A's along n is penetration
+        const depth = (bx - ax) * nx + (by - ay) * ny + (bz - az) * nz;
+
+        if (depth < 0) continue;
+
+        const o = 4 + count * 7;
+        out[o] = ax; out[o + 1] = ay; out[o + 2] = az;
+        out[o + 3] = bx; out[o + 4] = by; out[o + 5] = bz;
+        out[o + 6] = depth;
+        count++;
+    }
+
+    if (count === 0) return false;
+
+    out[0] = nx;
+    out[1] = ny;
+    out[2] = nz;
+    out[3] = count;
+
+    return true;
+}
+
+/**
+ * How far two features overlap along an axis `m` pointing from B toward A: B's furthest point along it
+ * less A's nearest.
+ */
+function feature_overlap(fa, fb, mx, my, mz) {
+    let b_max = -Infinity;
+    for (let i = 0; i < fb.count; i++) {
+        const o = i * 3;
+        const d = fb.points[o] * mx + fb.points[o + 1] * my + fb.points[o + 2] * mz;
+        if (d > b_max) b_max = d;
+    }
+
+    let a_min = Infinity;
+    for (let i = 0; i < fa.count; i++) {
+        const o = i * 3;
+        const d = fa.points[o] * mx + fa.points[o + 1] * my + fa.points[o + 2] * mz;
+        if (d < a_min) a_min = d;
+    }
+
+    return b_max - a_min;
+}
+
+/**
+ * Output length of {@link feature_manifold}: `[nx, ny, nz, count, (ax, ay, az, bx, by, bz, depth) × 4]`.
+ * @type {number}
+ */
+export const FEATURE_MANIFOLD_OUT_LENGTH = 4 + 4 * 7;
+
+/**
+ * Contacts between two supporting features, along the axis `n` (unit, from B toward A) the pair
+ * penetrates along by `depth`. A's feature must face B (taken along −n), B's face A (along +n).
+ *
+ * When either feature is a face, the other is clipped to that face's prism and every point that
+ * reaches behind it is a contact, at the depth it reaches, with the face's own normal — the exact
+ * normal of a face-on-face contact, however rough the axis it was found along. Otherwise, or when
+ * the clip leaves nothing, one contact: two segments meet at their closest points; anything else on
+ * the smaller feature's centroid, projected along `n` onto the other side's support plane, at
+ * `depth`.
+ *
+ * Layout matches {@link convex_hull_clip}: `out[0..2]` the normal (B→A), `out[3]` the count, then
+ * per contact the point on A, the point on B and the depth.
+ *
+ * @param {Float64Array} out length ≥ {@link FEATURE_MANIFOLD_OUT_LENGTH}
+ * @param {SupportFeature} fa
+ * @param {SupportFeature} fb
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} depth
+ */
+export function feature_manifold(out, fa, fb, nx, ny, nz, depth) {
+    let ref = null, inc = null, ref_is_a = false;
+
+    if (fa.kind === FEATURE_POLYGON && fb.kind === FEATURE_POLYGON) {
+        // SAT over the two faces' normals: the reference is the face whose normal the features overlap
+        // least along — for a cap leaning on a floor, the floor, whose normal the rim only just reaches
+        // past, not the cap, along whose tilted normal the floor's far corners stand proud. The axis
+        // the pair was found along cannot decide it: off a triangle's degenerate support it leans
+        // toward either. Faces parallel to each other overlap equally along both; then the one that
+        // meets the axis more squarely.
+        const along_a = feature_overlap(fa, fb, -fa.nx, -fa.ny, -fa.nz);
+        const along_b = feature_overlap(fa, fb, fb.nx, fb.ny, fb.nz);
+        const tie = 1e-9 * (1 + Math.max(Math.abs(along_a), Math.abs(along_b)));
+
+        if (along_a < along_b - tie) {
+            ref_is_a = true;
+        } else if (along_b < along_a - tie) {
+            ref_is_a = false;
+        } else {
+            ref_is_a = -(fa.nx * nx + fa.ny * ny + fa.nz * nz) >= fb.nx * nx + fb.ny * ny + fb.nz * nz;
+        }
+    } else if (fa.kind === FEATURE_POLYGON) {
+        ref_is_a = true;
+    }
+
+    if (fa.kind === FEATURE_POLYGON || fb.kind === FEATURE_POLYGON) {
+        ref = ref_is_a ? fa : fb;
+        inc = ref_is_a ? fb : fa;
+
+        const kept = clip_to_reference(ref, inc);
+
+        if (kept > 0) {
+            const count = reduce_manifold_contacts(candidates, kept, 4, 4, 3);
+            const rnx = ref.nx, rny = ref.ny, rnz = ref.nz;
+            const rp = ref.points;
+
+            // the reference face's outward normal points at the other body: B→A if it is B's
+            out[0] = ref_is_a ? -rnx : rnx;
+            out[1] = ref_is_a ? -rny : rny;
+            out[2] = ref_is_a ? -rnz : rnz;
+            out[3] = count;
+
+            for (let k = 0; k < count; k++) {
+                const x = candidates[k * 4], y = candidates[k * 4 + 1], z = candidates[k * 4 + 2];
+                const d = candidates[k * 4 + 3];
+
+                // onto the reference plane
+                const sep = (x - rp[0]) * rnx + (y - rp[1]) * rny + (z - rp[2]) * rnz;
+                const qx = x - rnx * sep, qy = y - rny * sep, qz = z - rnz * sep;
+
+                const o = 4 + k * 7;
+                if (ref_is_a) {
+                    out[o] = qx; out[o + 1] = qy; out[o + 2] = qz;
+                    out[o + 3] = x; out[o + 4] = y; out[o + 5] = z;
+                } else {
+                    out[o] = x; out[o + 1] = y; out[o + 2] = z;
+                    out[o + 3] = qx; out[o + 4] = qy; out[o + 5] = qz;
+                }
+                out[o + 6] = d;
+            }
+
+            return;
+        }
+    }
+
+    out[0] = nx;
+    out[1] = ny;
+    out[2] = nz;
+    out[3] = 1;
+    out[10] = depth;
+
+    if (fa.kind === FEATURE_SEGMENT && fb.kind === FEATURE_SEGMENT) {
+        if (parallel_segments(out, fa, fb, nx, ny, nz)) {
+            return;
+        }
+
+        const pa = fa.points, pb = fb.points;
+
+        line3_compute_segment_segment_closest_points(
+            scratch_st,
+            pa[0], pa[1], pa[2], pa[3], pa[4], pa[5],
+            pb[0], pb[1], pb[2], pb[3], pb[4], pb[5]
+        );
+
+        const s = scratch_st[0], t = scratch_st[1];
+
+        out[4] = pa[0] + (pa[3] - pa[0]) * s;
+        out[5] = pa[1] + (pa[4] - pa[1]) * s;
+        out[6] = pa[2] + (pa[5] - pa[2]) * s;
+        out[7] = pb[0] + (pb[3] - pb[0]) * t;
+        out[8] = pb[1] + (pb[4] - pb[1]) * t;
+        out[9] = pb[2] + (pb[5] - pb[2]) * t;
+        return;
+    }
+
+    feature_centroid(centroid_a, fa);
+    feature_centroid(centroid_b, fb);
+
+    // n · x is −fa.extreme on A's support plane (A's was taken along −n), fb.extreme on B's
+    if (centroid_a[3] <= centroid_b[3]) {
+        const cx = centroid_a[0], cy = centroid_a[1], cz = centroid_a[2];
+        const k = fb.extreme - (nx * cx + ny * cy + nz * cz);
+
+        out[4] = cx; out[5] = cy; out[6] = cz;
+        out[7] = cx + nx * k; out[8] = cy + ny * k; out[9] = cz + nz * k;
+    } else {
+        const cx = centroid_b[0], cy = centroid_b[1], cz = centroid_b[2];
+        const k = -fa.extreme - (nx * cx + ny * cy + nz * cz);
+
+        out[4] = cx + nx * k; out[5] = cy + ny * k; out[6] = cz + nz * k;
+        out[7] = cx; out[8] = cy; out[9] = cz;
+    }
+}