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

package/dist/collider-cooking.d.ts

@@ -0,0 +1,141 @@
+import type { DeterministicPhysicsShape3D } from './physics3d.js';
+import type { Point3D } from './physics3d-shared.js';
+export interface ColliderSourceMesh {
+    /** Triangle-list vertices; `length` must be a positive multiple of 3. */
+    readonly vertices: readonly Point3D[];
+}
+export interface ColliderCookOptions {
+    /** Voxel grid resolution along the mesh's longest axis (4..96). */
+    readonly resolution?: number;
+    /** Upper bound on emitted hull children (1..64). */
+    readonly maxHulls?: number;
+    /** Vertex cap per emitted hull (8..16); 8 is the voxel-AABB fallback's size. */
+    readonly maxHullVertices?: number;
+    /** Stop splitting a part once `1 - partVolume/hullVolume` falls under this. */
+    readonly concavityTolerance?: number;
+    /** Output vertex quantum; must match the runtime's distance quantum or be coarser. */
+    readonly quantum?: number;
+    /** Candidate split planes evaluated per axis. */
+    readonly splitCandidates?: number;
+}
+export interface CookedColliderHull {
+    readonly vertexCount: number;
+    /** `1 - partVoxelVolume / hullVolume` for the part this hull covers. */
+    readonly concavity: number;
+}
+export interface CookedCollider {
+    readonly schemaVersion: 1;
+    readonly kind: 'deterministic-convex-decomposition';
+    readonly shape: Extract<DeterministicPhysicsShape3D, {
+        readonly type: 'compound';
+    }>;
+    readonly hulls: readonly CookedColliderHull[];
+    readonly sourceTriangles: number;
+    readonly resolution: number;
+    /** Volume-weighted mean concavity across the emitted hulls. */
+    readonly concavity: number;
+    readonly hash: string;
+}
+interface Lattice {
+    /** Grid dimensions in voxels. */
+    readonly nx: number;
+    readonly ny: number;
+    readonly nz: number;
+    readonly voxelSize: number;
+    readonly originX: number;
+    readonly originY: number;
+    readonly originZ: number;
+    /** Occupied voxel indices, ascending. */
+    readonly occupied: readonly number[];
+}
+/** A voxel-index subset of the lattice. */
+interface Part {
+    readonly voxels: readonly number[];
+    readonly hull: LatticeHull;
+    readonly concavity: number;
+}
+/** Convex hull in corner-lattice integer coordinates. */
+interface LatticeHull {
+    readonly vertices: readonly (readonly [number, number, number])[];
+    readonly faces: readonly (readonly [number, number, number])[];
+    /** Exact hull volume in corner-lattice units (voxel = 1 unit³). */
+    readonly volume: number;
+}
+export declare function cookConvexDecomposition(source: ColliderSourceMesh, options?: ColliderCookOptions): CookedCollider;
+/**
+ * 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.
+ */
+export declare function assertCookedColliderIsRuntimeValid(cooked: CookedCollider): void;
+declare function voxelize(triangles: readonly (readonly [Point3D, Point3D, Point3D])[], resolution: number): Lattice;
+/**
+ * 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".
+ */
+declare function triangleIntersectsBox(triangle: readonly [Point3D, Point3D, Point3D], center: Point3D, half: number): boolean;
+declare function makePart(voxels: readonly number[], lattice: Lattice): Part;
+declare function bestSplit(part: Part, lattice: Lattice, splitCandidates: number): readonly [Part, Part] | undefined;
+type IVec = readonly [number, number, number];
+/**
+ * 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.
+ */
+declare function convexHullLattice(points: readonly IVec[]): LatticeHull;
+declare function collinear(a: IVec, b: IVec, c: IVec): boolean;
+declare function finalizeHull(part: Part, lattice: Lattice, maxHullVertices: number, quantum: number): readonly Point3D[];
+/**
+ * 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.
+ */
+declare function reduceLatticeHull(hull: LatticeHull, maxHullVertices: number): readonly IVec[];
+/**
+ * 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.
+ */
+declare function inflateToContain(hullPoints: readonly Point3D[], mustContain: readonly Point3D[]): readonly Point3D[];
+interface SupportPlane {
+    readonly normal: Point3D;
+    /** Signed distance from the centroid to the plane; always > 0. */
+    readonly offset: number;
+}
+declare function supportingPlanes(points: readonly Point3D[], centroid: Point3D): readonly SupportPlane[];
+/** Vertices of `points` that survive on the convex boundary, in canonical order. */
+declare function boundaryVertices(points: readonly Point3D[]): readonly Point3D[];
+declare function dedupePoints(points: readonly Point3D[]): readonly Point3D[];
+/**
+ * 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.
+ */
+export declare const __colliderCookingInternals: {
+    bestSplit: typeof bestSplit;
+    boundaryVertices: typeof boundaryVertices;
+    collinear: typeof collinear;
+    convexHullLattice: typeof convexHullLattice;
+    dedupePoints: typeof dedupePoints;
+    finalizeHull: typeof finalizeHull;
+    inflateToContain: typeof inflateToContain;
+    makePart: typeof makePart;
+    reduceLatticeHull: typeof reduceLatticeHull;
+    supportingPlanes: typeof supportingPlanes;
+    triangleIntersectsBox: typeof triangleIntersectsBox;
+    voxelize: typeof voxelize;
+};
+export {};