@driftengine/terrain 3.61.0

package/dist/heightfieldPatch.js

@@ -0,0 +1,159 @@
+/** How far along an edge a vertex sits on the coarse lattice, and the two coarse heights round it. */
+function chord(low, high, at, height) {
+    if (high === low)
+        return height(low);
+    const t = (at - low) / (high - low);
+    return height(low) * (1 - t) + height(high) * t;
+}
+export function heightfieldPatch(terrain, options) {
+    const step = Math.round(options.step ?? 1);
+    const cells = Math.round(options.cells);
+    if (!(step >= 1))
+        throw new Error(`heightfieldPatch: step must be at least 1, got ${step}`);
+    if (cells % step !== 0) {
+        throw new Error(`heightfieldPatch: a step of ${step} does not divide ${cells} cells, so a strip would go undrawn`);
+    }
+    if (options.x < 0 ||
+        options.z < 0 ||
+        options.x + cells > terrain.width - 1 ||
+        options.z + cells > terrain.depth - 1) {
+        throw new Error(`heightfieldPatch: a patch at ${options.x}, ${options.z} of ${cells} cells runs off a field ` +
+            `of ${terrain.width} by ${terrain.depth}`);
+    }
+    const neighbours = options.neighbours ?? {};
+    for (const [side, theirs] of Object.entries(neighbours)) {
+        if (theirs === undefined)
+            continue;
+        if (theirs % step !== 0) {
+            throw new Error(`heightfieldPatch: a neighbour on ${side} drawn at ${theirs} cannot be matched by a patch ` +
+                `drawn at ${step}, since one does not divide the other`);
+        }
+    }
+    const across = cells / step;
+    const vertices = (across + 1) * (across + 1);
+    const spacing = terrain.spacingM;
+    const originX = (terrain.origin[0] ?? 0) + options.x * spacing;
+    const originZ = (terrain.origin[2] ?? 0) + options.z * spacing;
+    const materials = options.materials;
+    const colour = options.color ?? [0.42, 0.45, 0.36];
+    const emissive = options.emissive ?? 0;
+    const positions = new Float32Array(vertices * 3);
+    const normals = new Float32Array(vertices * 3);
+    const colors = new Float32Array(vertices * 3);
+    const emissives = new Float32Array(vertices);
+    /* Allocated only where something shines, which is the promise `MeshData.specular` makes: geometry
+       that does not shine produces exactly the mesh it produced before the attribute existed. */
+    const speculars = materials?.shines === true ? new Float32Array(vertices) : null;
+    const indices = new Uint32Array(across * across * 6);
+    const normal = new Float32Array(3);
+    const shade = new Float32Array(3);
+    for (let row = 0; row <= across; row++) {
+        for (let column = 0; column <= across; column++) {
+            const at = (row * (across + 1) + column) * 3;
+            const x = originX + column * step * spacing;
+            const z = originZ + row * step * spacing;
+            /*
+             * The field's own height, unless this vertex is on an edge whose neighbour is coarser — in
+             * which case it takes that neighbour's chord instead, and the two patches then share one
+             * polyline. A corner sits on two edges and is a multiple of every step, so it is never moved
+             * and the two rules cannot disagree about it.
+             */
+            let y = terrain.heightAt(x, z);
+            const onMinusX = column === 0;
+            const onPlusX = column === across;
+            const onMinusZ = row === 0;
+            const onPlusZ = row === across;
+            if (onMinusX && neighbours.minusX !== undefined) {
+                y = matched(row, neighbours.minusX, (index) => terrain.heightAt(x, originZ + index * spacing));
+            }
+            else if (onPlusX && neighbours.plusX !== undefined) {
+                y = matched(row, neighbours.plusX, (index) => terrain.heightAt(x, originZ + index * spacing));
+            }
+            else if (onMinusZ && neighbours.minusZ !== undefined) {
+                y = matched(column, neighbours.minusZ, (index) => terrain.heightAt(originX + index * spacing, z));
+            }
+            else if (onPlusZ && neighbours.plusZ !== undefined) {
+                y = matched(column, neighbours.plusZ, (index) => terrain.heightAt(originX + index * spacing, z));
+            }
+            positions[at] = x;
+            positions[at + 1] = y;
+            positions[at + 2] = z;
+            /* The field's normal and never the patch's, so two patches shade identically along the edge
+               they share. `heightfield.ts` argues that where the query is defined. */
+            terrain.normalAt(x, z, normal);
+            normals[at] = normal[0] ?? 0;
+            normals[at + 1] = normal[1] ?? 1;
+            normals[at + 2] = normal[2] ?? 0;
+            if (materials === undefined) {
+                colors[at] = colour[0] ?? 1;
+                colors[at + 1] = colour[1] ?? 1;
+                colors[at + 2] = colour[2] ?? 1;
+                emissives[row * (across + 1) + column] = emissive;
+            }
+            else {
+                /* The field's own extent, so the blend is continuous across every patch boundary. */
+                const u = terrain.extentX === 0 ? 0 : (x - (terrain.origin[0] ?? 0)) / terrain.extentX;
+                const w = terrain.extentZ === 0 ? 0 : (z - (terrain.origin[2] ?? 0)) / terrain.extentZ;
+                materials.colorAt(u, w, shade);
+                colors[at] = shade[0] ?? 1;
+                colors[at + 1] = shade[1] ?? 1;
+                colors[at + 2] = shade[2] ?? 1;
+                emissives[row * (across + 1) + column] = materials.emissiveAt(u, w);
+                if (speculars !== null) {
+                    speculars[row * (across + 1) + column] = materials.specularAt(u, w);
+                }
+            }
+        }
+    }
+    /**
+     * Where a vertex on a matched edge actually sits.
+     *
+     * `index` counts drawn cells along the edge and `theirs` is the neighbour's step in field cells,
+     * so `theirs / step` drawn vertices span one of the neighbour's. A vertex on that lattice keeps
+     * the field; one between two of them takes the chord.
+     */
+    function matched(index, theirs, height) {
+        const ratio = theirs / step;
+        const low = Math.floor(index / ratio) * ratio;
+        const high = Math.min(across, low + ratio);
+        return chord(low * step, high * step, index * step, height);
+    }
+    let at = 0;
+    for (let row = 0; row < across; row++) {
+        for (let column = 0; column < across; column++) {
+            const a = row * (across + 1) + column;
+            const b = a + 1;
+            const d = a + (across + 1);
+            const c = d + 1;
+            /*
+             * **Split along `a`-`c`, which is the diagonal `Terrain.heightAt` reads.** The two surfaces
+             * are the same surface or a query answers a place the picture does not have.
+             *
+             * This said `a, d, b` and `b, d, c` until 2026-09-02, which is the *other* diagonal — the
+             * mesh was split one way and the query read the other, so the two disagreed by up to the
+             * height of the cell everywhere except along the anti-diagonal itself. **Nothing caught it
+             * for two rows**: every vertex lies on both triangulations, so a per-vertex assertion passes
+             * either way, and the test fields were of the form `f(x) + g(z)` — separable, and for a
+             * separable field both diagonals give the identical surface. It surfaced when a cross term
+             * went into the field and a ray cast against the mesh landed 11.6 mm off the query.
+             *
+             * Wound so the face normal points up either way: with x to the right and z away, `a, d, c`
+             * and `a, c, b` both cross upward.
+             */
+            indices[at++] = a;
+            indices[at++] = d;
+            indices[at++] = c;
+            indices[at++] = a;
+            indices[at++] = c;
+            indices[at++] = b;
+        }
+    }
+    return {
+        positions,
+        normals,
+        colors,
+        emissive: emissives,
+        ...(speculars === null ? {} : { specular: speculars }),
+        indices,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/terrain` — a heightfield, the surface it draws, and the same answer to both.
+ *
+ * **It imports no renderer.** What it hands back is `MeshData`, which a consumer gives to
+ * `createMesh` like any other geometry, so terrain is drawn by the pass that already exists rather
+ * than by one of its own. That is why this is a package and not a part of core: a world with no
+ * terrain in it pays nothing, and a world with terrain pays for arithmetic rather than for a
+ * second renderer.
+ *
+ * The three things it is careful about are written where they are decided — `heightfield.ts` on why
+ * a query reads the triangle rather than the bilinear patch, `heightfieldPatch.ts` on why a seam
+ * between two levels of detail is matched rather than covered with a skirt, and
+ * `terrainMaterials.ts` on why a weight map is read the *other* way, bilinearly, and baked into
+ * vertex colour rather than sampled by a shader.
+ */
+export { Terrain } from './heightfield.ts';
+export type { HeightfieldOptions } from './heightfield.ts';
+export { heightfieldPatch } from './heightfieldPatch.ts';
+export type { HeightfieldPatchOptions } from './heightfieldPatch.ts';
+export { TerrainMaterials, terrainMaterialWeights } from './terrainMaterials.ts';
+export type { TerrainMaterial, TerrainMaterialsOptions } from './terrainMaterials.ts';

package/dist/index.js

@@ -0,0 +1,19 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * `@driftengine/terrain` — a heightfield, the surface it draws, and the same answer to both.
+ *
+ * **It imports no renderer.** What it hands back is `MeshData`, which a consumer gives to
+ * `createMesh` like any other geometry, so terrain is drawn by the pass that already exists rather
+ * than by one of its own. That is why this is a package and not a part of core: a world with no
+ * terrain in it pays nothing, and a world with terrain pays for arithmetic rather than for a
+ * second renderer.
+ *
+ * The three things it is careful about are written where they are decided — `heightfield.ts` on why
+ * a query reads the triangle rather than the bilinear patch, `heightfieldPatch.ts` on why a seam
+ * between two levels of detail is matched rather than covered with a skirt, and
+ * `terrainMaterials.ts` on why a weight map is read the *other* way, bilinearly, and baked into
+ * vertex colour rather than sampled by a shader.
+ */
+export { Terrain } from './heightfield.js';
+export { heightfieldPatch } from './heightfieldPatch.js';
+export { TerrainMaterials, terrainMaterialWeights } from './terrainMaterials.js';

package/dist/terrainMaterials.d.ts

@@ -0,0 +1,79 @@
+import type { ReadonlyVec3 } from 'gl-matrix';
+/**
+ * Several materials blended across one field, as vertex colour.
+ *
+ * **A weight map baked into vertex colour, and that is the idiomatic answer here rather than a
+ * compromise.** This engine's colour *is* vertex data — it is what makes the world one flat-shaded
+ * draw call, and the root README says so where it introduces `drawMesh`'s tint. A splat map read by
+ * a shader would mean a texture bound on every terrain draw and a branch in `flatFrag`, which Track
+ * D measured at 19.8 KB gzipped for a capability generated into sixteen fragment permutations. This
+ * costs nothing at all at runtime: the blend happens once, where the patch is built.
+ *
+ * **What that gives up, and it is the honest limit**: the blend is only as sharp as the mesh. A
+ * material boundary inside a cell is drawn as a gradient across that cell, and a patch drawn at a
+ * quarter detail blends four times as coarsely as one at full detail. A consumer who wants a sharp
+ * line — a road edge, a cliff base — draws that patch at full detail, which is the same dial the
+ * geometry already uses.
+ *
+ * **The weights are read bilinearly, which is the opposite of how a height is read**, and the
+ * contrast is the whole reason both decisions are written down. A height is read as the *triangle*
+ * because the surface is drawn as triangles and the query has to agree with the picture
+ * (`heightfield.ts` argues that at length). A weight is not drawn: it decides a vertex colour, and
+ * the vertex is wherever the mesh put it. There is no triangulation to agree with, so the smooth
+ * interpolation is simply the better one — reading a weight map as triangles would put a visible
+ * crease along every cell diagonal for nothing.
+ */
+export interface TerrainMaterial {
+    readonly color: ReadonlyVec3;
+    /** Self-illumination, revealed at night. Zero unless a material glows. */
+    readonly emissive?: number;
+    /** How sharply this material takes a sun highlight, 0 to 1. */
+    readonly specular?: number;
+}
+export interface TerrainMaterialsOptions {
+    /** The materials being blended. At least one. */
+    readonly materials: readonly TerrainMaterial[];
+    /** Samples of the weight map across x. It need not match the heightfield's own resolution. */
+    readonly width: number;
+    /** Samples across z. */
+    readonly depth: number;
+    /**
+     * `width * depth * materials.length` weights, row-major with the material running fastest.
+     *
+     * They need not sum to anything: `terrainMaterialWeights` normalises what it reads, because a
+     * map is painted or generated and nothing balances its channels.
+     */
+    readonly weights: ArrayLike<number>;
+}
+/**
+ * The normalised weights at a point in the field's own `0..1` extent.
+ *
+ * **Normalised, and a sample that weighs nothing falls back to the first material.** An unpainted
+ * corner of a map sums to zero, and dividing by that gives a NaN or a black patch depending on
+ * where it lands — both of which read as a rendering fault rather than as an unpainted map. Black
+ * is not a colour terrain should ever be by accident.
+ *
+ * `out` must hold one number per material; it is returned for convenience and is the caller's.
+ */
+export declare function terrainMaterialWeights(map: TerrainMaterials, u: number, v: number, out: Float32Array): Float32Array;
+export declare class TerrainMaterials {
+    readonly materials: readonly TerrainMaterial[];
+    readonly width: number;
+    readonly depth: number;
+    readonly weights: Float32Array;
+    /**
+     * Whether any material shines, so a patch built from this uploads a specular buffer only if one
+     * is wanted — the promise `MeshData.specular` makes and the reason it is optional.
+     */
+    readonly shines: boolean;
+    /** The same question for emissive, and for the same reason. */
+    readonly glows: boolean;
+    private readonly scratch;
+    constructor(options: TerrainMaterialsOptions);
+    /** The blended colour at a point in the field's `0..1` extent. */
+    colorAt(u: number, v: number, out: Float32Array): Float32Array;
+    /** The blended self-illumination, on the same weights the colour used. */
+    emissiveAt(u: number, v: number): number;
+    /** The blended highlight, likewise. */
+    specularAt(u: number, v: number): number;
+}

package/dist/terrainMaterials.js

@@ -0,0 +1,111 @@
+/** Scratch for one blend, so shading a patch allocates nothing per vertex. */
+const SCRATCH = new Float32Array(16);
+/**
+ * The normalised weights at a point in the field's own `0..1` extent.
+ *
+ * **Normalised, and a sample that weighs nothing falls back to the first material.** An unpainted
+ * corner of a map sums to zero, and dividing by that gives a NaN or a black patch depending on
+ * where it lands — both of which read as a rendering fault rather than as an unpainted map. Black
+ * is not a colour terrain should ever be by accident.
+ *
+ * `out` must hold one number per material; it is returned for convenience and is the caller's.
+ */
+export function terrainMaterialWeights(map, u, v, out) {
+    const count = map.materials.length;
+    /* Clamped rather than wrapped: a field has an edge, and a query past it should answer the edge
+       rather than the far side of the map. */
+    const x = Math.min(map.width - 1, Math.max(0, u * (map.width - 1)));
+    const z = Math.min(map.depth - 1, Math.max(0, v * (map.depth - 1)));
+    const ix = Math.min(map.width - 2, Math.floor(x));
+    const iz = Math.min(map.depth - 2, Math.floor(z));
+    const fu = map.width < 2 ? 0 : x - ix;
+    const fv = map.depth < 2 ? 0 : z - iz;
+    const a = (iz * map.width + ix) * count;
+    const b = (iz * map.width + Math.min(map.width - 1, ix + 1)) * count;
+    const c = (Math.min(map.depth - 1, iz + 1) * map.width + ix) * count;
+    const d = (Math.min(map.depth - 1, iz + 1) * map.width + Math.min(map.width - 1, ix + 1)) * count;
+    let total = 0;
+    for (let m = 0; m < count; m++) {
+        const top = (map.weights[a + m] ?? 0) * (1 - fu) + (map.weights[b + m] ?? 0) * fu;
+        const bottom = (map.weights[c + m] ?? 0) * (1 - fu) + (map.weights[d + m] ?? 0) * fu;
+        const weight = top * (1 - fv) + bottom * fv;
+        out[m] = weight;
+        total += weight;
+    }
+    if (total <= 0) {
+        out[0] = 1;
+        for (let m = 1; m < count; m++)
+            out[m] = 0;
+        return out;
+    }
+    for (let m = 0; m < count; m++)
+        out[m] = (out[m] ?? 0) / total;
+    return out;
+}
+export class TerrainMaterials {
+    materials;
+    width;
+    depth;
+    weights;
+    /**
+     * Whether any material shines, so a patch built from this uploads a specular buffer only if one
+     * is wanted — the promise `MeshData.specular` makes and the reason it is optional.
+     */
+    shines;
+    /** The same question for emissive, and for the same reason. */
+    glows;
+    scratch;
+    constructor(options) {
+        const count = options.materials.length;
+        if (count < 1)
+            throw new Error('TerrainMaterials: needs at least one material to blend');
+        const needed = options.width * options.depth * count;
+        if (options.weights.length !== needed) {
+            throw new Error(`TerrainMaterials: ${options.width} by ${options.depth} over ${count} materials needs ` +
+                `${needed} weights, got ${options.weights.length}`);
+        }
+        this.materials = [...options.materials];
+        this.width = Math.round(options.width);
+        this.depth = Math.round(options.depth);
+        this.weights = Float32Array.from(options.weights);
+        this.shines = this.materials.some((material) => (material.specular ?? 0) !== 0);
+        this.glows = this.materials.some((material) => (material.emissive ?? 0) !== 0);
+        this.scratch = count <= SCRATCH.length ? SCRATCH : new Float32Array(count);
+    }
+    /** The blended colour at a point in the field's `0..1` extent. */
+    colorAt(u, v, out) {
+        const weights = terrainMaterialWeights(this, u, v, this.scratch);
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        for (let m = 0; m < this.materials.length; m++) {
+            const weight = weights[m] ?? 0;
+            const colour = this.materials[m]?.color;
+            r += (colour?.[0] ?? 0) * weight;
+            g += (colour?.[1] ?? 0) * weight;
+            b += (colour?.[2] ?? 0) * weight;
+        }
+        out[0] = r;
+        out[1] = g;
+        out[2] = b;
+        return out;
+    }
+    /** The blended self-illumination, on the same weights the colour used. */
+    emissiveAt(u, v) {
+        const weights = terrainMaterialWeights(this, u, v, this.scratch);
+        let sum = 0;
+        for (let m = 0; m < this.materials.length; m++) {
+            sum += (this.materials[m]?.emissive ?? 0) * (weights[m] ?? 0);
+        }
+        return sum;
+    }
+    /** The blended highlight, likewise. */
+    specularAt(u, v) {
+        const weights = terrainMaterialWeights(this, u, v, this.scratch);
+        let sum = 0;
+        for (let m = 0; m < this.materials.length; m++) {
+            sum += (this.materials[m]?.specular ?? 0) * (weights[m] ?? 0);
+        }
+        return sum;
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@driftengine/terrain",
+  "version": "3.61.0",
+  "description": "Heightfields: a query that answers the surface that is drawn, and patches that meet without cracks",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "drift-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*": "./*"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.mjs",
+    "!src/**/__snapshots__",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@driftengine/drft": "3.61.0"
+  },
+  "devDependencies": {
+    "@driftengine/physics": "3.61.0"
+  },
+  "author": "Drift Technologies",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drftrun/driftengine.git",
+    "directory": "packages/terrain"
+  },
+  "homepage": "https://github.com/drftrun/driftengine#readme",
+  "bugs": "https://github.com/drftrun/driftengine/issues",
+  "keywords": [
+    "driftengine",
+    "3d",
+    "webgl",
+    "webgpu",
+    "typescript",
+    "heightfield",
+    "terrain",
+    "level-of-detail"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/heightfield.ts

@@ -0,0 +1,134 @@
+import type { ReadonlyVec3 } from 'gl-matrix';
+
+/**
+ * A heightfield, and the two questions everything else asks it.
+ *
+ * **The whole design of this file is one rule: the answer a query gives is the surface that is
+ * drawn.** A heightfield is stored as a lattice of samples and drawn as triangles, and those are
+ * not the same surface — a bilinear patch through four corners and the two triangles that span
+ * them agree only along their shared diagonal and at the corners. Interpolating bilinearly because
+ * it is the obvious thing gives a character that floats over half of every cell and sinks into the
+ * other half, by up to a quarter of the cell's height range, everywhere, for ever. It is a defect
+ * with no symptom a screenshot can show and no test that fails, which is exactly the kind this
+ * repository writes down.
+ *
+ * So `heightAt` reads the *triangle*, and `heightfieldPatch` builds those same triangles, and a
+ * test asserts each vertex against the query.
+ *
+ * **The normal is the other way round on purpose.** A face normal is constant over a triangle and
+ * jumps at every edge, so a field built from them is faceted, and — worse — two patches meeting at
+ * a boundary shade differently along it, which reads as a crack that is not there. `normalAt` is a
+ * central difference over the samples, continuous by construction, and it is what the mesh carries
+ * as its vertex normals. A caller who wants the plane a wheel actually rests on takes three
+ * `heightAt` samples; a caller who wants to orient a character takes this.
+ */
+
+export interface HeightfieldOptions {
+  /** 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 in metres, row-major with x running fastest. */
+  readonly heights: ArrayLike<number>;
+  /** World position of sample `(0, 0)`. The origin's own y is added to every height. */
+  readonly origin?: ReadonlyVec3;
+}
+
+export class Terrain {
+  readonly width: number;
+  readonly depth: number;
+  readonly spacingM: number;
+  /** World position of sample `(0, 0)`, copied because a caller reuses its vectors. */
+  readonly origin = new Float32Array(3);
+  /** The samples, copied for the same reason and because this is read every frame. */
+  readonly heights: Float32Array;
+
+  constructor(options: HeightfieldOptions) {
+    const { width, depth, spacingM } = options;
+    if (!(width >= 2)) throw new Error(`Terrain: width must be at least 2, got ${width}`);
+    if (!(depth >= 2)) throw new Error(`Terrain: depth must be at least 2, got ${depth}`);
+    if (!(spacingM > 0)) throw new Error(`Terrain: spacing must be above zero, got ${spacingM}`);
+    if (options.heights.length !== width * depth) {
+      throw new Error(
+        `Terrain: ${width} by ${depth} needs ${width * depth} heights, got ${options.heights.length}`,
+      );
+    }
+    this.width = Math.round(width);
+    this.depth = Math.round(depth);
+    this.spacingM = spacingM;
+    this.heights = Float32Array.from(options.heights);
+    if (options.origin !== undefined) this.origin.set(options.origin as ArrayLike<number>);
+  }
+
+  /** How far the field reaches along x, metres. One less cell than it has samples. */
+  get extentX(): number {
+    return (this.width - 1) * this.spacingM;
+  }
+
+  get extentZ(): number {
+    return (this.depth - 1) * this.spacingM;
+  }
+
+  /** One sample, by grid index, clamped to the field rather than wrapping or answering NaN. */
+  sample(ix: number, iz: number): number {
+    const x = Math.min(this.width - 1, Math.max(0, ix));
+    const z = Math.min(this.depth - 1, Math.max(0, iz));
+    return (this.origin[1] ?? 0) + (this.heights[z * this.width + x] ?? 0);
+  }
+
+  /**
+   * The height of the drawn surface at a world position.
+   *
+   * **The triangle and not the bilinear patch**, for the reason at the top of this file. The cell
+   * is split along its `a`-`c` diagonal — from the sample at `(ix, iz)` to the one at
+   * `(ix + 1, iz + 1)` — and `heightfieldPatch` emits exactly that split, so the two cannot
+   * disagree about where the ground is.
+   *
+   * Clamped outside the field. A world has an edge and a query past it should answer the edge
+   * rather than extrapolate a slope into a place that has no samples.
+   */
+  heightAt(x: number, z: number): number {
+    const u = (x - (this.origin[0] ?? 0)) / this.spacingM;
+    const v = (z - (this.origin[2] ?? 0)) / this.spacingM;
+    const clampedU = Math.min(this.width - 1, Math.max(0, u));
+    const clampedV = Math.min(this.depth - 1, Math.max(0, v));
+    /* One short of the last sample, so `ix + 1` is always a sample and the cell is always whole. */
+    const ix = Math.min(this.width - 2, Math.floor(clampedU));
+    const iz = Math.min(this.depth - 2, Math.floor(clampedV));
+    const fu = clampedU - ix;
+    const fv = clampedV - iz;
+
+    const a = this.sample(ix, iz);
+    const c = this.sample(ix + 1, iz + 1);
+    if (fu >= fv) {
+      /* Below the diagonal: the triangle a, b, c. */
+      const b = this.sample(ix + 1, iz);
+      return a + (b - a) * fu + (c - b) * fv;
+    }
+    /* Above it: the triangle a, c, d. */
+    const d = this.sample(ix, iz + 1);
+    return a + (d - a) * fv + (c - d) * fu;
+  }
+
+  /**
+   * The surface normal at a world position, as a central difference over the samples.
+   *
+   * Continuous across every cell boundary, which is what stops two patches shading differently
+   * along the edge they share — the failure that reads as a crack in geometry that has none.
+   */
+  normalAt(x: number, z: number, out: Float32Array): Float32Array {
+    const step = this.spacingM;
+    const dx = this.heightAt(x + step, z) - this.heightAt(x - step, z);
+    const dz = this.heightAt(x, z + step) - this.heightAt(x, z - step);
+    /* The gradient of a height field, normalised: (-dh/dx, 1, -dh/dz) over twice the step. */
+    const nx = -dx / (2 * step);
+    const nz = -dz / (2 * step);
+    const length = Math.sqrt(nx * nx + 1 + nz * nz);
+    out[0] = nx / length;
+    out[1] = 1 / length;
+    out[2] = nz / length;
+    return out;
+  }
+}