@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,122 @@
+/**
+ * Compute the two world endpoints of a capsule's central segment given its
+ * pose. The capsule is Y-aligned in body frame; the segment runs from
+ * `(0, -h/2, 0)` to `(0, +h/2, 0)`. Writes endpoints into `out` as
+ * `[ax, ay, az, bx, by, bz]`.
+ *
+ * @param {number[]|Float64Array} out length >= 6
+ * @param {number} cx capsule centre x
+ * @param {number} cy
+ * @param {number} cz
+ * @param {number} qx quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} half_height
+ */
+export function capsule_world_segment(out: number[] | Float64Array, cx: number, cy: number, cz: number, qx: number, qy: number, qz: number, qw: number, half_height: number): void;
+/**
+ * Capsule (A) vs sphere (B) contact, closed-form via point-segment distance.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} a_cx  capsule centre x
+ * @param {number} a_cy
+ * @param {number} a_cz
+ * @param {number} a_qx  capsule rotation
+ * @param {number} a_qy
+ * @param {number} a_qz
+ * @param {number} a_qw
+ * @param {number} a_radius
+ * @param {number} a_half_h capsule half-height (not including caps)
+ * @param {number} b_cx  sphere centre x
+ * @param {number} b_cy
+ * @param {number} b_cz
+ * @param {number} b_radius
+ * @returns {boolean} true on overlap
+ */
+export function capsule_sphere_contact(out: number[] | Float64Array, a_cx: number, a_cy: number, a_cz: number, a_qx: number, a_qy: number, a_qz: number, a_qw: number, a_radius: number, a_half_h: number, b_cx: number, b_cy: number, b_cz: number, b_radius: number): boolean;
+/**
+ * Two capsules (A and B). Reduces to segment-segment closest pair + radius.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @returns {boolean} true on overlap
+ */
+export function capsule_capsule_contact(out: number[] | Float64Array, a_cx: any, a_cy: any, a_cz: any, a_qx: any, a_qy: any, a_qz: any, a_qw: any, a_radius: any, a_half_h: any, b_cx: any, b_cy: any, b_cz: any, b_qx: any, b_qy: any, b_qz: any, b_qw: any, b_radius: any, b_half_h: any): boolean;
+/**
+ * Capsule (A) vs oriented box (B). Brings the capsule segment into box-local
+ * space, then refines via 2 fixed-point iterations between:
+ *   - closest point on the segment to the current box-side candidate
+ *   - clamped point on the box closest to the current segment-side candidate
+ *
+ * Two iterations suffice for the cases this engine targets (sphere-like cap
+ * geometry against axis-aligned-in-local box). When the segment passes
+ * through the box, the "inside" branch picks the smallest-overlap face
+ * deterministically, mirroring {@link sphere_box_contact}.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @returns {boolean}
+ */
+export function capsule_box_contact(out: number[] | Float64Array, a_cx: any, a_cy: any, a_cz: any, a_qx: any, a_qy: any, a_qz: any, a_qw: any, a_radius: any, a_half_h: any, b_cx: any, b_cy: any, b_cz: any, b_qx: any, b_qy: any, b_qz: any, b_qw: any, b_hx: any, b_hy: any, b_hz: any): boolean;
+/**
+ * Multi-point capsule-vs-OBB contact generation. Emits up to
+ * {@link CAPSULE_BOX_MAX_CONTACTS} contacts into `out` in the
+ * `(wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth)` stride layout.
+ *
+ * The motivation: a capsule lying flat on a face needs more than one
+ * contact to rest stably — a single contact at the segment's closest point
+ * is positionally ambiguous (every interior segment point is equidistant
+ * from the face), and the body wobbles around whichever point the
+ * iterative closest-point solver happened to converge on. Two contacts at
+ * the cap centres pin the capsule's rotation about its long axis.
+ *
+ * Algorithm:
+ *  1. Closest-point-on-segment vs OBB → primary contact (same as
+ *     {@link capsule_box_contact}).
+ *  2. Treat each cap centre as a sphere of cap-radius and run
+ *     {@link sphere_box_contact} → up to two additional contacts.
+ *  3. Dedupe spatially against the primary so a capsule touching with one
+ *     cap doesn't emit two contacts at the same point.
+ *
+ * @param {Float64Array} out length >= CAPSULE_BOX_MAX_CONTACTS * CAPSULE_BOX_CONTACT_STRIDE
+ * @param {number} a_cx capsule centre x
+ * @param {number} a_cy
+ * @param {number} a_cz
+ * @param {number} a_qx capsule rotation
+ * @param {number} a_qy
+ * @param {number} a_qz
+ * @param {number} a_qw
+ * @param {number} a_radius
+ * @param {number} a_half_h
+ * @param {number} b_cx box centre x
+ * @param {number} b_cy
+ * @param {number} b_cz
+ * @param {number} b_qx
+ * @param {number} b_qy
+ * @param {number} b_qz
+ * @param {number} b_qw
+ * @param {number} b_hx
+ * @param {number} b_hy
+ * @param {number} b_hz
+ * @returns {number} number of contacts emitted, in `[0, CAPSULE_BOX_MAX_CONTACTS]`
+ */
+export function capsule_box_multi_contacts(out: Float64Array, a_cx: number, a_cy: number, a_cz: number, a_qx: number, a_qy: number, a_qz: number, a_qw: number, a_radius: number, a_half_h: number, b_cx: number, b_cy: number, b_cz: number, b_qx: number, b_qy: number, b_qz: number, b_qw: number, b_hx: number, b_hy: number, b_hz: number): number;
+/**
+ * Output stride per contact in {@link capsule_box_multi_contacts}.
+ * Matches the candidate-buffer layout used by `narrowphase_step`.
+ *
+ *   0..2  : world contact on capsule side
+ *   3..5  : world contact on box side
+ *   6..8  : normal from box (B) toward capsule (A)
+ *   9     : depth (positive = penetration)
+ *
+ * @type {number}
+ */
+export const CAPSULE_BOX_CONTACT_STRIDE: number;
+/**
+ * Maximum contact points {@link capsule_box_multi_contacts} can emit.
+ *  - 1 from the closest-point-on-segment vs OBB query (primary)
+ *  - up to 2 from the cap-centre sphere-vs-OBB queries (one per endpoint)
+ * @type {number}
+ */
+export const CAPSULE_BOX_MAX_CONTACTS: number;
+//# sourceMappingURL=capsule_contacts.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capsule_contacts.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/capsule_contacts.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;GAeG;AACH,2CAVW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,eACN,MAAM,QAOhB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,4CAhBW,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,GACJ,OAAO,CA6CnB;AAMD;;;;;GAKG;AACH,6CAHW,MAAM,EAAE,GAAC,YAAY,yNACnB,OAAO,CAuEnB;AAOD;;;;;;;;;;;;;GAaG;AACH,yCAHW,MAAM,EAAE,GAAC,YAAY,4NACnB,OAAO,CA8FnB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,gDAtBW,YAAY,QACZ,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,MAAM,CAuElB;AApJD;;;;;;;;;;GAUG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}

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

@@ -0,0 +1,462 @@
+import { line3_closest_points_segment_segment } from "../../../core/geom/3d/line/line3_closest_points_segment_segment.js";
+import { line3_compute_segment_nearest_point_to_point_t } from "../../../core/geom/3d/line/line3_compute_segment_nearest_point_to_point_t.js";
+import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { v3_quat3_apply_inverse } from "../../../core/geom/vec3/v3_quat3_apply_inverse.js";
+import { sphere_box_contact } from "./sphere_box_contact.js";
+
+/**
+ * Closed-form narrowphase helpers for the capsule family. A capsule is the
+ * Minkowski sum of a line segment and a sphere of radius `r`, so contact
+ * resolution reduces to:
+ *   - capsule-sphere      → point-on-segment distance, then sphere-style normal
+ *   - capsule-capsule     → segment-segment closest pair
+ *   - capsule-box         → segment-vs-OBB closest point (iterative)
+ *
+ * Output convention (matches the rest of the narrowphase family):
+ *   out[0..2] : normal pointing from B toward A
+ *   out[3]    : penetration depth (positive)
+ *   out[4..6] : world contact on A's surface
+ *   out[7..9] : world contact on B's surface
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const scratch_st = new Float64Array(2);
+
+const scratch_seg = new Float64Array(6);
+
+/**
+ * Compute the two world endpoints of a capsule's central segment given its
+ * pose. The capsule is Y-aligned in body frame; the segment runs from
+ * `(0, -h/2, 0)` to `(0, +h/2, 0)`. Writes endpoints into `out` as
+ * `[ax, ay, az, bx, by, bz]`.
+ *
+ * @param {number[]|Float64Array} out length >= 6
+ * @param {number} cx capsule centre x
+ * @param {number} cy
+ * @param {number} cz
+ * @param {number} qx quaternion x
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw
+ * @param {number} half_height
+ */
+export function capsule_world_segment(out, cx, cy, cz, qx, qy, qz, qw, half_height) {
+    v3_quat3_apply(out, 0, 0, -half_height, 0, qx, qy, qz, qw);
+    v3_quat3_apply(out, 3, 0,  half_height, 0, qx, qy, qz, qw);
+    out[0] += cx; out[1] += cy; out[2] += cz;
+    out[3] += cx; out[4] += cy; out[5] += cz;
+}
+
+// --- capsule vs sphere ------------------------------------------------------
+
+/**
+ * Capsule (A) vs sphere (B) contact, closed-form via point-segment distance.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @param {number} a_cx  capsule centre x
+ * @param {number} a_cy
+ * @param {number} a_cz
+ * @param {number} a_qx  capsule rotation
+ * @param {number} a_qy
+ * @param {number} a_qz
+ * @param {number} a_qw
+ * @param {number} a_radius
+ * @param {number} a_half_h capsule half-height (not including caps)
+ * @param {number} b_cx  sphere centre x
+ * @param {number} b_cy
+ * @param {number} b_cz
+ * @param {number} b_radius
+ * @returns {boolean} true on overlap
+ */
+export function capsule_sphere_contact(
+    out,
+    a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_radius, a_half_h,
+    b_cx, b_cy, b_cz, b_radius
+) {
+    capsule_world_segment(scratch_seg, a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_half_h);
+    const sax = scratch_seg[0], say = scratch_seg[1], saz = scratch_seg[2];
+    const sbx = scratch_seg[3], sby = scratch_seg[4], sbz = scratch_seg[5];
+
+    const t = line3_compute_segment_nearest_point_to_point_t(sax, say, saz, sbx, sby, sbz, b_cx, b_cy, b_cz);
+
+    const px = sax + (sbx - sax) * t;
+    const py = say + (sby - say) * t;
+    const pz = saz + (sbz - saz) * t;
+
+    const dx = px - b_cx;
+    const dy = py - b_cy;
+    const dz = pz - b_cz;
+    const dist_sqr = dx * dx + dy * dy + dz * dz;
+    const sum = a_radius + b_radius;
+    if (dist_sqr >= sum * sum) return false;
+
+    const dist = Math.sqrt(dist_sqr);
+    let nx, ny, nz;
+    if (dist > 0) {
+        const inv = 1 / dist;
+        nx = dx * inv; ny = dy * inv; nz = dz * inv;
+    } else {
+        // Sphere centre exactly on the capsule segment — pick a deterministic tie-break.
+        nx = 1; ny = 0; nz = 0;
+    }
+
+    out[0] = nx; out[1] = ny; out[2] = nz; // normal from B to A
+    out[3] = sum - dist;
+    // World contact on A (capsule): segment point pushed back by capsule radius along -normal
+    out[4] = px - nx * a_radius;
+    out[5] = py - ny * a_radius;
+    out[6] = pz - nz * a_radius;
+    // World contact on B (sphere): sphere centre pushed along +normal by sphere radius
+    out[7] = b_cx + nx * b_radius;
+    out[8] = b_cy + ny * b_radius;
+    out[9] = b_cz + nz * b_radius;
+    return true;
+}
+
+// --- capsule vs capsule -----------------------------------------------------
+
+const scratch_seg_b = new Float64Array(6);
+
+/**
+ * Two capsules (A and B). Reduces to segment-segment closest pair + radius.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @returns {boolean} true on overlap
+ */
+export function capsule_capsule_contact(
+    out,
+    a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_radius, a_half_h,
+    b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw, b_radius, b_half_h
+) {
+    capsule_world_segment(scratch_seg,   a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_half_h);
+    capsule_world_segment(scratch_seg_b, b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw, b_half_h);
+
+    const a0x = scratch_seg[0], a0y = scratch_seg[1], a0z = scratch_seg[2];
+    const a1x = scratch_seg[3], a1y = scratch_seg[4], a1z = scratch_seg[5];
+    const b0x = scratch_seg_b[0], b0y = scratch_seg_b[1], b0z = scratch_seg_b[2];
+    const b1x = scratch_seg_b[3], b1y = scratch_seg_b[4], b1z = scratch_seg_b[5];
+
+    line3_closest_points_segment_segment(
+        scratch_st,
+        a0x, a0y, a0z, a1x, a1y, a1z,
+        b0x, b0y, b0z, b1x, b1y, b1z
+    );
+
+    const s = scratch_st[0];
+    const t = scratch_st[1];
+
+    const pax = a0x + (a1x - a0x) * s;
+    const pay = a0y + (a1y - a0y) * s;
+    const paz = a0z + (a1z - a0z) * s;
+    const pbx = b0x + (b1x - b0x) * t;
+    const pby = b0y + (b1y - b0y) * t;
+    const pbz = b0z + (b1z - b0z) * t;
+
+    const dx = pax - pbx;
+    const dy = pay - pby;
+    const dz = paz - pbz;
+    const dist_sqr = dx * dx + dy * dy + dz * dz;
+    const sum = a_radius + b_radius;
+    if (dist_sqr >= sum * sum) return false;
+
+    const dist = Math.sqrt(dist_sqr);
+    let nx, ny, nz;
+    if (dist > 0) {
+        const inv = 1 / dist;
+        nx = dx * inv; ny = dy * inv; nz = dz * inv;
+    } else {
+        // Segments touch — fall back to the world-frame direction from B's
+        // segment centre toward A's segment centre as a tie-break.
+        const acx = (a0x + a1x) * 0.5;
+        const acy = (a0y + a1y) * 0.5;
+        const acz = (a0z + a1z) * 0.5;
+        const bcx = (b0x + b1x) * 0.5;
+        const bcy = (b0y + b1y) * 0.5;
+        const bcz = (b0z + b1z) * 0.5;
+        const ddx = acx - bcx, ddy = acy - bcy, ddz = acz - bcz;
+        const dd_sqr = ddx * ddx + ddy * ddy + ddz * ddz;
+        if (dd_sqr > 0) {
+            const inv2 = 1 / Math.sqrt(dd_sqr);
+            nx = ddx * inv2; ny = ddy * inv2; nz = ddz * inv2;
+        } else {
+            nx = 1; ny = 0; nz = 0;
+        }
+    }
+
+    out[0] = nx; out[1] = ny; out[2] = nz;
+    out[3] = sum - dist;
+    out[4] = pax - nx * a_radius;
+    out[5] = pay - ny * a_radius;
+    out[6] = paz - nz * a_radius;
+    out[7] = pbx + nx * b_radius;
+    out[8] = pby + ny * b_radius;
+    out[9] = pbz + nz * b_radius;
+    return true;
+}
+
+// --- capsule vs oriented box ------------------------------------------------
+
+const scratch_a0_local = new Float64Array(3);
+const scratch_a1_local = new Float64Array(3);
+
+/**
+ * Capsule (A) vs oriented box (B). Brings the capsule segment into box-local
+ * space, then refines via 2 fixed-point iterations between:
+ *   - closest point on the segment to the current box-side candidate
+ *   - clamped point on the box closest to the current segment-side candidate
+ *
+ * Two iterations suffice for the cases this engine targets (sphere-like cap
+ * geometry against axis-aligned-in-local box). When the segment passes
+ * through the box, the "inside" branch picks the smallest-overlap face
+ * deterministically, mirroring {@link sphere_box_contact}.
+ *
+ * @param {number[]|Float64Array} out length >= 10
+ * @returns {boolean}
+ */
+export function capsule_box_contact(
+    out,
+    a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_radius, a_half_h,
+    b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw, b_hx, b_hy, b_hz
+) {
+    // Bring the capsule's segment endpoints into box-local space.
+    v3_quat3_apply_inverse(scratch_a0_local, 0, -0, -a_half_h, 0, a_qx, a_qy, a_qz, a_qw);
+    // Note: we constructed the segment ends in body frame as (0, ±h, 0). We
+    // need them in world first, then box-local. Build world here directly
+    // for clarity.
+    capsule_world_segment(scratch_seg, a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_half_h);
+    // World → box-local: subtract box centre, then rotate by conjugate of box quat.
+    const w_a0x = scratch_seg[0] - b_cx, w_a0y = scratch_seg[1] - b_cy, w_a0z = scratch_seg[2] - b_cz;
+    const w_a1x = scratch_seg[3] - b_cx, w_a1y = scratch_seg[4] - b_cy, w_a1z = scratch_seg[5] - b_cz;
+    v3_quat3_apply_inverse(scratch_a0_local, 0, w_a0x, w_a0y, w_a0z, b_qx, b_qy, b_qz, b_qw);
+    v3_quat3_apply_inverse(scratch_a1_local, 0, w_a1x, w_a1y, w_a1z, b_qx, b_qy, b_qz, b_qw);
+
+    const a0lx = scratch_a0_local[0], a0ly = scratch_a0_local[1], a0lz = scratch_a0_local[2];
+    const a1lx = scratch_a1_local[0], a1ly = scratch_a1_local[1], a1lz = scratch_a1_local[2];
+
+    // Fixed-point iteration: start with t at the closest point to the box centre.
+    let t = line3_compute_segment_nearest_point_to_point_t(a0lx, a0ly, a0lz, a1lx, a1ly, a1lz, 0, 0, 0);
+    let plx = a0lx + (a1lx - a0lx) * t;
+    let ply = a0ly + (a1ly - a0ly) * t;
+    let plz = a0lz + (a1lz - a0lz) * t;
+
+    for (let iter = 0; iter < 2; iter++) {
+        // Clamp current segment point to the box → closest box-surface point.
+        const qlx = plx < -b_hx ? -b_hx : (plx > b_hx ? b_hx : plx);
+        const qly = ply < -b_hy ? -b_hy : (ply > b_hy ? b_hy : ply);
+        const qlz = plz < -b_hz ? -b_hz : (plz > b_hz ? b_hz : plz);
+
+        // Re-find closest segment point to that box point.
+        t = line3_compute_segment_nearest_point_to_point_t(
+            a0lx, a0ly, a0lz, a1lx, a1ly, a1lz,
+            qlx, qly, qlz
+        );
+        plx = a0lx + (a1lx - a0lx) * t;
+        ply = a0ly + (a1ly - a0ly) * t;
+        plz = a0lz + (a1lz - a0lz) * t;
+    }
+
+    // Final box-side point.
+    const qlx = plx < -b_hx ? -b_hx : (plx > b_hx ? b_hx : plx);
+    const qly = ply < -b_hy ? -b_hy : (ply > b_hy ? b_hy : ply);
+    const qlz = plz < -b_hz ? -b_hz : (plz > b_hz ? b_hz : plz);
+    const inside = qlx === plx && qly === ply && qlz === plz;
+
+    let nlx, nly, nlz, dist;
+    if (!inside) {
+        const ex = plx - qlx, ey = ply - qly, ez = plz - qlz;
+        const d_sqr = ex * ex + ey * ey + ez * ez;
+        if (d_sqr >= a_radius * a_radius) return false;
+        dist = Math.sqrt(d_sqr);
+        if (dist > 0) {
+            const inv = 1 / dist;
+            nlx = ex * inv; nly = ey * inv; nlz = ez * inv;
+        } else {
+            nlx = 1; nly = 0; nlz = 0;
+        }
+    } else {
+        // Segment point is inside the box. Pick smallest-overlap face.
+        const dxf = b_hx - Math.abs(plx);
+        const dyf = b_hy - Math.abs(ply);
+        const dzf = b_hz - Math.abs(plz);
+        if (dxf <= dyf && dxf <= dzf) {
+            nlx = plx >= 0 ? 1 : -1; nly = 0; nlz = 0; dist = -dxf;
+        } else if (dyf <= dzf) {
+            nlx = 0; nly = ply >= 0 ? 1 : -1; nlz = 0; dist = -dyf;
+        } else {
+            nlx = 0; nly = 0; nlz = plz >= 0 ? 1 : -1; dist = -dzf;
+        }
+    }
+
+    // Normal (box → capsule axis point) into world.
+    v3_quat3_apply(out, 0, nlx, nly, nlz, b_qx, b_qy, b_qz, b_qw);
+    const nx = out[0], ny = out[1], nz = out[2];
+    out[3] = a_radius - dist;
+
+    // Capsule-side contact: world segment point pushed back by radius.
+    v3_quat3_apply(out, 4, plx, ply, plz, b_qx, b_qy, b_qz, b_qw);
+    out[4] += b_cx - nx * a_radius;
+    out[5] += b_cy - ny * a_radius;
+    out[6] += b_cz - nz * a_radius;
+
+    // Box-side contact: world projection of the box-surface point.
+    v3_quat3_apply(out, 7, qlx, qly, qlz, b_qx, b_qy, b_qz, b_qw);
+    out[7] += b_cx;
+    out[8] += b_cy;
+    out[9] += b_cz;
+
+    return true;
+}
+
+// --- capsule vs oriented box, multi-point manifold --------------------------
+
+/**
+ * Output stride per contact in {@link capsule_box_multi_contacts}.
+ * Matches the candidate-buffer layout used by `narrowphase_step`.
+ *
+ *   0..2  : world contact on capsule side
+ *   3..5  : world contact on box side
+ *   6..8  : normal from box (B) toward capsule (A)
+ *   9     : depth (positive = penetration)
+ *
+ * @type {number}
+ */
+export const CAPSULE_BOX_CONTACT_STRIDE = 10;
+
+/**
+ * Maximum contact points {@link capsule_box_multi_contacts} can emit.
+ *  - 1 from the closest-point-on-segment vs OBB query (primary)
+ *  - up to 2 from the cap-centre sphere-vs-OBB queries (one per endpoint)
+ * @type {number}
+ */
+export const CAPSULE_BOX_MAX_CONTACTS = 3;
+
+const scratch_primary = new Float64Array(10);
+const scratch_endpoint = new Float64Array(10);
+
+/**
+ * Two world positions are treated as the same contact when their squared
+ * distance is below this threshold. Picked so that a capsule resting flat
+ * doesn't double up the primary closest-segment-point contact with whichever
+ * endpoint it happens to coincide with.
+ *
+ * Looser than the manifold's warm-start match tolerance (≈0.02) because we
+ * specifically want to dedupe contacts at the *same* point; small lateral
+ * shifts of the capsule produce distinct contacts that should both be kept.
+ * @type {number}
+ */
+const DEDUPE_DIST_SQR = 1e-6;
+
+/**
+ * Multi-point capsule-vs-OBB contact generation. Emits up to
+ * {@link CAPSULE_BOX_MAX_CONTACTS} contacts into `out` in the
+ * `(wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth)` stride layout.
+ *
+ * The motivation: a capsule lying flat on a face needs more than one
+ * contact to rest stably — a single contact at the segment's closest point
+ * is positionally ambiguous (every interior segment point is equidistant
+ * from the face), and the body wobbles around whichever point the
+ * iterative closest-point solver happened to converge on. Two contacts at
+ * the cap centres pin the capsule's rotation about its long axis.
+ *
+ * Algorithm:
+ *  1. Closest-point-on-segment vs OBB → primary contact (same as
+ *     {@link capsule_box_contact}).
+ *  2. Treat each cap centre as a sphere of cap-radius and run
+ *     {@link sphere_box_contact} → up to two additional contacts.
+ *  3. Dedupe spatially against the primary so a capsule touching with one
+ *     cap doesn't emit two contacts at the same point.
+ *
+ * @param {Float64Array} out length >= CAPSULE_BOX_MAX_CONTACTS * CAPSULE_BOX_CONTACT_STRIDE
+ * @param {number} a_cx capsule centre x
+ * @param {number} a_cy
+ * @param {number} a_cz
+ * @param {number} a_qx capsule rotation
+ * @param {number} a_qy
+ * @param {number} a_qz
+ * @param {number} a_qw
+ * @param {number} a_radius
+ * @param {number} a_half_h
+ * @param {number} b_cx box centre x
+ * @param {number} b_cy
+ * @param {number} b_cz
+ * @param {number} b_qx
+ * @param {number} b_qy
+ * @param {number} b_qz
+ * @param {number} b_qw
+ * @param {number} b_hx
+ * @param {number} b_hy
+ * @param {number} b_hz
+ * @returns {number} number of contacts emitted, in `[0, CAPSULE_BOX_MAX_CONTACTS]`
+ */
+export function capsule_box_multi_contacts(
+    out,
+    a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_radius, a_half_h,
+    b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw, b_hx, b_hy, b_hz
+) {
+    // 1. Primary contact: closest segment point vs OBB.
+    const primary_ok = capsule_box_contact(
+        scratch_primary,
+        a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_radius, a_half_h,
+        b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw, b_hx, b_hy, b_hz
+    );
+    if (!primary_ok) return 0;
+
+    // Repack scratch_primary (normal, depth, A, B) into the candidate stride
+    // (A, B, normal, depth) at out[0..10).
+    const p_nx = scratch_primary[0], p_ny = scratch_primary[1], p_nz = scratch_primary[2];
+    const p_depth = scratch_primary[3];
+    const p_ax = scratch_primary[4], p_ay = scratch_primary[5], p_az = scratch_primary[6];
+    const p_bx = scratch_primary[7], p_by = scratch_primary[8], p_bz = scratch_primary[9];
+    out[0] = p_ax; out[1] = p_ay; out[2] = p_az;
+    out[3] = p_bx; out[4] = p_by; out[5] = p_bz;
+    out[6] = p_nx; out[7] = p_ny; out[8] = p_nz;
+    out[9] = p_depth;
+    let count = 1;
+
+    // 2. Endpoint contacts: treat each cap centre as a sphere of cap-radius.
+    capsule_world_segment(scratch_seg, a_cx, a_cy, a_cz, a_qx, a_qy, a_qz, a_qw, a_half_h);
+    const ep_x = [scratch_seg[0], scratch_seg[3]];
+    const ep_y = [scratch_seg[1], scratch_seg[4]];
+    const ep_z = [scratch_seg[2], scratch_seg[5]];
+
+    for (let i = 0; i < 2; i++) {
+        const ok = sphere_box_contact(
+            scratch_endpoint,
+            ep_x[i], ep_y[i], ep_z[i], a_radius,
+            b_cx, b_cy, b_cz, b_qx, b_qy, b_qz, b_qw,
+            b_hx, b_hy, b_hz
+        );
+        if (!ok) continue;
+
+        const e_nx = scratch_endpoint[0], e_ny = scratch_endpoint[1], e_nz = scratch_endpoint[2];
+        const e_depth = scratch_endpoint[3];
+        const e_ax = scratch_endpoint[4], e_ay = scratch_endpoint[5], e_az = scratch_endpoint[6];
+        const e_bx = scratch_endpoint[7], e_by = scratch_endpoint[8], e_bz = scratch_endpoint[9];
+
+        // Dedupe against every already-emitted contact (primary, then any
+        // prior endpoint we've already accepted). The capsule-side world
+        // point uniquely identifies a contact for this purpose — two distinct
+        // box-surface points always have distinct capsule-side projections
+        // along the local-A axis.
+        let duplicate = false;
+        for (let k = 0; k < count; k++) {
+            const ko = k * CAPSULE_BOX_CONTACT_STRIDE;
+            const dx = e_ax - out[ko];
+            const dy = e_ay - out[ko + 1];
+            const dz = e_az - out[ko + 2];
+            if (dx * dx + dy * dy + dz * dz < DEDUPE_DIST_SQR) { duplicate = true; break; }
+        }
+        if (duplicate) continue;
+
+        const o = count * CAPSULE_BOX_CONTACT_STRIDE;
+        out[o]     = e_ax; out[o + 1] = e_ay; out[o + 2] = e_az;
+        out[o + 3] = e_bx; out[o + 4] = e_by; out[o + 5] = e_bz;
+        out[o + 6] = e_nx; out[o + 7] = e_ny; out[o + 8] = e_nz;
+        out[o + 9] = e_depth;
+        count++;
+    }
+
+    return count;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @param {number[]|Float64Array} out length >= CAPSULE_TRIANGLE_MAX_CONTACTS *
+ *   CAPSULE_TRIANGLE_CONTACT_STRIDE
+ * @param {number} c_cx capsule centre x
+ * @param {number} c_cy
+ * @param {number} c_cz
+ * @param {number} c_qx capsule rotation
+ * @param {number} c_qy
+ * @param {number} c_qz
+ * @param {number} c_qw
+ * @param {number} c_radius
+ * @param {number} c_half_h capsule half-height (not including caps)
+ * @param {number} ax triangle vertex A x (world)
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx triangle vertex B x (world)
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} cx triangle vertex C x (world)
+ * @param {number} cy
+ * @param {number} cz
+ * @returns {number} number of contacts emitted, in `[0, CAPSULE_TRIANGLE_MAX_CONTACTS]`
+ */
+export function capsule_triangle_contact(out: number[] | Float64Array, c_cx: number, c_cy: number, c_cz: number, c_qx: number, c_qy: number, c_qz: number, c_qw: number, c_radius: number, c_half_h: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): number;
+/**
+ * Multi-point capsule-vs-triangle contact generation.
+ *
+ * A capsule is the Minkowski sum of a line segment and a sphere of
+ * radius `r`, so capsule-vs-triangle reduces to:
+ *
+ *   1. Find the closest pair of points between the capsule's central
+ *      segment and the triangle (segment ↔ triangle distance).
+ *   2. If distance ≥ radius, no overlap.
+ *   3. Otherwise emit a primary contact at the segment-triangle
+ *      closest pair, then additionally treat each cap centre (segment
+ *      endpoint) as a sphere of cap-radius and run
+ *      {@link sphere_triangle_contact} to produce up to 2 endpoint
+ *      contacts. Spatial dedup against the primary so a capsule
+ *      touching with one cap doesn't emit two contacts at the same
+ *      point.
+ *
+ * The multi-point manifold (1 primary + 2 endpoints) is what allows a
+ * capsule resting flat on a triangle face to be stable — a single
+ * contact at the segment's closest point is positionally ambiguous
+ * (every interior segment point is equidistant from the face), and
+ * the body wobbles around whichever point the iterative closest-point
+ * solver happened to converge on. The endpoint contacts pin the
+ * capsule's rotation about its long axis.
+ *
+ * Output layout per contact (matches
+ * {@link CAPSULE_BOX_CONTACT_STRIDE} so the same downstream wiring
+ * works):
+ *   0..2 : world contact on capsule side
+ *   3..5 : world contact on triangle side
+ *   6..8 : normal from triangle (B) toward capsule (A)
+ *   9    : depth (positive = penetration)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Output stride per contact.
+ * @type {number}
+ */
+export const CAPSULE_TRIANGLE_CONTACT_STRIDE: number;
+/**
+ * Maximum contacts emitted: 1 primary + 2 endpoint sphere contacts.
+ * @type {number}
+ */
+export const CAPSULE_TRIANGLE_MAX_CONTACTS: number;
+//# sourceMappingURL=capsule_triangle_contact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capsule_triangle_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/capsule_triangle_contact.js"],"names":[],"mappings":"AAgPA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8CAtBW,MAAM,EAAE,GAAC,YAAY,QAErB,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,YACN,MAAM,YACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAqElB;AArUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;GAGG;AACH,8CAFU,MAAM,CAEkC;AAElD;;;GAGG;AACH,4CAFU,MAAM,CAE+B"}