@driftengine/core 3.61.0

package/dist/nav/navPath.js

@@ -0,0 +1,162 @@
+export function createNavSteer() {
+    return { x: 0, y: 0, z: 0, remainingM: 0, arrived: false };
+}
+/**
+ * A route being walked: the nodes, and how far along them the agent is.
+ *
+ * **Progress is a distance along the path, not an index into it**, and that is what makes this
+ * survive an agent being shoved. An index only ever counts up when a waypoint is reached, so an
+ * agent knocked backwards past one keeps aiming at the waypoint behind it; a distance is recovered
+ * from the agent's own position every update, against the segment it is nearest to, so being pushed
+ * about costs progress and never correctness.
+ */
+export class NavPath {
+    graph;
+    lookaheadM;
+    arriveM;
+    /** Node indices of the route, and how many are live. */
+    nodes;
+    length = 0;
+    /** Cumulative distance to the start of each segment, so a lookahead is a lookup. */
+    distanceTo;
+    total = 0;
+    /** Which segment the agent was on last update: where the search for the nearest one starts. */
+    segment = 0;
+    constructor(graph, capacity, options = {}) {
+        if (!(capacity > 1))
+            throw new Error(`NavPath: capacity must be at least 2, got ${capacity}`);
+        this.graph = graph;
+        this.nodes = new Uint32Array(capacity);
+        this.distanceTo = new Float64Array(capacity);
+        this.lookaheadM = options.lookaheadM ?? 2;
+        this.arriveM = options.arriveM ?? 0.5;
+    }
+    get nodeCount() {
+        return this.length;
+    }
+    get lengthM() {
+        return this.total;
+    }
+    /** Whether there is a route to follow at all. */
+    get active() {
+        return this.length > 1;
+    }
+    /**
+     * Take a route, as `NavSearch.find` filled it.
+     *
+     * A route of one node is a route to where the agent already is, and is stored as no route: it
+     * has no direction to steer along and every caller would otherwise have to special-case it.
+     */
+    set(path, count) {
+        this.length = 0;
+        this.total = 0;
+        this.segment = 0;
+        if (count < 2)
+            return;
+        const usable = Math.min(count, this.nodes.length);
+        this.nodes.set(path.subarray(0, usable));
+        this.length = usable;
+        this.distanceTo[0] = 0;
+        for (let i = 1; i < usable; i++) {
+            this.total += this.span(i - 1, i);
+            this.distanceTo[i] = this.total;
+        }
+    }
+    clear() {
+        this.length = 0;
+        this.total = 0;
+        this.segment = 0;
+    }
+    /**
+     * Where an agent at `(x, y, z)` should aim next.
+     *
+     * With no route, the agent is told to aim where it stands and that it has arrived, so a caller
+     * driving off `arrived` needs no separate check for having no path at all.
+     */
+    steer(x, y, z, out) {
+        if (this.length < 2) {
+            out.x = x;
+            out.y = y;
+            out.z = z;
+            out.remainingM = 0;
+            out.arrived = true;
+            return;
+        }
+        /*
+         * Where the agent is, as a distance along the route. Searched over the whole path rather than
+         * forward from the last segment: an agent carried backwards — a lift, a shove, a vehicle it
+         * was standing on — is exactly the case a forward-only scan gets wrong, and a route is tens of
+         * nodes rather than thousands.
+         */
+        let bestSquared = Infinity;
+        let travelled = 0;
+        for (let i = 0; i + 1 < this.length; i++) {
+            const along = this.project(i, x, y, z);
+            const squared = this.distanceSquaredTo(i, along, x, y, z);
+            if (squared < bestSquared) {
+                bestSquared = squared;
+                travelled = (this.distanceTo[i] ?? 0) + along;
+                this.segment = i;
+            }
+        }
+        const remaining = this.total - travelled;
+        out.remainingM = remaining > 0 ? remaining : 0;
+        out.arrived = remaining <= this.arriveM;
+        /* Aim ahead along the line, clamped to the end: near the goal the target is the goal, which is
+           what stops an agent overshooting it to satisfy a lookahead. */
+        this.pointAt(Math.min(travelled + this.lookaheadM, this.total), out);
+    }
+    /** How far along segment `i` the point `(x, y, z)` projects, clamped to the segment. */
+    project(i, x, y, z) {
+        const ax = this.px(i);
+        const ay = this.py(i);
+        const az = this.pz(i);
+        const dx = this.px(i + 1) - ax;
+        const dy = this.py(i + 1) - ay;
+        const dz = this.pz(i + 1) - az;
+        const lengthSquared = dx * dx + dy * dy + dz * dz;
+        if (lengthSquared === 0)
+            return 0;
+        let t = ((x - ax) * dx + (y - ay) * dy + (z - az) * dz) / lengthSquared;
+        if (t < 0)
+            t = 0;
+        else if (t > 1)
+            t = 1;
+        return t * Math.sqrt(lengthSquared);
+    }
+    distanceSquaredTo(i, along, x, y, z) {
+        const span = this.span(i, i + 1);
+        const t = span === 0 ? 0 : along / span;
+        const dx = this.px(i) + (this.px(i + 1) - this.px(i)) * t - x;
+        const dy = this.py(i) + (this.py(i + 1) - this.py(i)) * t - y;
+        const dz = this.pz(i) + (this.pz(i + 1) - this.pz(i)) * t - z;
+        return dx * dx + dy * dy + dz * dz;
+    }
+    /** The world point a given distance along the route. */
+    pointAt(distance, out) {
+        let i = this.segment;
+        while (i + 2 < this.length && (this.distanceTo[i + 1] ?? 0) < distance)
+            i++;
+        const base = this.distanceTo[i] ?? 0;
+        const span = this.span(i, i + 1);
+        const t = span === 0 ? 0 : Math.min(1, Math.max(0, (distance - base) / span));
+        out.x = this.px(i) + (this.px(i + 1) - this.px(i)) * t;
+        out.y = this.py(i) + (this.py(i + 1) - this.py(i)) * t;
+        out.z = this.pz(i) + (this.pz(i + 1) - this.pz(i)) * t;
+    }
+    span(a, b) {
+        const dx = this.px(b) - this.px(a);
+        const dy = this.py(b) - this.py(a);
+        const dz = this.pz(b) - this.pz(a);
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    px(i) {
+        return this.graph.positions[(this.nodes[i] ?? 0) * 3] ?? 0;
+    }
+    py(i) {
+        return this.graph.positions[(this.nodes[i] ?? 0) * 3 + 1] ?? 0;
+    }
+    pz(i) {
+        return this.graph.positions[(this.nodes[i] ?? 0) * 3 + 2] ?? 0;
+    }
+}

package/dist/nav/navSearch.d.ts

@@ -0,0 +1,74 @@
+import type { NavGraph } from './navGraph.ts';
+/**
+ * A* over a `NavGraph`, allocating nothing per query and answering the same route every time.
+ *
+ * **Reused rather than constructed per search**, because the scratch is proportional to the graph
+ * and a world with a dozen agents re-pathing on a schedule would otherwise allocate a dozen arrays
+ * the size of the map every time somebody changed their mind. One of these per thread of control;
+ * a search is not re-entrant and says so.
+ *
+ * **The route is a function of the graph and the two endpoints, and of nothing else.** Two runs, two
+ * machines, a replay: same nodes out. That takes more than avoiding randomness — a heap pops ties in
+ * whatever order it happens to hold them, and two equally good routes through a symmetric world are
+ * exactly the case a road network produces constantly. So ties break on the node index, which is
+ * arbitrary but *stable*, and the sequence is frozen the same way the engine's RNG is.
+ *
+ * **The heuristic is straight-line distance**, which is admissible precisely because
+ * `buildNavGraph` refuses an edge cheaper than its own span. That refusal is what makes the first
+ * route this returns the cheapest one rather than merely a good one, and it is why it is a build
+ * error rather than a note.
+ */
+export declare class NavSearch {
+    private readonly graph;
+    private readonly gScore;
+    private readonly fScore;
+    private readonly cameFrom;
+    /** 0 unseen, 1 open, 2 closed. */
+    private readonly state;
+    /**
+     * A binary heap of node indices, ordered by `fScore` then by index.
+     *
+     * **Sized by edges and not by nodes**, from an argument rather than from a measurement: a push
+     * happens at most once per directed edge — a node goes on when it is first reached and again only
+     * when an edge improves it — so an array of that length cannot overflow. A node count is *not* a
+     * bound on that, and the failure it would allow is the quiet kind: a dropped push is not a slower
+     * search, it is a node marked open that nothing will ever pop, so a route that exists comes back
+     * as none.
+     *
+     * **No test here exhibits that**, and `nav.test.ts` says so where the dense graph is: occupancy
+     * in practice sits far below either bound, so a graph that could tell the two sizings apart is
+     * larger than a suite should carry. The argument is what the sizing rests on and the guard in
+     * `push` is what stands behind the argument.
+     */
+    private readonly heap;
+    private heapSize;
+    /** How many nodes the last search took off the heap. Useful for a budget, and for a test. */
+    private lastExpanded;
+    constructor(graph: NavGraph);
+    /** Nodes taken off the heap by the last `find`. */
+    get expanded(): number;
+    /**
+     * Fill `outPath` with the node indices from `from` to `to`, and return how many there are.
+     *
+     * Zero means there is no route, which is a real answer and not an error: a road network with a
+     * bridge out is a graph with two components, and an agent that asks for the other side has to be
+     * told rather than thrown at inside a frame.
+     *
+     * A path longer than `outPath` is refused by returning zero rather than by writing a prefix,
+     * because half a route is worse than none — an agent would follow it confidently into the middle
+     * of nowhere and stop.
+     */
+    find(from: number, to: number, outPath: Uint32Array): number;
+    /**
+     * Straight-line distance, the heuristic.
+     *
+     * Never an overestimate, because no edge may cost less than its own span — `buildNavGraph`
+     * enforces it — so the first time the goal comes off the heap its cost is final.
+     */
+    private straightLine;
+    /** Walk `cameFrom` back from the goal, then reverse it in place. */
+    private unwind;
+    private better;
+    private push;
+    private pop;
+}

package/dist/nav/navSearch.js

@@ -0,0 +1,198 @@
+/**
+ * A* over a `NavGraph`, allocating nothing per query and answering the same route every time.
+ *
+ * **Reused rather than constructed per search**, because the scratch is proportional to the graph
+ * and a world with a dozen agents re-pathing on a schedule would otherwise allocate a dozen arrays
+ * the size of the map every time somebody changed their mind. One of these per thread of control;
+ * a search is not re-entrant and says so.
+ *
+ * **The route is a function of the graph and the two endpoints, and of nothing else.** Two runs, two
+ * machines, a replay: same nodes out. That takes more than avoiding randomness — a heap pops ties in
+ * whatever order it happens to hold them, and two equally good routes through a symmetric world are
+ * exactly the case a road network produces constantly. So ties break on the node index, which is
+ * arbitrary but *stable*, and the sequence is frozen the same way the engine's RNG is.
+ *
+ * **The heuristic is straight-line distance**, which is admissible precisely because
+ * `buildNavGraph` refuses an edge cheaper than its own span. That refusal is what makes the first
+ * route this returns the cheapest one rather than merely a good one, and it is why it is a build
+ * error rather than a note.
+ */
+export class NavSearch {
+    graph;
+    gScore;
+    fScore;
+    cameFrom;
+    /** 0 unseen, 1 open, 2 closed. */
+    state;
+    /**
+     * A binary heap of node indices, ordered by `fScore` then by index.
+     *
+     * **Sized by edges and not by nodes**, from an argument rather than from a measurement: a push
+     * happens at most once per directed edge — a node goes on when it is first reached and again only
+     * when an edge improves it — so an array of that length cannot overflow. A node count is *not* a
+     * bound on that, and the failure it would allow is the quiet kind: a dropped push is not a slower
+     * search, it is a node marked open that nothing will ever pop, so a route that exists comes back
+     * as none.
+     *
+     * **No test here exhibits that**, and `nav.test.ts` says so where the dense graph is: occupancy
+     * in practice sits far below either bound, so a graph that could tell the two sizings apart is
+     * larger than a suite should carry. The argument is what the sizing rests on and the guard in
+     * `push` is what stands behind the argument.
+     */
+    heap;
+    heapSize = 0;
+    /** How many nodes the last search took off the heap. Useful for a budget, and for a test. */
+    lastExpanded = 0;
+    constructor(graph) {
+        this.graph = graph;
+        this.gScore = new Float64Array(graph.nodeCount);
+        this.fScore = new Float64Array(graph.nodeCount);
+        this.cameFrom = new Int32Array(graph.nodeCount);
+        this.state = new Uint8Array(graph.nodeCount);
+        this.heap = new Uint32Array(graph.edgeTarget.length + 1);
+    }
+    /** Nodes taken off the heap by the last `find`. */
+    get expanded() {
+        return this.lastExpanded;
+    }
+    /**
+     * Fill `outPath` with the node indices from `from` to `to`, and return how many there are.
+     *
+     * Zero means there is no route, which is a real answer and not an error: a road network with a
+     * bridge out is a graph with two components, and an agent that asks for the other side has to be
+     * told rather than thrown at inside a frame.
+     *
+     * A path longer than `outPath` is refused by returning zero rather than by writing a prefix,
+     * because half a route is worse than none — an agent would follow it confidently into the middle
+     * of nowhere and stop.
+     */
+    find(from, to, outPath) {
+        const { graph } = this;
+        if (from < 0 || from >= graph.nodeCount || to < 0 || to >= graph.nodeCount)
+            return 0;
+        this.state.fill(0);
+        this.heapSize = 0;
+        this.lastExpanded = 0;
+        this.gScore[from] = 0;
+        this.fScore[from] = this.straightLine(from, to);
+        this.cameFrom[from] = -1;
+        this.state[from] = 1;
+        this.push(from);
+        while (this.heapSize > 0) {
+            const current = this.pop();
+            if (current === to)
+                return this.unwind(from, to, outPath);
+            /* A duplicate of a node already expanded, left behind by pushing instead of decreasing a
+               key. Its cost is already final, so re-walking its edges would find nothing. */
+            if (this.state[current] === 2)
+                continue;
+            this.state[current] = 2;
+            this.lastExpanded++;
+            const end = graph.edgeStart[current + 1] ?? 0;
+            for (let e = graph.edgeStart[current] ?? 0; e < end; e++) {
+                const next = graph.edgeTarget[e] ?? 0;
+                if (this.state[next] === 2)
+                    continue;
+                const tentative = (this.gScore[current] ?? 0) + (graph.edgeCost[e] ?? 0);
+                if (this.state[next] === 1 && tentative >= (this.gScore[next] ?? 0))
+                    continue;
+                this.gScore[next] = tentative;
+                this.fScore[next] = tentative + this.straightLine(next, to);
+                this.cameFrom[next] = current;
+                /*
+                 * Pushed again rather than decreased in place. A decrease-key needs every node's position
+                 * in the heap maintained on every swap, which is a second array and a write per sift step
+                 * for a graph where a node is rarely improved twice; the duplicate is popped later, found
+                 * closed, and skipped. The heap is sized for that: a node can be open once per edge into
+                 * it, and the loop below tolerates a full heap by dropping the worse copy.
+                 */
+                this.state[next] = 1;
+                this.push(next);
+            }
+        }
+        return 0;
+    }
+    /**
+     * Straight-line distance, the heuristic.
+     *
+     * Never an overestimate, because no edge may cost less than its own span — `buildNavGraph`
+     * enforces it — so the first time the goal comes off the heap its cost is final.
+     */
+    straightLine(a, b) {
+        const p = this.graph.positions;
+        const dx = (p[a * 3] ?? 0) - (p[b * 3] ?? 0);
+        const dy = (p[a * 3 + 1] ?? 0) - (p[b * 3 + 1] ?? 0);
+        const dz = (p[a * 3 + 2] ?? 0) - (p[b * 3 + 2] ?? 0);
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    /** Walk `cameFrom` back from the goal, then reverse it in place. */
+    unwind(from, to, outPath) {
+        let length = 0;
+        for (let node = to; node !== -1; node = this.cameFrom[node] ?? -1) {
+            if (length >= outPath.length)
+                return 0;
+            outPath[length++] = node;
+            if (node === from)
+                break;
+        }
+        for (let i = 0, j = length - 1; i < j; i++, j--) {
+            const swap = outPath[i] ?? 0;
+            outPath[i] = outPath[j] ?? 0;
+            outPath[j] = swap;
+        }
+        return length;
+    }
+    better(a, b) {
+        const fa = this.fScore[a] ?? 0;
+        const fb = this.fScore[b] ?? 0;
+        if (fa !== fb)
+            return fa < fb;
+        /* The tie-break that makes a route reproducible. See the class note. */
+        return a < b;
+    }
+    push(node) {
+        /*
+         * Unreachable with the heap sized by edges above, and kept because the alternative to a guard
+         * here is writing past the end of the array in a frame. If it ever fires, the sizing argument
+         * is wrong and a route will be missed rather than a crash reported — which is why the sizing
+         * argument is written out where the array is declared.
+         */
+        if (this.heapSize >= this.heap.length)
+            return;
+        let at = this.heapSize++;
+        this.heap[at] = node;
+        while (at > 0) {
+            const parent = (at - 1) >> 1;
+            if (!this.better(this.heap[at] ?? 0, this.heap[parent] ?? 0))
+                break;
+            const swap = this.heap[at] ?? 0;
+            this.heap[at] = this.heap[parent] ?? 0;
+            this.heap[parent] = swap;
+            at = parent;
+        }
+    }
+    pop() {
+        const top = this.heap[0] ?? 0;
+        this.heapSize--;
+        if (this.heapSize > 0) {
+            this.heap[0] = this.heap[this.heapSize] ?? 0;
+            let at = 0;
+            for (;;) {
+                const left = at * 2 + 1;
+                const right = left + 1;
+                let best = at;
+                if (left < this.heapSize && this.better(this.heap[left] ?? 0, this.heap[best] ?? 0))
+                    best = left;
+                if (right < this.heapSize && this.better(this.heap[right] ?? 0, this.heap[best] ?? 0))
+                    best = right;
+                if (best === at)
+                    break;
+                const swap = this.heap[at] ?? 0;
+                this.heap[at] = this.heap[best] ?? 0;
+                this.heap[best] = swap;
+                at = best;
+            }
+        }
+        return top;
+    }
+}

package/dist/physics/boxSurface.d.ts

@@ -0,0 +1,48 @@
+import type { GroundSurface, SurfaceHit } from './ribbonSurface.ts';
+/**
+ * The tops of a set of flat, axis-aligned pads, answering as a ground surface.
+ *
+ * For the parts of a route that are *platforms* rather than ribbon — a flight of
+ * steps, a run of pads with gaps between them. Those are still the route, and
+ * that is the whole reason this exists rather than letting the collision boxes
+ * carry them: a character on ordinary geometry is off the route as far as anything
+ * asking the surface is concerned, and the route is what decides top speed, what
+ * the camera leans on, and how far along the run somebody is.
+ *
+ * Deliberately flat. A pad is an AABB, its top is level, and pretending
+ * otherwise would mean inventing a normal that the collider it shares a shape
+ * with does not have.
+ */
+export interface SurfaceBox {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+    /** Height of the walkable face. */
+    topY: number;
+    /** How far along the route this pad sits, metres. */
+    distanceM: number;
+    /** Direction of travel across it, for the camera and the pose. */
+    tangentX: number;
+    tangentZ: number;
+}
+export declare class BoxSurface implements GroundSurface {
+    private readonly boxes;
+    constructor(boxes: readonly SurfaceBox[]);
+    get count(): number;
+    /**
+     * The highest pad whose footprint contains the column.
+     *
+     * Highest rather than nearest, because pads never overlap in a way where the
+     * lower one is the answer — a flight of steps is monotone — and "highest"
+     * needs no reference height, which keeps this usable from a plain
+     * `GroundSurface` call.
+     *
+     * A linear scan: a day's route carries a few dozen pads, and a scan over
+     * thirty boxes inside a fixed tick costs less than the branch needed to skip
+     * it. Allocation-free either way.
+     */
+    sample(x: number, z: number, out: SurfaceHit, atY?: number): boolean;
+    /** See `GroundSurface.sampleBand`: the highest pad whose top is in the band. */
+    sampleBand(x: number, z: number, out: SurfaceHit, loY: number, hiY: number): boolean;
+}

package/dist/physics/boxSurface.js

@@ -0,0 +1,73 @@
+export class BoxSurface {
+    boxes;
+    constructor(boxes) {
+        this.boxes = boxes;
+    }
+    get count() {
+        return this.boxes.length;
+    }
+    /**
+     * The highest pad whose footprint contains the column.
+     *
+     * Highest rather than nearest, because pads never overlap in a way where the
+     * lower one is the answer — a flight of steps is monotone — and "highest"
+     * needs no reference height, which keeps this usable from a plain
+     * `GroundSurface` call.
+     *
+     * A linear scan: a day's route carries a few dozen pads, and a scan over
+     * thirty boxes inside a fixed tick costs less than the branch needed to skip
+     * it. Allocation-free either way.
+     */
+    sample(x, z, out, atY = Infinity) {
+        let best = null;
+        for (const box of this.boxes) {
+            if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ)
+                continue;
+            // Highest pad at or below the asker, so a run of pads under a flyover
+            // does not hand a character the deck above them.
+            if (box.topY > atY + 1.2)
+                continue;
+            if (best === null || box.topY > best.topY)
+                best = box;
+        }
+        if (best === null)
+            return false;
+        describe(best, out);
+        return true;
+    }
+    /** See `GroundSurface.sampleBand`: the highest pad whose top is in the band. */
+    sampleBand(x, z, out, loY, hiY) {
+        let best = null;
+        for (const box of this.boxes) {
+            if (x < box.minX || x > box.maxX || z < box.minZ || z > box.maxZ)
+                continue;
+            if (box.topY < loY || box.topY >= hiY)
+                continue;
+            if (best === null || box.topY > best.topY)
+                best = box;
+        }
+        if (best === null)
+            return false;
+        describe(best, out);
+        return true;
+    }
+}
+function describe(box, out) {
+    out.y = box.topY;
+    out.normalX = 0;
+    out.normalY = 1;
+    // A lid is flat, so it looks exactly as it collides. See `SurfaceHit.tilt`.
+    out.tiltX = 0;
+    out.tiltY = 1;
+    out.tiltZ = 0;
+    out.normalZ = 0;
+    out.tangentX = box.tangentX;
+    out.tangentY = 0;
+    out.tangentZ = box.tangentZ;
+    out.distanceM = box.distanceM;
+    out.lateralM = 0;
+    // Half the smaller footprint axis: the honest answer to "how much room is
+    // left", which is what a caller uses it for.
+    out.halfWidthM = Math.min(box.maxX - box.minX, box.maxZ - box.minZ) * 0.5;
+    out.bankRad = 0;
+}

package/dist/physics/colliderSurface.d.ts

@@ -0,0 +1,46 @@
+import type { ColliderSet } from '@driftengine/physics';
+import type { GroundSurface } from './ribbonSurface.ts';
+/**
+ * A `ColliderSet` answering "where is the ground here?", so a solid holds a body up.
+ *
+ * **Because a collider was solid to walk into and not to stand on.** The kinematic sweep resolves a
+ * body against a collider set laterally, and `CharacterController` senses ground through
+ * `PhysicsWorld` bodies and through a `GroundSurface` — a collider set is neither, so nothing ever
+ * asked it what was under your feet. Measured before this existed: a character dropped over a
+ * `ColliderSet` slab whose top face is at 5.5 m falls to −84 m in three seconds, which is exactly
+ * what it does with no slab at all.
+ *
+ * Reported by a consumer building flyovers, who could express a sloped deck as a hull already and
+ * found that standing on one did not hold them up. The alternative available to them was to add
+ * every deck to a `PhysicsWorld` as a static body as well — the same geometry twice, in two
+ * structures that can disagree.
+ *
+ * **It is a `GroundSurface` and not a new seam, which is what makes it worth having.** Everything
+ * that stands on ground already takes one: the character controller, the raycast vehicle, the
+ * third-person camera boom, the rain field. And because `heightSurface` takes a list of surfaces,
+ * a world can be terrain *and* slabs without either knowing about the other:
+ *
+ * ```ts
+ * const ground = new CompositeSurface([
+ *   heightSurface((x, z) => terrainAt(x, z)),
+ *   colliderSurface(decks, { minY: -10, maxY: 60 }),
+ * ]);
+ * ```
+ *
+ * **What it is not.** It is not a replacement for the sweep: the sweep is what stops a body walking
+ * *into* a collider, and this is what stops it falling *through* one. A consumer wants both, and
+ * they read the same set.
+ */
+export interface ColliderSurfaceOptions {
+    /**
+     * The vertical extent to look through, metres.
+     *
+     * **Required, and guessing would be worse than asking.** A ground query is a column, and the
+     * spatial hash walks every cell in it — an unbounded column over a 4 m grid is half a million
+     * cells and a frozen frame. A consumer knows how tall their world is; the engine does not, and a
+     * default would be wrong quietly.
+     */
+    readonly minY: number;
+    readonly maxY: number;
+}
+export declare function colliderSurface(set: ColliderSet, options: ColliderSurfaceOptions): GroundSurface;