@driftengine/physics 3.61.0

package/dist/fingerprint.js

@@ -0,0 +1,139 @@
+import { STRIDE_BYTES } from './colliderSet.js';
+/**
+ * A stable hash of the static geometry a simulation ran against.
+ *
+ * A recording made of a deterministic simulation is only replayable against the
+ * world it was recorded in. When world generation changes — a fixed bug, a
+ * retuned curve, a new build — recordings from before it desync, and they do it
+ * *silently*: the run is reproduced faithfully against geometry that is no longer
+ * there, so what appears on screen is a body moving through empty space with
+ * nothing to explain it.
+ *
+ * Storing this alongside a recording lets a caller compare the world it has
+ * against the world the recording was made in, and refuse rather than guess.
+ *
+ * **Determinism is the whole contract.** The same colliders must give the same
+ * string on every machine and in every build, so this reads the raw bytes of the
+ * bounds array: a float's decimal rendering is a platform question and its bit
+ * pattern is not. Nothing here iterates a `Map` or a `Set`, both of which would
+ * make the answer depend on insertion order.
+ *
+ * **No tolerance, deliberately.** A sub-millimetre difference changes the answer.
+ * Whether a given difference *matters* is the caller's judgement, and a hash that
+ * quietly rounded would take that judgement away from every caller at once.
+ *
+ * FNV-1a over 64 bits, carried as two 32-bit halves because JavaScript's bitwise
+ * operators are 32-bit and a single accumulator would silently lose the top half.
+ * Not a cryptographic hash: this detects change, it does not resist forgery, and
+ * a caller that needs the second property needs `crypto.subtle` and an await.
+ *
+ * **On a set that has been mutated, this answers "the same set with the same history" and not
+ * "the same world".** A set can take and drop groups now, and a slot freed by one region is
+ * refilled by another, so the same geometry sits at different indices depending on the path
+ * driven to reach it.
+ *
+ * *Replay is not what that costs.* The same inputs drive the same path, which produces the same
+ * load order and so the same slots, and a recording replays against the set it was recorded
+ * against exactly as it always did. What it costs is comparing two *sessions* that arrived at the
+ * same world by different routes.
+ *
+ * **`fingerprintBodies`'s escape hatch does not transfer**, which is worth saying because the two
+ * functions are otherwise the same construction. There, a caller wanting the multiset sorts what
+ * it feeds in, because it hands over an array. Here a caller hands over an object whose slot order
+ * is a load history they neither chose nor can observe, so there is nothing for them to sort. A
+ * canonical variant hashing live slots sorted by their packed bytes would answer the cross-session
+ * question and is about fifteen lines; it is not here because nothing is asking it yet.
+ */
+export function fingerprintColliders(set) {
+    // Two FNV-1a streams, offset-basis and prime per the 32-bit spec.
+    let low = 0x811c9dc5;
+    let high = 0x811c9dc5;
+    /*
+     * The count first, so two sets whose float payloads coincide still differ, and
+     * four bytes of it rather than one — a set of exactly 256 colliders must not
+     * hash as a set of none.
+     *
+     * The *live* count, which is what `count` has always meant. A set that has dropped a group
+     * holds slots it does not use, and hashing those would make the answer depend on how much room
+     * happened to be spare.
+     */
+    const count = set.count >>> 0;
+    mix(count & 0xff);
+    mix((count >>> 8) & 0xff);
+    mix((count >>> 16) & 0xff);
+    mix((count >>> 24) & 0xff);
+    /*
+     * **Live slots only, in index order, and this produces exactly the stream it always did for a
+     * set built by the constructor.** Such a set is dense — every slot live, `capacity` equal to
+     * `count` — so the walk covers the whole of `data` and skips nothing, which is why the golden
+     * strings in the tests beside this file did not move when liveness arrived. Only a set that has
+     * grown or dropped a group can differ here, and no recording predates those.
+     */
+    const bytes = new Uint8Array(set.data.buffer, set.data.byteOffset, set.data.byteLength);
+    for (let slot = 0; slot < set.capacity; slot++) {
+        if (!set.liveAt(slot))
+            continue;
+        const from = slot * STRIDE_BYTES;
+        for (let i = from; i < from + STRIDE_BYTES; i++)
+            mix(bytes[i] ?? 0);
+    }
+    return hex(high) + hex(low);
+    function mix(byte) {
+        low ^= byte & 0xff;
+        low = Math.imul(low, 0x01000193) >>> 0;
+        /*
+         * The high half consumes the low half's *current* state rather than the same
+         * input byte, so it cannot degenerate into a copy of it. Without this the
+         * string would be sixteen characters carrying thirty-two bits of information,
+         * which every equality test above would still pass.
+         */
+        high ^= low & 0xff;
+        high = Math.imul(high, 0x01000193) >>> 0;
+    }
+}
+function hex(value) {
+    return value.toString(16).padStart(8, '0');
+}
+/**
+ * A stable hash of every body's state, for comparing one run against another.
+ *
+ * The same FNV-1a construction and the same reasoning as `fingerprintColliders`: the raw bytes of a
+ * float, because its decimal rendering is a platform question and its bit pattern is not. No
+ * tolerance, deliberately — whether a difference *matters* is the caller's judgement, and a hash
+ * that quietly rounded would take that judgement away from every caller at once.
+ *
+ * **Order matters here and that is the point.** Two runs of the same scene must agree body for
+ * body. A caller comparing scenes *built* in different orders wants the multiset instead, and has
+ * to sort what it feeds in — see the permutation gate beside the solver baseline, which does.
+ */
+export function fingerprintBodies(bodies) {
+    let low = 0x811c9dc5;
+    let high = 0x811c9dc5;
+    const channels = [
+        bodies.posX,
+        bodies.posY,
+        bodies.posZ,
+        bodies.rotX,
+        bodies.rotY,
+        bodies.rotZ,
+        bodies.rotW,
+        bodies.velX,
+        bodies.velY,
+        bodies.velZ,
+        bodies.angX,
+        bodies.angY,
+        bodies.angZ,
+    ];
+    const scratch = new Float32Array(1);
+    const view = new Uint8Array(scratch.buffer);
+    for (let i = 0; i < bodies.count; i++) {
+        for (const channel of channels) {
+            scratch[0] = channel[i] ?? 0;
+            for (let b = 0; b < 4; b++) {
+                low = Math.imul(low ^ (view[b] ?? 0), 0x01000193) >>> 0;
+                high = Math.imul(high ^ (view[3 - b] ?? 0), 0x01000193) >>> 0;
+            }
+        }
+    }
+    return `${low.toString(16).padStart(8, '0')}${high.toString(16).padStart(8, '0')}`;
+}

package/dist/groundMotor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Accelerate along a wish direction, Quake's way.
+ *
+ * **Six lines, and the most reimplemented six lines in movement code.** Every kinematic character
+ * needs them and the trap is specific: the amount added is clamped against *how much of the wish
+ * speed the body does not already have along the wish direction*, not against the wish speed
+ * itself. Get that wrong and a body accelerates to `wishSpeed` in every direction at once, which
+ * is a body that cannot turn; leave the clamp out and it accelerates for ever.
+ *
+ * **What the projection buys is air-strafing.** `currentSpeed` is the *dot product*, so a body
+ * moving fast in one direction still has room to add speed at right angles to it — which is why
+ * turning while airborne gains speed in every game descended from Quake, and why it is a verb
+ * players learn rather than a bug. A consumer that wants that behaviour gets it; one that does not
+ * passes a small `accel` while airborne, which is what the parameter is for.
+ *
+ * **`accel` is what a consumer decides**, and it is where every game's own answer lives: a surface
+ * that grips or slips, a motor that is winded, a slope that foreshortens the thrust. This takes
+ * the number and applies it, which is the boundary this whole package draws.
+ */
+/** Anything with a planar velocity. Declared structurally so nothing is imported either way. */
+export interface PlanarState {
+    velX: number;
+    velZ: number;
+}
+/**
+ * @param wishX Unit direction the body is asking to travel in.
+ * @param wishZ
+ * @param wishSpeed How fast it is asking to go, in that direction.
+ * @param accel Metres per second squared this tick may deliver.
+ * @returns How much speed was actually added, so a consumer can tell a stalled motor from a
+ *   satisfied one — a demand the ground refuses is exactly the interesting case for anything
+ *   drawing wheelspin or smoke.
+ */
+export declare function accelerateAlong(state: PlanarState, wishX: number, wishZ: number, wishSpeed: number, accel: number, dt: number): number;

package/dist/groundMotor.js

@@ -0,0 +1,41 @@
+/**
+ * Accelerate along a wish direction, Quake's way.
+ *
+ * **Six lines, and the most reimplemented six lines in movement code.** Every kinematic character
+ * needs them and the trap is specific: the amount added is clamped against *how much of the wish
+ * speed the body does not already have along the wish direction*, not against the wish speed
+ * itself. Get that wrong and a body accelerates to `wishSpeed` in every direction at once, which
+ * is a body that cannot turn; leave the clamp out and it accelerates for ever.
+ *
+ * **What the projection buys is air-strafing.** `currentSpeed` is the *dot product*, so a body
+ * moving fast in one direction still has room to add speed at right angles to it — which is why
+ * turning while airborne gains speed in every game descended from Quake, and why it is a verb
+ * players learn rather than a bug. A consumer that wants that behaviour gets it; one that does not
+ * passes a small `accel` while airborne, which is what the parameter is for.
+ *
+ * **`accel` is what a consumer decides**, and it is where every game's own answer lives: a surface
+ * that grips or slips, a motor that is winded, a slope that foreshortens the thrust. This takes
+ * the number and applies it, which is the boundary this whole package draws.
+ */
+/**
+ * @param wishX Unit direction the body is asking to travel in.
+ * @param wishZ
+ * @param wishSpeed How fast it is asking to go, in that direction.
+ * @param accel Metres per second squared this tick may deliver.
+ * @returns How much speed was actually added, so a consumer can tell a stalled motor from a
+ *   satisfied one — a demand the ground refuses is exactly the interesting case for anything
+ *   drawing wheelspin or smoke.
+ */
+export function accelerateAlong(state, wishX, wishZ, wishSpeed, accel, dt) {
+    if (wishSpeed < 1e-6)
+        return 0;
+    /* How much of the wish speed the body already has *along the wish direction*. */
+    const currentSpeed = state.velX * wishX + state.velZ * wishZ;
+    const addSpeed = wishSpeed - currentSpeed;
+    if (addSpeed <= 0)
+        return 0;
+    const added = Math.min(accel * dt, addSpeed);
+    state.velX += wishX * added;
+    state.velZ += wishZ * added;
+    return added;
+}

package/dist/heightfieldShape.d.ts

@@ -0,0 +1,128 @@
+import type { Aabb } from './collide/index.ts';
+import type { ConvexShape } from './shape.ts';
+/**
+ * A heightfield as a collision shape: the samples, and every triangle generated from them.
+ *
+ * **The whole of this is a memory argument.** Terrain already collides, as a static triangle mesh —
+ * `meshShape` takes exactly the arrays a heightfield renderer hands back, so the geometry drawn is
+ * the geometry collided with, which is the property that matters most and the reason that path is
+ * still the right one for a level. What it costs is the triangles: measured on a 129-square field,
+ * the positions and indices alone are more than five times the bytes of the heights they were built
+ * from, before the tree over them is counted at all.
+ *
+ * A heightfield needs none of it. The samples *are* the geometry, the cell under a body is an index
+ * rather than a tree query, and every triangle, plane and edge classification is arithmetic on four
+ * numbers. So this carries the heights and nothing else.
+ *
+ * **What it is not is a second narrow phase.** `meshContact.ts` owns the contact rules — many
+ * manifolds rather than one, one-sided triangles, the interior-edge filter that stops a box
+ * stumbling on a flat seam — and this changes none of them. It is a *source of triangles*, and the
+ * only thing it replaces is where they come from: an index range instead of a tree, and four
+ * samples instead of an index buffer. That split is the 2026-08-13 rule applied to the one file in
+ * this package it would be most expensive to have two of.
+ *
+ * **The triangulation is stated here and mirrored in `@driftengine/terrain`**, which draws the
+ * picture this collides with. It has to be: `@driftengine/physics` imports no other engine package,
+ * so the rule cannot be shared as code. What is shared instead is an assertion — that package's
+ * `terrainCollision.test.ts` compares the two — which is the same arrangement `glDepthFunc` has with
+ * `DEPTH_COMPARE` for the same reason. Track L already paid once for two copies of this rule
+ * disagreeing, when a mesh was split one way and its query read the other, so the mirror is guarded
+ * rather than trusted.
+ */
+export interface Heightfield {
+    /** Samples across x. At least two, since one sample is not a cell. */
+    readonly width: number;
+    /** Samples across z. */
+    readonly depth: number;
+    /** Metres between samples, the same both ways. */
+    readonly spacingM: number;
+    /** `width * depth` heights, row-major with x running fastest. Kept, not copied. */
+    readonly heights: Float32Array;
+    /**
+     * World position of sample `(0, 0)`, or nothing for a field at the origin. Its own y is added to
+     * every height.
+     *
+     * **Three numbers in an array rather than three fields, and that is the boundary doing its work.**
+     * `@driftengine/physics` imports no other engine package, so it cannot know what a `Terrain` is —
+     * but a `Terrain` *is* one of these, structurally: same names, same meanings, an `origin` that is
+     * a `Float32Array`. So `heightfieldShape(terrain)` type-checks with no import in either
+     * direction, and the seam is a shape rather than a dependency.
+     */
+    readonly origin?: ArrayLike<number>;
+}
+/**
+ * The three corners of a triangle, in the field's own space.
+ *
+ * **The cell is split along `a`-`c`**, the diagonal from its own sample to the one across it, and
+ * the two halves are `a, d, c` and `a, c, b` — wound so the face normal points up. That is the same
+ * split `@driftengine/terrain`'s `heightfieldPatch` emits, and it has to be: a collider split the
+ * other way disagrees with the picture by up to the height of a cell everywhere but the
+ * anti-diagonal, and nothing about that failure is visible.
+ *
+ * `out` takes nine numbers.
+ */
+export declare function fieldCorners(field: Heightfield, triangle: number, out: Float64Array): void;
+/**
+ * The triangle's outward plane as `nx, ny, nz, d`, with `d = n · v0`.
+ *
+ * Normalised, and pointing up: a heightfield has no overhangs, so every face of it faces the sky.
+ * A degenerate triangle — two samples at the same place, which a spacing of zero would give and
+ * nothing else does — writes a zero normal, which the contact code skips exactly as it does for a
+ * degenerate mesh triangle.
+ */
+export declare function fieldPlane(field: Heightfield, triangle: number, out: Float64Array): void;
+/**
+ * Which of a triangle's three edges a contact normal may come off, as three bits.
+ *
+ * **Computed rather than precomputed, and that is the saving.** `meshShape` walks every edge of a
+ * level once at build time and stores three bits per triangle; a field's answer is four samples and
+ * a subtraction, so there is nothing to store. Edge `i` runs from local vertex `i` to `(i + 1) % 3`,
+ * matching `TriangleMesh.convexEdges` exactly, because `meshContact.ts` reads both the same way.
+ *
+ * The rule is `meshShape`'s: an edge is convex where the neighbouring triangle's opposite vertex
+ * sits *below* this triangle's plane, and where the edge has no neighbour at all. A coplanar seam is
+ * **not** convex, which is the whole of the interior-edge filter — a flat floor made of triangles
+ * must not push a body back along the joins.
+ *
+ * Each of the five edges a cell has meets its neighbour at a single lattice point, and the
+ * neighbour exists exactly when that point is inside the field:
+ *
+ * - half 0: edge 0 at `(cx - 1, cz)`, edge 1 at `(cx + 1, cz + 2)`, edge 2 — the diagonal — at
+ *   `(cx + 1, cz)`, which is the other half's own third corner.
+ * - half 1: edge 0 — the same diagonal — at `(cx, cz + 1)`, edge 1 at `(cx + 2, cz + 1)`, edge 2 at
+ *   `(cx, cz - 1)`.
+ */
+export declare function fieldConvexEdges(field: Heightfield, triangle: number): number;
+/**
+ * The triangles a box could touch, written into `out`, as a count.
+ *
+ * **An index range rather than a tree**, which is the other half of what a heightfield buys: the
+ * cells a box covers are `(minX - originX) / spacing` to `(maxX - originX) / spacing`, and the same
+ * in z. There is no structure to build, to keep, or to rebuild when the field changes.
+ *
+ * **And a height test per cell, which is most of the saving in practice.** A body on a hillside
+ * covers a wide footprint in x and z and touches almost none of it, the rest being metres above or
+ * below — so a cell whose four samples all sit outside the box's own y range is skipped before the
+ * narrow phase ever sees it.
+ *
+ * Fills to `out.length` and stops, exactly as `DynamicTree.query` does, so the caller's grow-and-
+ * retry loop works unchanged.
+ */
+export declare function fieldCandidates(field: Heightfield, box: Aabb, out: Int32Array): number;
+/**
+ * Build a heightfield collision shape.
+ *
+ * Returns a `ConvexShape` whose `triangles` names the field — so every existing test of "is this a
+ * mesh" answers yes and every rule that follows from it holds: refused as a kinematic collider,
+ * refused on anything but a static body, and given a static body's own zero mass tensor. Its
+ * `vertices` are the eight corners of the field's bounds, so the broad phase measures the right box,
+ * and its `faceNormals` and `edgeDirs` are empty for the reason `meshShape` gives: a field has no
+ * separating axes worth enumerating, and handing the kinematic sweep the box's three would make a
+ * hillside a solid brick.
+ *
+ * **The heights are kept and not copied**, the same bargain `meshShape` makes with a level's
+ * vertices: a field is the thing being avoided allocating twice. A caller must not go on mutating
+ * them, which is stated here because nothing enforces it — and unlike a mesh there is nothing to
+ * rebuild if they do, so a caller who *wants* a changing field may mutate and the collider follows.
+ */
+export declare function heightfieldShape(field: Heightfield): ConvexShape;

package/dist/heightfieldShape.js

@@ -0,0 +1,328 @@
+/** How many cells a field has across x, which is one fewer than its samples. */
+function cellsX(field) {
+    return field.width - 1;
+}
+function cellsZ(field) {
+    return field.depth - 1;
+}
+/** One sample, by grid index, clamped — a query at the rim reads the rim. */
+function sample(field, ix, iz) {
+    const x = ix < 0 ? 0 : ix > field.width - 1 ? field.width - 1 : ix;
+    const z = iz < 0 ? 0 : iz > field.depth - 1 ? field.depth - 1 : iz;
+    return (field.origin?.[1] ?? 0) + (field.heights[z * field.width + x] ?? 0);
+}
+/** Where sample `(0, 0)` stands, along x and z. */
+function originX(field) {
+    return field.origin?.[0] ?? 0;
+}
+function originZ(field) {
+    return field.origin?.[2] ?? 0;
+}
+/** Whether a lattice point is inside the field, which is what says an edge has a neighbour. */
+function inside(field, ix, iz) {
+    return ix >= 0 && iz >= 0 && ix < field.width && iz < field.depth;
+}
+/**
+ * The three corners of a triangle, in the field's own space.
+ *
+ * **The cell is split along `a`-`c`**, the diagonal from its own sample to the one across it, and
+ * the two halves are `a, d, c` and `a, c, b` — wound so the face normal points up. That is the same
+ * split `@driftengine/terrain`'s `heightfieldPatch` emits, and it has to be: a collider split the
+ * other way disagrees with the picture by up to the height of a cell everywhere but the
+ * anti-diagonal, and nothing about that failure is visible.
+ *
+ * `out` takes nine numbers.
+ */
+export function fieldCorners(field, triangle, out) {
+    const across = cellsX(field);
+    const cell = triangle >> 1;
+    const half = triangle & 1;
+    const cx = cell % across;
+    const cz = (cell - cx) / across;
+    const step = field.spacingM;
+    const x0 = originX(field) + cx * step;
+    const x1 = x0 + step;
+    const z0 = originZ(field) + cz * step;
+    const z1 = z0 + step;
+    if (half === 0) {
+        /* a, d, c */
+        out[0] = x0;
+        out[1] = sample(field, cx, cz);
+        out[2] = z0;
+        out[3] = x0;
+        out[4] = sample(field, cx, cz + 1);
+        out[5] = z1;
+        out[6] = x1;
+        out[7] = sample(field, cx + 1, cz + 1);
+        out[8] = z1;
+        return;
+    }
+    /* a, c, b */
+    out[0] = x0;
+    out[1] = sample(field, cx, cz);
+    out[2] = z0;
+    out[3] = x1;
+    out[4] = sample(field, cx + 1, cz + 1);
+    out[5] = z1;
+    out[6] = x1;
+    out[7] = sample(field, cx + 1, cz);
+    out[8] = z0;
+}
+/** Scratch for a plane derived from corners, so nothing here allocates in the tick. */
+const CORNERS = new Float64Array(9);
+/**
+ * The triangle's outward plane as `nx, ny, nz, d`, with `d = n · v0`.
+ *
+ * Normalised, and pointing up: a heightfield has no overhangs, so every face of it faces the sky.
+ * A degenerate triangle — two samples at the same place, which a spacing of zero would give and
+ * nothing else does — writes a zero normal, which the contact code skips exactly as it does for a
+ * degenerate mesh triangle.
+ */
+export function fieldPlane(field, triangle, out) {
+    fieldCorners(field, triangle, CORNERS);
+    const ax = CORNERS[0] ?? 0;
+    const ay = CORNERS[1] ?? 0;
+    const az = CORNERS[2] ?? 0;
+    const ux = (CORNERS[3] ?? 0) - ax;
+    const uy = (CORNERS[4] ?? 0) - ay;
+    const uz = (CORNERS[5] ?? 0) - az;
+    const vx = (CORNERS[6] ?? 0) - ax;
+    const vy = (CORNERS[7] ?? 0) - ay;
+    const vz = (CORNERS[8] ?? 0) - az;
+    let nx = uy * vz - uz * vy;
+    let ny = uz * vx - ux * vz;
+    let nz = ux * vy - uy * vx;
+    const length = Math.sqrt(nx * nx + ny * ny + nz * nz);
+    if (length > 1e-12) {
+        nx /= length;
+        ny /= length;
+        nz /= length;
+    }
+    else {
+        nx = 0;
+        ny = 0;
+        nz = 0;
+    }
+    out[0] = nx;
+    out[1] = ny;
+    out[2] = nz;
+    out[3] = nx * ax + ny * ay + nz * az;
+}
+/** How far a neighbour's opposite sample must sit below the plane before the fold has a direction. */
+const COPLANAR_M = 1e-5;
+/** Scratch for the classification, which runs per candidate triangle inside the tick. */
+const PLANE = new Float64Array(4);
+/**
+ * Which of a triangle's three edges a contact normal may come off, as three bits.
+ *
+ * **Computed rather than precomputed, and that is the saving.** `meshShape` walks every edge of a
+ * level once at build time and stores three bits per triangle; a field's answer is four samples and
+ * a subtraction, so there is nothing to store. Edge `i` runs from local vertex `i` to `(i + 1) % 3`,
+ * matching `TriangleMesh.convexEdges` exactly, because `meshContact.ts` reads both the same way.
+ *
+ * The rule is `meshShape`'s: an edge is convex where the neighbouring triangle's opposite vertex
+ * sits *below* this triangle's plane, and where the edge has no neighbour at all. A coplanar seam is
+ * **not** convex, which is the whole of the interior-edge filter — a flat floor made of triangles
+ * must not push a body back along the joins.
+ *
+ * Each of the five edges a cell has meets its neighbour at a single lattice point, and the
+ * neighbour exists exactly when that point is inside the field:
+ *
+ * - half 0: edge 0 at `(cx - 1, cz)`, edge 1 at `(cx + 1, cz + 2)`, edge 2 — the diagonal — at
+ *   `(cx + 1, cz)`, which is the other half's own third corner.
+ * - half 1: edge 0 — the same diagonal — at `(cx, cz + 1)`, edge 1 at `(cx + 2, cz + 1)`, edge 2 at
+ *   `(cx, cz - 1)`.
+ */
+export function fieldConvexEdges(field, triangle) {
+    const across = cellsX(field);
+    const cell = triangle >> 1;
+    const half = triangle & 1;
+    const cx = cell % across;
+    const cz = (cell - cx) / across;
+    fieldPlane(field, triangle, PLANE);
+    let bits = 0b111;
+    for (let e = 0; e < 3; e++) {
+        let ox = 0;
+        let oz = 0;
+        if (half === 0) {
+            if (e === 0) {
+                ox = cx - 1;
+                oz = cz;
+            }
+            else if (e === 1) {
+                ox = cx + 1;
+                oz = cz + 2;
+            }
+            else {
+                ox = cx + 1;
+                oz = cz;
+            }
+        }
+        else if (e === 0) {
+            ox = cx;
+            oz = cz + 1;
+        }
+        else if (e === 1) {
+            ox = cx + 2;
+            oz = cz + 1;
+        }
+        else {
+            ox = cx;
+            oz = cz - 1;
+        }
+        /* No neighbour is a boundary edge, and a boundary edge is convex: there is nothing on the other
+           side for a body to be caught between. */
+        if (!inside(field, ox, oz))
+            continue;
+        const px = originX(field) + ox * field.spacingM;
+        const py = sample(field, ox, oz);
+        const pz = originZ(field) + oz * field.spacingM;
+        const height = px * (PLANE[0] ?? 0) + py * (PLANE[1] ?? 0) + pz * (PLANE[2] ?? 0) - (PLANE[3] ?? 0);
+        if (!(height < -COPLANAR_M))
+            bits &= ~(1 << e);
+    }
+    return bits;
+}
+/**
+ * The triangles a box could touch, written into `out`, as a count.
+ *
+ * **An index range rather than a tree**, which is the other half of what a heightfield buys: the
+ * cells a box covers are `(minX - originX) / spacing` to `(maxX - originX) / spacing`, and the same
+ * in z. There is no structure to build, to keep, or to rebuild when the field changes.
+ *
+ * **And a height test per cell, which is most of the saving in practice.** A body on a hillside
+ * covers a wide footprint in x and z and touches almost none of it, the rest being metres above or
+ * below — so a cell whose four samples all sit outside the box's own y range is skipped before the
+ * narrow phase ever sees it.
+ *
+ * Fills to `out.length` and stops, exactly as `DynamicTree.query` does, so the caller's grow-and-
+ * retry loop works unchanged.
+ */
+export function fieldCandidates(field, box, out) {
+    const step = field.spacingM;
+    const across = cellsX(field);
+    const down = cellsZ(field);
+    const ox = originX(field);
+    const oz = originZ(field);
+    const fromX = Math.max(0, Math.floor((box.minX - ox) / step));
+    const toX = Math.min(across - 1, Math.floor((box.maxX - ox) / step));
+    const fromZ = Math.max(0, Math.floor((box.minZ - oz) / step));
+    const toZ = Math.min(down - 1, Math.floor((box.maxZ - oz) / step));
+    let count = 0;
+    for (let cz = fromZ; cz <= toZ; cz++) {
+        for (let cx = fromX; cx <= toX; cx++) {
+            const a = sample(field, cx, cz);
+            const b = sample(field, cx + 1, cz);
+            const c = sample(field, cx + 1, cz + 1);
+            const d = sample(field, cx, cz + 1);
+            const low = Math.min(a, b, c, d);
+            const high = Math.max(a, b, c, d);
+            if (high < box.minY || low > box.maxY)
+                continue;
+            const cell = cz * across + cx;
+            if (count === out.length)
+                return count;
+            out[count++] = cell * 2;
+            if (count === out.length)
+                return count;
+            out[count++] = cell * 2 + 1;
+        }
+    }
+    return count;
+}
+/**
+ * Build a heightfield collision shape.
+ *
+ * Returns a `ConvexShape` whose `triangles` names the field — so every existing test of "is this a
+ * mesh" answers yes and every rule that follows from it holds: refused as a kinematic collider,
+ * refused on anything but a static body, and given a static body's own zero mass tensor. Its
+ * `vertices` are the eight corners of the field's bounds, so the broad phase measures the right box,
+ * and its `faceNormals` and `edgeDirs` are empty for the reason `meshShape` gives: a field has no
+ * separating axes worth enumerating, and handing the kinematic sweep the box's three would make a
+ * hillside a solid brick.
+ *
+ * **The heights are kept and not copied**, the same bargain `meshShape` makes with a level's
+ * vertices: a field is the thing being avoided allocating twice. A caller must not go on mutating
+ * them, which is stated here because nothing enforces it — and unlike a mesh there is nothing to
+ * rebuild if they do, so a caller who *wants* a changing field may mutate and the collider follows.
+ */
+export function heightfieldShape(field) {
+    if (!(field.width >= 2)) {
+        throw new Error(`heightfieldShape: width must be at least 2, got ${field.width}`);
+    }
+    if (!(field.depth >= 2)) {
+        throw new Error(`heightfieldShape: depth must be at least 2, got ${field.depth}`);
+    }
+    if (!(field.spacingM > 0)) {
+        throw new Error(`heightfieldShape: spacing must be above zero, got ${field.spacingM}`);
+    }
+    if (field.heights.length !== field.width * field.depth) {
+        throw new Error(`heightfieldShape: ${field.width} by ${field.depth} needs ${field.width * field.depth} ` +
+            `heights, got ${field.heights.length}`);
+    }
+    let low = Infinity;
+    let high = -Infinity;
+    for (let i = 0; i < field.heights.length; i++) {
+        const h = field.heights[i] ?? 0;
+        if (h < low)
+            low = h;
+        if (h > high)
+            high = h;
+    }
+    const baseX = originX(field);
+    const baseY = field.origin?.[1] ?? 0;
+    const baseZ = originZ(field);
+    const minX = baseX;
+    const maxX = baseX + cellsX(field) * field.spacingM;
+    const minY = baseY + low;
+    const maxY = baseY + high;
+    const minZ = baseZ;
+    const maxZ = baseZ + cellsZ(field) * field.spacingM;
+    return {
+        vertices: new Float32Array([
+            minX,
+            minY,
+            minZ,
+            maxX,
+            minY,
+            minZ,
+            minX,
+            maxY,
+            minZ,
+            maxX,
+            maxY,
+            minZ,
+            minX,
+            minY,
+            maxZ,
+            maxX,
+            minY,
+            maxZ,
+            minX,
+            maxY,
+            maxZ,
+            maxX,
+            maxY,
+            maxZ,
+        ]),
+        faceNormals: new Float32Array(0),
+        edgeDirs: new Float32Array(0),
+        radius: 0,
+        sideRadius: 0,
+        boundRadius: Math.sqrt(Math.max(minX * minX, maxX * maxX) +
+            Math.max(minY * minY, maxY * maxY) +
+            Math.max(minZ * minZ, maxZ * maxZ)),
+        facePlanes: new Float32Array(0),
+        faceVertexStart: new Uint16Array(0),
+        faceVertexIndices: new Uint16Array(0),
+        triangles: {
+            positions: new Float32Array(0),
+            indices: new Uint32Array(0),
+            triangleCount: cellsX(field) * cellsZ(field) * 2,
+            planes: new Float32Array(0),
+            convexEdges: new Uint8Array(0),
+            tree: null,
+            field,
+        },
+    };
+}