@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/collide/bvh.js

@@ -0,0 +1,493 @@
+import { gridTriangles } from './grid.js';
+export const SOURCE_GEOMETRY = 0;
+export const SOURCE_HEIGHTFIELD = 1;
+export const SOURCE_GRID = 2;
+/**
+ * A world of static triangles under a BVH. Build with `createStaticCollider`, query with
+ * `raycast`, `overlap`, `sweep` and `slide`, ship with `exportCollider`.
+ */
+export class StaticCollider {
+    /** World-space triangles, nine floats each, in BVH leaf order. */
+    tris;
+    /** The source index of each triangle. */
+    triSource;
+    nodeMin;
+    nodeMax;
+    nodeLeaf;
+    nodeA;
+    nodeB;
+    /** The root node index. */
+    root;
+    /** Top-level nodes over the sources occupy `[0, topCount)` (0 when there is one source). */
+    topCount;
+    sources;
+    leafSize;
+    /** The union of every live source, kept current by `refit` and `remove`. */
+    bounds = {
+        min: [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY],
+        max: [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY],
+    };
+    constructor(parts) {
+        this.tris = parts.tris;
+        this.triSource = parts.triSource;
+        this.nodeMin = parts.nodeMin;
+        this.nodeMax = parts.nodeMax;
+        this.nodeLeaf = parts.nodeLeaf;
+        this.nodeA = parts.nodeA;
+        this.nodeB = parts.nodeB;
+        this.root = parts.root;
+        this.topCount = parts.topCount;
+        this.sources = parts.sources;
+        this.leafSize = parts.leafSize;
+        this.updateBounds();
+    }
+    /** Triangles in the live (not removed) sources. */
+    get triangleCount() {
+        let n = 0;
+        for (const s of this.sources)
+            if (!s.removed)
+                n += s.count;
+        return n;
+    }
+    /** Number of sources, removed ones included (indices stay stable). */
+    get sourceCount() {
+        return this.sources.length;
+    }
+    /** The `userData` of a source (-1 or out of range gives `undefined`). */
+    userData(source) {
+        return this.sources[source]?.userData;
+    }
+    /**
+     * Moves a geometry source to `transform` (a 3×4 `Transform.world` or a 4×4 column-major
+     * matrix): rewrites its world triangles from the local copy, refits its leaves and inner nodes
+     * bottom-up, then the top-level nodes. Nothing is rebuilt; a tree whose leaves have drifted far
+     * apart only gets looser. Throws for a heightfield or grid source.
+     */
+    refit(sourceIndex, transform) {
+        const s = this.sources[sourceIndex];
+        if (!s)
+            throw new Error(`collide: no source ${sourceIndex}`);
+        if (!s.local)
+            throw new Error(`collide: source ${sourceIndex} is not a geometry; only geometry sources refit`);
+        if (s.removed)
+            return;
+        const local = s.local;
+        const tris = this.tris;
+        const base = s.start * 9;
+        for (let i = 0; i < local.length; i += 3) {
+            applyTransform(transform, local[i], local[i + 1], local[i + 2], tris, base + i);
+        }
+        this.refitBlock(s.nodeStart, s.nodeEnd);
+        this.refitTop();
+    }
+    /** Drops a source from every query (its root box becomes empty). Indices do not shift. */
+    remove(sourceIndex) {
+        const s = this.sources[sourceIndex];
+        if (!s)
+            throw new Error(`collide: no source ${sourceIndex}`);
+        if (s.removed)
+            return;
+        s.removed = true;
+        setEmpty(this.nodeMin, this.nodeMax, s.root);
+        this.refitTop();
+    }
+    /** Recomputes the nodes of one block from its leaves up (children always follow parents). */
+    refitBlock(start, end) {
+        const { nodeMin, nodeMax, nodeLeaf, nodeA, nodeB, tris } = this;
+        for (let n = end - 1; n >= start; n--) {
+            if (nodeLeaf[n]) {
+                let minX = Number.POSITIVE_INFINITY;
+                let minY = Number.POSITIVE_INFINITY;
+                let minZ = Number.POSITIVE_INFINITY;
+                let maxX = Number.NEGATIVE_INFINITY;
+                let maxY = Number.NEGATIVE_INFINITY;
+                let maxZ = Number.NEGATIVE_INFINITY;
+                const t0 = nodeA[n] * 9;
+                const t1 = t0 + nodeB[n] * 9;
+                for (let i = t0; i < t1; i += 3) {
+                    const x = tris[i];
+                    const y = tris[i + 1];
+                    const z = tris[i + 2];
+                    if (x < minX)
+                        minX = x;
+                    if (x > maxX)
+                        maxX = x;
+                    if (y < minY)
+                        minY = y;
+                    if (y > maxY)
+                        maxY = y;
+                    if (z < minZ)
+                        minZ = z;
+                    if (z > maxZ)
+                        maxZ = z;
+                }
+                nodeMin[n * 3] = minX;
+                nodeMin[n * 3 + 1] = minY;
+                nodeMin[n * 3 + 2] = minZ;
+                nodeMax[n * 3] = maxX;
+                nodeMax[n * 3 + 1] = maxY;
+                nodeMax[n * 3 + 2] = maxZ;
+            }
+            else {
+                unionChildren(nodeMin, nodeMax, n, nodeA[n], nodeB[n]);
+            }
+        }
+    }
+    refitTop() {
+        const { nodeMin, nodeMax, nodeA, nodeB } = this;
+        for (let n = this.topCount - 1; n >= 0; n--) {
+            unionChildren(nodeMin, nodeMax, n, nodeA[n], nodeB[n]);
+        }
+        this.updateBounds();
+    }
+    updateBounds() {
+        const r = this.root * 3;
+        const b = this.bounds;
+        b.min[0] = this.nodeMin[r];
+        b.min[1] = this.nodeMin[r + 1];
+        b.min[2] = this.nodeMin[r + 2];
+        b.max[0] = this.nodeMax[r];
+        b.max[1] = this.nodeMax[r + 1];
+        b.max[2] = this.nodeMax[r + 2];
+    }
+}
+function setEmpty(nodeMin, nodeMax, n) {
+    nodeMin[n * 3] = nodeMin[n * 3 + 1] = nodeMin[n * 3 + 2] = Number.POSITIVE_INFINITY;
+    nodeMax[n * 3] = nodeMax[n * 3 + 1] = nodeMax[n * 3 + 2] = Number.NEGATIVE_INFINITY;
+}
+function unionChildren(nodeMin, nodeMax, n, a, b) {
+    for (let k = 0; k < 3; k++) {
+        nodeMin[n * 3 + k] = Math.min(nodeMin[a * 3 + k], nodeMin[b * 3 + k]);
+        nodeMax[n * 3 + k] = Math.max(nodeMax[a * 3 + k], nodeMax[b * 3 + k]);
+    }
+}
+/**
+ * Writes `m × (x, y, z, 1)` into `out` at `o`. `m` is a 3×4 row-major matrix (12 floats, as
+ * `Transform.world`) or a 4×4 column-major one (16 floats, as `Camera.view`). Anything else throws.
+ */
+export function applyTransform(m, x, y, z, out, o) {
+    if (m.length === 12) {
+        out[o] = m[0] * x + m[1] * y + m[2] * z + m[3];
+        out[o + 1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+        out[o + 2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+    }
+    else if (m.length === 16) {
+        out[o] = m[0] * x + m[4] * y + m[8] * z + m[12];
+        out[o + 1] = m[1] * x + m[5] * y + m[9] * z + m[13];
+        out[o + 2] = m[2] * x + m[6] * y + m[10] * z + m[14];
+    }
+    else {
+        throw new Error(`collide: a transform has 12 (3×4 row-major) or 16 (4×4) floats, got ${m.length}`);
+    }
+}
+// ------------------------------------------------------------------ building
+/**
+ * The nine floats per triangle of a vertex array (`floats` per vertex, xyz first) and its
+ * indices, in its own space: the one position accessor both triangle-set source forms go through.
+ */
+function indexedTriangles(v, floats, idx) {
+    if (idx.length % 3 !== 0) {
+        throw new Error(`collide: a source's index count must be a multiple of 3, got ${idx.length}`);
+    }
+    const out = new Float32Array(idx.length * 3);
+    for (let i = 0; i < idx.length; i++) {
+        const o = idx[i] * floats;
+        out[i * 3] = v[o];
+        out[i * 3 + 1] = v[o + 1];
+        out[i * 3 + 2] = v[o + 2];
+    }
+    return out;
+}
+/** Two triangles per cell, counter-clockwise seen from +y, the same surface `heightAt` samples. */
+function heightfieldTriangles(hf) {
+    const { width, depth, heights, scale, origin } = hf;
+    const cells = (width - 1) * (depth - 1);
+    const out = new Float32Array(cells * 18);
+    let o = 0;
+    const at = (x, z, k) => {
+        out[o + k] = origin[0] + x * scale[0];
+        out[o + k + 1] = origin[1] + heights[z * width + x] * scale[1];
+        out[o + k + 2] = origin[2] + z * scale[2];
+    };
+    for (let z = 0; z < depth - 1; z++) {
+        for (let x = 0; x < width - 1; x++) {
+            // (x, z) (x, z+1) (x+1, z+1) and (x, z) (x+1, z+1) (x+1, z): CCW from above (+y).
+            at(x, z, 0);
+            at(x, z + 1, 3);
+            at(x + 1, z + 1, 6);
+            o += 9;
+            at(x, z, 0);
+            at(x + 1, z + 1, 3);
+            at(x + 1, z, 6);
+            o += 9;
+        }
+    }
+    return out;
+}
+/**
+ * Builds a subtree over triangles `order[lo..hi)` of `tris` into `tree`, node indices offset by
+ * `nodeBase` (the index the first node of this block gets). Returns the root's index.
+ */
+function buildSubtree(tris, order, centroids, lo, hi, leafSize, tree, nodeBase) {
+    const index = nodeBase + tree.leaf.length;
+    // Bounds of the range and of its centroids.
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let minZ = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let maxZ = Number.NEGATIVE_INFINITY;
+    let cMinX = Number.POSITIVE_INFINITY;
+    let cMinY = Number.POSITIVE_INFINITY;
+    let cMinZ = Number.POSITIVE_INFINITY;
+    let cMaxX = Number.NEGATIVE_INFINITY;
+    let cMaxY = Number.NEGATIVE_INFINITY;
+    let cMaxZ = Number.NEGATIVE_INFINITY;
+    for (let i = lo; i < hi; i++) {
+        const t = order[i];
+        for (let k = 0; k < 9; k += 3) {
+            const x = tris[t * 9 + k];
+            const y = tris[t * 9 + k + 1];
+            const z = tris[t * 9 + k + 2];
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+            if (z < minZ)
+                minZ = z;
+            if (z > maxZ)
+                maxZ = z;
+        }
+        const cx = centroids[t * 3];
+        const cy = centroids[t * 3 + 1];
+        const cz = centroids[t * 3 + 2];
+        if (cx < cMinX)
+            cMinX = cx;
+        if (cx > cMaxX)
+            cMaxX = cx;
+        if (cy < cMinY)
+            cMinY = cy;
+        if (cy > cMaxY)
+            cMaxY = cy;
+        if (cz < cMinZ)
+            cMinZ = cz;
+        if (cz > cMaxZ)
+            cMaxZ = cz;
+    }
+    tree.min.push(minX, minY, minZ);
+    tree.max.push(maxX, maxY, maxZ);
+    const count = hi - lo;
+    const ex = cMaxX - cMinX;
+    const ey = cMaxY - cMinY;
+    const ez = cMaxZ - cMinZ;
+    const widest = Math.max(ex, ey, ez);
+    if (count <= leafSize || count < 2 || !(widest > 0)) {
+        tree.leaf.push(1);
+        tree.a.push(lo);
+        tree.b.push(count);
+        return index;
+    }
+    const axis = widest === ex ? 0 : widest === ey ? 1 : 2;
+    order.subarray(lo, hi).sort((p, q) => centroids[p * 3 + axis] - centroids[q * 3 + axis]);
+    const mid = (lo + hi) >> 1;
+    tree.leaf.push(0);
+    tree.a.push(0);
+    tree.b.push(0);
+    const slot = index - nodeBase;
+    tree.a[slot] = buildSubtree(tris, order, centroids, lo, mid, leafSize, tree, nodeBase);
+    tree.b[slot] = buildSubtree(tris, order, centroids, mid, hi, leafSize, tree, nodeBase);
+    return index;
+}
+function prepareSource(src) {
+    const layer = src.layer ?? 0;
+    if (!(layer >= 0 && layer < 32 && Number.isInteger(layer))) {
+        throw new Error(`collide: layer must be an integer 0..31, got ${layer}`);
+    }
+    if ('geometry' in src || 'positions' in src) {
+        const local = 'geometry' in src
+            ? indexedTriangles(src.geometry.vertices, src.geometry.layout.floats, src.geometry.indices)
+            : indexedTriangles(src.positions, 3, src.indices);
+        let world = local;
+        if (src.transform) {
+            world = new Float32Array(local.length);
+            for (let i = 0; i < local.length; i += 3) {
+                applyTransform(src.transform, local[i], local[i + 1], local[i + 2], world, i);
+            }
+        }
+        else {
+            world = new Float32Array(local);
+        }
+        return { kind: SOURCE_GEOMETRY, world, local, layer, userData: src.userData };
+    }
+    if ('heightfield' in src) {
+        return {
+            kind: SOURCE_HEIGHTFIELD,
+            world: heightfieldTriangles(src.heightfield),
+            local: null,
+            layer,
+            userData: src.userData,
+        };
+    }
+    if ('grid' in src) {
+        return {
+            kind: SOURCE_GRID,
+            world: gridTriangles(src.grid),
+            local: null,
+            layer,
+            userData: src.userData,
+        };
+    }
+    throw new Error('collide: a source is { geometry }, { positions, indices }, { heightfield } or { grid }');
+}
+/**
+ * Builds a `StaticCollider` over `sources`. Every source becomes a block of triangles (world
+ * space) and a BVH sub-tree (median split on the widest centroid axis, leaves of at most
+ * `leafSize` triangles, default 4); a top-level tree over the sources' roots joins them.
+ * Build-time allocation only; queries then allocate nothing.
+ */
+export function createStaticCollider(sources, opts = {}) {
+    const leafSize = Math.max(1, Math.floor(opts.leafSize ?? 4));
+    if (sources.length === 0)
+        throw new Error('collide: at least one source is needed');
+    const builds = sources.map(prepareSource);
+    let total = 0;
+    for (const b of builds)
+        total += b.world.length / 9;
+    const tris = new Float32Array(total * 9);
+    const triSource = new Uint32Array(total);
+    const records = [];
+    const trees = [];
+    const roots = [];
+    // Top-level nodes come first: with S sources a binary tree over them has S - 1 inner nodes.
+    const topCount = builds.length > 1 ? builds.length - 1 : 0;
+    let nodeCursor = topCount;
+    let triCursor = 0;
+    for (let si = 0; si < builds.length; si++) {
+        const b = builds[si];
+        const n = b.world.length / 9;
+        const order = new Uint32Array(n);
+        const centroids = new Float32Array(n * 3);
+        for (let t = 0; t < n; t++) {
+            order[t] = t;
+            const o = t * 9;
+            centroids[t * 3] = (b.world[o] + b.world[o + 3] + b.world[o + 6]) / 3;
+            centroids[t * 3 + 1] = (b.world[o + 1] + b.world[o + 4] + b.world[o + 7]) / 3;
+            centroids[t * 3 + 2] = (b.world[o + 2] + b.world[o + 5] + b.world[o + 8]) / 3;
+        }
+        const tree = { min: [], max: [], leaf: [], a: [], b: [] };
+        let root;
+        if (n === 0) {
+            root = nodeCursor;
+            tree.min.push(Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY);
+            tree.max.push(Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY);
+            tree.leaf.push(1);
+            tree.a.push(0);
+            tree.b.push(0);
+        }
+        else {
+            root = buildSubtree(b.world, order, centroids, 0, n, leafSize, tree, nodeCursor);
+        }
+        // Leaf triangle ranges are in `order` positions; place the triangles in that order.
+        for (let k = 0; k < tree.leaf.length; k++) {
+            if (tree.leaf[k])
+                tree.a[k] = tree.a[k] + triCursor;
+        }
+        const local = b.local ? new Float32Array(n * 9) : null;
+        for (let p = 0; p < n; p++) {
+            const t = order[p];
+            tris.set(b.world.subarray(t * 9, t * 9 + 9), (triCursor + p) * 9);
+            if (local && b.local)
+                local.set(b.local.subarray(t * 9, t * 9 + 9), p * 9);
+            triSource[triCursor + p] = si;
+        }
+        records.push({
+            kind: b.kind,
+            start: triCursor,
+            count: n,
+            root,
+            nodeStart: nodeCursor,
+            nodeEnd: nodeCursor + tree.leaf.length,
+            layer: b.layer,
+            removed: false,
+            local,
+            userData: b.userData,
+        });
+        trees.push(tree);
+        roots.push(root);
+        nodeCursor += tree.leaf.length;
+        triCursor += n;
+    }
+    const nodeCount = nodeCursor;
+    const nodeMin = new Float32Array(nodeCount * 3);
+    const nodeMax = new Float32Array(nodeCount * 3);
+    const nodeLeaf = new Uint8Array(nodeCount);
+    const nodeA = new Int32Array(nodeCount);
+    const nodeB = new Int32Array(nodeCount);
+    for (let si = 0; si < trees.length; si++) {
+        const tree = trees[si];
+        const base = records[si].nodeStart;
+        for (let k = 0; k < tree.leaf.length; k++) {
+            nodeMin.set(tree.min.slice(k * 3, k * 3 + 3), (base + k) * 3);
+            nodeMax.set(tree.max.slice(k * 3, k * 3 + 3), (base + k) * 3);
+            nodeLeaf[base + k] = tree.leaf[k];
+            nodeA[base + k] = tree.a[k];
+            nodeB[base + k] = tree.b[k];
+        }
+    }
+    // The top-level tree: median split over the source roots by their box centres.
+    let root;
+    if (topCount === 0) {
+        root = roots[0];
+    }
+    else {
+        let next = 0;
+        const centre = (n, axis) => (nodeMin[n * 3 + axis] + nodeMax[n * 3 + axis]) / 2;
+        const buildTop = (items) => {
+            if (items.length === 1)
+                return items[0];
+            const index = next++;
+            let axis = 0;
+            let widest = Number.NEGATIVE_INFINITY;
+            for (let k = 0; k < 3; k++) {
+                let lo = Number.POSITIVE_INFINITY;
+                let hi = Number.NEGATIVE_INFINITY;
+                for (const n of items) {
+                    const c = centre(n, k);
+                    if (Number.isFinite(c)) {
+                        lo = Math.min(lo, c);
+                        hi = Math.max(hi, c);
+                    }
+                }
+                if (hi - lo > widest) {
+                    widest = hi - lo;
+                    axis = k;
+                }
+            }
+            const sorted = items.slice().sort((p, q) => centre(p, axis) - centre(q, axis));
+            const mid = sorted.length >> 1;
+            nodeLeaf[index] = 0;
+            nodeA[index] = buildTop(sorted.slice(0, mid));
+            nodeB[index] = buildTop(sorted.slice(mid));
+            unionChildren(nodeMin, nodeMax, index, nodeA[index], nodeB[index]);
+            return index;
+        };
+        root = buildTop(roots);
+    }
+    return new StaticCollider({
+        tris,
+        triSource,
+        nodeMin,
+        nodeMax,
+        nodeLeaf,
+        nodeA,
+        nodeB,
+        root,
+        topCount,
+        sources: records,
+        leafSize,
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Wireframes of a collider for `createDebugDraw`: either every triangle's three edges or the
+ * boxes of the BVH leaves (twelve edges each). Six floats per segment, `x0 y0 z0 x1 y1 z1`.
+ */
+import type { StaticCollider } from './bvh.js';
+export type WireframeMode = 'triangles' | 'leaves';
+/** The number of floats `colliderWireframe` writes for `c` in `mode`. */
+export declare function colliderWireframeLength(c: StaticCollider, mode?: WireframeMode): number;
+/**
+ * Line segments for the collider's live triangles (`'triangles'`) or BVH leaf boxes
+ * (`'leaves'`). Reuses `out` when it is long enough, else allocates; returns the array (which may
+ * be longer than the written part: `colliderWireframeLength` gives the exact count).
+ */
+export declare function colliderWireframe(c: StaticCollider, out?: Float32Array, mode?: WireframeMode): Float32Array;

package/dist/geom/collide/debug.js

@@ -0,0 +1,74 @@
+/** The number of floats `colliderWireframe` writes for `c` in `mode`. */
+export function colliderWireframeLength(c, mode = 'triangles') {
+    if (mode === 'leaves') {
+        let leaves = 0;
+        for (let n = 0; n < c.nodeLeaf.length; n++) {
+            if (c.nodeLeaf[n] && c.nodeB[n] > 0 && !c.sources[c.triSource[c.nodeA[n]]].removed)
+                leaves++;
+        }
+        return leaves * 12 * 6;
+    }
+    return c.triangleCount * 3 * 6;
+}
+const BOX_EDGES = [
+    [0, 1],
+    [1, 3],
+    [3, 2],
+    [2, 0],
+    [4, 5],
+    [5, 7],
+    [7, 6],
+    [6, 4],
+    [0, 4],
+    [1, 5],
+    [2, 6],
+    [3, 7],
+];
+/**
+ * Line segments for the collider's live triangles (`'triangles'`) or BVH leaf boxes
+ * (`'leaves'`). Reuses `out` when it is long enough, else allocates; returns the array (which may
+ * be longer than the written part: `colliderWireframeLength` gives the exact count).
+ */
+export function colliderWireframe(c, out, mode = 'triangles') {
+    const need = colliderWireframeLength(c, mode);
+    const buf = out && out.length >= need ? out : new Float32Array(need);
+    let o = 0;
+    if (mode === 'leaves') {
+        for (let n = 0; n < c.nodeLeaf.length; n++) {
+            if (!c.nodeLeaf[n] || c.nodeB[n] <= 0)
+                continue;
+            if (c.sources[c.triSource[c.nodeA[n]]].removed)
+                continue;
+            const b = n * 3;
+            for (const [i, j] of BOX_EDGES) {
+                buf[o++] = i & 1 ? c.nodeMax[b] : c.nodeMin[b];
+                buf[o++] = i & 2 ? c.nodeMax[b + 1] : c.nodeMin[b + 1];
+                buf[o++] = i & 4 ? c.nodeMax[b + 2] : c.nodeMin[b + 2];
+                buf[o++] = j & 1 ? c.nodeMax[b] : c.nodeMin[b];
+                buf[o++] = j & 2 ? c.nodeMax[b + 1] : c.nodeMin[b + 1];
+                buf[o++] = j & 4 ? c.nodeMax[b + 2] : c.nodeMin[b + 2];
+            }
+        }
+        return buf;
+    }
+    const tris = c.tris;
+    for (const s of c.sources) {
+        if (s.removed)
+            continue;
+        const t0 = s.start * 9;
+        const t1 = t0 + s.count * 9;
+        for (let t = t0; t < t1; t += 9) {
+            for (let e = 0; e < 3; e++) {
+                const a = t + e * 3;
+                const b = t + ((e + 1) % 3) * 3;
+                buf[o++] = tris[a];
+                buf[o++] = tris[a + 1];
+                buf[o++] = tris[a + 2];
+                buf[o++] = tris[b];
+                buf[o++] = tris[b + 1];
+                buf[o++] = tris[b + 2];
+            }
+        }
+    }
+    return buf;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * The 2D tile case: a grid of solid cells in the xz plane becomes boxes, `cellSize` wide and
+ * deep, from `y` to `y + wallHeight`. Faces shared by two solid cells are left out, so a wall of
+ * tiles is one flat run of quads and a circle sliding along it meets no interior edges (the
+ * corridor case). Column `x` runs along +x, row `z` along +z, `solid[z * width + x]`.
+ */
+export interface GridSource {
+    /** Cells along x. */
+    width: number;
+    /** Cells along z. */
+    height: number;
+    /** World size of one cell (x and z). */
+    cellSize: number;
+    /** World x, z of the corner of cell (0, 0). */
+    origin: [number, number];
+    /** Which cells are solid: a predicate over cell coordinates or a `width × height` array. */
+    solid: ((x: number, z: number) => boolean) | Uint8Array;
+    /** World y of the cells' bottom face. Default 0. */
+    y?: number;
+    /** Height of the cells' walls. Default `cellSize`. */
+    wallHeight?: number;
+}
+/** Whether cell (x, z) is solid; out-of-range cells are open. */
+export declare function gridSolid(grid: GridSource, x: number, z: number): boolean;
+/** The grid's exposed faces as triangles, nine floats each, counter-clockwise from outside. */
+export declare function gridTriangles(grid: GridSource): Float32Array;

package/dist/geom/collide/grid.js

@@ -0,0 +1,91 @@
+/**
+ * The 2D tile case: a grid of solid cells in the xz plane becomes boxes, `cellSize` wide and
+ * deep, from `y` to `y + wallHeight`. Faces shared by two solid cells are left out, so a wall of
+ * tiles is one flat run of quads and a circle sliding along it meets no interior edges (the
+ * corridor case). Column `x` runs along +x, row `z` along +z, `solid[z * width + x]`.
+ */
+/** Whether cell (x, z) is solid; out-of-range cells are open. */
+export function gridSolid(grid, x, z) {
+    if (x < 0 || z < 0 || x >= grid.width || z >= grid.height)
+        return false;
+    const s = grid.solid;
+    return typeof s === 'function' ? s(x, z) : s[z * grid.width + x] !== 0;
+}
+/** The grid's exposed faces as triangles, nine floats each, counter-clockwise from outside. */
+export function gridTriangles(grid) {
+    const { width, height, cellSize } = grid;
+    if (!(width >= 1 && height >= 1)) {
+        throw new Error(`collide: a grid needs at least 1×1 cells, got ${width}×${height}`);
+    }
+    if (!(cellSize > 0))
+        throw new Error(`collide: grid cellSize must be positive, got ${cellSize}`);
+    const y0 = grid.y ?? 0;
+    const y1 = y0 + (grid.wallHeight ?? cellSize);
+    const ox = grid.origin[0];
+    const oz = grid.origin[1];
+    // Count faces first so the array is allocated once.
+    let faces = 0;
+    for (let z = 0; z < height; z++) {
+        for (let x = 0; x < width; x++) {
+            if (!gridSolid(grid, x, z))
+                continue;
+            faces += 2; // top and bottom
+            if (!gridSolid(grid, x - 1, z))
+                faces++;
+            if (!gridSolid(grid, x + 1, z))
+                faces++;
+            if (!gridSolid(grid, x, z - 1))
+                faces++;
+            if (!gridSolid(grid, x, z + 1))
+                faces++;
+        }
+    }
+    const out = new Float32Array(faces * 18);
+    let o = 0;
+    const quad = (ax, ay, az, bx, by, bz, cx, cy, cz, dx, dy, dz) => {
+        out[o++] = ax;
+        out[o++] = ay;
+        out[o++] = az;
+        out[o++] = bx;
+        out[o++] = by;
+        out[o++] = bz;
+        out[o++] = cx;
+        out[o++] = cy;
+        out[o++] = cz;
+        out[o++] = ax;
+        out[o++] = ay;
+        out[o++] = az;
+        out[o++] = cx;
+        out[o++] = cy;
+        out[o++] = cz;
+        out[o++] = dx;
+        out[o++] = dy;
+        out[o++] = dz;
+    };
+    for (let z = 0; z < height; z++) {
+        for (let x = 0; x < width; x++) {
+            if (!gridSolid(grid, x, z))
+                continue;
+            const x0 = ox + x * cellSize;
+            const x1 = x0 + cellSize;
+            const z0 = oz + z * cellSize;
+            const z1 = z0 + cellSize;
+            // Top (+y) and bottom (-y).
+            quad(x0, y1, z0, x0, y1, z1, x1, y1, z1, x1, y1, z0);
+            quad(x0, y0, z0, x1, y0, z0, x1, y0, z1, x0, y0, z1);
+            // -x face
+            if (!gridSolid(grid, x - 1, z))
+                quad(x0, y0, z0, x0, y0, z1, x0, y1, z1, x0, y1, z0);
+            // +x face
+            if (!gridSolid(grid, x + 1, z))
+                quad(x1, y0, z1, x1, y0, z0, x1, y1, z0, x1, y1, z1);
+            // -z face
+            if (!gridSolid(grid, x, z - 1))
+                quad(x1, y0, z0, x0, y0, z0, x0, y1, z0, x1, y1, z0);
+            // +z face
+            if (!gridSolid(grid, x, z + 1))
+                quad(x0, y0, z1, x1, y0, z1, x1, y1, z1, x0, y1, z1);
+        }
+    }
+    return out;
+}