@driftengine/physics 3.61.0

package/dist/shape.js

@@ -0,0 +1,533 @@
+/** What a shape with no faces carries: a sphere, a capsule, or any cloud too flat to bound one. */
+const EMPTY_FACES = {
+    facePlanes: new Float32Array(0),
+    faceVertexStart: new Uint16Array(0),
+    faceVertexIndices: new Uint16Array(0),
+};
+/**
+ * Hard cap on hull input size. The builder is O(n^4); at 64 points that is a
+ * few million build-time operations, and anything larger is a sign the caller
+ * is feeding it a render mesh instead of an element's defining points.
+ */
+const MAX_POINTS = 64;
+/** Points closer than this are the same point. */
+const POINT_EPS = 1e-6;
+/** Distance within which a point counts as lying on a plane, metres. */
+const COPLANAR_M = 1e-4;
+/** Dot product above which two directions are the same line. */
+const DIR_DEDUP = 1 - 1e-7;
+/** The exact shape `MeshBuilder.addBox` draws: eight corners, three axes. */
+export function boxShape(hx, hy, hz) {
+    const vertices = new Float32Array(24);
+    let v = 0;
+    for (let i = 0; i < 8; i++) {
+        vertices[v++] = i & 1 ? hx : -hx;
+        vertices[v++] = i & 2 ? hy : -hy;
+        vertices[v++] = i & 4 ? hz : -hz;
+    }
+    const axes = new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1]);
+    /*
+     * Six faces, where `axes` above is three directions. Corner `i` has bit 0 for +x, bit 1 for +y
+     * and bit 2 for +z, so each face is the four corners sharing one bit, listed counter-clockwise
+     * seen from outside. Written out rather than derived because the loop that derives it is longer
+     * than the table and this is build-time code that runs once per shape.
+     */
+    const facePlanes = new Float32Array([
+        1,
+        0,
+        0,
+        hx,
+        -1,
+        0,
+        0,
+        hx,
+        0,
+        1,
+        0,
+        hy,
+        0,
+        -1,
+        0,
+        hy,
+        0,
+        0,
+        1,
+        hz,
+        0,
+        0,
+        -1,
+        hz,
+    ]);
+    const faceVertexIndices = new Uint16Array([
+        1, 3, 7, 5, 4, 6, 2, 0, 2, 6, 7, 3, 0, 1, 5, 4, 4, 5, 7, 6, 0, 2, 3, 1,
+    ]);
+    const faceVertexStart = new Uint16Array([0, 4, 8, 12, 16, 20, 24]);
+    return {
+        vertices,
+        faceNormals: axes,
+        edgeDirs: axes,
+        radius: 0,
+        sideRadius: 0,
+        boundRadius: Math.sqrt(hx * hx + hy * hy + hz * hz),
+        facePlanes,
+        faceVertexStart,
+        faceVertexIndices,
+    };
+}
+/** A ball: one point, all radius. It separates on other shapes' features. */
+export function sphereShape(radius) {
+    return {
+        vertices: new Float32Array(3),
+        faceNormals: new Float32Array(0),
+        edgeDirs: new Float32Array(0),
+        radius,
+        sideRadius: 0,
+        boundRadius: radius,
+        ...EMPTY_FACES,
+    };
+}
+/**
+ * A capsule: a segment along y with a rounding radius.
+ *
+ * **No new representation.** Point-cloud-plus-radius already expresses a capsule exactly, so this
+ * is a named constructor over `hullShape` rather than a shape type. A named thing is discoverable
+ * and an idiom is not. It stands along y because that is the axis a character capsule uses, and a
+ * rotation nobody has to apply is a rotation nobody gets wrong.
+ *
+ * At `halfHeight` zero the two points dedupe to one and the result *is* a sphere, which is the
+ * right degenerate case rather than an error.
+ *
+ * **A cylinder is a different shape and has its own constructor**, `cylinderShape` below. The
+ * rounding radius here grows uniformly around every feature, so applying it to a segment can only
+ * ever give a capsule: it would round a cylinder's rim as well as its side. `sideRadius` is the
+ * field that expresses the difference, and it was added on 2026-08-27 with the second condition
+ * this file had been recording — a wheel rim, a rolling barrel — as its reason.
+ *
+ * The advice until then was "build one as an n-gon prism with `hullShape` and accept the facets",
+ * and it had a measured ceiling: `hullShape` refuses more than 64 points, a prism spends two a
+ * side, so thirty-two sides was the wall, and a thirty-two-sided wheel of radius 1 rolling at
+ * 6 m/s bobbed 16 mm that no side count could reduce. `prismRoll.test.ts` still measures that,
+ * beside the same wheel built as a cylinder, because the comparison is the reason the shape kind
+ * exists.
+ */
+export function capsuleShape(radius, halfHeight) {
+    if (!(radius > 0))
+        throw new Error(`capsuleShape: radius must be positive, got ${radius}`);
+    if (!(halfHeight >= 0)) {
+        throw new Error(`capsuleShape: halfHeight must not be negative, got ${halfHeight}`);
+    }
+    return hullShape([0, -halfHeight, 0, 0, halfHeight, 0], radius);
+}
+/**
+ * A cylinder: a segment along y, grown by a disc rather than by a ball.
+ *
+ * **The one shape a point cloud plus a rounding radius cannot express**, and the reason it needed
+ * a second kind of rounding rather than a second shape type. `radius` grows a shape uniformly, so
+ * applying it to a segment gives a capsule; `sideRadius` grows it only perpendicular to that
+ * segment, which gives two flat cap discs, a curved side, and a sharp rim between them. That rim
+ * is the whole difference, and it is what a wheel rolls on.
+ *
+ * **What this replaces is an n-gon prism with a measured floor.** `prismRoll.test.ts` had the
+ * numbers: `hullShape` refuses more than 64 points, a prism spends two a side, so thirty-two sides
+ * was the wall, and a thirty-two-sided wheel of radius 1 rolling at 6 m/s bobbed **16 mm** — which
+ * no side count could reduce. A cylinder's support along any direction perpendicular to its axis
+ * is exactly `sideRadius`, at every angle, so the same wheel bobs by nothing at all. The same test
+ * file now measures both and compares them.
+ *
+ * It stands along y for `capsuleShape`'s reason: a rotation nobody has to apply is a rotation
+ * nobody gets wrong. A wheel wants its axis across the vehicle, and the body carries a quaternion
+ * for exactly that. A static collider baked into world space carries its axis in its own two
+ * points, so nothing stores a direction that could disagree with them.
+ *
+ * **`halfHeight` must be positive**, unlike `capsuleShape`, whose zero case degenerates into a
+ * sphere and is right. A cylinder of zero height is a disc: a shape with no interior, whose mass
+ * properties are zero and whose contact normal is undefined on its rim. Refused rather than
+ * silently produced.
+ */
+export function cylinderShape(radius, halfHeight) {
+    if (!(radius > 0))
+        throw new Error(`cylinderShape: radius must be positive, got ${radius}`);
+    if (!(halfHeight > 0)) {
+        throw new Error(`cylinderShape: halfHeight must be positive, got ${halfHeight}`);
+    }
+    /*
+     * One axis in `faceNormals` and in `edgeDirs`, which is the honest answer for both: the caps are
+     * the only planar faces a cylinder has, and they share one direction, while the axis is the only
+     * straight edge direction on it. The curved side has neither, and the contact code reaches it
+     * through `sideRadius` rather than through an enumerated axis — which is the point of the field.
+     */
+    const axis = new Float32Array([0, 1, 0]);
+    return {
+        vertices: new Float32Array([0, -halfHeight, 0, 0, halfHeight, 0]),
+        faceNormals: axis,
+        edgeDirs: axis,
+        radius: 0,
+        sideRadius: radius,
+        boundRadius: Math.sqrt(halfHeight * halfHeight + radius * radius),
+        ...EMPTY_FACES,
+    };
+}
+/**
+ * The convex hull of a point cloud, with its separating features enumerated.
+ *
+ * Brute force by design: every point triple proposes a plane, and a plane with
+ * every point on one side is a face. Edges are point pairs lying on two
+ * distinct faces. No incremental hull, no floating-point pivoting — the same
+ * input yields the same features in the same order on every machine, which the
+ * replay contract needs from anything that feeds collision.
+ *
+ * **Every length here is `Math.sqrt` of a sum of squares rather than `Math.hypot`**, and that is
+ * what makes the sentence above true rather than merely intended. ECMAScript declines to specify
+ * `hypot` precisely, so two engines may differ by an ulp — and an ulp here is not a slightly
+ * different axis. `proposePlane`'s normal classifies every point against `COPLANAR_M`, so it
+ * decides whether a plane becomes a face at all; `appendDirection`'s is compared against
+ * `DIR_DEDUP`, so it decides how many separating axes exist and in what order. SAT then takes a
+ * minimum over that list.
+ *
+ * `hypot` is the more accurate of the two, guarding against intermediate overflow at magnitudes a
+ * collision shape does not reach. **What would make this wrong** is a shape built at astronomical
+ * or atomic scale, where that guard is worth more than the reproducibility; the answer then is an
+ * explicit rescale rather than the call back. Asserted by `scripts/determinism.test.mjs`.
+ */
+export function hullShape(points, radius = 0) {
+    const pts = dedupePoints(points);
+    const n = pts.length / 3;
+    if (n === 0)
+        throw new Error('hullShape: no points');
+    if (n > MAX_POINTS) {
+        throw new Error(`hullShape: ${n} points exceeds ${MAX_POINTS} — derive shapes from defining points, not meshes`);
+    }
+    let boundRadius = 0;
+    for (let i = 0; i < n; i++) {
+        const px = pts[i * 3] ?? 0;
+        const py = pts[i * 3 + 1] ?? 0;
+        const pz = pts[i * 3 + 2] ?? 0;
+        const d = Math.sqrt(px * px + py * py + pz * pz);
+        if (d > boundRadius)
+            boundRadius = d;
+    }
+    boundRadius += radius;
+    // Every plane that supports the hull: (nx, ny, nz, offset), outward.
+    const planes = [];
+    for (let i = 0; i < n - 2; i++) {
+        for (let j = i + 1; j < n - 1; j++) {
+            for (let k = j + 1; k < n; k++) {
+                proposePlane(pts, n, i, j, k, planes);
+            }
+        }
+    }
+    const faceNormals = dedupeDirections(planes, 4);
+    const edgeDirs = planes.length >= 8
+        ? hullEdges(pts, n, planes)
+        : // Flat or degenerate cloud (one plane or none): there are no two faces
+            // to intersect, so every pairwise direction stands in for the rim.
+            pairwiseDirections(pts, n);
+    /*
+     * The planes are what `proposePlane` already found; only their offsets were being discarded. A
+     * face is one plane plus the points lying on it, ordered around the normal — which is what
+     * clipping and an inertia tensor both need, and what `faceNormals` cannot give, being deduped
+     * directions rather than faces.
+     */
+    const faces = planes.length >= 4 ? buildFaces(pts, n, planes) : EMPTY_FACES;
+    return { vertices: pts, faceNormals, edgeDirs, radius, sideRadius: 0, boundRadius, ...faces };
+}
+/**
+ * World-axis bounds of a shape as placed (its points are its placement).
+ *
+ * **`radius` and `sideRadius` grow the box differently, and the second one is not `sideRadius` on
+ * every axis.** A ball grows a box by its radius along all three; a disc perpendicular to a unit
+ * axis `a` grows it by `sideRadius * sqrt(1 - a[i]^2)` along axis `i` — the disc's own extent seen
+ * down that axis, which is the full radius across the axis and exactly nothing along it. Using
+ * `sideRadius` on all three instead would bound a lying cylinder as if it were a sphere, which is
+ * conservative and therefore not wrong, and would cost the broad phase the difference on every
+ * cylinder in the world.
+ */
+export function shapeBounds(shape, out) {
+    const v = shape.vertices;
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i < v.length; i += 3) {
+        const x = v[i] ?? 0;
+        const y = v[i + 1] ?? 0;
+        const z = v[i + 2] ?? 0;
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+        if (z < minZ)
+            minZ = z;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    let growX = shape.radius;
+    let growY = shape.radius;
+    let growZ = shape.radius;
+    if (shape.sideRadius > 0) {
+        const ax = (v[3] ?? 0) - (v[0] ?? 0);
+        const ay = (v[4] ?? 0) - (v[1] ?? 0);
+        const az = (v[5] ?? 0) - (v[2] ?? 0);
+        const length = Math.sqrt(ax * ax + ay * ay + az * az) || 1;
+        const ux = ax / length;
+        const uy = ay / length;
+        const uz = az / length;
+        growX += shape.sideRadius * Math.sqrt(Math.max(0, 1 - ux * ux));
+        growY += shape.sideRadius * Math.sqrt(Math.max(0, 1 - uy * uy));
+        growZ += shape.sideRadius * Math.sqrt(Math.max(0, 1 - uz * uz));
+    }
+    out.minX = minX - growX;
+    out.minY = minY - growY;
+    out.minZ = minZ - growZ;
+    out.maxX = maxX + growX;
+    out.maxY = maxY + growY;
+    out.maxZ = maxZ + growZ;
+    return out;
+}
+function dedupePoints(points) {
+    const kept = [];
+    for (let i = 0; i + 2 < points.length; i += 3) {
+        const x = points[i] ?? 0;
+        const y = points[i + 1] ?? 0;
+        const z = points[i + 2] ?? 0;
+        let duplicate = false;
+        for (let k = 0; k < kept.length; k += 3) {
+            if (Math.abs((kept[k] ?? 0) - x) < POINT_EPS &&
+                Math.abs((kept[k + 1] ?? 0) - y) < POINT_EPS &&
+                Math.abs((kept[k + 2] ?? 0) - z) < POINT_EPS) {
+                duplicate = true;
+                break;
+            }
+        }
+        if (!duplicate)
+            kept.push(x, y, z);
+    }
+    return new Float32Array(kept);
+}
+/** If the triple (i, j, k) spans a supporting plane, record it outward in `planes`. */
+function proposePlane(pts, n, i, j, k, planes) {
+    const ax = pts[i * 3] ?? 0;
+    const ay = pts[i * 3 + 1] ?? 0;
+    const az = pts[i * 3 + 2] ?? 0;
+    const ux = (pts[j * 3] ?? 0) - ax;
+    const uy = (pts[j * 3 + 1] ?? 0) - ay;
+    const uz = (pts[j * 3 + 2] ?? 0) - az;
+    const vx = (pts[k * 3] ?? 0) - ax;
+    const vy = (pts[k * 3 + 1] ?? 0) - ay;
+    const vz = (pts[k * 3 + 2] ?? 0) - az;
+    let nx = uy * vz - uz * vy;
+    let ny = uz * vx - ux * vz;
+    let nz = ux * vy - uy * vx;
+    const len = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (len < 1e-9)
+        return;
+    nx /= len;
+    ny /= len;
+    nz /= len;
+    let above = 0;
+    let below = 0;
+    for (let p = 0; p < n; p++) {
+        const d = ((pts[p * 3] ?? 0) - ax) * nx +
+            ((pts[p * 3 + 1] ?? 0) - ay) * ny +
+            ((pts[p * 3 + 2] ?? 0) - az) * nz;
+        if (d > COPLANAR_M)
+            above++;
+        else if (d < -COPLANAR_M)
+            below++;
+        if (above > 0 && below > 0)
+            return;
+    }
+    // Outward means every other point sits behind the plane.
+    if (above === 0)
+        recordPlane(planes, nx, ny, nz, nx * ax + ny * ay + nz * az);
+    if (below === 0)
+        recordPlane(planes, -nx, -ny, -nz, -(nx * ax + ny * ay + nz * az));
+}
+function recordPlane(planes, nx, ny, nz, d) {
+    for (let p = 0; p < planes.length; p += 4) {
+        const dot = (planes[p] ?? 0) * nx + (planes[p + 1] ?? 0) * ny + (planes[p + 2] ?? 0) * nz;
+        if (dot > DIR_DEDUP && Math.abs((planes[p + 3] ?? 0) - d) < COPLANAR_M)
+            return;
+    }
+    planes.push(nx, ny, nz, d);
+}
+/** Unique directions (as lines) from a packed list with the given stride. */
+function dedupeDirections(packed, stride) {
+    const dirs = [];
+    for (let p = 0; p < packed.length; p += stride) {
+        const x = packed[p] ?? 0;
+        const y = packed[p + 1] ?? 0;
+        const z = packed[p + 2] ?? 0;
+        appendDirection(dirs, x, y, z);
+    }
+    return new Float32Array(dirs);
+}
+function appendDirection(dirs, x, y, z) {
+    const len = Math.sqrt(x * x + y * y + z * z);
+    if (len < 1e-9)
+        return;
+    const nx = x / len;
+    const ny = y / len;
+    const nz = z / len;
+    for (let d = 0; d < dirs.length; d += 3) {
+        const dot = (dirs[d] ?? 0) * nx + (dirs[d + 1] ?? 0) * ny + (dirs[d + 2] ?? 0) * nz;
+        if (Math.abs(dot) > DIR_DEDUP)
+            return;
+    }
+    dirs.push(nx, ny, nz);
+}
+/** Edge directions: point pairs lying on at least two distinct supporting planes. */
+function hullEdges(pts, n, planes) {
+    const dirs = [];
+    for (let i = 0; i < n - 1; i++) {
+        for (let j = i + 1; j < n; j++) {
+            let shared = 0;
+            for (let p = 0; p < planes.length && shared < 2; p += 4) {
+                const nx = planes[p] ?? 0;
+                const ny = planes[p + 1] ?? 0;
+                const nz = planes[p + 2] ?? 0;
+                const d = planes[p + 3] ?? 0;
+                const di = (pts[i * 3] ?? 0) * nx + (pts[i * 3 + 1] ?? 0) * ny + (pts[i * 3 + 2] ?? 0) * nz - d;
+                if (Math.abs(di) > COPLANAR_M)
+                    continue;
+                const dj = (pts[j * 3] ?? 0) * nx + (pts[j * 3 + 1] ?? 0) * ny + (pts[j * 3 + 2] ?? 0) * nz - d;
+                if (Math.abs(dj) > COPLANAR_M)
+                    continue;
+                shared++;
+            }
+            if (shared < 2)
+                continue;
+            appendDirection(dirs, (pts[j * 3] ?? 0) - (pts[i * 3] ?? 0), (pts[j * 3 + 1] ?? 0) - (pts[i * 3 + 1] ?? 0), (pts[j * 3 + 2] ?? 0) - (pts[i * 3 + 2] ?? 0));
+        }
+    }
+    return new Float32Array(dirs);
+}
+function pairwiseDirections(pts, n) {
+    const dirs = [];
+    for (let i = 0; i < n - 1; i++) {
+        for (let j = i + 1; j < n; j++) {
+            appendDirection(dirs, (pts[j * 3] ?? 0) - (pts[i * 3] ?? 0), (pts[j * 3 + 1] ?? 0) - (pts[i * 3 + 1] ?? 0), (pts[j * 3 + 2] ?? 0) - (pts[i * 3 + 2] ?? 0));
+        }
+    }
+    return new Float32Array(dirs);
+}
+/**
+ * Group the supporting planes into faces and order each face's points around its normal.
+ *
+ * `proposePlane` records one plane per point triple, so a square face arrives four times over. The
+ * dedupe here is by *direction and offset together*, unlike `appendDirection`, which folds a plane
+ * into its opposite because a separating axis has no sign. A face does.
+ *
+ * **What this gives up:** a face with fewer than three points on it is dropped, so a shape flat
+ * enough to have no interior yields no faces and falls back to the empty set. **What would make it
+ * wrong** is a caller expecting a degenerate cloud to clip, which it cannot: there is no volume to
+ * clip against.
+ */
+function buildFaces(pts, n, planes) {
+    const kept = [];
+    const loops = [];
+    for (let p = 0; p + 3 < planes.length; p += 4) {
+        const nx = planes[p] ?? 0;
+        const ny = planes[p + 1] ?? 0;
+        const nz = planes[p + 2] ?? 0;
+        const d = planes[p + 3] ?? 0;
+        let seen = false;
+        for (let k = 0; k + 3 < kept.length; k += 4) {
+            const dot = (kept[k] ?? 0) * nx + (kept[k + 1] ?? 0) * ny + (kept[k + 2] ?? 0) * nz;
+            if (dot > DIR_DEDUP && Math.abs((kept[k + 3] ?? 0) - d) < COPLANAR_M) {
+                seen = true;
+                break;
+            }
+        }
+        if (seen)
+            continue;
+        const on = [];
+        for (let i = 0; i < n; i++) {
+            const x = pts[i * 3] ?? 0;
+            const y = pts[i * 3 + 1] ?? 0;
+            const z = pts[i * 3 + 2] ?? 0;
+            if (Math.abs(nx * x + ny * y + nz * z - d) < COPLANAR_M)
+                on.push(i);
+        }
+        if (on.length < 3)
+            continue;
+        kept.push(nx, ny, nz, d);
+        loops.push(orderAroundNormal(pts, on, nx, ny, nz));
+    }
+    if (loops.length === 0)
+        return EMPTY_FACES;
+    const starts = new Uint16Array(loops.length + 1);
+    let total = 0;
+    for (let i = 0; i < loops.length; i++) {
+        starts[i] = total;
+        total += loops[i]?.length ?? 0;
+    }
+    starts[loops.length] = total;
+    const indices = new Uint16Array(total);
+    let at = 0;
+    for (const loop of loops)
+        for (const index of loop)
+            indices[at++] = index;
+    return {
+        facePlanes: new Float32Array(kept),
+        faceVertexStart: starts,
+        faceVertexIndices: indices,
+    };
+}
+/**
+ * Sort a face's points counter-clockwise about its outward normal.
+ *
+ * A comparison sort on a key computed from the two in-plane axes, **not `Math.atan2`** — the
+ * determinism gate bans that outright, and the ordering only has to be *consistent*, which a
+ * pseudo-angle gives for free. `Array.prototype.sort` is stable by specification, and `on` is built
+ * in ascending index order, so two coincident points keep a defined order.
+ */
+function orderAroundNormal(pts, on, nx, ny, nz) {
+    // Any axis not parallel to the normal gives an in-plane basis.
+    const ax = Math.abs(nx) < 0.5 ? 1 : 0;
+    const ay = Math.abs(nx) < 0.5 ? 0 : 1;
+    let ux = ay * nz;
+    let uy = -ax * nz;
+    let uz = ax * ny - ay * nx;
+    const ulen = Math.sqrt(ux * ux + uy * uy + uz * uz) || 1;
+    ux /= ulen;
+    uy /= ulen;
+    uz /= ulen;
+    const vx = ny * uz - nz * uy;
+    const vy = nz * ux - nx * uz;
+    const vz = nx * uy - ny * ux;
+    let cx = 0;
+    let cy = 0;
+    let cz = 0;
+    for (const i of on) {
+        cx += pts[i * 3] ?? 0;
+        cy += pts[i * 3 + 1] ?? 0;
+        cz += pts[i * 3 + 2] ?? 0;
+    }
+    cx /= on.length;
+    cy /= on.length;
+    cz /= on.length;
+    const key = new Map();
+    for (const i of on) {
+        const dx = (pts[i * 3] ?? 0) - cx;
+        const dy = (pts[i * 3 + 1] ?? 0) - cy;
+        const dz = (pts[i * 3 + 2] ?? 0) - cz;
+        key.set(i, pseudoAngle(dx * ux + dy * uy + dz * uz, dx * vx + dy * vy + dz * vz));
+    }
+    // A copy, because `on` is the caller's and sorting in place would surprise it.
+    return [...on].sort((p, q) => (key.get(p) ?? 0) - (key.get(q) ?? 0));
+}
+/** A monotonic stand-in for `atan2`, in [0, 4), costing one divide and no transcendental. */
+function pseudoAngle(x, y) {
+    const sum = Math.abs(x) + Math.abs(y);
+    if (sum === 0)
+        return 0;
+    const t = y / sum;
+    return x < 0 ? 2 - t : t < 0 ? 4 + t : t;
+}

package/dist/solver.d.ts

@@ -0,0 +1,136 @@
+import type { BodySet } from './bodies.ts';
+import type { Manifold } from './manifold.ts';
+/**
+ * Contact constraints, and the substepped soft solve over them.
+ *
+ * **Soft rather than Baumgarte, and the difference is a property rather than a preference.** Every
+ * constraint carries a *hertz* and a damping ratio, from which the bias rate, mass scale and
+ * impulse scale are derived using the substep length. Stating stiffness as a frequency is what
+ * makes the substep count a quality dial: turn it up and nothing moves differently. A Baumgarte
+ * bias is a fraction of penetration per step, so it means something different at every step length,
+ * and the mitigations for that are all tuning constants — which `AGENTS.md` says never to assert.
+ *
+ * **Nothing here recomputes a manifold.** Anchors are stored in body-local frame at prepare time
+ * along with a separation offset, so the current separation is exact at any point inside the tick
+ * without re-running narrowphase per substep. `s = sBase + dot((pB + rB') − (pA + rA'), n)` is that
+ * identity, and it holds because `sBase` is defined to make it hold at prepare.
+ *
+ * **Every entry point takes an order array rather than a contiguous range.** Islands are disjoint
+ * by construction, so they can be solved in any order or simultaneously — but a constraint list
+ * built in pair order is not grouped by island. Indirecting through an order array groups them
+ * without permuting eleven parallel arrays, and it is what lets one `solveIsland` serve both
+ * executors.
+ *
+ * **Friction is solved before the normal**, against the normal impulse accumulated so far. Solving
+ * it after means the first iteration has no normal impulse to bound against and applies none, so a
+ * resting body slides for one iteration every substep.
+ */
+/** Contacts start with this much slack allowed before the bias fights them, in metres. */
+export declare const LINEAR_SLOP = 0.005;
+/** How fast the bias may push overlap out, in metres per second. */
+export declare const MAX_BIAS_VELOCITY = 4;
+/** Below this approach speed a bounce is not worth having, and jitters if it is applied. */
+export declare const RESTITUTION_THRESHOLD = 1;
+export declare class ContactConstraints {
+    /** One entry per manifold. */
+    count: number;
+    bodyA: Int32Array;
+    bodyB: Int32Array;
+    nx: Float32Array;
+    ny: Float32Array;
+    nz: Float32Array;
+    t1x: Float32Array;
+    t1y: Float32Array;
+    t1z: Float32Array;
+    t2x: Float32Array;
+    t2y: Float32Array;
+    t2z: Float32Array;
+    friction: Float32Array;
+    restitution: Float32Array;
+    pointStart: Int32Array;
+    pointCount: Int32Array;
+    /** One entry per contact point. */
+    points: number;
+    localA: Float32Array;
+    localB: Float32Array;
+    sBase: Float32Array;
+    normalMass: Float32Array;
+    tangent1Mass: Float32Array;
+    tangent2Mass: Float32Array;
+    normalImpulse: Float32Array;
+    tangent1Impulse: Float32Array;
+    tangent2Impulse: Float32Array;
+    /** Approach speed when the constraint was prepared, which is what restitution answers to. */
+    approach: Float32Array;
+    featureId: Int32Array;
+    /**
+     * Whether each side's anchor sits on a curved surface, one byte per point.
+     *
+     * A curved anchor is held in world frame rather than in the body's, for the reason `Manifold`
+     * states at length: the point where a ball touches the floor does not turn with the ball, and an
+     * anchor that turns anyway climbs its side and reports a gap that is not there. Per point rather
+     * than per manifold so `worldAnchors` needs only the point index, which is all its callers have.
+     */
+    curvedA: Uint8Array;
+    curvedB: Uint8Array;
+    private cap;
+    private pcap;
+    constructor(capacity?: number);
+    clear(): void;
+    reserve(pointsNeeded: number): void;
+    private growConstraints;
+    private growPoints;
+}
+/**
+ * Turn one manifold into a constraint, with its effective masses and its local anchors.
+ *
+ * `warm` supplies the previous tick's impulses by feature id, or −1 where there is none. Warm
+ * starting is what lets a stack converge in a handful of iterations rather than a hundred.
+ */
+export declare function prepareContact(bodies: BodySet, a: number, b: number, m: Manifold, c: ContactConstraints, warmNormal: Float32Array | null, warmT1: Float32Array | null, warmT2: Float32Array | null): void;
+/** Apply the impulses carried over from the previous tick, before the first iteration. */
+export declare function warmStart(bodies: BodySet, c: ContactConstraints, order: Int32Array, from: number, to: number): void;
+/**
+ * One iteration over a range of constraints.
+ *
+ * `useBias` is false on the relax pass, which is what removes the energy the bias added and is why
+ * a stack stops breathing.
+ */
+/**
+ * How the two tangent rows are bounded against each other.
+ *
+ * **`box` is two independent clamps and is what this solver has always done.** Each axis is bounded
+ * at `mu * N` on its own, so along the diagonal between them the pair reaches `sqrt(2) * mu * N` —
+ * forty-one per cent more friction than the same surface offers along an axis. The tangent basis is
+ * constructed from the contact normal, so *which* headings are cheap is an artefact of that
+ * construction rather than a fact about the world, and a box measurably slides further in some
+ * directions than others.
+ *
+ * **`elliptical` couples them and friction becomes isotropic**, which is what it physically is. It
+ * is a correctness fix and it is **not the default**, because every stacking result moves under it:
+ * `fingerprintBodies`, both baselines, and any golden fingerprint or stored replay a consumer has
+ * kept. A production engine does not silently invalidate those. *What would reverse
+ * that:* a major version, where the honest thing is to make the ellipse the default and say so in
+ * the porting guide.
+ *
+ * **One coefficient, not two, and that is a decision rather than an omission.** Anisotropic
+ * friction is the natural API for an ellipse — different `mu` along each tangent — and it needs a
+ * tangent frame anchored to a *material*, which this solver does not have: `prepareContact` builds
+ * the tangents from the normal, so they rotate arbitrarily as a contact moves and a per-axis
+ * coefficient would mean something different from one tick to the next. That is a silent wrong
+ * answer, so the ellipse here is a circle. *What would reverse it:* a tangent frame carried by the
+ * body, which is a larger change than the cone; `vehicle.ts` already needs that and answers it its
+ * own way, with a grip table rather than a coefficient.
+ */
+export type FrictionModel = 'box' | 'elliptical';
+export declare function solveContacts(bodies: BodySet, c: ContactConstraints, order: Int32Array, from: number, to: number, h: number, useBias: boolean, hertz: number, damping: number, friction?: FrictionModel): void;
+/**
+ * One pass after every substep, giving back the bounce the solve suppressed.
+ *
+ * Applied once against the approach speed captured at prepare, so a drop returns to the same height
+ * whatever the substep count. A bounce driven from the *current* velocity instead compounds with
+ * every substep and turns the coefficient into a function of the dial.
+ */
+export declare function applyRestitution(bodies: BodySet, c: ContactConstraints, order: Int32Array, from: number, to: number): void;
+/** Whether a body is one the solver may move. */
+export declare function isDynamicBody(bodies: BodySet, i: number): boolean;