@driftengine/physics 3.61.0

package/dist/shape.d.ts

@@ -0,0 +1,177 @@
+import type { Aabb } from './collide/index.ts';
+import type { TriangleMesh } from './meshShape.ts';
+/**
+ * Convex collision shapes: the volume an element actually occupies, rather than
+ * a world-axis box around it.
+ *
+ * One representation covers every convex solid — a point cloud plus two kinds of
+ * rounding. A box is its eight corners; a sphere is one point and a radius; a
+ * stretch of banked track is its own drawn cross-sections, so the geometry a
+ * player sees is the geometry that stops them. Face normals and edge directions
+ * are enumerated once, at build time, because they are the separating-axis
+ * candidates the sweep in `collide.ts` tests — a fixed, data-driven axis list
+ * per shape pair is what lets two machines replay the same run bit for bit,
+ * where an iterate-to-tolerance method would not.
+ *
+ * **Two kinds of rounding rather than one, as of 2026-08-27.** `radius` grows a
+ * shape by a ball and is what makes a sphere and a capsule; `sideRadius` grows
+ * it by a disc perpendicular to the segment through its first two points, and is
+ * what makes a cylinder. The second exists because the first cannot express a
+ * cylinder at all: a uniform radius rounds the rim along with the side, and the
+ * rim is what a wheel rolls on. Everything that consumes a shape reads both, and
+ * a shape carrying neither is a plain polytope, which is most of them.
+ *
+ * Build-time only: nothing here may be called per frame or per tick. The hull
+ * builder is O(n^4) in the point count — trivial for the intended n (a slab is
+ * 8–16 points, a body part 8), wrong for a render mesh, hence the cap. Shapes
+ * come from the few points that *define* an element, not from its triangles.
+ */
+export interface ConvexShape {
+    /**
+     * xyz-packed points whose convex hull is the shape. Local space for a body's
+     * shape, world space for a static collider's — the sweep never needs to know
+     * which, because bodies carry a frame and colliders are baked.
+     */
+    readonly vertices: Float32Array;
+    /** xyz-packed unit face normals, one per direction (a line: n and −n once). */
+    readonly faceNormals: Float32Array;
+    /** xyz-packed unit edge directions, one per direction. */
+    readonly edgeDirs: Float32Array;
+    /** Rounding grown around the points — a sphere is one point and this. */
+    readonly radius: number;
+    /**
+     * Rounding grown around the points **only perpendicular to the segment through them**, in
+     * metres. Zero for everything but a cylinder, which is what it exists for.
+     *
+     * `radius` grows a shape uniformly, which is why it cannot express a cylinder: it would round
+     * the rim as well as the side. This one grows a shape by a disc rather than by a ball, so the
+     * two points of `cylinderShape` become two flat cap discs joined by a curved side, with a sharp
+     * rim between them. The two are independent and compose — a shape with both is a cylinder with
+     * a filleted rim — and every constructor but `cylinderShape` leaves this at zero.
+     *
+     * The axis is the shape's own first two points, not a stored vector, so a cylinder baked into
+     * world space by a collider carries its orientation the same way its position is carried.
+     */
+    readonly sideRadius: number;
+    /** Distance from the local origin enclosing the whole shape, for broad bounds. */
+    readonly boundRadius: number;
+    /**
+     * xyzw-packed outward face planes, four floats per face: normal then offset, so a point `p` lies
+     * on the face when `dot(n, p) === d`.
+     *
+     * **One entry per face, where `faceNormals` has one per direction.** A box has six here and three
+     * there, and they are separate arrays because conflating them is what left the gap: SAT wants
+     * directions, while clipping and an inertia tensor want faces. Empty for a shape with no faces.
+     */
+    readonly facePlanes: Float32Array;
+    /** CSR offsets into `faceVertexIndices`, length `faceCount + 1`. Empty when there are no faces. */
+    readonly faceVertexStart: Uint16Array;
+    /** Vertex indices, each face's loop wound counter-clockwise seen from outside. */
+    readonly faceVertexIndices: Uint16Array;
+    /**
+     * A **static triangle mesh**, where this shape is one, or absent where it is a convex solid.
+     *
+     * **The one thing in this file that is not convex, and it is a field rather than a second type
+     * on purpose.** A union would put a narrowing at every call site that takes a shape — the broad
+     * phase, the bounds, the collider set, the sweep, the mass, the queries, the cloth — for a shape
+     * only the narrow phase and the raycast can act on, and every one of those narrowings would be a
+     * place to forget one. A discriminating field is what `sideRadius` already is, one line up, and
+     * this reads the same way: the shape carries what it is and the two places that care ask.
+     *
+     * A mesh's `vertices` are the eight corners of its bounding box, so everything that measures a
+     * shape measures the right box; its `faceNormals` and `edgeDirs` are **empty**, so nothing
+     * mistakes a hollow level for a solid brick. See `meshShape`.
+     */
+    readonly triangles?: TriangleMesh;
+}
+/** The exact shape `MeshBuilder.addBox` draws: eight corners, three axes. */
+export declare function boxShape(hx: number, hy: number, hz: number): ConvexShape;
+/** A ball: one point, all radius. It separates on other shapes' features. */
+export declare function sphereShape(radius: number): ConvexShape;
+/**
+ * A capsule: a segment along y with a rounding radius.
+ *
+ * **No new representation.** Point-cloud-plus-radius already expresses a capsule exactly, so this
+ * is a named constructor over `hullShape` rather than a shape type. A named thing is discoverable
+ * and an idiom is not. It stands along y because that is the axis a character capsule uses, and a
+ * rotation nobody has to apply is a rotation nobody gets wrong.
+ *
+ * At `halfHeight` zero the two points dedupe to one and the result *is* a sphere, which is the
+ * right degenerate case rather than an error.
+ *
+ * **A cylinder is a different shape and has its own constructor**, `cylinderShape` below. The
+ * rounding radius here grows uniformly around every feature, so applying it to a segment can only
+ * ever give a capsule: it would round a cylinder's rim as well as its side. `sideRadius` is the
+ * field that expresses the difference, and it was added on 2026-08-27 with the second condition
+ * this file had been recording — a wheel rim, a rolling barrel — as its reason.
+ *
+ * The advice until then was "build one as an n-gon prism with `hullShape` and accept the facets",
+ * and it had a measured ceiling: `hullShape` refuses more than 64 points, a prism spends two a
+ * side, so thirty-two sides was the wall, and a thirty-two-sided wheel of radius 1 rolling at
+ * 6 m/s bobbed 16 mm that no side count could reduce. `prismRoll.test.ts` still measures that,
+ * beside the same wheel built as a cylinder, because the comparison is the reason the shape kind
+ * exists.
+ */
+export declare function capsuleShape(radius: number, halfHeight: number): ConvexShape;
+/**
+ * A cylinder: a segment along y, grown by a disc rather than by a ball.
+ *
+ * **The one shape a point cloud plus a rounding radius cannot express**, and the reason it needed
+ * a second kind of rounding rather than a second shape type. `radius` grows a shape uniformly, so
+ * applying it to a segment gives a capsule; `sideRadius` grows it only perpendicular to that
+ * segment, which gives two flat cap discs, a curved side, and a sharp rim between them. That rim
+ * is the whole difference, and it is what a wheel rolls on.
+ *
+ * **What this replaces is an n-gon prism with a measured floor.** `prismRoll.test.ts` had the
+ * numbers: `hullShape` refuses more than 64 points, a prism spends two a side, so thirty-two sides
+ * was the wall, and a thirty-two-sided wheel of radius 1 rolling at 6 m/s bobbed **16 mm** — which
+ * no side count could reduce. A cylinder's support along any direction perpendicular to its axis
+ * is exactly `sideRadius`, at every angle, so the same wheel bobs by nothing at all. The same test
+ * file now measures both and compares them.
+ *
+ * It stands along y for `capsuleShape`'s reason: a rotation nobody has to apply is a rotation
+ * nobody gets wrong. A wheel wants its axis across the vehicle, and the body carries a quaternion
+ * for exactly that. A static collider baked into world space carries its axis in its own two
+ * points, so nothing stores a direction that could disagree with them.
+ *
+ * **`halfHeight` must be positive**, unlike `capsuleShape`, whose zero case degenerates into a
+ * sphere and is right. A cylinder of zero height is a disc: a shape with no interior, whose mass
+ * properties are zero and whose contact normal is undefined on its rim. Refused rather than
+ * silently produced.
+ */
+export declare function cylinderShape(radius: number, halfHeight: number): ConvexShape;
+/**
+ * The convex hull of a point cloud, with its separating features enumerated.
+ *
+ * Brute force by design: every point triple proposes a plane, and a plane with
+ * every point on one side is a face. Edges are point pairs lying on two
+ * distinct faces. No incremental hull, no floating-point pivoting — the same
+ * input yields the same features in the same order on every machine, which the
+ * replay contract needs from anything that feeds collision.
+ *
+ * **Every length here is `Math.sqrt` of a sum of squares rather than `Math.hypot`**, and that is
+ * what makes the sentence above true rather than merely intended. ECMAScript declines to specify
+ * `hypot` precisely, so two engines may differ by an ulp — and an ulp here is not a slightly
+ * different axis. `proposePlane`'s normal classifies every point against `COPLANAR_M`, so it
+ * decides whether a plane becomes a face at all; `appendDirection`'s is compared against
+ * `DIR_DEDUP`, so it decides how many separating axes exist and in what order. SAT then takes a
+ * minimum over that list.
+ *
+ * `hypot` is the more accurate of the two, guarding against intermediate overflow at magnitudes a
+ * collision shape does not reach. **What would make this wrong** is a shape built at astronomical
+ * or atomic scale, where that guard is worth more than the reproducibility; the answer then is an
+ * explicit rescale rather than the call back. Asserted by `scripts/determinism.test.mjs`.
+ */
+export declare function hullShape(points: ArrayLike<number>, radius?: number): ConvexShape;
+/**
+ * World-axis bounds of a shape as placed (its points are its placement).
+ *
+ * **`radius` and `sideRadius` grow the box differently, and the second one is not `sideRadius` on
+ * every axis.** A ball grows a box by its radius along all three; a disc perpendicular to a unit
+ * axis `a` grows it by `sideRadius * sqrt(1 - a[i]^2)` along axis `i` — the disc's own extent seen
+ * down that axis, which is the full radius across the axis and exactly nothing along it. Using
+ * `sideRadius` on all three instead would bound a lying cylinder as if it were a sphere, which is
+ * conservative and therefore not wrong, and would cost the broad phase the difference on every
+ * cylinder in the world.
+ */
+export declare function shapeBounds(shape: ConvexShape, out: Aabb): Aabb;