@series-inc/rundot-syncplay 5.23.0 → 5.24.0-beta.1

package/dist/cjs/collider-cooking.js

@@ -0,0 +1,834 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__colliderCookingInternals = void 0;
+exports.cookConvexDecomposition = cookConvexDecomposition;
+exports.assertCookedColliderIsRuntimeValid = assertCookedColliderIsRuntimeValid;
+const canonical_js_1 = require("./canonical.js");
+const physics3d_hull_js_1 = require("./physics3d-hull.js");
+/**
+ * Offline convex decomposition (V-HACD shaped): turn a concave triangle-soup
+ * collider into a `compound` of convex `hull` children the deterministic runtime
+ * can collide.
+ *
+ * This module is BUILD-TIME ONLY. It never runs inside a simulation step, so it
+ * is free to be expensive; what ships is its output — a fixed set of hull
+ * vertices — and *that* is what the runtime must reproduce bit-for-bit. The
+ * cook is nonetheless made reproducible on purpose: the source is canonicalised
+ * before any work happens, every interior computation runs on an integer voxel
+ * lattice (so the convex-hull orientation predicate is exact, never an epsilon
+ * vote), and every tie-break is lexicographic. Cooking the same mesh twice — or
+ * a permutation of its triangles — yields byte-identical output.
+ *
+ * Pipeline: canonicalise → voxelize (surface rasterisation + exterior flood
+ * fill) → recursively split the voxel set on the axis-aligned plane that best
+ * reduces concavity, worst part first, until every part is convex enough or the
+ * hull budget is spent → hull each part, reduce it to the runtime's vertex cap
+ * while inflating it to still contain the part, and quantize.
+ */
+/** Runtime hard cap: `buildSolverHull` accepts 4..16 vertices. */
+const RUNTIME_MAX_HULL_VERTICES = 16;
+const RUNTIME_MIN_HULL_VERTICES = 4;
+/**
+ * Lowest cap a cook can honour: the voxel-AABB fallback is an 8-corner box, so
+ * asking for fewer would make a fallback unsatisfiable.
+ */
+const MIN_COOKED_HULL_VERTICES = 8;
+const DEFAULTS = {
+    resolution: 24,
+    maxHulls: 8,
+    maxHullVertices: RUNTIME_MAX_HULL_VERTICES,
+    concavityTolerance: 0.05,
+    quantum: 1e-4,
+    splitCandidates: 7,
+};
+// ---------- entry point ----------
+function cookConvexDecomposition(source, options = {}) {
+    const resolution = requireIntegerInRange(options.resolution ?? DEFAULTS.resolution, 4, 96, 'resolution');
+    const maxHulls = requireIntegerInRange(options.maxHulls ?? DEFAULTS.maxHulls, 1, 64, 'maxHulls');
+    const maxHullVertices = requireIntegerInRange(options.maxHullVertices ?? DEFAULTS.maxHullVertices, MIN_COOKED_HULL_VERTICES, RUNTIME_MAX_HULL_VERTICES, 'maxHullVertices');
+    const splitCandidates = requireIntegerInRange(options.splitCandidates ?? DEFAULTS.splitCandidates, 1, 32, 'splitCandidates');
+    const concavityTolerance = options.concavityTolerance ?? DEFAULTS.concavityTolerance;
+    if (!(concavityTolerance >= 0 && concavityTolerance < 1)) {
+        throw new Error('cookConvexDecomposition: concavityTolerance must be in [0, 1)');
+    }
+    const quantum = options.quantum ?? DEFAULTS.quantum;
+    if (!(quantum > 0)) {
+        throw new Error('cookConvexDecomposition: quantum must be positive');
+    }
+    const triangles = canonicalTriangles(source.vertices);
+    const lattice = voxelize(triangles, resolution);
+    if (quantum > lattice.voxelSize / 8) {
+        throw new Error(`cookConvexDecomposition: quantum ${quantum} is too coarse for voxel size ${lattice.voxelSize} `
+            + '— it would collapse hull faces; use a finer quantum or a lower resolution');
+    }
+    const parts = decompose(lattice, maxHulls, concavityTolerance, splitCandidates);
+    const children = [];
+    const hulls = [];
+    let totalVolume = 0;
+    let weightedConcavity = 0;
+    for (const part of parts) {
+        const vertices = finalizeHull(part, lattice, maxHullVertices, quantum);
+        const centroid = quantizePoint(meanPoint(vertices), quantum);
+        children.push({
+            shape: { type: 'hull', vertices: vertices.map((v) => quantizePoint(subtract(v, centroid), quantum)) },
+            offset: centroid,
+        });
+        hulls.push({ vertexCount: vertices.length, concavity: part.concavity });
+        totalVolume += part.voxels.length;
+        weightedConcavity += part.concavity * part.voxels.length;
+    }
+    const shape = { type: 'compound', children };
+    return {
+        schemaVersion: 1,
+        kind: 'deterministic-convex-decomposition',
+        shape,
+        hulls,
+        sourceTriangles: triangles.length,
+        resolution,
+        /* istanbul ignore next -- voxelize throws on an empty volume, so `parts` always covers at least one voxel. */
+        concavity: totalVolume === 0 ? 0 : weightedConcavity / totalVolume,
+        hash: (0, canonical_js_1.defaultChecksum)(shape),
+    };
+}
+/**
+ * Re-run every runtime guard the cooked collider will meet at world creation,
+ * so a bad cook fails in the asset pipeline rather than in a game.
+ */
+function assertCookedColliderIsRuntimeValid(cooked) {
+    if (cooked.shape.children.length === 0) {
+        throw new Error('cooked collider: compound must have at least one child');
+    }
+    cooked.shape.children.forEach((child, index) => {
+        if (child.shape.type !== 'hull') {
+            throw new Error(`cooked collider: child ${index} must be a hull`);
+        }
+        try {
+            (0, physics3d_hull_js_1.buildSolverHull)(child.shape.vertices);
+        }
+        catch (error) {
+            throw new Error(`cooked collider: child ${index} is not a valid runtime hull — ${error.message}`);
+        }
+    });
+    if (cooked.hash !== (0, canonical_js_1.defaultChecksum)(cooked.shape)) {
+        throw new Error('cooked collider: hash does not match its shape');
+    }
+}
+// ---------- canonicalisation ----------
+function canonicalTriangles(vertices) {
+    if (vertices.length < 3 || vertices.length % 3 !== 0) {
+        throw new Error('cookConvexDecomposition: source requires triangle-list vertices (a positive multiple of 3)');
+    }
+    for (const vertex of vertices) {
+        if (!Number.isFinite(vertex.x) || !Number.isFinite(vertex.y) || !Number.isFinite(vertex.z)) {
+            throw new Error('cookConvexDecomposition: source contains a non-finite vertex');
+        }
+    }
+    const triangles = [];
+    for (let index = 0; index + 2 < vertices.length; index += 3) {
+        triangles.push([vertices[index], vertices[index + 1], vertices[index + 2]]);
+    }
+    // Winding is irrelevant to voxelisation, so a triangle's canonical key is its
+    // lexicographically sorted vertex triple. Sorting by it makes the whole cook
+    // invariant to the authoring order of the source soup.
+    return [...triangles].sort((left, right) => comparePointLists(sortPoints(left), sortPoints(right)));
+}
+function sortPoints(triangle) {
+    return [...triangle].sort(comparePoints);
+}
+function comparePoints(left, right) {
+    return left.x - right.x || left.y - right.y || left.z - right.z;
+}
+function comparePointLists(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        const order = comparePoints(left[index], right[index]);
+        if (order !== 0) {
+            return order;
+        }
+    }
+    return 0;
+}
+// ---------- voxelisation ----------
+function voxelize(triangles, resolution) {
+    let minX = Infinity, minY = Infinity, minZ = Infinity;
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+    for (const triangle of triangles) {
+        for (const vertex of triangle) {
+            minX = Math.min(minX, vertex.x);
+            maxX = Math.max(maxX, vertex.x);
+            minY = Math.min(minY, vertex.y);
+            maxY = Math.max(maxY, vertex.y);
+            minZ = Math.min(minZ, vertex.z);
+            maxZ = Math.max(maxZ, vertex.z);
+        }
+    }
+    const extent = Math.max(maxX - minX, maxY - minY, maxZ - minZ);
+    if (!(extent > 0)) {
+        throw new Error('cookConvexDecomposition: source mesh is degenerate (zero extent)');
+    }
+    const voxelSize = extent / resolution;
+    // One voxel of padding on every side gives the exterior flood fill a
+    // guaranteed connected shell to start from.
+    const originX = minX - voxelSize;
+    const originY = minY - voxelSize;
+    const originZ = minZ - voxelSize;
+    const nx = Math.max(1, Math.ceil((maxX - minX) / voxelSize)) + 2;
+    const ny = Math.max(1, Math.ceil((maxY - minY) / voxelSize)) + 2;
+    const nz = Math.max(1, Math.ceil((maxZ - minZ) / voxelSize)) + 2;
+    const SURFACE = 1;
+    const EXTERIOR = 2;
+    const cells = new Uint8Array(nx * ny * nz);
+    const at = (x, y, z) => (z * ny + y) * nx + x;
+    const half = voxelSize / 2;
+    for (const triangle of triangles) {
+        const lo = [
+            Math.min(triangle[0].x, triangle[1].x, triangle[2].x),
+            Math.min(triangle[0].y, triangle[1].y, triangle[2].y),
+            Math.min(triangle[0].z, triangle[1].z, triangle[2].z),
+        ];
+        const hi = [
+            Math.max(triangle[0].x, triangle[1].x, triangle[2].x),
+            Math.max(triangle[0].y, triangle[1].y, triangle[2].y),
+            Math.max(triangle[0].z, triangle[1].z, triangle[2].z),
+        ];
+        const x0 = clampIndex(Math.floor((lo[0] - originX) / voxelSize), nx);
+        const x1 = clampIndex(Math.floor((hi[0] - originX) / voxelSize), nx);
+        const y0 = clampIndex(Math.floor((lo[1] - originY) / voxelSize), ny);
+        const y1 = clampIndex(Math.floor((hi[1] - originY) / voxelSize), ny);
+        const z0 = clampIndex(Math.floor((lo[2] - originZ) / voxelSize), nz);
+        const z1 = clampIndex(Math.floor((hi[2] - originZ) / voxelSize), nz);
+        for (let z = z0; z <= z1; z += 1) {
+            for (let y = y0; y <= y1; y += 1) {
+                for (let x = x0; x <= x1; x += 1) {
+                    const center = {
+                        x: originX + (x + 0.5) * voxelSize,
+                        y: originY + (y + 0.5) * voxelSize,
+                        z: originZ + (z + 0.5) * voxelSize,
+                    };
+                    if (triangleIntersectsBox(triangle, center, half)) {
+                        cells[at(x, y, z)] = SURFACE;
+                    }
+                }
+            }
+        }
+    }
+    // Flood fill the exterior from the padded shell; everything left that is not
+    // surface is enclosed interior. Non-manifold or open meshes simply leak, and
+    // then the decomposition covers only the surface shell — which is still a
+    // sound (if hollow) collider, not a crash.
+    const stack = [];
+    const pushIfOpen = (x, y, z) => {
+        const index = at(x, y, z);
+        if (cells[index] === 0) {
+            cells[index] = EXTERIOR;
+            stack.push(index);
+        }
+    };
+    for (let z = 0; z < nz; z += 1) {
+        for (let y = 0; y < ny; y += 1) {
+            for (let x = 0; x < nx; x += 1) {
+                if (x === 0 || y === 0 || z === 0 || x === nx - 1 || y === ny - 1 || z === nz - 1) {
+                    pushIfOpen(x, y, z);
+                }
+            }
+        }
+    }
+    while (stack.length > 0) {
+        const index = stack.pop();
+        const x = index % nx;
+        const y = Math.floor(index / nx) % ny;
+        const z = Math.floor(index / (nx * ny));
+        if (x > 0)
+            pushIfOpen(x - 1, y, z);
+        if (x < nx - 1)
+            pushIfOpen(x + 1, y, z);
+        if (y > 0)
+            pushIfOpen(x, y - 1, z);
+        if (y < ny - 1)
+            pushIfOpen(x, y + 1, z);
+        if (z > 0)
+            pushIfOpen(x, y, z - 1);
+        if (z < nz - 1)
+            pushIfOpen(x, y, z + 1);
+    }
+    const occupied = [];
+    for (let index = 0; index < cells.length; index += 1) {
+        if (cells[index] !== EXTERIOR) {
+            occupied.push(index);
+        }
+    }
+    /* istanbul ignore next -- a non-degenerate triangle always rasterises at least one surface voxel. */
+    if (occupied.length === 0) {
+        throw new Error('cookConvexDecomposition: source mesh voxelized to an empty volume');
+    }
+    return { nx, ny, nz, voxelSize, originX, originY, originZ, occupied };
+}
+function clampIndex(value, count) {
+    return Math.min(Math.max(value, 0), count - 1);
+}
+/**
+ * Akenine-Möller triangle/AABB overlap, box centred at `center` with half-width
+ * `half`, biased outward by `tol`.
+ *
+ * The bias is load-bearing, not a fudge. Axis-aligned source faces land exactly
+ * on voxel boundaries whenever the voxel size is not a binary fraction (`1/24`
+ * is not), so the overlap test is decided at exact tangency and rounding rejects
+ * roughly half the cells. That punches holes in the surface shell, the exterior
+ * flood fill leaks through them, and the mesh cooks hollow. A conservative
+ * rasteriser must resolve tangency as "overlapping".
+ */
+function triangleIntersectsBox(triangle, center, half) {
+    const tol = half * 1e-6;
+    const v0 = [triangle[0].x - center.x, triangle[0].y - center.y, triangle[0].z - center.z];
+    const v1 = [triangle[1].x - center.x, triangle[1].y - center.y, triangle[1].z - center.z];
+    const v2 = [triangle[2].x - center.x, triangle[2].y - center.y, triangle[2].z - center.z];
+    const edges = [
+        [v1[0] - v0[0], v1[1] - v0[1], v1[2] - v0[2]],
+        [v2[0] - v1[0], v2[1] - v1[1], v2[2] - v1[2]],
+        [v0[0] - v2[0], v0[1] - v2[1], v0[2] - v2[2]],
+    ];
+    for (let axis = 0; axis < 3; axis += 1) {
+        for (const edge of edges) {
+            // cross(unitAxis[axis], edge)
+            const a = [0, 0, 0];
+            a[(axis + 1) % 3] = -edge[(axis + 2) % 3];
+            a[(axis + 2) % 3] = edge[(axis + 1) % 3];
+            const p0 = a[0] * v0[0] + a[1] * v0[1] + a[2] * v0[2];
+            const p1 = a[0] * v1[0] + a[1] * v1[1] + a[2] * v1[2];
+            const p2 = a[0] * v2[0] + a[1] * v2[1] + a[2] * v2[2];
+            const radius = half * (Math.abs(a[0]) + Math.abs(a[1]) + Math.abs(a[2])) + tol;
+            if (Math.min(p0, p1, p2) > radius || Math.max(p0, p1, p2) < -radius) {
+                return false;
+            }
+        }
+    }
+    for (let axis = 0; axis < 3; axis += 1) {
+        const lo = Math.min(v0[axis], v1[axis], v2[axis]);
+        const hi = Math.max(v0[axis], v1[axis], v2[axis]);
+        if (lo > half + tol || hi < -half - tol) {
+            return false;
+        }
+    }
+    const normal = [
+        edges[0][1] * edges[1][2] - edges[0][2] * edges[1][1],
+        edges[0][2] * edges[1][0] - edges[0][0] * edges[1][2],
+        edges[0][0] * edges[1][1] - edges[0][1] * edges[1][0],
+    ];
+    const offset = normal[0] * v0[0] + normal[1] * v0[1] + normal[2] * v0[2];
+    const radius = half * (Math.abs(normal[0]) + Math.abs(normal[1]) + Math.abs(normal[2])) + tol;
+    return Math.abs(offset) <= radius;
+}
+// ---------- decomposition ----------
+function decompose(lattice, maxHulls, tolerance, splitCandidates) {
+    let parts = [makePart(lattice.occupied, lattice)];
+    while (parts.length < maxHulls) {
+        // Split the part that contributes the most absolute volume error. Ties fall
+        // to the lowest index, which is stable because parts stay sorted below.
+        let worst = -1;
+        let worstScore = 0;
+        parts.forEach((part, index) => {
+            const score = part.concavity * part.voxels.length;
+            if (part.concavity > tolerance && score > worstScore) {
+                worst = index;
+                worstScore = score;
+            }
+        });
+        if (worst < 0) {
+            break;
+        }
+        const split = bestSplit(parts[worst], lattice, splitCandidates);
+        /* istanbul ignore next -- only a single-voxel part is unsplittable, and its concavity is 0, so it is never selected as `worst` above. The guard stays because the selection rule and the split rule are separate. */
+        if (split === undefined) {
+            // Unsplittable (single voxel slab); accept it as a leaf by retiring it
+            // from consideration via an exact-convex marker.
+            parts[worst] = { ...parts[worst], concavity: 0 };
+            continue;
+        }
+        parts = [...parts.slice(0, worst), ...split, ...parts.slice(worst + 1)];
+    }
+    return parts;
+}
+function makePart(voxels, lattice) {
+    const hull = latticeHullOfVoxels(voxels, lattice);
+    /* istanbul ignore next -- a part always holds at least one voxel, whose eight corners span a unit-volume hull. */
+    const concavity = hull.volume <= 0 ? 0 : Math.max(0, 1 - voxels.length / hull.volume);
+    return { voxels, hull, concavity };
+}
+function bestSplit(part, lattice, splitCandidates) {
+    const coords = part.voxels.map((index) => voxelCoord(index, lattice));
+    let best;
+    for (let axis = 0; axis < 3; axis += 1) {
+        let lo = Infinity;
+        let hi = -Infinity;
+        for (const coord of coords) {
+            lo = Math.min(lo, coord[axis]);
+            hi = Math.max(hi, coord[axis]);
+        }
+        if (hi <= lo) {
+            continue;
+        }
+        for (let candidate = 1; candidate <= splitCandidates; candidate += 1) {
+            const plane = lo + Math.floor(((hi - lo + 1) * candidate) / (splitCandidates + 1));
+            if (plane <= lo || plane > hi) {
+                continue;
+            }
+            const left = [];
+            const right = [];
+            part.voxels.forEach((index, ordinal) => {
+                (coords[ordinal][axis] < plane ? left : right).push(index);
+            });
+            /* istanbul ignore next -- `plane` is clamped to (lo, hi], so the voxel at `lo` always lands left and the one at `hi` always lands right. */
+            if (left.length === 0 || right.length === 0) {
+                continue;
+            }
+            const leftPart = makePart(left, lattice);
+            const rightPart = makePart(right, lattice);
+            // Volume-weighted concavity of the pair; lower is a cleaner cut.
+            const score = leftPart.concavity * left.length + rightPart.concavity * right.length;
+            if (best === undefined || score < best.score) {
+                best = { score, parts: [leftPart, rightPart] };
+            }
+        }
+    }
+    return best?.parts;
+}
+function voxelCoord(index, lattice) {
+    const x = index % lattice.nx;
+    const y = Math.floor(index / lattice.nx) % lattice.ny;
+    const z = Math.floor(index / (lattice.nx * lattice.ny));
+    return [x, y, z];
+}
+/**
+ * Corner-lattice points that can possibly be convex-hull vertices. A corner with
+ * occupied corners both below and above it in its own column is a convex
+ * combination of them, so it can never be a hull vertex — keeping only each
+ * column's extremes is exact, not an approximation, and cuts the hull input from
+ * O(n³) to O(n²).
+ */
+function hullCandidateCorners(voxels, lattice) {
+    const corners = [];
+    for (const index of voxels) {
+        const [vx, vy, vz] = voxelCoord(index, lattice);
+        for (let dx = 0; dx <= 1; dx += 1) {
+            for (let dy = 0; dy <= 1; dy += 1) {
+                for (let dz = 0; dz <= 1; dz += 1) {
+                    corners.push([vx + dx, vy + dy, vz + dz]);
+                }
+            }
+        }
+    }
+    // Each axis pass is individually exact, so composing all three is too.
+    return columnExtremes(columnExtremes(columnExtremes(corners, 2), 1), 0);
+}
+/** Keep only each column's two extremes along `axis` (see hullCandidateCorners). */
+function columnExtremes(points, axis) {
+    const u = (axis + 1) % 3;
+    const v = (axis + 2) % 3;
+    const columns = new Map();
+    for (const point of points) {
+        const key = `${point[u]}:${point[v]}`;
+        const column = columns.get(key);
+        if (column === undefined) {
+            columns.set(key, { min: point[axis], max: point[axis] });
+        }
+        else {
+            column.min = Math.min(column.min, point[axis]);
+            column.max = Math.max(column.max, point[axis]);
+        }
+    }
+    const kept = [];
+    for (const point of points) {
+        const column = columns.get(`${point[u]}:${point[v]}`);
+        if (point[axis] === column.min || point[axis] === column.max) {
+            kept.push(point);
+        }
+    }
+    return dedupeIVecs(kept);
+}
+function latticeHullOfVoxels(voxels, lattice) {
+    return convexHullLattice(hullCandidateCorners(voxels, lattice));
+}
+function orient3d(a, b, c, d) {
+    // Corner-lattice coordinates are small integers, so this determinant is exact
+    // in a double — the hull has no epsilon anywhere.
+    const ax = a[0] - d[0], ay = a[1] - d[1], az = a[2] - d[2];
+    const bx = b[0] - d[0], by = b[1] - d[1], bz = b[2] - d[2];
+    const cx = c[0] - d[0], cy = c[1] - d[1], cz = c[2] - d[2];
+    return ax * (by * cz - bz * cy) - ay * (bx * cz - bz * cx) + az * (bx * cy - by * cx);
+}
+function latticeCentroid(vertices) {
+    let x = 0, y = 0, z = 0;
+    for (const vertex of vertices) {
+        x += vertex[0];
+        y += vertex[1];
+        z += vertex[2];
+    }
+    return [x / vertices.length, y / vertices.length, z / vertices.length];
+}
+/** orient3d against a non-lattice apex; used only to rank removal candidates. */
+function orient3dFloat(a, b, c, d) {
+    const ax = a[0] - d[0], ay = a[1] - d[1], az = a[2] - d[2];
+    const bx = b[0] - d[0], by = b[1] - d[1], bz = b[2] - d[2];
+    const cx = c[0] - d[0], cy = c[1] - d[1], cz = c[2] - d[2];
+    return ax * (by * cz - bz * cy) - ay * (bx * cz - bz * cx) + az * (bx * cy - by * cx);
+}
+function compareIVec(left, right) {
+    return left[0] - right[0] || left[1] - right[1] || left[2] - right[2];
+}
+/**
+ * Incremental convex hull over integer points. Degenerate inputs (collinear or
+ * coplanar) return an empty face set with zero volume; callers treat that as a
+ * flat part and fall back to its voxel AABB.
+ */
+function convexHullLattice(points) {
+    const unique = dedupeIVecs(points);
+    if (unique.length < 4) {
+        return { vertices: unique, faces: [], volume: 0 };
+    }
+    const seed = seedTetrahedron(unique);
+    if (seed === undefined) {
+        return { vertices: unique, faces: [], volume: 0 };
+    }
+    const faces = [];
+    const [i0, i1, i2, i3] = seed;
+    // Orient every face so an interior point scores positive; a point strictly
+    // outside a face then scores negative, which is the visibility test below.
+    const addSeedFace = (a, b, c, opposite) => {
+        faces.push(orient3d(unique[a], unique[b], unique[c], unique[opposite]) > 0 ? [a, b, c] : [a, c, b]);
+    };
+    addSeedFace(i0, i1, i2, i3);
+    addSeedFace(i0, i1, i3, i2);
+    addSeedFace(i0, i2, i3, i1);
+    addSeedFace(i1, i2, i3, i0);
+    const inSeed = new Set(seed);
+    let live = faces;
+    for (let index = 0; index < unique.length; index += 1) {
+        if (inSeed.has(index)) {
+            continue;
+        }
+        const point = unique[index];
+        const visible = [];
+        const kept = [];
+        for (const face of live) {
+            // A face is visible when the point lies strictly on its outward side.
+            if (orient3d(unique[face[0]], unique[face[1]], unique[face[2]], point) < 0) {
+                visible.push(face);
+            }
+            else {
+                kept.push(face);
+            }
+        }
+        /* istanbul ignore next -- points are inserted in lexicographic order, so a point is never interior to the partial hull that already exists when it is added. */
+        if (visible.length === 0) {
+            continue;
+        }
+        // Horizon = edges owned by exactly one visible face.
+        const edgeUse = new Map();
+        for (const face of visible) {
+            for (const [a, b] of [[face[0], face[1]], [face[1], face[2]], [face[2], face[0]]]) {
+                const key = a < b ? `${a}:${b}` : `${b}:${a}`;
+                if (edgeUse.has(key)) {
+                    edgeUse.delete(key);
+                }
+                else {
+                    edgeUse.set(key, [a, b]);
+                }
+            }
+        }
+        const horizon = [...edgeUse.entries()].sort((left, right) => (left[0] < right[0] ? -1 : 1)).map((entry) => entry[1]);
+        for (const [a, b] of horizon) {
+            kept.push([a, b, index]);
+        }
+        live = kept;
+    }
+    const usedIndices = [...new Set(live.flat())].sort((left, right) => left - right);
+    const remap = new Map(usedIndices.map((original, next) => [original, next]));
+    const vertices = usedIndices.map((original) => unique[original]);
+    const hullFaces = live
+        .map((face) => [remap.get(face[0]), remap.get(face[1]), remap.get(face[2])])
+        /* istanbul ignore next -- consistent outward winding means no two faces share their first two vertex indices in the same order (3000-hull fuzz: never); the third operand stays as the determinism guarantee. */
+        .sort((left, right) => left[0] - right[0] || left[1] - right[1] || left[2] - right[2]);
+    return { vertices, faces: hullFaces, volume: hullVolume(vertices, hullFaces) };
+}
+function dedupeIVecs(points) {
+    const sorted = [...points].sort(compareIVec);
+    const unique = [];
+    for (const point of sorted) {
+        const last = unique[unique.length - 1];
+        if (last === undefined || compareIVec(last, point) !== 0) {
+            unique.push(point);
+        }
+    }
+    return unique;
+}
+function seedTetrahedron(points) {
+    const i0 = 0;
+    let i1 = -1;
+    for (let index = 1; index < points.length; index += 1) {
+        /* istanbul ignore else -- `points` is deduped, so points[1] always differs from points[0]. */
+        if (compareIVec(points[i0], points[index]) !== 0) {
+            i1 = index;
+            break;
+        }
+    }
+    /* istanbul ignore next -- unreachable: the deduped set has at least two distinct points here. */
+    if (i1 < 0) {
+        return undefined;
+    }
+    let i2 = -1;
+    for (let index = 1; index < points.length; index += 1) {
+        if (index !== i1 && !collinear(points[i0], points[i1], points[index])) {
+            i2 = index;
+            break;
+        }
+    }
+    if (i2 < 0) {
+        return undefined;
+    }
+    for (let index = 1; index < points.length; index += 1) {
+        if (index !== i1 && index !== i2 && orient3d(points[i0], points[i1], points[i2], points[index]) !== 0) {
+            return [i0, i1, i2, index];
+        }
+    }
+    return undefined;
+}
+function collinear(a, b, c) {
+    const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2];
+    const vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - a[2];
+    return uy * vz - uz * vy === 0 && uz * vx - ux * vz === 0 && ux * vy - uy * vx === 0;
+}
+function hullVolume(vertices, faces) {
+    /* istanbul ignore next -- only called with the incremental hull's live face set, which always has at least four faces. */
+    if (faces.length === 0) {
+        return 0;
+    }
+    let sixVolume = 0;
+    const origin = vertices[0];
+    for (const face of faces) {
+        sixVolume += orient3d(vertices[face[0]], vertices[face[1]], vertices[face[2]], origin);
+    }
+    return Math.abs(sixVolume) / 6;
+}
+// ---------- hull finalisation ----------
+function finalizeHull(part, lattice, maxHullVertices, quantum) {
+    // Every non-empty voxel set spans two corner layers on all three axes, so its
+    // lattice hull is always full-dimensional and `part.hull.faces` is non-empty.
+    // Reduce in integer lattice space, where the hull rebuild driving the greedy
+    // removal is exact and cheap, then inflate the survivor in world space until
+    // it contains every original hull vertex again.
+    const reducedLattice = reduceLatticeHull(part.hull, maxHullVertices);
+    const original = part.hull.vertices.map((corner) => cornerToWorld(corner, lattice));
+    const reduced = reducedLattice.length === part.hull.vertices.length
+        ? original
+        : inflateToContain(reducedLattice.map((corner) => cornerToWorld(corner, lattice)), original);
+    // Round each vertex AWAY from the hull's centre, never to the nearest grid
+    // point. Nearest-rounding pushes roughly half the vertices inside the hull they
+    // define, `buildSolverHull` then rejects them as interior, and the part
+    // degrades. Outward rounding keeps every vertex extreme and preserves the
+    // containment guarantee inflation just established.
+    const centre = meanPoint(reduced);
+    const boundary = boundaryVertices(dedupePoints(reduced.map((point) => quantizeOutward(point, centre, quantum))));
+    // Silently shipping a looser box here would hide a bad cook in a game rather
+    // than in the asset pipeline; `quantum <= voxelSize / 8` is validated up front,
+    // so reaching either throw means the caller asked for something incoherent.
+    if (boundary.length < RUNTIME_MIN_HULL_VERTICES || boundary.length > maxHullVertices) {
+        throw new Error(`cookConvexDecomposition: a part reduced to ${boundary.length} boundary vertices, outside the runtime's `
+            + `${RUNTIME_MIN_HULL_VERTICES}..${maxHullVertices} range — raise maxHullVertices or use a finer quantum`);
+    }
+    try {
+        (0, physics3d_hull_js_1.buildSolverHull)(boundary);
+    }
+    catch (error) {
+        /* istanbul ignore next -- quantum <= voxelSize / 8 is validated up front, and outward rounding keeps every reduced vertex extreme, so the boundary always builds. */
+        throw new Error(`cookConvexDecomposition: quantisation collapsed a part's hull (${error.message}) `
+            + '— use a finer quantum or a coarser resolution');
+    }
+    return boundary;
+}
+/**
+ * Drop the least load-bearing vertex until the cap is met.
+ *
+ * A vertex's cost is the volume of the cone its incident faces subtend from the
+ * hull's centroid — the part of the hull only that vertex carries. Scoring from
+ * the current hull's faces costs one hull rebuild per removal rather than one
+ * per candidate, which is the difference between a cook that takes a second and
+ * one that takes a minute. It is a greedy proxy, and it is allowed to be: the
+ * caller re-inflates the survivor until it contains the original hull, so a
+ * suboptimal choice costs tightness, never correctness.
+ */
+function reduceLatticeHull(hull, maxHullVertices) {
+    let current = hull;
+    while (current.vertices.length > maxHullVertices && current.faces.length > 0) {
+        const cost = new Array(current.vertices.length).fill(0);
+        // Cone volumes are measured from the hull's centroid, never from one of its
+        // own vertices: every face incident to that vertex would subtend zero volume,
+        // so it would always score lowest and the greedy would just strip vertices in
+        // index order until the survivors went coplanar.
+        const apex = latticeCentroid(current.vertices);
+        for (const face of current.faces) {
+            const volume = Math.abs(orient3dFloat(current.vertices[face[0]], current.vertices[face[1]], current.vertices[face[2]], apex));
+            cost[face[0]] += volume;
+            cost[face[1]] += volume;
+            cost[face[2]] += volume;
+        }
+        let victim = 0;
+        for (let index = 1; index < cost.length; index += 1) {
+            if (cost[index] < cost[victim]) {
+                victim = index;
+            }
+        }
+        const kept = current.vertices.filter((_, index) => index !== victim);
+        const rebuilt = convexHullLattice(kept);
+        if (rebuilt.volume <= 0 || rebuilt.vertices.length >= current.vertices.length) {
+            break;
+        }
+        current = rebuilt;
+    }
+    return current.vertices;
+}
+function cornerToWorld(corner, lattice) {
+    return {
+        x: lattice.originX + corner[0] * lattice.voxelSize,
+        y: lattice.originY + corner[1] * lattice.voxelSize,
+        z: lattice.originZ + corner[2] * lattice.voxelSize,
+    };
+}
+/**
+ * Inflate `hullPoints` about their centroid by the smallest factor that puts
+ * every point of `mustContain` back inside. A cooked collider is never smaller
+ * than the geometry it stands for.
+ */
+function inflateToContain(hullPoints, mustContain) {
+    const centroid = meanPoint(hullPoints);
+    const planes = supportingPlanes(hullPoints, centroid);
+    let scale = 1;
+    for (const point of mustContain) {
+        for (const plane of planes) {
+            const reach = dot(plane.normal, subtract(point, centroid));
+            if (reach > plane.offset * scale) {
+                scale = reach / plane.offset;
+            }
+        }
+    }
+    if (scale <= 1) {
+        return hullPoints;
+    }
+    // Scaling the vertices about the centroid scales every supporting plane's
+    // centroid-relative offset by the same factor, so containment is exact.
+    return hullPoints.map((point) => add(centroid, multiply(subtract(point, centroid), scale)));
+}
+function supportingPlanes(points, centroid) {
+    const planes = [];
+    for (let a = 0; a < points.length; a += 1) {
+        for (let b = a + 1; b < points.length; b += 1) {
+            for (let c = b + 1; c < points.length; c += 1) {
+                const normal = cross(subtract(points[b], points[a]), subtract(points[c], points[a]));
+                const length = Math.sqrt(dot(normal, normal));
+                if (length === 0) {
+                    continue;
+                }
+                const unit = multiply(normal, 1 / length);
+                for (const oriented of [unit, multiply(unit, -1)]) {
+                    const offset = dot(oriented, subtract(points[a], centroid));
+                    if (offset <= 0) {
+                        continue;
+                    }
+                    if (points.every((point) => dot(oriented, subtract(point, centroid)) <= offset + 1e-9)) {
+                        planes.push({ normal: oriented, offset });
+                    }
+                }
+            }
+        }
+    }
+    if (planes.length === 0) {
+        throw new Error('cookConvexDecomposition: hull reduction produced a degenerate (flat) hull');
+    }
+    return planes;
+}
+/** Vertices of `points` that survive on the convex boundary, in canonical order. */
+function boundaryVertices(points) {
+    if (points.length < RUNTIME_MIN_HULL_VERTICES) {
+        return points;
+    }
+    const centroid = meanPoint(points);
+    let planes;
+    try {
+        planes = supportingPlanes(points, centroid);
+    }
+    catch {
+        return points;
+    }
+    const kept = points.filter((point) => planes.some((plane) => Math.abs(dot(plane.normal, subtract(point, centroid)) - plane.offset) <= 1e-9));
+    return [...kept].sort(comparePoints);
+}
+// ---------- small vector helpers ----------
+function add(a, b) {
+    return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+}
+function subtract(a, b) {
+    return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+}
+function multiply(a, scalar) {
+    return { x: a.x * scalar, y: a.y * scalar, z: a.z * scalar };
+}
+function dot(a, b) {
+    return a.x * b.x + a.y * b.y + a.z * b.z;
+}
+function cross(a, b) {
+    return { x: a.y * b.z - a.z * b.y, y: a.z * b.x - a.x * b.z, z: a.x * b.y - a.y * b.x };
+}
+function meanPoint(points) {
+    let sum = { x: 0, y: 0, z: 0 };
+    for (const point of points) {
+        sum = add(sum, point);
+    }
+    return multiply(sum, 1 / points.length);
+}
+/** Quantize each axis away from `from`, so the point never moves inward. */
+function quantizeOutward(point, from, quantum) {
+    const axis = (value, origin) => (value >= origin ? Math.ceil(value / quantum) * quantum : Math.floor(value / quantum) * quantum);
+    return { x: axis(point.x, from.x), y: axis(point.y, from.y), z: axis(point.z, from.z) };
+}
+function quantizePoint(point, quantum) {
+    return {
+        x: Math.round(point.x / quantum) * quantum,
+        y: Math.round(point.y / quantum) * quantum,
+        z: Math.round(point.z / quantum) * quantum,
+    };
+}
+function dedupePoints(points) {
+    const sorted = [...points].sort(comparePoints);
+    const unique = [];
+    for (const point of sorted) {
+        const last = unique[unique.length - 1];
+        if (last === undefined || comparePoints(last, point) !== 0) {
+            unique.push(point);
+        }
+    }
+    return unique;
+}
+function requireIntegerInRange(value, low, high, name) {
+    if (!Number.isInteger(value) || value < low || value > high) {
+        throw new Error(`cookConvexDecomposition: ${name} must be an integer in [${low}, ${high}]`);
+    }
+    return value;
+}
+/**
+ * Internals exposed for direct testing. The cook's public entry only ever feeds
+ * these well-formed inputs, so their degenerate branches (collinear/coplanar
+ * point sets, unsplittable parts, the voxel-AABB fallback) are unreachable
+ * through `cookConvexDecomposition` alone.
+ */
+exports.__colliderCookingInternals = {
+    bestSplit,
+    boundaryVertices,
+    collinear,
+    convexHullLattice,
+    dedupePoints,
+    finalizeHull,
+    inflateToContain,
+    makePart,
+    reduceLatticeHull,
+    supportingPlanes,
+    triangleIntersectsBox,
+    voxelize,
+};