@driftengine/physics 3.61.0

package/dist/decompose.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A triangle mesh, offline, into a handful of convex hulls the runtime can carry on one body.
+ *
+ * **This is the only function in this package that is not meant to run in a frame**, and that is a
+ * statement about what it costs rather than about where it lives. It allocates three grids, walks
+ * every cell of them several times, and calls `hullShape` once per part. A bake does that; a tick
+ * does not. The convex-decomposition design records the
+ * refusal and what would reverse it.
+ *
+ * **It lives here anyway, beside `hullShape`, because that is what it produces.** The fixtures
+ * `scripts/size-gate.test.mjs` measures import named symbols and this package is `sideEffects:
+ * false`, so a consumer who never calls this never bundles it — which is measured by `physics-only`
+ * staying where it is rather than asserted here.
+ *
+ * **Why a voxel grid and not the triangles.** A collision mesh is a triangle soup: it is routinely
+ * not watertight, routinely self-intersecting, and routinely has a hole where an artist deleted a
+ * face nobody would see. Every decomposition that reasons over the source triangles has to decide
+ * what the inside of such a thing is, and gets it wrong in a way that depends on the mesh. A grid
+ * with a flood fill from the outside answers that question once, the same way, for any input — and
+ * its cost is set by the resolution rather than by the triangle count, so a 200,000-triangle
+ * collision mesh decomposes in the time a 2,000-triangle one does.
+ *
+ * **What it gives up** is everything below the cell size: a plate thinner than one cell either
+ * disappears or becomes a cell thick. `resolution` is the control, and `Decomposition.resolution`
+ * reports what was actually used so a caller who passed nothing can see it.
+ */
+/** How the interior of the mesh is decided. See `DecomposeOptions.fill`. */
+export type DecomposeFill = 'solid' | 'surface';
+export interface DecomposeOptions {
+    /**
+     * Cells along the longest axis of the mesh's bounds. Default 64, refused above 256.
+     *
+     * **The cap is stated because the alternative is discovering it as an allocation failure.** Two
+     * grids are held, a byte of state and four bytes of region index per cell, so 256 is 16.8 million
+     * cells and **83.9 MB**. 64 is 262,144 cells and 1.3 MB, which is the design point.
+     */
+    readonly resolution?: number;
+    /** How many hulls to stop at. Default 16, refused above `MAX_BODY_PARTS`. */
+    readonly maxHulls?: number;
+    /**
+     * How empty a merged region's bounding box may be before the merge stops being free. Default 0.05.
+     *
+     * It does not cap the part count: merging continues past this while more than `maxHulls` regions
+     * remain, because a caller asked for a body that a body can be made of. Below that count it is
+     * what decides whether two neighbours are worth keeping apart.
+     */
+    readonly concavity?: number;
+    /**
+     * `'solid'` fills the interior, `'surface'` keeps the shell alone. Default `'solid'`.
+     *
+     * **A mesh with a hole in it leaks under `'solid'`, and the fill has no way to know.** The flood
+     * escapes through the hole, nothing is left marked inside, and the result is the shell — which is
+     * very nearly harmless for collision, because contact only ever touches the boundary, and wrong
+     * for mass, because a hollow solid has the wrong inertia. `Decomposition.sourceVolume` is the
+     * voxelised volume, so the hollow is visible in the number; `'surface'` is how a caller asks for
+     * it deliberately.
+     */
+    readonly fill?: DecomposeFill;
+}
+/** One convex piece of the decomposition, ready for `hullShape`. */
+export interface ConvexPart {
+    /** xyz-packed, at most `SUPPORT_DIRECTIONS` points, in the source mesh's own space. */
+    readonly points: Float32Array;
+    /** The hull's volume, exactly, by the tetrahedral decomposition `mass.ts` already computes. */
+    readonly volume: number;
+    /** Cells this part was grown from, as a fraction of its own hull volume. */
+    readonly fill: number;
+}
+export interface Decomposition {
+    readonly parts: readonly ConvexPart[];
+    /** The voxelised source's volume. What `bloat` is measured against. */
+    readonly sourceVolume: number;
+    /** The parts' volumes summed, which double-counts wherever two hulls overlap. */
+    readonly hullVolume: number;
+    /**
+     * `(hullVolume - sourceVolume) / sourceVolume`: the empty space the decomposition added.
+     *
+     * **The number that says whether the decomposition is worth having.** A single hull of a bowl has
+     * an enormous one; a decomposition that respects the cavity has a small one. It is not a bound on
+     * error in either direction — a hull can only add space, never remove it — which is why
+     * `coverage` is reported beside it.
+     */
+    readonly bloat: number;
+    /**
+     * The fraction of solid cells whose centre lies inside the part they were grown into.
+     *
+     * **Below one, and that is the support sampling of `SUPPORT_DIRECTIONS` showing up.** A support
+     * set is inscribed in the true hull of a region's corners, so a cell at a corner the direction set
+     * does not point at can fall outside by a little. It is the one place this function loses material
+     * rather than adding it.
+     */
+    readonly coverage: number;
+    /** The grid that was used, which a caller who passed no resolution wants to know. */
+    readonly resolution: number;
+    /** Cells in that grid, all three axes multiplied. */
+    readonly cells: number;
+}
+/** The default `maxHulls`, chosen so a decomposed body is well inside `MAX_BODY_PARTS`. */
+export declare const DEFAULT_MAX_HULLS = 16;
+/** The default and maximum grids. See `DecomposeOptions.resolution`. */
+export declare const DEFAULT_RESOLUTION = 64;
+export declare const MAX_RESOLUTION = 256;
+/** How many, which is also the most points any part can carry. */
+export declare const SUPPORT_DIRECTIONS: number;
+export declare function decomposeConvex(positions: ArrayLike<number>, indices: ArrayLike<number>, options?: DecomposeOptions): Decomposition;