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

package/dist/cjs/physics3d-hull.js

@@ -0,0 +1,381 @@
+"use strict";
+/**
+ * Deterministic convex-hull preprocessing for the rigid-body solver.
+ *
+ * Given ≤ 16 local-space vertices, this builds the outward face planes (with
+ * CCW-ordered polygons) and the unique edge directions the SAT narrow phase
+ * needs. It uses exhaustive supporting-plane enumeration over vertex triples
+ * (C(16,3) = 560 candidates — trivial), never a quickhull, so the result is a
+ * pure deterministic function of the input with lexicographic tie-breaking.
+ *
+ * Numeric regime: add/mul/cmp plus `solverSqrt` for the final unit normals only.
+ * No transcendentals (banned in src/ by the static determinism checker).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSolverHull = buildSolverHull;
+exports.rayHullIntervalLocal = rayHullIntervalLocal;
+exports.closestPointOnHullLocal = closestPointOnHullLocal;
+const physics3d_shared_js_1 = require("./physics3d-shared.js");
+const PLANE_TOL = 1e-9;
+const COPLANAR_TOL = 1e-6;
+const DEDUP_TOL2 = 1e-12;
+const EDGE_TOL = 1e-6;
+function lexCompare(a, b) {
+    if (a.x !== b.x) {
+        return a.x < b.x ? -1 : 1;
+    }
+    if (a.y !== b.y) {
+        return a.y < b.y ? -1 : 1;
+    }
+    if (a.z !== b.z) {
+        return a.z < b.z ? -1 : 1;
+    }
+    return 0;
+}
+function dedupSorted(input) {
+    const sorted = [...input].sort(lexCompare);
+    const out = [];
+    for (const v of sorted) {
+        const last = out[out.length - 1];
+        if (last !== undefined) {
+            const dx = v.x - last.x;
+            const dy = v.y - last.y;
+            const dz = v.z - last.z;
+            if (dx * dx + dy * dy + dz * dz <= DEDUP_TOL2) {
+                continue;
+            }
+        }
+        out.push({ x: v.x, y: v.y, z: v.z });
+    }
+    return out;
+}
+function isFinitePoint(v) {
+    return Number.isFinite(v.x) && Number.isFinite(v.y) && Number.isFinite(v.z);
+}
+/**
+ * Order the on-plane vertex indices CCW around `normal` (right-hand rule) using
+ * a signed-angle comparator built from cross/dot sign tests only — no atan2.
+ * The polygon is convex, so all points share a consistent winding relative to
+ * the centroid; we sort by half-plane then by cross-product sign.
+ */
+function orderFaceVerts(indices, verts, normal) {
+    /* istanbul ignore next -- a supporting-plane face always carries at least three vertices. */
+    if (indices.length <= 2) {
+        return [...indices];
+    }
+    let cx = 0;
+    let cy = 0;
+    let cz = 0;
+    for (const i of indices) {
+        cx += verts[i].x;
+        cy += verts[i].y;
+        cz += verts[i].z;
+    }
+    const inv = 1 / indices.length;
+    const center = { x: cx * inv, y: cy * inv, z: cz * inv };
+    // Build an orthonormal basis (u, w) spanning the face plane.
+    const ref = (0, physics3d_shared_js_1.subVec3)(verts[indices[0]], center);
+    const refLen = (0, physics3d_shared_js_1.solverSqrt)((0, physics3d_shared_js_1.dotVec3)(ref, ref));
+    /* istanbul ignore next -- a face vertex never coincides with its own face centroid, so refLen is always positive. */
+    const u = refLen > EDGE_TOL ? (0, physics3d_shared_js_1.scaleVec3)(ref, 1 / refLen) : orthonormalAny(normal);
+    const w = (0, physics3d_shared_js_1.crossVec3)(normal, u);
+    const key = (i) => {
+        const d = (0, physics3d_shared_js_1.subVec3)(verts[i], center);
+        const s = (0, physics3d_shared_js_1.dotVec3)(d, w);
+        const c = (0, physics3d_shared_js_1.dotVec3)(d, u);
+        // half 0 for upper (s>=0), 1 for lower — upper sweeps first for CCW order.
+        return { half: s >= 0 ? 0 : 1, s, c };
+    };
+    return [...indices].sort((ia, ib) => {
+        const a = key(ia);
+        const b = key(ib);
+        if (a.half !== b.half) {
+            return a.half - b.half;
+        }
+        // Within a half-plane, angle increases as (c descending) via cross sign:
+        // cross of the two direction vectors' sign gives relative order.
+        const da = (0, physics3d_shared_js_1.subVec3)(verts[ia], center);
+        const db = (0, physics3d_shared_js_1.subVec3)(verts[ib], center);
+        const cr = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.crossVec3)(da, db), normal);
+        if (cr > EDGE_TOL) {
+            return -1;
+        }
+        /* istanbul ignore else -- an exact cross-product tie needs two same-half face vertices antipodal through the centroid; no convex face produces one (searched over cube + 4/6/8-gon prisms at four phases). The index tie-break stays as the determinism guarantee. */
+        if (cr < -EDGE_TOL) {
+            return 1;
+        }
+        /* istanbul ignore next -- see above: the exact tie is unreachable, the tie-break stays for determinism. */
+        return ia - ib;
+    });
+}
+/* istanbul ignore next -- only reachable from the unreachable refLen guard in orderFaceVerts. */
+function orthonormalAny(n) {
+    const ax = Math.abs(n.x);
+    const ay = Math.abs(n.y);
+    const az = Math.abs(n.z);
+    const pick = ax <= ay && ax <= az ? { x: 1, y: 0, z: 0 } : ay <= az ? { x: 0, y: 1, z: 0 } : { x: 0, y: 0, z: 1 };
+    const proj = (0, physics3d_shared_js_1.dotVec3)(pick, n);
+    const t = (0, physics3d_shared_js_1.subVec3)(pick, (0, physics3d_shared_js_1.scaleVec3)(n, proj));
+    const len = (0, physics3d_shared_js_1.solverSqrt)((0, physics3d_shared_js_1.dotVec3)(t, t));
+    return len > EDGE_TOL ? (0, physics3d_shared_js_1.scaleVec3)(t, 1 / len) : { x: 1, y: 0, z: 0 };
+}
+function buildHullUncached(vertices) {
+    if (vertices.length < 4 || vertices.length > 16) {
+        throw new Error(`hull requires 4-16 finite vertices with non-zero volume, received ${vertices.length}`);
+    }
+    for (const v of vertices) {
+        if (!isFinitePoint(v)) {
+            throw new Error('hull requires 4-16 finite vertices with non-zero volume, received non-finite vertex');
+        }
+    }
+    const verts = dedupSorted(vertices);
+    if (verts.length < 4) {
+        throw new Error('hull requires 4-16 finite vertices with non-zero volume, received degenerate vertex set');
+    }
+    const n = verts.length;
+    let cx = 0;
+    let cy = 0;
+    let cz = 0;
+    for (const v of verts) {
+        cx += v.x;
+        cy += v.y;
+        cz += v.z;
+    }
+    const centroid = { x: cx / n, y: cy / n, z: cz / n };
+    // Enumerate every triple as a candidate supporting plane.
+    const candidates = [];
+    for (let i = 0; i < n; i += 1) {
+        for (let j = i + 1; j < n; j += 1) {
+            for (let k = j + 1; k < n; k += 1) {
+                const e1 = (0, physics3d_shared_js_1.subVec3)(verts[j], verts[i]);
+                const e2 = (0, physics3d_shared_js_1.subVec3)(verts[k], verts[i]);
+                const cr = (0, physics3d_shared_js_1.crossVec3)(e1, e2);
+                const len2 = (0, physics3d_shared_js_1.dotVec3)(cr, cr);
+                if (len2 < PLANE_TOL * PLANE_TOL) {
+                    continue; // collinear triple
+                }
+                const invLen = 1 / (0, physics3d_shared_js_1.solverSqrt)(len2);
+                let nx = cr.x * invLen;
+                let ny = cr.y * invLen;
+                let nz = cr.z * invLen;
+                let offset = nx * verts[i].x + ny * verts[i].y + nz * verts[i].z;
+                // Orient outward: centroid must lie behind the plane (dot < offset).
+                const centroidDot = nx * centroid.x + ny * centroid.y + nz * centroid.z;
+                if (centroidDot > offset) {
+                    nx = -nx;
+                    ny = -ny;
+                    nz = -nz;
+                    offset = -offset;
+                }
+                // Keep iff all vertices lie on or behind the plane.
+                let supporting = true;
+                const onPlane = [];
+                for (let m = 0; m < n; m += 1) {
+                    const d = nx * verts[m].x + ny * verts[m].y + nz * verts[m].z - offset;
+                    if (d > PLANE_TOL) {
+                        supporting = false;
+                        break;
+                    }
+                    if (d >= -PLANE_TOL) {
+                        onPlane.push(m);
+                    }
+                }
+                if (supporting && onPlane.length >= 3) {
+                    candidates.push({ nx, ny, nz, offset, onPlane });
+                }
+            }
+        }
+    }
+    // Merge coplanar candidates (same oriented plane within tolerance).
+    const faces = [];
+    const usedVerts = new Array(n).fill(false);
+    for (const cand of candidates) {
+        const existing = faces.find((f) => Math.abs(f.normal.x - cand.nx) <= COPLANAR_TOL
+            && Math.abs(f.normal.y - cand.ny) <= COPLANAR_TOL
+            && Math.abs(f.normal.z - cand.nz) <= COPLANAR_TOL
+            && Math.abs(f.offset - cand.offset) <= COPLANAR_TOL);
+        if (existing !== undefined) {
+            continue;
+        }
+        const merged = new Set(cand.onPlane);
+        for (let m = 0; m < n; m += 1) {
+            const d = cand.nx * verts[m].x + cand.ny * verts[m].y + cand.nz * verts[m].z - cand.offset;
+            if (d >= -PLANE_TOL && d <= PLANE_TOL) {
+                merged.add(m);
+            }
+        }
+        const normal = { x: cand.nx, y: cand.ny, z: cand.nz };
+        const ordered = orderFaceVerts([...merged], verts, normal);
+        for (const idx of ordered) {
+            usedVerts[idx] = true;
+        }
+        faces.push({ normal, offset: cand.offset, verts: ordered });
+    }
+    if (faces.length < 4) {
+        throw new Error('hull requires 4-16 finite vertices with non-zero volume, received coplanar vertex set');
+    }
+    for (let m = 0; m < n; m += 1) {
+        if (!usedVerts[m]) {
+            throw new Error('hull requires all vertices on the convex boundary, received interior vertex');
+        }
+    }
+    // Sort faces deterministically by outward normal then offset.
+    /* istanbul ignore next -- two faces of a convex hull never share a normal, so the offset tie-break never runs; it stays as the determinism guarantee. */
+    faces.sort((a, b) => lexCompare(a.normal, b.normal) || (a.offset < b.offset ? -1 : a.offset > b.offset ? 1 : 0));
+    // Unique undirected edge directions from face polygon edges.
+    const edgeDirs = [];
+    for (const face of faces) {
+        const fv = face.verts;
+        for (let e = 0; e < fv.length; e += 1) {
+            const a = verts[fv[e]];
+            const b = verts[fv[(e + 1) % fv.length]];
+            let dir = (0, physics3d_shared_js_1.subVec3)(b, a);
+            const len = (0, physics3d_shared_js_1.solverSqrt)((0, physics3d_shared_js_1.dotVec3)(dir, dir));
+            /* istanbul ignore next -- dedupSorted removes coincident vertices, so no face edge is degenerate. */
+            if (len <= EDGE_TOL) {
+                continue;
+            }
+            dir = (0, physics3d_shared_js_1.scaleVec3)(dir, 1 / len);
+            // Canonical sign: first non-zero component positive.
+            if (dir.x < -EDGE_TOL || (Math.abs(dir.x) <= EDGE_TOL && (dir.y < -EDGE_TOL || (Math.abs(dir.y) <= EDGE_TOL && dir.z < 0)))) {
+                dir = (0, physics3d_shared_js_1.scaleVec3)(dir, -1);
+            }
+            const dup = edgeDirs.some((d) => Math.abs(d.x - dir.x) <= EDGE_TOL && Math.abs(d.y - dir.y) <= EDGE_TOL && Math.abs(d.z - dir.z) <= EDGE_TOL);
+            if (!dup) {
+                edgeDirs.push(dir);
+            }
+        }
+    }
+    edgeDirs.sort(lexCompare);
+    return { vertices: verts, faces, edgeDirs };
+}
+// Memoize by vertex-array identity: hull topology is a pure derived function of
+// the immutable input vertex list (same rationale as quatMat3Cache) — never
+// canonical rollback state, so it is safe to keep outside the frame.
+// rdm-ignore-next-line determinism/no-module-mutable-state: pure derived hull data keyed by immutable input identity
+const hullCache = new WeakMap();
+function buildSolverHull(vertices) {
+    const cached = hullCache.get(vertices);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const built = buildHullUncached(vertices);
+    hullCache.set(vertices, built);
+    return built;
+}
+/**
+ * Ray-vs-hull interval clip in hull-local space. Returns the [tEnter, tExit]
+ * parameter interval where the ray lies inside all half-spaces, or undefined
+ * when the ray misses. When the origin is inside the hull, tEnter < 0; callers
+ * clamp the reported hit distance to 0 (matching sphere/AABB inside-ray semantics).
+ */
+function rayHullIntervalLocal(origin, dir, hull) {
+    let tEnter = -Infinity;
+    let tExit = Infinity;
+    let enterNormal = { x: 0, y: 1, z: 0 };
+    for (const face of hull.faces) {
+        const nd = face.normal.x * dir.x + face.normal.y * dir.y + face.normal.z * dir.z;
+        const dist = face.offset - (face.normal.x * origin.x + face.normal.y * origin.y + face.normal.z * origin.z);
+        // Half-space: dot(n, origin + t·dir) <= offset  ⇔  t·nd <= dist
+        if (Math.abs(nd) < 1e-12) {
+            if (dist < 0) {
+                return undefined; // parallel and outside this face
+            }
+            continue;
+        }
+        const t = dist / nd;
+        if (nd < 0) {
+            // entering this half-space at t
+            if (t > tEnter) {
+                tEnter = t;
+                enterNormal = face.normal;
+            }
+        }
+        else if (t < tExit) {
+            tExit = t;
+        }
+        if (tEnter > tExit) {
+            return undefined;
+        }
+    }
+    if (tExit < 0) {
+        return undefined;
+    }
+    return { tEnter, tExit, enterNormal };
+}
+/**
+ * Closest point on (or inside) the hull to `point`, in hull-local space, plus
+ * the deepest-violated face normal and its signed distance (positive outside).
+ * When the point is inside every face, `inside` is true and the closest point
+ * is `point` itself.
+ */
+function closestPointOnHullLocal(point, hull) {
+    let maxDist = -Infinity;
+    let maxFace = hull.faces[0];
+    for (const face of hull.faces) {
+        const d = face.normal.x * point.x + face.normal.y * point.y + face.normal.z * point.z - face.offset;
+        if (d > maxDist) {
+            maxDist = d;
+            maxFace = face;
+        }
+    }
+    if (maxDist <= 0) {
+        return { point: { x: point.x, y: point.y, z: point.z }, inside: true, normal: maxFace.normal, distance: maxDist };
+    }
+    // Outside: project onto the deepest-violated face polygon (clamped to it),
+    // which is the exact closest point for points beyond a single face and a good
+    // deterministic approximation near edges/corners (refined by clamping).
+    const projected = projectOntoFacePolygon(point, hull, maxFace);
+    return { point: projected, inside: false, normal: maxFace.normal, distance: maxDist };
+}
+function projectOntoFacePolygon(point, hull, face) {
+    const d = face.normal.x * point.x + face.normal.y * point.y + face.normal.z * point.z - face.offset;
+    const onPlane = {
+        x: point.x - face.normal.x * d,
+        y: point.y - face.normal.y * d,
+        z: point.z - face.normal.z * d,
+    };
+    // If the projection is inside the face polygon, that is the closest point.
+    const fv = face.verts;
+    let insidePolygon = true;
+    for (let e = 0; e < fv.length; e += 1) {
+        const a = hull.vertices[fv[e]];
+        const b = hull.vertices[fv[(e + 1) % fv.length]];
+        const edge = (0, physics3d_shared_js_1.subVec3)(b, a);
+        const toPoint = (0, physics3d_shared_js_1.subVec3)(onPlane, a);
+        const c = (0, physics3d_shared_js_1.crossVec3)(edge, toPoint);
+        if ((0, physics3d_shared_js_1.dotVec3)(c, face.normal) < -EDGE_TOL) {
+            insidePolygon = false;
+            break;
+        }
+    }
+    if (insidePolygon) {
+        return onPlane;
+    }
+    // Otherwise clamp to the nearest polygon edge segment.
+    let best = hull.vertices[fv[0]];
+    let bestDist2 = Infinity;
+    for (let e = 0; e < fv.length; e += 1) {
+        const a = hull.vertices[fv[e]];
+        const b = hull.vertices[fv[(e + 1) % fv.length]];
+        const cand = closestPointOnSegmentLocal(point, a, b);
+        const dd = (0, physics3d_shared_js_1.subVec3)(cand, point);
+        const dist2 = (0, physics3d_shared_js_1.dotVec3)(dd, dd);
+        if (dist2 < bestDist2) {
+            bestDist2 = dist2;
+            best = cand;
+        }
+    }
+    return best;
+}
+function closestPointOnSegmentLocal(point, a, b) {
+    const ab = (0, physics3d_shared_js_1.subVec3)(b, a);
+    const denom = (0, physics3d_shared_js_1.dotVec3)(ab, ab);
+    /* istanbul ignore next -- hull edges are never degenerate (dedupSorted). */
+    if (denom === 0) {
+        return { x: a.x, y: a.y, z: a.z };
+    }
+    let t = (0, physics3d_shared_js_1.dotVec3)((0, physics3d_shared_js_1.subVec3)(point, a), ab) / denom;
+    t = t < 0 ? 0 : t > 1 ? 1 : t;
+    return (0, physics3d_shared_js_1.addVec3)(a, (0, physics3d_shared_js_1.scaleVec3)(ab, t));
+}