@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/heightfield.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Heightfields: a grid of heights a game stands on and clicks. `heightAt` and `normalAt` sample
+ * the bilinear surface, `raycastHeightfield` walks the grid cells a ray crosses (DDA) and solves
+ * the ray against each cell's bilinear patch exactly, and `heightfieldGeometry` builds the same
+ * surface as triangles. Nothing here allocates after the field exists.
+ *
+ * Layout: `heights[z * width + x]`, row-major by z then x, in height units; a sample `(x, z)`
+ * sits in the world at `origin + (x * scale[0], heights * scale[1], z * scale[2])`. Outside the
+ * field the surface continues flat from the nearest edge sample.
+ */
+import { type Geometry, type GeometryOptions } from './geometry.js';
+/** A 3-vector the heightfield functions read or write in place. */
+export type HeightfieldVec3 = [number, number, number] | Float32Array | Float64Array;
+/** A ray in world units: `origin` and a direction (`raycastHeightfield` returns distance along it). */
+export interface HeightfieldRay {
+    readonly origin: ArrayLike<number>;
+    readonly dir: ArrayLike<number>;
+}
+export interface Heightfield {
+    /** Samples along x (≥ 2). */
+    readonly width: number;
+    /** Samples along z (≥ 2). */
+    readonly depth: number;
+    /** `width × depth` heights, `heights[z * width + x]`, in height units (× `scale[1]`). */
+    readonly heights: Float32Array;
+    /** World units per sample along x, per height unit, per sample along z. */
+    readonly scale: [number, number, number];
+    /** World position of sample (0, 0) at height 0. */
+    readonly origin: [number, number, number];
+}
+export interface HeightfieldOptions {
+    /** Default `[1, 1, 1]`. */
+    scale?: [number, number, number];
+    /** Default `[0, 0, 0]`. */
+    origin?: [number, number, number];
+    /** Initial heights (`width × depth`, copied by reference). Default all zero. */
+    heights?: Float32Array;
+}
+/** A heightfield of `width × depth` samples; fill `heights` in place. */
+export declare function createHeightfield(width: number, depth: number, opts?: HeightfieldOptions): Heightfield;
+/** World height of the surface under world `(x, z)`: bilinear between the four nearest samples. */
+export declare function heightAt(hf: Heightfield, x: number, z: number): number;
+/**
+ * Unit surface normal at world `(x, z)`, written to `out` (y up). Central differences over half
+ * a sample on each side, so it is the bilinear surface's slope smoothed across cell edges.
+ */
+export declare function normalAt<T extends HeightfieldVec3>(hf: Heightfield, x: number, z: number, out: T): T;
+/**
+ * Nearest intersection of `ray` with the surface, as the distance along `ray.dir` (world units
+ * when `dir` is unit length), or -1 for a miss. The ray is clipped to the field's footprint, the
+ * cells it crosses are walked in order (DDA), and in each the ray is solved against that cell's
+ * bilinear patch (a quadratic in the distance), so a hit lies exactly on `heightAt`. Hits from
+ * below count too. `out`, when given, receives the hit point. No allocation.
+ */
+export declare function raycastHeightfield(hf: Heightfield, ray: HeightfieldRay, out?: HeightfieldVec3): number;
+/**
+ * `raycastHeightfield` taking the ray as two arrays: `origin` and `dir` (a `Ray` from `input`,
+ * a camera's eye and look direction, or plain `[x, y, z]`s), so a game casts without building a
+ * `HeightfieldRay`. Returns the distance along `dir` or -1; `out` receives the hit point.
+ */
+export declare function rayHeightfield(hf: Heightfield, origin: ArrayLike<number>, dir: ArrayLike<number>, out?: HeightfieldVec3): number;
+export interface HeightfieldGeometryOptions extends GeometryOptions {
+    /** Flat normals from each cell's two triangles instead of the smooth surface normal. Default false. */
+    flat?: boolean;
+}
+/**
+ * The field as triangles in world units: one vertex per sample (u along x, v along z, 0..1
+ * across the field), two triangles per cell, smooth normals from `normalAt`. Promotes to 32-bit
+ * indices past 65535 samples. With `flat`, each cell's triangles get their own vertices and face
+ * normals (six vertices per cell).
+ */
+export declare function heightfieldGeometry(hf: Heightfield, opts?: HeightfieldGeometryOptions): Geometry;

package/dist/geom/heightfield.js

@@ -0,0 +1,295 @@
+/**
+ * Heightfields: a grid of heights a game stands on and clicks. `heightAt` and `normalAt` sample
+ * the bilinear surface, `raycastHeightfield` walks the grid cells a ray crosses (DDA) and solves
+ * the ray against each cell's bilinear patch exactly, and `heightfieldGeometry` builds the same
+ * surface as triangles. Nothing here allocates after the field exists.
+ *
+ * Layout: `heights[z * width + x]`, row-major by z then x, in height units; a sample `(x, z)`
+ * sits in the world at `origin + (x * scale[0], heights * scale[1], z * scale[2])`. Outside the
+ * field the surface continues flat from the nearest edge sample.
+ */
+import { GeometryWriter } from './geometry.js';
+/** A heightfield of `width × depth` samples; fill `heights` in place. */
+export function createHeightfield(width, depth, opts = {}) {
+    if (!(width >= 2) || !(depth >= 2)) {
+        throw new Error(`geom: a heightfield needs at least 2×2 samples, got ${width}×${depth}`);
+    }
+    const heights = opts.heights ?? new Float32Array(width * depth);
+    if (heights.length !== width * depth) {
+        throw new Error(`geom: heights has ${heights.length} samples, expected ${width * depth}`);
+    }
+    const s = opts.scale ?? [1, 1, 1];
+    const o = opts.origin ?? [0, 0, 0];
+    return {
+        width,
+        depth,
+        heights,
+        scale: [s[0], s[1], s[2]],
+        origin: [o[0], o[1], o[2]],
+    };
+}
+/** Bilinear height in grid space (`gx`, `gz` in samples), clamped to the field. Height units. */
+function sampleGrid(hf, gx, gz) {
+    const { width, depth, heights } = hf;
+    const cx = Math.min(Math.max(gx, 0), width - 1);
+    const cz = Math.min(Math.max(gz, 0), depth - 1);
+    let x0 = Math.floor(cx);
+    let z0 = Math.floor(cz);
+    if (x0 >= width - 1)
+        x0 = width - 2;
+    if (z0 >= depth - 1)
+        z0 = depth - 2;
+    const u = cx - x0;
+    const v = cz - z0;
+    const o = z0 * width + x0;
+    const h00 = heights[o];
+    const h10 = heights[o + 1];
+    const h01 = heights[o + width];
+    const h11 = heights[o + width + 1];
+    return (h00 * (1 - u) + h10 * u) * (1 - v) + (h01 * (1 - u) + h11 * u) * v;
+}
+/** World height of the surface under world `(x, z)`: bilinear between the four nearest samples. */
+export function heightAt(hf, x, z) {
+    const gx = (x - hf.origin[0]) / hf.scale[0];
+    const gz = (z - hf.origin[2]) / hf.scale[2];
+    return hf.origin[1] + sampleGrid(hf, gx, gz) * hf.scale[1];
+}
+/**
+ * Unit surface normal at world `(x, z)`, written to `out` (y up). Central differences over half
+ * a sample on each side, so it is the bilinear surface's slope smoothed across cell edges.
+ */
+export function normalAt(hf, x, z, out) {
+    const hx = hf.scale[0] * 0.5;
+    const hz = hf.scale[2] * 0.5;
+    const dx = heightAt(hf, x - hx, z) - heightAt(hf, x + hx, z);
+    const dz = heightAt(hf, x, z - hz) - heightAt(hf, x, z + hz);
+    const nx = dx;
+    const ny = 2 * hx;
+    const nz = dz * (hx / hz);
+    const l = Math.hypot(nx, ny, nz);
+    out[0] = nx / l;
+    out[1] = ny / l;
+    out[2] = nz / l;
+    return out;
+}
+/** Cells a DDA may visit beyond the grid's own extent before it is forced to stop. */
+const DDA_SLACK = 2;
+const EPS = 1e-9;
+/**
+ * Nearest intersection of `ray` with the surface, as the distance along `ray.dir` (world units
+ * when `dir` is unit length), or -1 for a miss. The ray is clipped to the field's footprint, the
+ * cells it crosses are walked in order (DDA), and in each the ray is solved against that cell's
+ * bilinear patch (a quadratic in the distance), so a hit lies exactly on `heightAt`. Hits from
+ * below count too. `out`, when given, receives the hit point. No allocation.
+ */
+export function raycastHeightfield(hf, ray, out) {
+    const { width, depth, heights, scale, origin } = hf;
+    // Grid space: x and z in samples, y in height units.
+    const ox = (ray.origin[0] - origin[0]) / scale[0];
+    const oy = (ray.origin[1] - origin[1]) / scale[1];
+    const oz = (ray.origin[2] - origin[2]) / scale[2];
+    const dx = ray.dir[0] / scale[0];
+    const dy = ray.dir[1] / scale[1];
+    const dz = ray.dir[2] / scale[2];
+    // Clip to the footprint 0..width-1 × 0..depth-1.
+    let t0 = 0;
+    let t1 = Number.POSITIVE_INFINITY;
+    if (Math.abs(dx) < EPS) {
+        if (ox < 0 || ox > width - 1)
+            return -1;
+    }
+    else {
+        const ta = -ox / dx;
+        const tb = (width - 1 - ox) / dx;
+        t0 = Math.max(t0, Math.min(ta, tb));
+        t1 = Math.min(t1, Math.max(ta, tb));
+    }
+    if (Math.abs(dz) < EPS) {
+        if (oz < 0 || oz > depth - 1)
+            return -1;
+    }
+    else {
+        const ta = -oz / dz;
+        const tb = (depth - 1 - oz) / dz;
+        t0 = Math.max(t0, Math.min(ta, tb));
+        t1 = Math.min(t1, Math.max(ta, tb));
+    }
+    if (t1 < t0)
+        return -1;
+    // Starting cell, clamped so a ray entering on the far edge lands in the last cell.
+    const sx = ox + dx * t0;
+    const sz = oz + dz * t0;
+    let cx = Math.floor(sx);
+    let cz = Math.floor(sz);
+    if (cx < 0)
+        cx = 0;
+    if (cx > width - 2)
+        cx = width - 2;
+    if (cz < 0)
+        cz = 0;
+    if (cz > depth - 2)
+        cz = depth - 2;
+    const stepX = dx > 0 ? 1 : -1;
+    const stepZ = dz > 0 ? 1 : -1;
+    const tDeltaX = Math.abs(dx) < EPS ? Number.POSITIVE_INFINITY : Math.abs(1 / dx);
+    const tDeltaZ = Math.abs(dz) < EPS ? Number.POSITIVE_INFINITY : Math.abs(1 / dz);
+    let tMaxX = Math.abs(dx) < EPS ? Number.POSITIVE_INFINITY : ((dx > 0 ? cx + 1 : cx) - ox) / dx;
+    let tMaxZ = Math.abs(dz) < EPS ? Number.POSITIVE_INFINITY : ((dz > 0 ? cz + 1 : cz) - oz) / dz;
+    let t = t0;
+    const maxSteps = width + depth + DDA_SLACK;
+    for (let step = 0; step < maxSteps; step++) {
+        const tEnd = Math.min(tMaxX, tMaxZ, t1);
+        // The patch of cell (cx, cz): h(u, v) = h00 + a u + b v + c u v, u = x - cx, v = z - cz.
+        const o = cz * width + cx;
+        const h00 = heights[o];
+        const a = heights[o + 1] - h00;
+        const b = heights[o + width] - h00;
+        const c = h00 - heights[o + 1] - heights[o + width] + heights[o + width + 1];
+        // f(t) = y(t) - h(u(t), v(t)), with u(t) = u0 + dx t, v(t) = v0 + dz t:
+        const u0 = ox - cx;
+        const v0 = oz - cz;
+        const qa = -c * dx * dz;
+        const qb = dy - a * dx - b * dz - c * (u0 * dz + v0 * dx);
+        const qc = oy - h00 - a * u0 - b * v0 - c * u0 * v0;
+        const hit = smallestRoot(qa, qb, qc, t, tEnd);
+        if (hit >= 0) {
+            if (out) {
+                out[0] = ray.origin[0] + ray.dir[0] * hit;
+                out[1] = ray.origin[1] + ray.dir[1] * hit;
+                out[2] = ray.origin[2] + ray.dir[2] * hit;
+            }
+            return hit;
+        }
+        if (tEnd >= t1)
+            return -1;
+        if (tMaxX < tMaxZ) {
+            cx += stepX;
+            t = tMaxX;
+            tMaxX += tDeltaX;
+        }
+        else {
+            cz += stepZ;
+            t = tMaxZ;
+            tMaxZ += tDeltaZ;
+        }
+        if (cx < 0 || cx > width - 2 || cz < 0 || cz > depth - 2)
+            return -1;
+    }
+    return -1;
+}
+/** Scratch ray for `rayHeightfield` (no allocation per call). */
+const scratchRay = {
+    origin: [0, 0, 0],
+    dir: [0, 0, 1],
+};
+/**
+ * `raycastHeightfield` taking the ray as two arrays: `origin` and `dir` (a `Ray` from `input`,
+ * a camera's eye and look direction, or plain `[x, y, z]`s), so a game casts without building a
+ * `HeightfieldRay`. Returns the distance along `dir` or -1; `out` receives the hit point.
+ */
+export function rayHeightfield(hf, origin, dir, out) {
+    scratchRay.origin = origin;
+    scratchRay.dir = dir;
+    return raycastHeightfield(hf, scratchRay, out);
+}
+/** Smallest root of `a t² + b t + c = 0` within `[lo, hi]`, or -1. */
+function smallestRoot(a, b, c, lo, hi) {
+    const tol = 1e-7 * Math.max(1, Math.abs(lo));
+    if (Math.abs(a) < 1e-12) {
+        if (Math.abs(b) < 1e-12)
+            return -1;
+        const t = -c / b;
+        return t >= lo - tol && t <= hi + tol ? Math.max(lo, t) : -1;
+    }
+    const disc = b * b - 4 * a * c;
+    if (disc < 0)
+        return -1;
+    const s = Math.sqrt(disc);
+    // Stable pair: q avoids cancellation.
+    const q = b >= 0 ? -(b + s) / 2 : -(b - s) / 2;
+    const r1 = q / a;
+    const r2 = q !== 0 ? c / q : r1;
+    const tA = Math.min(r1, r2);
+    const tB = Math.max(r1, r2);
+    if (tA >= lo - tol && tA <= hi + tol)
+        return Math.max(lo, tA);
+    if (tB >= lo - tol && tB <= hi + tol)
+        return Math.max(lo, tB);
+    return -1;
+}
+/**
+ * The field as triangles in world units: one vertex per sample (u along x, v along z, 0..1
+ * across the field), two triangles per cell, smooth normals from `normalAt`. Promotes to 32-bit
+ * indices past 65535 samples. With `flat`, each cell's triangles get their own vertices and face
+ * normals (six vertices per cell).
+ */
+export function heightfieldGeometry(hf, opts = {}) {
+    const { width, depth, scale, origin } = hf;
+    const cells = (width - 1) * (depth - 1);
+    if (opts.flat)
+        return flatGeometry(hf, opts);
+    const w = new GeometryWriter(width * depth, cells * 6, opts);
+    const n = [0, 1, 0];
+    for (let j = 0; j < depth; j++) {
+        for (let i = 0; i < width; i++) {
+            const x = origin[0] + i * scale[0];
+            const z = origin[2] + j * scale[2];
+            const y = origin[1] + hf.heights[j * width + i] * scale[1];
+            normalAt(hf, x, z, n);
+            w.vertex(x, y, z, n[0], n[1], n[2], i / (width - 1), j / (depth - 1));
+        }
+    }
+    for (let j = 0; j < depth - 1; j++) {
+        for (let i = 0; i < width - 1; i++) {
+            const a = j * width + i;
+            // (i, j) → (i, j+1) → (i+1, j+1) → (i+1, j): +z then +x, normal up.
+            w.quad(a, a + width, a + width + 1, a + 1);
+        }
+    }
+    return w.finish();
+}
+function flatGeometry(hf, opts) {
+    const { width, depth, scale, origin, heights } = hf;
+    const cells = (width - 1) * (depth - 1);
+    const w = new GeometryWriter(cells * 6, cells * 6, opts);
+    const px = (i) => origin[0] + i * scale[0];
+    const pz = (j) => origin[2] + j * scale[2];
+    const py = (i, j) => origin[1] + heights[j * width + i] * scale[1];
+    const tri = (i0, j0, i1, j1, i2, j2) => {
+        const x0 = px(i0);
+        const y0 = py(i0, j0);
+        const z0 = pz(j0);
+        const x1 = px(i1);
+        const y1 = py(i1, j1);
+        const z1 = pz(j1);
+        const x2 = px(i2);
+        const y2 = py(i2, j2);
+        const z2 = pz(j2);
+        const ax = x1 - x0;
+        const ay = y1 - y0;
+        const az = z1 - z0;
+        const bx = x2 - x0;
+        const by = y2 - y0;
+        const bz = z2 - z0;
+        let nx = ay * bz - az * by;
+        let ny = az * bx - ax * bz;
+        let nz = ax * by - ay * bx;
+        const l = Math.hypot(nx, ny, nz) || 1;
+        nx /= l;
+        ny /= l;
+        nz /= l;
+        const uw = width - 1;
+        const vd = depth - 1;
+        const a = w.vertex(x0, y0, z0, nx, ny, nz, i0 / uw, j0 / vd);
+        const b = w.vertex(x1, y1, z1, nx, ny, nz, i1 / uw, j1 / vd);
+        const c = w.vertex(x2, y2, z2, nx, ny, nz, i2 / uw, j2 / vd);
+        w.tri(a, b, c);
+    };
+    for (let j = 0; j < depth - 1; j++) {
+        for (let i = 0; i < width - 1; i++) {
+            tri(i, j, i, j + 1, i + 1, j + 1);
+            tri(i, j, i + 1, j + 1, i + 1, j);
+        }
+    }
+    return w.finish();
+}

package/dist/geom/hull.d.ts

@@ -0,0 +1,27 @@
+import { type Geometry } from './geometry.js';
+/**
+ * The convex hull of a point set (xyz triples, or a geometry's positions) as a flat-shaded
+ * `VERTEX_LAYOUT_3D` geometry: three vertices per triangle, wound counter-clockwise seen from
+ * outside, each carrying its face normal, uv 0 and white. Quickhull: start from a tetrahedron of
+ * extreme points, then repeatedly lift the farthest outside point of a face, replacing the faces
+ * it sees with a fan from their horizon. Points within a small tolerance of a face (scaled to the
+ * cloud's extent) count as on it, so a cube's corners give 12 triangles however noisy its inside.
+ * Fewer than four points, or a flat or collinear cloud, has no volume: the result is empty.
+ */
+export declare function convexHull(src: Float32Array | Geometry): Geometry;
+export interface CollisionProxyOptions {
+    /** Most triangles the proxy may have. */
+    maxTriangles: number;
+    /**
+     * `'hull'` (default): the convex hull, simplified further when it is over budget; solid and
+     * cheapest to query, but it fills concavities. `'simplified'`: the mesh itself simplified to
+     * the budget; keeps its shape, concavities included.
+     */
+    kind?: 'hull' | 'simplified';
+}
+/**
+ * A low-triangle stand-in for `g` to hand `createStaticCollider` (as `{ geometry }`) in place of
+ * the render mesh: at most `maxTriangles` triangles, in `VERTEX_LAYOUT_3D` for `'hull'` and in
+ * `g`'s layout for `'simplified'`.
+ */
+export declare function collisionProxy(g: Geometry, opts: CollisionProxyOptions): Geometry;

package/dist/geom/hull.js

@@ -0,0 +1,279 @@
+/**
+ * Convex hulls (`convexHull`, 3D quickhull) and cheap collision stand-ins for render meshes
+ * (`collisionProxy`). Build-time work: allocates freely, deterministic for a given input.
+ */
+import { VERTEX_LAYOUT_3D } from '../render/mesh.js';
+import { computeBounds, createIndices } from './geometry.js';
+import { simplifyGeometry } from './simplify.js';
+const F3 = VERTEX_LAYOUT_3D.floats;
+function emptyGeometry() {
+    return {
+        vertices: new Float32Array(0),
+        indices: new Uint16Array(0),
+        bounds: { center: [0, 0, 0], radius: 0 },
+        layout: VERTEX_LAYOUT_3D,
+    };
+}
+/** xyz triples from a positions array or a geometry's position lane (float 0 of each vertex). */
+function pointsOf(src) {
+    if (src instanceof Float32Array) {
+        if (src.length % 3 !== 0)
+            throw new Error(`geom: convexHull positions need xyz triples, got ${src.length} floats`);
+        return Float64Array.from(src);
+    }
+    const F = src.layout.floats;
+    const n = src.vertices.length / F;
+    const out = new Float64Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        out[i * 3] = src.vertices[i * F];
+        out[i * 3 + 1] = src.vertices[i * F + 1];
+        out[i * 3 + 2] = src.vertices[i * F + 2];
+    }
+    return out;
+}
+/**
+ * The convex hull of a point set (xyz triples, or a geometry's positions) as a flat-shaded
+ * `VERTEX_LAYOUT_3D` geometry: three vertices per triangle, wound counter-clockwise seen from
+ * outside, each carrying its face normal, uv 0 and white. Quickhull: start from a tetrahedron of
+ * extreme points, then repeatedly lift the farthest outside point of a face, replacing the faces
+ * it sees with a fan from their horizon. Points within a small tolerance of a face (scaled to the
+ * cloud's extent) count as on it, so a cube's corners give 12 triangles however noisy its inside.
+ * Fewer than four points, or a flat or collinear cloud, has no volume: the result is empty.
+ */
+export function convexHull(src) {
+    const p = pointsOf(src);
+    const n = p.length / 3;
+    if (n < 4)
+        return emptyGeometry();
+    const x = (i) => p[i * 3];
+    const y = (i) => p[i * 3 + 1];
+    const z = (i) => p[i * 3 + 2];
+    // Extreme points on each axis; the widest pair seeds the hull.
+    const lo = [0, 0, 0];
+    const hi = [0, 0, 0];
+    for (let i = 1; i < n; i++) {
+        for (let k = 0; k < 3; k++) {
+            if (p[i * 3 + k] < p[lo[k] * 3 + k])
+                lo[k] = i;
+            if (p[i * 3 + k] > p[hi[k] * 3 + k])
+                hi[k] = i;
+        }
+    }
+    let axis = 0;
+    let span = -1;
+    for (let k = 0; k < 3; k++) {
+        const s = p[hi[k] * 3 + k] - p[lo[k] * 3 + k];
+        if (s > span) {
+            span = s;
+            axis = k;
+        }
+    }
+    const eps = 1e-9 + 1e-6 * span;
+    if (!(span > eps))
+        return emptyGeometry();
+    const i0 = lo[axis];
+    const i1 = hi[axis];
+    // Farthest from the line i0 i1.
+    const ex = x(i1) - x(i0);
+    const ey = y(i1) - y(i0);
+    const ez = z(i1) - z(i0);
+    let i2 = -1;
+    let best = eps * eps;
+    for (let i = 0; i < n; i++) {
+        const vx = x(i) - x(i0);
+        const vy = y(i) - y(i0);
+        const vz = z(i) - z(i0);
+        const cx = vy * ez - vz * ey;
+        const cy = vz * ex - vx * ez;
+        const cz = vx * ey - vy * ex;
+        const d = cx * cx + cy * cy + cz * cz;
+        if (d > best) {
+            best = d;
+            i2 = i;
+        }
+    }
+    if (i2 < 0)
+        return emptyGeometry();
+    // Farthest from the plane i0 i1 i2.
+    const fx = x(i2) - x(i0);
+    const fy = y(i2) - y(i0);
+    const fz = z(i2) - z(i0);
+    let pnx = ey * fz - ez * fy;
+    let pny = ez * fx - ex * fz;
+    let pnz = ex * fy - ey * fx;
+    const pl = Math.hypot(pnx, pny, pnz);
+    pnx /= pl;
+    pny /= pl;
+    pnz /= pl;
+    let i3 = -1;
+    let bestD = eps;
+    for (let i = 0; i < n; i++) {
+        const d = Math.abs((x(i) - x(i0)) * pnx + (y(i) - y(i0)) * pny + (z(i) - z(i0)) * pnz);
+        if (d > bestD) {
+            bestD = d;
+            i3 = i;
+        }
+    }
+    if (i3 < 0)
+        return emptyGeometry();
+    const faces = [];
+    const makeFace = (a, b, c) => {
+        const ux = x(b) - x(a);
+        const uy = y(b) - y(a);
+        const uz = z(b) - z(a);
+        const vx = x(c) - x(a);
+        const vy = y(c) - y(a);
+        const vz = z(c) - z(a);
+        let nx = uy * vz - uz * vy;
+        let ny = uz * vx - ux * vz;
+        let nz = ux * vy - uy * vx;
+        const l = Math.hypot(nx, ny, nz) || 1;
+        nx /= l;
+        ny /= l;
+        nz /= l;
+        const f = {
+            a,
+            b,
+            c,
+            nx,
+            ny,
+            nz,
+            d: nx * x(a) + ny * y(a) + nz * z(a),
+            outside: [],
+            alive: true,
+        };
+        faces.push(f);
+        edgeOwner.set(a * n + b, f);
+        edgeOwner.set(b * n + c, f);
+        edgeOwner.set(c * n + a, f);
+        return f;
+    };
+    /** Directed edge `a → b` (key `a · n + b`) to the live face it bounds counter-clockwise. */
+    const edgeOwner = new Map();
+    const dist = (f, i) => f.nx * x(i) + f.ny * y(i) + f.nz * z(i) - f.d;
+    // The tetrahedron, wound outward (away from i3 for the base).
+    const above = (x(i3) - x(i0)) * pnx + (y(i3) - y(i0)) * pny + (z(i3) - z(i0)) * pnz > 0;
+    const seed = above
+        ? [makeFace(i0, i2, i1), makeFace(i0, i1, i3), makeFace(i1, i2, i3), makeFace(i2, i0, i3)]
+        : [makeFace(i0, i1, i2), makeFace(i0, i3, i1), makeFace(i1, i3, i2), makeFace(i2, i3, i0)];
+    const assign = (candidates, i) => {
+        let bestFace;
+        let bd = eps;
+        for (const f of candidates) {
+            const d = dist(f, i);
+            if (d > bd) {
+                bd = d;
+                bestFace = f;
+            }
+        }
+        bestFace?.outside.push(i);
+    };
+    for (let i = 0; i < n; i++) {
+        if (i === i0 || i === i1 || i === i2 || i === i3)
+            continue;
+        assign(seed, i);
+    }
+    // Faces still to process, in creation order: deterministic.
+    for (let fi = 0; fi < faces.length; fi++) {
+        const face = faces[fi];
+        if (!face.alive || face.outside.length === 0)
+            continue;
+        // The farthest outside point (lowest index on ties).
+        let eye = -1;
+        let ed = -1;
+        for (const i of face.outside) {
+            const d = dist(face, i);
+            if (d > ed) {
+                ed = d;
+                eye = i;
+            }
+        }
+        // Every face the eye sees: a flood across shared edges from this face (the visible region of
+        // a convex hull is connected). Its horizon is the edges whose far face does not see the eye.
+        face.alive = false;
+        const visible = [face];
+        const horizon = [];
+        for (let k = 0; k < visible.length; k++) {
+            const f = visible[k];
+            for (const [a, b] of [
+                [f.a, f.b],
+                [f.b, f.c],
+                [f.c, f.a],
+            ]) {
+                const g = edgeOwner.get(b * n + a);
+                if (!g?.alive)
+                    continue;
+                if (dist(g, eye) > eps) {
+                    g.alive = false;
+                    visible.push(g);
+                }
+                else
+                    horizon.push(a, b);
+            }
+        }
+        for (const f of visible) {
+            edgeOwner.delete(f.a * n + f.b);
+            edgeOwner.delete(f.b * n + f.c);
+            edgeOwner.delete(f.c * n + f.a);
+        }
+        const created = [];
+        for (let k = 0; k < horizon.length; k += 2)
+            created.push(makeFace(horizon[k], horizon[k + 1], eye));
+        for (const f of visible) {
+            for (const i of f.outside)
+                if (i !== eye)
+                    assign(created, i);
+            f.outside = [];
+        }
+    }
+    const live = faces.filter((f) => f.alive);
+    const vertices = new Float32Array(live.length * 3 * F3);
+    let o = 0;
+    for (const f of live) {
+        for (const i of [f.a, f.b, f.c]) {
+            vertices[o] = x(i);
+            vertices[o + 1] = y(i);
+            vertices[o + 2] = z(i);
+            vertices[o + 3] = f.nx;
+            vertices[o + 4] = f.ny;
+            vertices[o + 5] = f.nz;
+            vertices[o + 8] = 1;
+            vertices[o + 9] = 1;
+            vertices[o + 10] = 1;
+            vertices[o + 11] = 1;
+            o += F3;
+        }
+    }
+    const count = live.length * 3;
+    const indices = createIndices(count, count);
+    for (let i = 0; i < count; i++)
+        indices[i] = i;
+    return { vertices, indices, bounds: computeBounds(vertices, F3), layout: VERTEX_LAYOUT_3D };
+}
+/**
+ * A low-triangle stand-in for `g` to hand `createStaticCollider` (as `{ geometry }`) in place of
+ * the render mesh: at most `maxTriangles` triangles, in `VERTEX_LAYOUT_3D` for `'hull'` and in
+ * `g`'s layout for `'simplified'`.
+ */
+export function collisionProxy(g, opts) {
+    const max = Math.max(0, Math.floor(opts.maxTriangles));
+    const toBudget = (s) => {
+        let out = s;
+        // Simplification can stall short of the target where a collapse would fold the surface; a
+        // tighter target then gets there.
+        for (let k = 0; out.indices.length / 3 > max && k < 8; k++) {
+            const over = out.indices.length / 3 - max;
+            out = simplifyGeometry(out, { targetTriangles: Math.max(0, max - over) }).geometry;
+        }
+        return out;
+    };
+    if ((opts.kind ?? 'hull') === 'simplified') {
+        if (g.indices.length / 3 <= max)
+            return g;
+        return toBudget(simplifyGeometry(g, { targetTriangles: max }).geometry);
+    }
+    const hull = convexHull(g);
+    if (hull.indices.length / 3 <= max)
+        return hull;
+    return toBudget(simplifyGeometry(hull, { targetTriangles: max }).geometry);
+}