@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/collide/serialize.js

@@ -0,0 +1,145 @@
+/**
+ * A built collider as bytes, so a level's BVH is baked once and loaded, not rebuilt on every
+ * start. Little-endian, versioned, typed arrays laid out whole; `userData` is not serialised
+ * (pass it to `importCollider` to reattach, by source index). Re-exporting an imported collider
+ * gives identical bytes.
+ */
+import { StaticCollider } from './bvh.js';
+const MAGIC = 0x54434f4c; // 'TCOL'
+const VERSION = 1;
+const HEADER_U32 = 8; // magic, version, leafSize, root, topCount, triCount, nodeCount, sourceCount
+const SOURCE_U32 = 8; // kind, start, count, root, nodeStart, nodeEnd, layer, flags (bit 0 removed, bit 1 has local)
+function align4(n) {
+    return (n + 3) & ~3;
+}
+/** Serialises `c` to a self-contained buffer. */
+export function exportCollider(c) {
+    const triCount = c.triSource.length;
+    const nodeCount = c.nodeLeaf.length;
+    let localFloats = 0;
+    for (const s of c.sources)
+        if (s.local)
+            localFloats += s.local.length;
+    const bytes = HEADER_U32 * 4 +
+        c.sources.length * SOURCE_U32 * 4 +
+        triCount * 9 * 4 +
+        triCount * 4 +
+        nodeCount * 3 * 4 * 2 +
+        align4(nodeCount) +
+        nodeCount * 4 * 2 +
+        localFloats * 4;
+    const buf = new ArrayBuffer(bytes);
+    const u32 = new Uint32Array(buf, 0, HEADER_U32 + c.sources.length * SOURCE_U32);
+    u32[0] = MAGIC;
+    u32[1] = VERSION;
+    u32[2] = c.leafSize;
+    u32[3] = c.root;
+    u32[4] = c.topCount;
+    u32[5] = triCount;
+    u32[6] = nodeCount;
+    u32[7] = c.sources.length;
+    let o = HEADER_U32;
+    for (const s of c.sources) {
+        u32[o++] = s.kind;
+        u32[o++] = s.start;
+        u32[o++] = s.count;
+        u32[o++] = s.root;
+        u32[o++] = s.nodeStart;
+        u32[o++] = s.nodeEnd;
+        u32[o++] = s.layer;
+        u32[o++] = (s.removed ? 1 : 0) | (s.local ? 2 : 0);
+    }
+    let byte = o * 4;
+    new Float32Array(buf, byte, triCount * 9).set(c.tris);
+    byte += triCount * 9 * 4;
+    new Uint32Array(buf, byte, triCount).set(c.triSource);
+    byte += triCount * 4;
+    new Float32Array(buf, byte, nodeCount * 3).set(c.nodeMin);
+    byte += nodeCount * 3 * 4;
+    new Float32Array(buf, byte, nodeCount * 3).set(c.nodeMax);
+    byte += nodeCount * 3 * 4;
+    new Uint8Array(buf, byte, nodeCount).set(c.nodeLeaf);
+    byte += align4(nodeCount);
+    new Int32Array(buf, byte, nodeCount).set(c.nodeA);
+    byte += nodeCount * 4;
+    new Int32Array(buf, byte, nodeCount).set(c.nodeB);
+    byte += nodeCount * 4;
+    for (const s of c.sources) {
+        if (!s.local)
+            continue;
+        new Float32Array(buf, byte, s.local.length).set(s.local);
+        byte += s.local.length * 4;
+    }
+    return buf;
+}
+/**
+ * Rebuilds a collider from `exportCollider` bytes. The arrays are copied out of `buf`, so it may
+ * be released. `userData[i]` is attached to source `i` when given.
+ */
+export function importCollider(buf, userData) {
+    if (buf.byteLength < HEADER_U32 * 4)
+        throw new Error('collide: buffer too short for a collider');
+    const head = new Uint32Array(buf, 0, HEADER_U32);
+    if (head[0] !== MAGIC)
+        throw new Error('collide: not a collider buffer');
+    if (head[1] !== VERSION)
+        throw new Error(`collide: unsupported collider version ${head[1]}`);
+    const leafSize = head[2];
+    const root = head[3];
+    const topCount = head[4];
+    const triCount = head[5];
+    const nodeCount = head[6];
+    const sourceCount = head[7];
+    const rec = new Uint32Array(buf, HEADER_U32 * 4, sourceCount * SOURCE_U32);
+    let byte = HEADER_U32 * 4 + sourceCount * SOURCE_U32 * 4;
+    const tris = new Float32Array(buf.slice(byte, byte + triCount * 9 * 4));
+    byte += triCount * 9 * 4;
+    const triSource = new Uint32Array(buf.slice(byte, byte + triCount * 4));
+    byte += triCount * 4;
+    const nodeMin = new Float32Array(buf.slice(byte, byte + nodeCount * 3 * 4));
+    byte += nodeCount * 3 * 4;
+    const nodeMax = new Float32Array(buf.slice(byte, byte + nodeCount * 3 * 4));
+    byte += nodeCount * 3 * 4;
+    const nodeLeaf = new Uint8Array(buf.slice(byte, byte + nodeCount));
+    byte += align4(nodeCount);
+    const nodeA = new Int32Array(buf.slice(byte, byte + nodeCount * 4));
+    byte += nodeCount * 4;
+    const nodeB = new Int32Array(buf.slice(byte, byte + nodeCount * 4));
+    byte += nodeCount * 4;
+    const sources = [];
+    for (let i = 0; i < sourceCount; i++) {
+        const o = i * SOURCE_U32;
+        const count = rec[o + 2];
+        const flags = rec[o + 7];
+        let local = null;
+        if (flags & 2) {
+            local = new Float32Array(buf.slice(byte, byte + count * 9 * 4));
+            byte += count * 9 * 4;
+        }
+        sources.push({
+            kind: rec[o],
+            start: rec[o + 1],
+            count,
+            root: rec[o + 3],
+            nodeStart: rec[o + 4],
+            nodeEnd: rec[o + 5],
+            layer: rec[o + 6],
+            removed: (flags & 1) !== 0,
+            local,
+            userData: userData?.[i],
+        });
+    }
+    return new StaticCollider({
+        tris,
+        triSource,
+        nodeMin,
+        nodeMax,
+        nodeLeaf,
+        nodeA,
+        nodeB,
+        root,
+        topCount,
+        sources,
+        leafSize,
+    });
+}

package/dist/geom/collide/shapes.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Collision shapes and the shape-vs-triangle tests the queries are built on. Every function is
+ * pure arithmetic over plain numbers: a triangle is its nine coordinates (so the collider's flat
+ * triangle array is read in place), the result goes into an `out` the caller owns, nothing here
+ * allocates.
+ */
+/** A sphere: centre and radius. */
+export interface Sphere {
+    x: number;
+    y: number;
+    z: number;
+    r: number;
+}
+/**
+ * A capsule along the y axis: centre, half the length of the inner segment (the distance from
+ * the centre to each hemisphere's centre) and the radius. Its total height is `2 × (halfHeight + r)`.
+ */
+export interface Capsule {
+    x: number;
+    y: number;
+    z: number;
+    halfHeight: number;
+    r: number;
+}
+/** An axis-aligned box: `min` and `max` corners (`[x, y, z]`). */
+export interface GeomAabb {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/** A circle in the xz plane (the 2D case). */
+export interface Circle {
+    x: number;
+    z: number;
+    r: number;
+}
+/** An axis-aligned rectangle in the xz plane: centre and half extents. */
+export interface Box2 {
+    x: number;
+    z: number;
+    hw: number;
+    hh: number;
+}
+/** Any 3D shape the queries take. */
+export type Shape = Sphere | Capsule | GeomAabb;
+/** Any 2D shape the `*2` queries take. */
+export type Shape2 = Circle | Box2;
+/** A 3-vector written in place. */
+export type Vec3Out = [number, number, number] | Float32Array | Float64Array;
+/**
+ * A touching or penetrating shape and triangle: `depth` is how far along the unit normal
+ * (`nx, ny, nz`, pointing from the triangle into the shape) the shape must move to separate;
+ * `px, py, pz` is the point on the triangle. `triangle` and `source` index the collider that
+ * produced it (-1 from the bare shape tests).
+ */
+export interface Contact {
+    depth: number;
+    nx: number;
+    ny: number;
+    nz: number;
+    px: number;
+    py: number;
+    pz: number;
+    triangle: number;
+    source: number;
+}
+/** A zeroed `Contact`, for the caller's preallocated arrays. */
+export declare function createContact(): Contact;
+export declare function isCapsule(s: Shape): s is Capsule;
+export declare function isAabb(s: Shape): s is GeomAabb;
+export declare function isBox2(s: Shape2): s is Box2;
+/** The current triangle: a, b, c as nine coordinates. */
+export declare const TRI: Float64Array<ArrayBuffer>;
+/** A point (0..2) or segment (0..2, 3..5). */
+export declare const SEG: Float64Array<ArrayBuffer>;
+/** Scalars: `R[0]` the squared distance of the last closest-point query; the rest internal. */
+export declare const R: Float64Array<ArrayBuffer>;
+/** The query point of `closestPointTri`; also the box centre of the box tests. */
+export declare const PT: Float64Array<ArrayBuffer>;
+/** Box state: half extents (0..2), triangle vertices relative to the box centre (3..11), axis (12..14). */
+export declare const BX: Float64Array<ArrayBuffer>;
+/**
+ * The query shape: kind (0), then for a sphere or capsule its centre (1..3), half height (4, 0
+ * for a sphere) and radius (5); for a box its min (1..3) and max (4..6). Queries read the shape
+ * from here, never from the caller's object: field loads from objects of varying layout box
+ * their doubles.
+ */
+export declare const SH: Float64Array<ArrayBuffer>;
+export declare const SH_SPHERE = 0;
+export declare const SH_CAPSULE = 1;
+export declare const SH_BOX = 2;
+/** Loads `s` into `SH`. */
+export declare function loadShape(s: Shape): void;
+/** Loads `TRI`. */
+export declare function loadTri(ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): void;
+/**
+ * The point of triangle `TRI` closest to `PT` (Ericson, Real-Time Collision Detection 5.1.5): the
+ * Voronoi region of the point decides between a vertex, an edge and the face. Writes `out`.
+ */
+export declare function closestPointTri(out: Vec3Out): void;
+/** The point of triangle `a, b, c` closest to `p`, into `out`; returns `out`. */
+export declare function closestPointTriangle(px: number, py: number, pz: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Vec3Out): Vec3Out;
+/** The unit normal of `TRI` (counter-clockwise front) into `out`; zero if degenerate. */
+export declare function triNormal(out: Vec3Out): void;
+/** The unit normal of triangle `a, b, c` (counter-clockwise front) into `out`; zero if degenerate. */
+export declare function triangleNormal(ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Vec3Out): Vec3Out;
+/**
+ * The closest points between segment `p0 p1` and segment `q0 q1`: writes the point on the first
+ * into `outP` and on the second into `outQ`, returns the squared distance.
+ */
+export declare function closestSegmentSegment(p0x: number, p0y: number, p0z: number, p1x: number, p1y: number, p1z: number, q0x: number, q0y: number, q0z: number, q1x: number, q1y: number, q1z: number, outP: Vec3Out, outQ: Vec3Out): number;
+/**
+ * The closest points between segment `SEG` and triangle `TRI`: the point on the segment into
+ * `outS`, the point on the triangle into `outT`, the squared distance into `R[0]` (0 when the
+ * segment crosses the face). Candidates: each endpoint against the face, the segment against
+ * each edge, and the face crossing. Clobbers `SEG2`, `PT` and `R[1]`.
+ */
+export declare function closestSegTri(outS: Vec3Out, outT: Vec3Out): void;
+/**
+ * The closest points between segment `p0 p1` and triangle `a b c`: the point on the segment
+ * into `outS`, the point on the triangle into `outT`; returns the squared distance (0 when the
+ * segment crosses the face).
+ */
+export declare function closestSegmentTriangle(p0x: number, p0y: number, p0z: number, p1x: number, p1y: number, p1z: number, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, outS: Vec3Out, outT: Vec3Out): number;
+/** The sphere in `SH` against `TRI`. */
+export declare function sphereTri(out: Contact): boolean;
+/** Sphere against a triangle: true and `out` filled when they overlap (touching is no contact). */
+export declare function sphereTriangle(s: Sphere, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Contact): boolean;
+/** The capsule (y axis) in `SH` against `TRI`. */
+export declare function capsuleTri(out: Contact): boolean;
+/**
+ * Capsule (y axis) against a triangle: the closest points between the inner segment and the
+ * triangle, then the sphere test there. True and `out` filled when they overlap.
+ */
+export declare function capsuleTriangle(cap: Capsule, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Contact): boolean;
+/**
+ * Loads the box in `SH` for the separating-axis tests: half extents into `BX[0..2]`, the
+ * vertices of `TRI` relative to the box centre into `BX[3..11]`, the centre into `PT`.
+ */
+export declare function loadBox(): void;
+/**
+ * Sets `BX[12..14]` to axis `i` of the thirteen box–triangle separating axes: the box axes
+ * (0..2), the face normal (3), each edge crossed with each box axis (4..12).
+ */
+export declare function boxAxis(i: number): void;
+/** The box in `SH` against `TRI` by the separating-axis test; see `aabbTriangle`. */
+export declare function aabbTri(out: Contact): boolean;
+/**
+ * Axis-aligned box against a triangle by the separating-axis test (Akenine-Möller: the three
+ * box axes, the face normal, the nine edge cross products). True and `out` filled when they
+ * overlap: the normal is the axis of least penetration pointing from the triangle into the box,
+ * `depth` the overlap along it, the point the triangle point closest to the box centre.
+ */
+export declare function aabbTriangle(box: GeomAabb, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Contact): boolean;
+/** The world AABB of the shape in `SH` into `min` and `max`. */
+export declare function shapeBoundsReg(min: Vec3Out, max: Vec3Out): void;
+/** The world AABB of a shape into `min` and `max`. */
+export declare function shapeBounds(s: Shape, min: Vec3Out, max: Vec3Out): void;
+/** The shape in `SH` against `TRI`, dispatching on its kind. */
+export declare function shapeTri(out: Contact): boolean;
+/** Shape against one triangle, dispatching on the shape kind. */
+export declare function shapeTriangle(s: Shape, ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number, out: Contact): boolean;