@driftengine/terrain 3.63.0 → 4.0.0

package/NOTICE

@@ -7,3 +7,23 @@ This product includes software developed at Drift Technologies
 Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
 requires this NOTICE to be reproduced in any derivative work you distribute,
 in the source, the documentation, or a display generated by the work.
+
+Models run by DriftCapture
+--------------------------
+DriftCapture runs the models below. Their weights are not in this repository
+and are not distributed with it: tools/capture-weights/ fetches each at the
+revision its manifest pins, verifies it, and converts it, and a game that
+ships one ships it under that model's own licence. Each model's definition in
+this engine is written from its project's published code.
+
+- Depth Anything 3 Small and Depth Anything 3 Base. Apache License 2.0.
+  Copyright (c) 2025 ByteDance Ltd. and/or its affiliates.
+- Depth Anything V2 Small. Apache License 2.0. The University of Hong Kong
+  and TikTok; converted to the Transformers layout by The HuggingFace Team.
+- MobileSAM. Apache License 2.0. Its image encoder is TinyViT, Copyright (c)
+  2022 Microsoft; its prompt encoder and mask decoder are Segment Anything's,
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+- SAM 2.1 tiny. Apache License 2.0. Copyright (c) Meta Platforms, Inc. and
+  affiliates.
+- OWLv2 base patch16. Apache License 2.0. Copyright 2023 Google AI and The
+  HuggingFace Team.

package/dist/clipmap.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Which squares of the field to draw, at what detail, for a camera standing somewhere.
+ *
+ * **A clipmap is rings of patches whose step doubles outward**, so the ground under the camera is
+ * drawn at full resolution and the horizon at a sixteenth of it, and the vertex count stays flat
+ * however large the world is. The hard part is not the rings; it is that they have to meet.
+ *
+ * **Two failures decide the whole design and neither is visible in a list of patches.** A field
+ * cell drawn by two patches is z-fighting on the ground. A field cell drawn by none is a hole
+ * through to the sky. Both come out of the arithmetic that snaps each level's block to a lattice,
+ * so that is what the tests assert directly: every cell in the footprint, counted.
+ *
+ * **Each level's block is snapped to an even patch index**, which is what makes the levels nest:
+ * an origin at an even multiple of a level's patch span is a multiple of the next level's patch
+ * span, so a finer block's edge always falls on a coarser patch boundary and never through the
+ * middle of one. A coarse patch is therefore covered by the finer block entirely or not at all,
+ * and culling it when it is covered leaves no gap and no overlap. The block being an even number
+ * of patches on each side of that index is why `patchesAcross` must be a multiple of four.
+ *
+ * **The hole a finer level leaves is not fixed at the centre**, which is the part that looks wrong
+ * and is right. Levels snap to their own lattices and re-centre at different moments, so the finer
+ * block sits a patch off-centre in the coarser one about half the time. Culling by *coverage*
+ * rather than by a fixed central hole is what makes that harmless — and a fixed hole is what the
+ * usual implementation does, which is why it needs an L-shaped strip to take up the slack.
+ *
+ * **The selection is one decision per patch**, taking the frame and an index and reading nothing
+ * else. That is what lets it move into a compute pass beside the cluster cut rather than be
+ * rewritten there: `clipmapPatchAt` is the body of that shader, and the test that asks for the
+ * patches in a scrambled order is what holds it.
+ *
+ * What it does *not* do is build geometry. `heightfieldPatch` does that, including moving a fine
+ * edge's odd vertices onto its coarse neighbour's chord — this module's job is to tell it which
+ * neighbour is coarser, because a patch that is not told draws an edge that follows the field
+ * while the patch beside it cuts the chord beneath.
+ */
+import type { Terrain } from './heightfield.ts';
+import type { HeightfieldPatchOptions } from './heightfieldPatch.ts';
+/** Drawn cells along one edge of every patch, at every level. */
+export declare const CLIPMAP_PATCH_CELLS = 8;
+/** Patches along one edge of a level's block. A multiple of four, for the reason above. */
+export declare const CLIPMAP_PATCHES_ACROSS = 8;
+/** Levels a frame builds when the caller does not say. */
+export declare const CLIPMAP_LEVELS = 4;
+export interface ClipmapOptions {
+    readonly levels?: number;
+    readonly patchCells?: number;
+    readonly patchesAcross?: number;
+}
+/**
+ * Everything a per-patch decision needs, computed once for a camera.
+ *
+ * Deliberately plain data: an `Int32Array` of origins and four numbers. What a compute pass would
+ * be handed as a uniform block, and nothing a shader could not hold.
+ */
+export interface ClipmapFrame {
+    readonly levels: number;
+    readonly patchCells: number;
+    readonly patchesAcross: number;
+    /** Two entries a level: the field-cell index of the block's first cell, x then z. */
+    readonly origins: Int32Array;
+    /** Cells the field has, which is one fewer than its samples. */
+    readonly fieldCellsX: number;
+    readonly fieldCellsZ: number;
+}
+/** A selected patch, in exactly the terms `heightfieldPatch` takes. */
+export interface ClipmapPatch {
+    level: number;
+    /** Grid index of the patch's first sample, along x. */
+    x: number;
+    z: number;
+    /** Field cells the patch spans: `patchCells * step`. */
+    cells: number;
+    /** Field cells per drawn cell: `1 << level`. */
+    step: number;
+    /** The step of each neighbour that is *coarser* than this patch. The finer side is the one that
+        moves, so nothing is said about a neighbour at the same level or a finer one. */
+    neighbours: {
+        minusX?: number;
+        plusX?: number;
+        minusZ?: number;
+        plusZ?: number;
+    };
+}
+/** A patch to write into, so a caller looping over indices allocates nothing. */
+export declare function emptyClipmapPatch(): ClipmapPatch;
+/**
+ * Snap a camera to each level's block, once, for a frame.
+ *
+ * The camera is in world coordinates and the blocks are in field cells, because that is what
+ * `heightfieldPatch` indexes by and converting in one place is one place to be wrong.
+ */
+export declare function clipmapFrame(terrain: Terrain, cameraX: number, cameraZ: number, options?: ClipmapOptions): ClipmapFrame;
+/** Patches a frame decides about: every index a compute pass would launch a thread for. */
+export declare function clipmapPatchCount(frame: ClipmapFrame): number;
+/**
+ * The level whose drawn patch covers a field cell, or `-1` where nothing draws it.
+ *
+ * The finest level whose block contains the cell and whose patch there fits on the field. Finest
+ * rather than any, because a coarser patch over the same ground is exactly what gets culled.
+ */
+export declare function clipmapLevelAt(frame: ClipmapFrame, cellX: number, cellZ: number): number;
+/**
+ * Decide one patch, by index, writing it into `out`.
+ *
+ * Returns whether it is drawn. Reads the frame and the index and nothing else, which is what makes
+ * this the body of a compute shader rather than a loop that has to be rewritten as one.
+ */
+export declare function clipmapPatchAt(frame: ClipmapFrame, index: number, out: ClipmapPatch): boolean;
+/** Every drawn patch, as a list. The convenience over `clipmapPatchAt`, not a second rule. */
+export declare function selectClipmap(frame: ClipmapFrame): ClipmapPatch[];
+/** A selected patch as the options `heightfieldPatch` takes, with nothing added or renamed. */
+export declare function clipmapPatchOptions(patch: ClipmapPatch): HeightfieldPatchOptions;

package/dist/clipmap.js

@@ -0,0 +1,154 @@
+/** Drawn cells along one edge of every patch, at every level. */
+export const CLIPMAP_PATCH_CELLS = 8;
+/** Patches along one edge of a level's block. A multiple of four, for the reason above. */
+export const CLIPMAP_PATCHES_ACROSS = 8;
+/** Levels a frame builds when the caller does not say. */
+export const CLIPMAP_LEVELS = 4;
+/** A patch to write into, so a caller looping over indices allocates nothing. */
+export function emptyClipmapPatch() {
+    return { level: 0, x: 0, z: 0, cells: 0, step: 1, neighbours: {} };
+}
+/**
+ * Snap a camera to each level's block, once, for a frame.
+ *
+ * The camera is in world coordinates and the blocks are in field cells, because that is what
+ * `heightfieldPatch` indexes by and converting in one place is one place to be wrong.
+ */
+export function clipmapFrame(terrain, cameraX, cameraZ, options = {}) {
+    const levels = Math.max(1, Math.round(options.levels ?? CLIPMAP_LEVELS));
+    const patchCells = Math.max(1, Math.round(options.patchCells ?? CLIPMAP_PATCH_CELLS));
+    const patchesAcross = Math.round(options.patchesAcross ?? CLIPMAP_PATCHES_ACROSS);
+    if (patchesAcross % 4 !== 0) {
+        throw new Error(`clipmapFrame: patchesAcross must be a multiple of four so the levels nest, got ${patchesAcross}`);
+    }
+    const spacing = terrain.spacingM;
+    const cellX = Math.floor((cameraX - (terrain.origin[0] ?? 0)) / spacing);
+    const cellZ = Math.floor((cameraZ - (terrain.origin[2] ?? 0)) / spacing);
+    const origins = new Int32Array(levels * 2);
+    for (let level = 0; level < levels; level += 1) {
+        const span = patchCells << level;
+        origins[level * 2] = blockOrigin(cellX, span, patchesAcross);
+        origins[level * 2 + 1] = blockOrigin(cellZ, span, patchesAcross);
+    }
+    return {
+        levels,
+        patchCells,
+        patchesAcross,
+        origins,
+        fieldCellsX: terrain.width - 1,
+        fieldCellsZ: terrain.depth - 1,
+    };
+}
+/**
+ * The first field cell of a level's block along one axis.
+ *
+ * The camera's patch index rounded *down to an even one*, then half the block subtracted. Even is
+ * what makes the origin a multiple of twice the span, which is the next level's span — the one
+ * property everything else rests on.
+ */
+function blockOrigin(cameraCell, span, patchesAcross) {
+    const patch = Math.floor(cameraCell / span);
+    const even = 2 * Math.floor(patch / 2);
+    return (even - patchesAcross / 2) * span;
+}
+/** Patches a frame decides about: every index a compute pass would launch a thread for. */
+export function clipmapPatchCount(frame) {
+    return frame.levels * frame.patchesAcross * frame.patchesAcross;
+}
+/** Whether `[x, x + span)` on both axes lies inside level `level`'s block. */
+function insideBlock(frame, level, x, z, span) {
+    const width = frame.patchesAcross * (frame.patchCells << level);
+    const x0 = frame.origins[level * 2];
+    const z0 = frame.origins[level * 2 + 1];
+    return x >= x0 && z >= z0 && x + span <= x0 + width && z + span <= z0 + width;
+}
+function onField(frame, x, z, span) {
+    return x >= 0 && z >= 0 && x + span <= frame.fieldCellsX && z + span <= frame.fieldCellsZ;
+}
+/**
+ * The level whose drawn patch covers a field cell, or `-1` where nothing draws it.
+ *
+ * The finest level whose block contains the cell and whose patch there fits on the field. Finest
+ * rather than any, because a coarser patch over the same ground is exactly what gets culled.
+ */
+export function clipmapLevelAt(frame, cellX, cellZ) {
+    for (let level = 0; level < frame.levels; level += 1) {
+        const span = frame.patchCells << level;
+        const x0 = frame.origins[level * 2];
+        const z0 = frame.origins[level * 2 + 1];
+        const width = frame.patchesAcross * span;
+        if (cellX < x0 || cellZ < z0 || cellX >= x0 + width || cellZ >= z0 + width)
+            continue;
+        const px = x0 + Math.floor((cellX - x0) / span) * span;
+        const pz = z0 + Math.floor((cellZ - z0) / span) * span;
+        if (!onField(frame, px, pz, span))
+            continue;
+        return level;
+    }
+    return -1;
+}
+/**
+ * Decide one patch, by index, writing it into `out`.
+ *
+ * Returns whether it is drawn. Reads the frame and the index and nothing else, which is what makes
+ * this the body of a compute shader rather than a loop that has to be rewritten as one.
+ */
+export function clipmapPatchAt(frame, index, out) {
+    const perLevel = frame.patchesAcross * frame.patchesAcross;
+    const level = Math.floor(index / perLevel);
+    if (level < 0 || level >= frame.levels)
+        return false;
+    const within = index - level * perLevel;
+    const i = within % frame.patchesAcross;
+    const j = Math.floor(within / frame.patchesAcross);
+    const step = 1 << level;
+    const span = frame.patchCells * step;
+    const x = frame.origins[level * 2] + i * span;
+    const z = frame.origins[level * 2 + 1] + j * span;
+    if (!onField(frame, x, z, span))
+        return false;
+    /* Covered by the level inside this one, whole — which is the only way it can be covered, because
+       a finer block's edge falls on this level's patch boundaries. */
+    if (level > 0 && insideBlock(frame, level - 1, x, z, span))
+        return false;
+    out.level = level;
+    out.x = x;
+    out.z = z;
+    out.cells = span;
+    out.step = step;
+    out.neighbours = {};
+    declareCoarser(frame, out, 'minusX', x - 1, z);
+    declareCoarser(frame, out, 'plusX', x + span, z);
+    declareCoarser(frame, out, 'minusZ', x, z - 1);
+    declareCoarser(frame, out, 'plusZ', x, z + span);
+    return true;
+}
+/** Name a neighbour's step where it is coarser than this patch, and say nothing otherwise. */
+function declareCoarser(frame, patch, side, probeX, probeZ) {
+    const level = clipmapLevelAt(frame, probeX, probeZ);
+    if (level <= patch.level)
+        return;
+    patch.neighbours[side] = 1 << level;
+}
+/** Every drawn patch, as a list. The convenience over `clipmapPatchAt`, not a second rule. */
+export function selectClipmap(frame) {
+    const patches = [];
+    const total = clipmapPatchCount(frame);
+    const scratch = emptyClipmapPatch();
+    for (let index = 0; index < total; index += 1) {
+        if (!clipmapPatchAt(frame, index, scratch))
+            continue;
+        patches.push({ ...scratch, neighbours: { ...scratch.neighbours } });
+    }
+    return patches;
+}
+/** A selected patch as the options `heightfieldPatch` takes, with nothing added or renamed. */
+export function clipmapPatchOptions(patch) {
+    return {
+        x: patch.x,
+        z: patch.z,
+        cells: patch.cells,
+        step: patch.step,
+        neighbours: patch.neighbours,
+    };
+}

package/dist/heightfield.d.ts

@@ -14,6 +14,13 @@ import type { ReadonlyVec3 } from 'gl-matrix';
  * So `heightAt` reads the *triangle*, and `heightfieldPatch` builds those same triangles, and a
  * test asserts each vertex against the query.
  *
+ * **And there is now a fourth surface, so the rule extends rather than changes.** Wave 4B stores
+ * heights as a `DTEX` layer, which quantises them — so a renderer reading the layer while a query
+ * reads the samples this class was built from differ by the format's tolerance, everywhere,
+ * permanently. `terrainTexture.ts` answers it the only way that holds: `terrainFromHeightLayer`
+ * builds a `Terrain` from the *decoded* samples, and everything reads that one object. The rule is
+ * unchanged — there is one surface — and what changed is where the numbers come from.
+ *
  * **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

package/dist/index.d.ts

@@ -20,3 +20,7 @@ export { heightfieldPatch } from './heightfieldPatch.ts';
 export type { HeightfieldPatchOptions } from './heightfieldPatch.ts';
 export { TerrainMaterials, terrainMaterialWeights } from './terrainMaterials.ts';
 export type { TerrainMaterial, TerrainMaterialsOptions } from './terrainMaterials.ts';
+export { CLIPMAP_LEVELS, CLIPMAP_PATCHES_ACROSS, CLIPMAP_PATCH_CELLS, clipmapFrame, clipmapLevelAt, clipmapPatchAt, clipmapPatchCount, clipmapPatchOptions, emptyClipmapPatch, selectClipmap, } from './clipmap.ts';
+export type { ClipmapFrame, ClipmapOptions, ClipmapPatch } from './clipmap.ts';
+export { TERRAIN_HEIGHT_LEVELS, TERRAIN_SPLAT_CHANNELS, TERRAIN_SPLAT_LEVELS, decodeTerrainHeights, decodeTerrainSplat, encodeTerrainHeights, encodeTerrainSplat, terrainFromHeightLayer, terrainHeightTolerance, } from './terrainTexture.ts';
+export type { TerrainHeightLayer, TerrainSplatLayer } from './terrainTexture.ts';

package/dist/index.js

@@ -17,3 +17,15 @@
 export { Terrain } from './heightfield.js';
 export { heightfieldPatch } from './heightfieldPatch.js';
 export { TerrainMaterials, terrainMaterialWeights } from './terrainMaterials.js';
+/*
+ * The clipmap: which squares of the field to draw at what detail, as one decision per patch so it
+ * can move into a compute pass beside the cluster cut rather than be rewritten there. It builds no
+ * geometry — `heightfieldPatch` does that, and matches the seam.
+ */
+export { CLIPMAP_LEVELS, CLIPMAP_PATCHES_ACROSS, CLIPMAP_PATCH_CELLS, clipmapFrame, clipmapLevelAt, clipmapPatchAt, clipmapPatchCount, clipmapPatchOptions, emptyClipmapPatch, selectClipmap, } from './clipmap.js';
+/*
+ * Heights and material weights as `DTEX` layers, and the one rule that makes it safe: a terrain
+ * rebuilt from a layer is built from the decoded samples, so collision and rendering cannot read
+ * different numbers. Opt-in — a consumer who never names these imports none of `@driftengine/texture`.
+ */
+export { TERRAIN_HEIGHT_LEVELS, TERRAIN_SPLAT_CHANNELS, TERRAIN_SPLAT_LEVELS, decodeTerrainHeights, decodeTerrainSplat, encodeTerrainHeights, encodeTerrainSplat, terrainFromHeightLayer, terrainHeightTolerance, } from './terrainTexture.js';

package/dist/terrainTexture.d.ts

@@ -0,0 +1,113 @@
+/**
+ * A heightfield and its material weights, held as `DTEX` layers.
+ *
+ * **What a layer is here is what a texture is everywhere in this engine: a small decode program
+ * over a latent image**, run by `@driftengine/texture`'s reference decoder. So terrain gets the
+ * whole format for free — the residency, the streaming, the tolerance, the determinism — instead of
+ * a second image path of its own, and a terrain layer is a texture a material graph could have
+ * produced.
+ *
+ * **The decode program produces a normalised channel and the range turns it into metres**, because
+ * the vocabulary has no affine operation and should not grow one for this: a height map in any
+ * format is a normalised value plus a range, and putting the range in the layer keeps the two
+ * together. `height-linear` is the semantic that says so.
+ *
+ * ---
+ *
+ * **The rule this file exists to hold, and the plan had it the other way round.** The plan asked
+ * that heights decoded from a layer match the source heightfield within the format's tolerance.
+ * They do. That is not enough, and believing it is is how the most reported terrain defect
+ * anywhere gets shipped: if the renderer reads the layer and collision reads the source, the two
+ * surfaces differ by exactly that tolerance, everywhere, permanently — a character floating or
+ * sinking by a fraction of a millimetre with nothing to attribute it to.
+ *
+ * So `terrainFromHeightLayer` builds a `Terrain` from the **decoded** samples, and everything —
+ * the query, the patch mesh, the collider `heightfieldPatch` feeds — reads that one. The two
+ * cannot disagree because there is only one set of numbers. `heightfield.ts` states the same rule
+ * one level down, for the triangle against the bilinear patch.
+ *
+ * **A consumer that never touches this path pays nothing for it.** The imports are named, the
+ * package is `sideEffects: false`, and `core-and-terrain`'s floor is what proves it stayed that
+ * way.
+ */
+import { type DecodeGraph, type DecodeResources } from '@driftengine/texture';
+import { Terrain } from './heightfield.ts';
+/** Quantisation levels a height layer carries: sixteen bits. */
+export declare const TERRAIN_HEIGHT_LEVELS = 65536;
+/** Quantisation levels one splat weight carries: eight bits, four of them to a texel. */
+export declare const TERRAIN_SPLAT_LEVELS = 256;
+/** Materials a splat layer blends. Four, because that is one texel. */
+export declare const TERRAIN_SPLAT_CHANNELS = 4;
+export interface TerrainHeightLayer {
+    readonly graph: DecodeGraph;
+    readonly resources: DecodeResources;
+    /** Samples across x and z, which is also the latent's size in texels. */
+    readonly width: number;
+    readonly depth: number;
+    /** Metres at the bottom of the encoded range. */
+    readonly minM: number;
+    /** Metres the encoded range spans. Zero for a flat field. */
+    readonly rangeM: number;
+    /** Metres between samples, carried so a rebuilt terrain cannot be given a different one. */
+    readonly spacingM: number;
+    /** World position of sample `(0, 0)`, carried for the same reason. */
+    readonly origin: Float32Array;
+}
+/**
+ * Encode a terrain's samples into a height layer.
+ *
+ * The range is the field's own, not a fixed world range: a valley two metres deep quantised
+ * against a range of four kilometres is a staircase, and terrain is where that is most visible
+ * because a shallow slope magnifies a step in height into a wide flat shelf.
+ */
+export declare function encodeTerrainHeights(terrain: Terrain): TerrainHeightLayer;
+/**
+ * The most a decoded height can differ from the one encoded.
+ *
+ * **Half a quantisation step plus one float32 step of the range, and the second term is not
+ * padding.** The normalised value is stored in the latent as a float32, so the code is exact but
+ * `code / 65535` is not — and the decode multiplies that representation error back up by the whole
+ * range. Written as half a step alone, this function is wrong by about a part in a thousand, which
+ * is exactly enough for a tolerance assertion to fail on a field somebody did not choose
+ * carefully: measured 4.6372e-5 against a half-step of 4.6314e-5 over a range of six metres.
+ *
+ * Stated as a function of the layer rather than as a constant, since it is the field's own range
+ * that sets both terms.
+ */
+export declare function terrainHeightTolerance(layer: TerrainHeightLayer): number;
+/** Decode every sample of a height layer into `out`, in metres, row-major with x fastest. */
+export declare function decodeTerrainHeights(layer: TerrainHeightLayer, out: Float32Array): void;
+/**
+ * The terrain a layer describes: the same class every consumer already queries, built from the
+ * decoded samples.
+ *
+ * **This is the whole answer to "collision and rendering read the same height".** They read the
+ * same object, because the layer produces exactly one.
+ */
+export declare function terrainFromHeightLayer(layer: TerrainHeightLayer): Terrain;
+export interface TerrainSplatLayer {
+    readonly graph: DecodeGraph;
+    readonly resources: DecodeResources;
+    readonly width: number;
+    readonly depth: number;
+}
+/**
+ * Encode four material weights per sample.
+ *
+ * Refuses a map whose weights do not already sum to one, rather than normalising it on the way in.
+ * A weight map nobody filled in sums to zero at every texel, and a normalisation applied quietly
+ * turns that into "material zero, everywhere" — a whole world of one texture, shipped, with no
+ * error anywhere. The caller's own weights are a statement about the ground and this does not
+ * edit it.
+ */
+export declare function encodeTerrainSplat(width: number, depth: number, weights: ArrayLike<number>): TerrainSplatLayer;
+/**
+ * Sample the four weights at a field coordinate, renormalised so they sum to one.
+ *
+ * **The renormalisation is not tidiness.** Four weights each rounded to eight bits sum to anywhere
+ * between 0.994 and 1.006, and a shader that trusts the sum draws a hillside slightly too bright
+ * or slightly too dark — smoothly, so it reads as lighting rather than as a texture bug. The
+ * alternative, storing three weights and deriving the fourth, puts the entire error on one
+ * material and is worse for the same total.
+ */
+export declare function decodeTerrainSplat(layer: TerrainSplatLayer, u: number, v: number, out: Float32Array): void;

package/dist/terrainTexture.js

@@ -0,0 +1,215 @@
+/**
+ * A heightfield and its material weights, held as `DTEX` layers.
+ *
+ * **What a layer is here is what a texture is everywhere in this engine: a small decode program
+ * over a latent image**, run by `@driftengine/texture`'s reference decoder. So terrain gets the
+ * whole format for free — the residency, the streaming, the tolerance, the determinism — instead of
+ * a second image path of its own, and a terrain layer is a texture a material graph could have
+ * produced.
+ *
+ * **The decode program produces a normalised channel and the range turns it into metres**, because
+ * the vocabulary has no affine operation and should not grow one for this: a height map in any
+ * format is a normalised value plus a range, and putting the range in the layer keeps the two
+ * together. `height-linear` is the semantic that says so.
+ *
+ * ---
+ *
+ * **The rule this file exists to hold, and the plan had it the other way round.** The plan asked
+ * that heights decoded from a layer match the source heightfield within the format's tolerance.
+ * They do. That is not enough, and believing it is is how the most reported terrain defect
+ * anywhere gets shipped: if the renderer reads the layer and collision reads the source, the two
+ * surfaces differ by exactly that tolerance, everywhere, permanently — a character floating or
+ * sinking by a fraction of a millimetre with nothing to attribute it to.
+ *
+ * So `terrainFromHeightLayer` builds a `Terrain` from the **decoded** samples, and everything —
+ * the query, the patch mesh, the collider `heightfieldPatch` feeds — reads that one. The two
+ * cannot disagree because there is only one set of numbers. `heightfield.ts` states the same rule
+ * one level down, for the triangle against the bilinear patch.
+ *
+ * **A consumer that never touches this path pays nothing for it.** The imports are named, the
+ * package is `sideEffects: false`, and `core-and-terrain`'s floor is what proves it stayed that
+ * way.
+ */
+import { DECODE_OP, addDecodeNode, createDecodeGraph, createDecodeRegisters, decodeCpu, REMAP_SEMANTICS, } from '@driftengine/texture';
+import { Terrain } from './heightfield.js';
+/** Quantisation levels a height layer carries: sixteen bits. */
+export const TERRAIN_HEIGHT_LEVELS = 65536;
+/** Quantisation levels one splat weight carries: eight bits, four of them to a texel. */
+export const TERRAIN_SPLAT_LEVELS = 256;
+/** Materials a splat layer blends. Four, because that is one texel. */
+export const TERRAIN_SPLAT_CHANNELS = 4;
+/** `b` for a `REMAP_CHANNEL` node: the semantic's index in `REMAP_SEMANTICS`, then the component. */
+function remapOperand(semantic, component) {
+    const index = REMAP_SEMANTICS.indexOf(semantic);
+    if (index < 0)
+        throw new Error(`terrainTexture: ${semantic} is not a remappable semantic`);
+    return (index << 4) | component;
+}
+/** A decode program that samples one latent and applies one channel convention. */
+function oneChannelGraph(semantic) {
+    const graph = createDecodeGraph(2);
+    addDecodeNode(graph, DECODE_OP.SAMPLE_LATENT, 0, 0, 0);
+    addDecodeNode(graph, DECODE_OP.REMAP_CHANNEL, 0, remapOperand(semantic, 0), 1);
+    graph.result = 1;
+    /* Clamped, not wrapped: a field has an edge, and a query past it answers the edge. */
+    graph.addressMode = 0;
+    return graph;
+}
+/**
+ * Encode a terrain's samples into a height layer.
+ *
+ * The range is the field's own, not a fixed world range: a valley two metres deep quantised
+ * against a range of four kilometres is a staircase, and terrain is where that is most visible
+ * because a shallow slope magnifies a step in height into a wide flat shelf.
+ */
+export function encodeTerrainHeights(terrain) {
+    const count = terrain.width * terrain.depth;
+    let minM = Infinity;
+    let maxM = -Infinity;
+    for (let at = 0; at < count; at += 1) {
+        const h = terrain.heights[at];
+        if (h < minM)
+            minM = h;
+        if (h > maxM)
+            maxM = h;
+    }
+    if (!Number.isFinite(minM)) {
+        minM = 0;
+        maxM = 0;
+    }
+    const rangeM = maxM - minM;
+    const data = new Float32Array(count);
+    for (let at = 0; at < count; at += 1) {
+        /* A flat field has no range to divide by, and every sample is the minimum. */
+        const normalised = rangeM === 0 ? 0 : (terrain.heights[at] - minM) / rangeM;
+        data[at] = Math.round(normalised * (TERRAIN_HEIGHT_LEVELS - 1)) / (TERRAIN_HEIGHT_LEVELS - 1);
+    }
+    const latent = { data, width: terrain.width, height: terrain.depth, channels: 1 };
+    return {
+        graph: oneChannelGraph('height-linear'),
+        resources: { latents: [latent], blocks: [], networks: [] },
+        width: terrain.width,
+        depth: terrain.depth,
+        minM,
+        rangeM,
+        spacingM: terrain.spacingM,
+        origin: Float32Array.from(terrain.origin),
+    };
+}
+/**
+ * The most a decoded height can differ from the one encoded.
+ *
+ * **Half a quantisation step plus one float32 step of the range, and the second term is not
+ * padding.** The normalised value is stored in the latent as a float32, so the code is exact but
+ * `code / 65535` is not — and the decode multiplies that representation error back up by the whole
+ * range. Written as half a step alone, this function is wrong by about a part in a thousand, which
+ * is exactly enough for a tolerance assertion to fail on a field somebody did not choose
+ * carefully: measured 4.6372e-5 against a half-step of 4.6314e-5 over a range of six metres.
+ *
+ * Stated as a function of the layer rather than as a constant, since it is the field's own range
+ * that sets both terms.
+ */
+export function terrainHeightTolerance(layer) {
+    /* 2⁻²⁴, written as a division because `**` is `Math.pow` to the determinism scan — and that
+       scan is right to refuse it: an engine is free to round `Math.pow` differently, and a
+       tolerance that differs by an ulp between two peers is a replay that disagrees. */
+    const FLOAT32_STEP = 1 / 16777216;
+    return layer.rangeM * (0.5 / (TERRAIN_HEIGHT_LEVELS - 1) + FLOAT32_STEP);
+}
+/** Decode every sample of a height layer into `out`, in metres, row-major with x fastest. */
+export function decodeTerrainHeights(layer, out) {
+    const registers = createDecodeRegisters();
+    const sample = new Float32Array(4);
+    for (let z = 0; z < layer.depth; z += 1) {
+        for (let x = 0; x < layer.width; x += 1) {
+            /* Lattice coordinates: the decoder maps `u` across `width - 1`, so a sample lands on its own
+               texel exactly and the bilinear filter contributes nothing to a sample-aligned read. */
+            const u = layer.width === 1 ? 0 : x / (layer.width - 1);
+            const v = layer.depth === 1 ? 0 : z / (layer.depth - 1);
+            decodeCpu(layer.graph, layer.resources, u, v, 0, sample, registers);
+            out[z * layer.width + x] = layer.minM + sample[0] * layer.rangeM;
+        }
+    }
+}
+/**
+ * The terrain a layer describes: the same class every consumer already queries, built from the
+ * decoded samples.
+ *
+ * **This is the whole answer to "collision and rendering read the same height".** They read the
+ * same object, because the layer produces exactly one.
+ */
+export function terrainFromHeightLayer(layer) {
+    const heights = new Float32Array(layer.width * layer.depth);
+    decodeTerrainHeights(layer, heights);
+    return new Terrain({
+        width: layer.width,
+        depth: layer.depth,
+        spacingM: layer.spacingM,
+        heights,
+        origin: layer.origin,
+    });
+}
+/**
+ * Encode four material weights per sample.
+ *
+ * Refuses a map whose weights do not already sum to one, rather than normalising it on the way in.
+ * A weight map nobody filled in sums to zero at every texel, and a normalisation applied quietly
+ * turns that into "material zero, everywhere" — a whole world of one texture, shipped, with no
+ * error anywhere. The caller's own weights are a statement about the ground and this does not
+ * edit it.
+ */
+export function encodeTerrainSplat(width, depth, weights) {
+    const count = width * depth;
+    if (weights.length !== count * TERRAIN_SPLAT_CHANNELS) {
+        throw new Error(`encodeTerrainSplat: ${width} by ${depth} needs ${count * TERRAIN_SPLAT_CHANNELS} weights, ` +
+            `got ${weights.length}`);
+    }
+    const data = new Float32Array(count * TERRAIN_SPLAT_CHANNELS);
+    for (let at = 0; at < count; at += 1) {
+        let sum = 0;
+        for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) {
+            sum += weights[at * TERRAIN_SPLAT_CHANNELS + c];
+        }
+        if (Math.abs(sum - 1) > 1e-3) {
+            throw new Error(`encodeTerrainSplat: the weights at sample ${at} sum to ${sum.toFixed(4)} and must sum to one`);
+        }
+        for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) {
+            const raw = weights[at * TERRAIN_SPLAT_CHANNELS + c];
+            data[at * TERRAIN_SPLAT_CHANNELS + c] =
+                Math.round(raw * (TERRAIN_SPLAT_LEVELS - 1)) / (TERRAIN_SPLAT_LEVELS - 1);
+        }
+    }
+    const latent = { data, width, height: depth, channels: TERRAIN_SPLAT_CHANNELS };
+    const graph = createDecodeGraph(1);
+    addDecodeNode(graph, DECODE_OP.SAMPLE_LATENT, 0, 0, 0);
+    graph.result = 0;
+    graph.addressMode = 0;
+    return { graph, resources: { latents: [latent], blocks: [], networks: [] }, width, depth };
+}
+const SPLAT_REGISTERS = createDecodeRegisters();
+const SPLAT_SAMPLE = new Float32Array(4);
+/**
+ * Sample the four weights at a field coordinate, renormalised so they sum to one.
+ *
+ * **The renormalisation is not tidiness.** Four weights each rounded to eight bits sum to anywhere
+ * between 0.994 and 1.006, and a shader that trusts the sum draws a hillside slightly too bright
+ * or slightly too dark — smoothly, so it reads as lighting rather than as a texture bug. The
+ * alternative, storing three weights and deriving the fourth, puts the entire error on one
+ * material and is worse for the same total.
+ */
+export function decodeTerrainSplat(layer, u, v, out) {
+    decodeCpu(layer.graph, layer.resources, u, v, 0, SPLAT_SAMPLE, SPLAT_REGISTERS);
+    let sum = 0;
+    for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1)
+        sum += SPLAT_SAMPLE[c];
+    if (sum <= 0) {
+        /* Unreachable through `encodeTerrainSplat`, which refuses a map that could produce it. Kept
+           because a caller may build a layer another way, and dividing by zero here would answer NaN
+           weights that a shader turns into a black patch of ground. */
+        for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1)
+            out[c] = c === 0 ? 1 : 0;
+        return;
+    }
+    for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1)
+        out[c] = SPLAT_SAMPLE[c] / sum;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/terrain",
-  "version": "3.63.0",
+  "version": "4.0.0",
   "description": "Heightfields: a query that answers the surface that is drawn, and patches that meet without cracks",
   "license": "Apache-2.0",
   "type": "module",
@@ -26,11 +26,15 @@
     "NOTICE"
   ],
   "sideEffects": false,
+  "dependencies": {
+    "@driftengine/texture": "4.0.0",
+    "gl-matrix": "^3.4.3"
+  },
   "peerDependencies": {
-    "@driftengine/drft": "3.63.0"
+    "@driftengine/drft": "4.0.0"
   },
   "devDependencies": {
-    "@driftengine/physics": "3.63.0"
+    "@driftengine/physics": "4.0.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/clipmap.ts

@@ -0,0 +1,265 @@
+/**
+ * Which squares of the field to draw, at what detail, for a camera standing somewhere.
+ *
+ * **A clipmap is rings of patches whose step doubles outward**, so the ground under the camera is
+ * drawn at full resolution and the horizon at a sixteenth of it, and the vertex count stays flat
+ * however large the world is. The hard part is not the rings; it is that they have to meet.
+ *
+ * **Two failures decide the whole design and neither is visible in a list of patches.** A field
+ * cell drawn by two patches is z-fighting on the ground. A field cell drawn by none is a hole
+ * through to the sky. Both come out of the arithmetic that snaps each level's block to a lattice,
+ * so that is what the tests assert directly: every cell in the footprint, counted.
+ *
+ * **Each level's block is snapped to an even patch index**, which is what makes the levels nest:
+ * an origin at an even multiple of a level's patch span is a multiple of the next level's patch
+ * span, so a finer block's edge always falls on a coarser patch boundary and never through the
+ * middle of one. A coarse patch is therefore covered by the finer block entirely or not at all,
+ * and culling it when it is covered leaves no gap and no overlap. The block being an even number
+ * of patches on each side of that index is why `patchesAcross` must be a multiple of four.
+ *
+ * **The hole a finer level leaves is not fixed at the centre**, which is the part that looks wrong
+ * and is right. Levels snap to their own lattices and re-centre at different moments, so the finer
+ * block sits a patch off-centre in the coarser one about half the time. Culling by *coverage*
+ * rather than by a fixed central hole is what makes that harmless — and a fixed hole is what the
+ * usual implementation does, which is why it needs an L-shaped strip to take up the slack.
+ *
+ * **The selection is one decision per patch**, taking the frame and an index and reading nothing
+ * else. That is what lets it move into a compute pass beside the cluster cut rather than be
+ * rewritten there: `clipmapPatchAt` is the body of that shader, and the test that asks for the
+ * patches in a scrambled order is what holds it.
+ *
+ * What it does *not* do is build geometry. `heightfieldPatch` does that, including moving a fine
+ * edge's odd vertices onto its coarse neighbour's chord — this module's job is to tell it which
+ * neighbour is coarser, because a patch that is not told draws an edge that follows the field
+ * while the patch beside it cuts the chord beneath.
+ */
+import type { Terrain } from './heightfield.ts';
+import type { HeightfieldPatchOptions } from './heightfieldPatch.ts';
+
+/** Drawn cells along one edge of every patch, at every level. */
+export const CLIPMAP_PATCH_CELLS = 8;
+
+/** Patches along one edge of a level's block. A multiple of four, for the reason above. */
+export const CLIPMAP_PATCHES_ACROSS = 8;
+
+/** Levels a frame builds when the caller does not say. */
+export const CLIPMAP_LEVELS = 4;
+
+export interface ClipmapOptions {
+  readonly levels?: number;
+  readonly patchCells?: number;
+  readonly patchesAcross?: number;
+}
+
+/**
+ * Everything a per-patch decision needs, computed once for a camera.
+ *
+ * Deliberately plain data: an `Int32Array` of origins and four numbers. What a compute pass would
+ * be handed as a uniform block, and nothing a shader could not hold.
+ */
+export interface ClipmapFrame {
+  readonly levels: number;
+  readonly patchCells: number;
+  readonly patchesAcross: number;
+  /** Two entries a level: the field-cell index of the block's first cell, x then z. */
+  readonly origins: Int32Array;
+  /** Cells the field has, which is one fewer than its samples. */
+  readonly fieldCellsX: number;
+  readonly fieldCellsZ: number;
+}
+
+/** A selected patch, in exactly the terms `heightfieldPatch` takes. */
+export interface ClipmapPatch {
+  level: number;
+  /** Grid index of the patch's first sample, along x. */
+  x: number;
+  z: number;
+  /** Field cells the patch spans: `patchCells * step`. */
+  cells: number;
+  /** Field cells per drawn cell: `1 << level`. */
+  step: number;
+  /** The step of each neighbour that is *coarser* than this patch. The finer side is the one that
+      moves, so nothing is said about a neighbour at the same level or a finer one. */
+  neighbours: {
+    minusX?: number;
+    plusX?: number;
+    minusZ?: number;
+    plusZ?: number;
+  };
+}
+
+/** A patch to write into, so a caller looping over indices allocates nothing. */
+export function emptyClipmapPatch(): ClipmapPatch {
+  return { level: 0, x: 0, z: 0, cells: 0, step: 1, neighbours: {} };
+}
+
+/**
+ * Snap a camera to each level's block, once, for a frame.
+ *
+ * The camera is in world coordinates and the blocks are in field cells, because that is what
+ * `heightfieldPatch` indexes by and converting in one place is one place to be wrong.
+ */
+export function clipmapFrame(
+  terrain: Terrain,
+  cameraX: number,
+  cameraZ: number,
+  options: ClipmapOptions = {},
+): ClipmapFrame {
+  const levels = Math.max(1, Math.round(options.levels ?? CLIPMAP_LEVELS));
+  const patchCells = Math.max(1, Math.round(options.patchCells ?? CLIPMAP_PATCH_CELLS));
+  const patchesAcross = Math.round(options.patchesAcross ?? CLIPMAP_PATCHES_ACROSS);
+  if (patchesAcross % 4 !== 0) {
+    throw new Error(
+      `clipmapFrame: patchesAcross must be a multiple of four so the levels nest, got ${patchesAcross}`,
+    );
+  }
+
+  const spacing = terrain.spacingM;
+  const cellX = Math.floor((cameraX - (terrain.origin[0] ?? 0)) / spacing);
+  const cellZ = Math.floor((cameraZ - (terrain.origin[2] ?? 0)) / spacing);
+
+  const origins = new Int32Array(levels * 2);
+  for (let level = 0; level < levels; level += 1) {
+    const span = patchCells << level;
+    origins[level * 2] = blockOrigin(cellX, span, patchesAcross);
+    origins[level * 2 + 1] = blockOrigin(cellZ, span, patchesAcross);
+  }
+  return {
+    levels,
+    patchCells,
+    patchesAcross,
+    origins,
+    fieldCellsX: terrain.width - 1,
+    fieldCellsZ: terrain.depth - 1,
+  };
+}
+
+/**
+ * The first field cell of a level's block along one axis.
+ *
+ * The camera's patch index rounded *down to an even one*, then half the block subtracted. Even is
+ * what makes the origin a multiple of twice the span, which is the next level's span — the one
+ * property everything else rests on.
+ */
+function blockOrigin(cameraCell: number, span: number, patchesAcross: number): number {
+  const patch = Math.floor(cameraCell / span);
+  const even = 2 * Math.floor(patch / 2);
+  return (even - patchesAcross / 2) * span;
+}
+
+/** Patches a frame decides about: every index a compute pass would launch a thread for. */
+export function clipmapPatchCount(frame: ClipmapFrame): number {
+  return frame.levels * frame.patchesAcross * frame.patchesAcross;
+}
+
+/** Whether `[x, x + span)` on both axes lies inside level `level`'s block. */
+function insideBlock(
+  frame: ClipmapFrame,
+  level: number,
+  x: number,
+  z: number,
+  span: number,
+): boolean {
+  const width = frame.patchesAcross * (frame.patchCells << level);
+  const x0 = frame.origins[level * 2] as number;
+  const z0 = frame.origins[level * 2 + 1] as number;
+  return x >= x0 && z >= z0 && x + span <= x0 + width && z + span <= z0 + width;
+}
+
+function onField(frame: ClipmapFrame, x: number, z: number, span: number): boolean {
+  return x >= 0 && z >= 0 && x + span <= frame.fieldCellsX && z + span <= frame.fieldCellsZ;
+}
+
+/**
+ * The level whose drawn patch covers a field cell, or `-1` where nothing draws it.
+ *
+ * The finest level whose block contains the cell and whose patch there fits on the field. Finest
+ * rather than any, because a coarser patch over the same ground is exactly what gets culled.
+ */
+export function clipmapLevelAt(frame: ClipmapFrame, cellX: number, cellZ: number): number {
+  for (let level = 0; level < frame.levels; level += 1) {
+    const span = frame.patchCells << level;
+    const x0 = frame.origins[level * 2] as number;
+    const z0 = frame.origins[level * 2 + 1] as number;
+    const width = frame.patchesAcross * span;
+    if (cellX < x0 || cellZ < z0 || cellX >= x0 + width || cellZ >= z0 + width) continue;
+    const px = x0 + Math.floor((cellX - x0) / span) * span;
+    const pz = z0 + Math.floor((cellZ - z0) / span) * span;
+    if (!onField(frame, px, pz, span)) continue;
+    return level;
+  }
+  return -1;
+}
+
+/**
+ * Decide one patch, by index, writing it into `out`.
+ *
+ * Returns whether it is drawn. Reads the frame and the index and nothing else, which is what makes
+ * this the body of a compute shader rather than a loop that has to be rewritten as one.
+ */
+export function clipmapPatchAt(frame: ClipmapFrame, index: number, out: ClipmapPatch): boolean {
+  const perLevel = frame.patchesAcross * frame.patchesAcross;
+  const level = Math.floor(index / perLevel);
+  if (level < 0 || level >= frame.levels) return false;
+  const within = index - level * perLevel;
+  const i = within % frame.patchesAcross;
+  const j = Math.floor(within / frame.patchesAcross);
+
+  const step = 1 << level;
+  const span = frame.patchCells * step;
+  const x = (frame.origins[level * 2] as number) + i * span;
+  const z = (frame.origins[level * 2 + 1] as number) + j * span;
+
+  if (!onField(frame, x, z, span)) return false;
+  /* Covered by the level inside this one, whole — which is the only way it can be covered, because
+     a finer block's edge falls on this level's patch boundaries. */
+  if (level > 0 && insideBlock(frame, level - 1, x, z, span)) return false;
+
+  out.level = level;
+  out.x = x;
+  out.z = z;
+  out.cells = span;
+  out.step = step;
+  out.neighbours = {};
+  declareCoarser(frame, out, 'minusX', x - 1, z);
+  declareCoarser(frame, out, 'plusX', x + span, z);
+  declareCoarser(frame, out, 'minusZ', x, z - 1);
+  declareCoarser(frame, out, 'plusZ', x, z + span);
+  return true;
+}
+
+/** Name a neighbour's step where it is coarser than this patch, and say nothing otherwise. */
+function declareCoarser(
+  frame: ClipmapFrame,
+  patch: ClipmapPatch,
+  side: keyof ClipmapPatch['neighbours'],
+  probeX: number,
+  probeZ: number,
+): void {
+  const level = clipmapLevelAt(frame, probeX, probeZ);
+  if (level <= patch.level) return;
+  patch.neighbours[side] = 1 << level;
+}
+
+/** Every drawn patch, as a list. The convenience over `clipmapPatchAt`, not a second rule. */
+export function selectClipmap(frame: ClipmapFrame): ClipmapPatch[] {
+  const patches: ClipmapPatch[] = [];
+  const total = clipmapPatchCount(frame);
+  const scratch = emptyClipmapPatch();
+  for (let index = 0; index < total; index += 1) {
+    if (!clipmapPatchAt(frame, index, scratch)) continue;
+    patches.push({ ...scratch, neighbours: { ...scratch.neighbours } });
+  }
+  return patches;
+}
+
+/** A selected patch as the options `heightfieldPatch` takes, with nothing added or renamed. */
+export function clipmapPatchOptions(patch: ClipmapPatch): HeightfieldPatchOptions {
+  return {
+    x: patch.x,
+    z: patch.z,
+    cells: patch.cells,
+    step: patch.step,
+    neighbours: patch.neighbours,
+  };
+}

package/src/heightfield.ts

@@ -15,6 +15,13 @@ import type { ReadonlyVec3 } from 'gl-matrix';
  * So `heightAt` reads the *triangle*, and `heightfieldPatch` builds those same triangles, and a
  * test asserts each vertex against the query.
  *
+ * **And there is now a fourth surface, so the rule extends rather than changes.** Wave 4B stores
+ * heights as a `DTEX` layer, which quantises them — so a renderer reading the layer while a query
+ * reads the samples this class was built from differ by the format's tolerance, everywhere,
+ * permanently. `terrainTexture.ts` answers it the only way that holds: `terrainFromHeightLayer`
+ * builds a `Terrain` from the *decoded* samples, and everything reads that one object. The rule is
+ * unchanged — there is one surface — and what changed is where the numbers come from.
+ *
  * **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

package/src/index.ts

@@ -21,3 +21,38 @@ export { heightfieldPatch } from './heightfieldPatch.ts';
 export type { HeightfieldPatchOptions } from './heightfieldPatch.ts';
 export { TerrainMaterials, terrainMaterialWeights } from './terrainMaterials.ts';
 export type { TerrainMaterial, TerrainMaterialsOptions } from './terrainMaterials.ts';
+/*
+ * The clipmap: which squares of the field to draw at what detail, as one decision per patch so it
+ * can move into a compute pass beside the cluster cut rather than be rewritten there. It builds no
+ * geometry — `heightfieldPatch` does that, and matches the seam.
+ */
+export {
+  CLIPMAP_LEVELS,
+  CLIPMAP_PATCHES_ACROSS,
+  CLIPMAP_PATCH_CELLS,
+  clipmapFrame,
+  clipmapLevelAt,
+  clipmapPatchAt,
+  clipmapPatchCount,
+  clipmapPatchOptions,
+  emptyClipmapPatch,
+  selectClipmap,
+} from './clipmap.ts';
+export type { ClipmapFrame, ClipmapOptions, ClipmapPatch } from './clipmap.ts';
+/*
+ * Heights and material weights as `DTEX` layers, and the one rule that makes it safe: a terrain
+ * rebuilt from a layer is built from the decoded samples, so collision and rendering cannot read
+ * different numbers. Opt-in — a consumer who never names these imports none of `@driftengine/texture`.
+ */
+export {
+  TERRAIN_HEIGHT_LEVELS,
+  TERRAIN_SPLAT_CHANNELS,
+  TERRAIN_SPLAT_LEVELS,
+  decodeTerrainHeights,
+  decodeTerrainSplat,
+  encodeTerrainHeights,
+  encodeTerrainSplat,
+  terrainFromHeightLayer,
+  terrainHeightTolerance,
+} from './terrainTexture.ts';
+export type { TerrainHeightLayer, TerrainSplatLayer } from './terrainTexture.ts';

package/src/terrainTexture.ts

@@ -0,0 +1,270 @@
+/**
+ * A heightfield and its material weights, held as `DTEX` layers.
+ *
+ * **What a layer is here is what a texture is everywhere in this engine: a small decode program
+ * over a latent image**, run by `@driftengine/texture`'s reference decoder. So terrain gets the
+ * whole format for free — the residency, the streaming, the tolerance, the determinism — instead of
+ * a second image path of its own, and a terrain layer is a texture a material graph could have
+ * produced.
+ *
+ * **The decode program produces a normalised channel and the range turns it into metres**, because
+ * the vocabulary has no affine operation and should not grow one for this: a height map in any
+ * format is a normalised value plus a range, and putting the range in the layer keeps the two
+ * together. `height-linear` is the semantic that says so.
+ *
+ * ---
+ *
+ * **The rule this file exists to hold, and the plan had it the other way round.** The plan asked
+ * that heights decoded from a layer match the source heightfield within the format's tolerance.
+ * They do. That is not enough, and believing it is is how the most reported terrain defect
+ * anywhere gets shipped: if the renderer reads the layer and collision reads the source, the two
+ * surfaces differ by exactly that tolerance, everywhere, permanently — a character floating or
+ * sinking by a fraction of a millimetre with nothing to attribute it to.
+ *
+ * So `terrainFromHeightLayer` builds a `Terrain` from the **decoded** samples, and everything —
+ * the query, the patch mesh, the collider `heightfieldPatch` feeds — reads that one. The two
+ * cannot disagree because there is only one set of numbers. `heightfield.ts` states the same rule
+ * one level down, for the triangle against the bilinear patch.
+ *
+ * **A consumer that never touches this path pays nothing for it.** The imports are named, the
+ * package is `sideEffects: false`, and `core-and-terrain`'s floor is what proves it stayed that
+ * way.
+ */
+import {
+  DECODE_OP,
+  addDecodeNode,
+  createDecodeGraph,
+  createDecodeRegisters,
+  decodeCpu,
+  REMAP_SEMANTICS,
+  type DecodeGraph,
+  type DecodeResources,
+  type LatentImage,
+} from '@driftengine/texture';
+
+import { Terrain } from './heightfield.ts';
+
+/** Quantisation levels a height layer carries: sixteen bits. */
+export const TERRAIN_HEIGHT_LEVELS = 65536;
+
+/** Quantisation levels one splat weight carries: eight bits, four of them to a texel. */
+export const TERRAIN_SPLAT_LEVELS = 256;
+
+/** Materials a splat layer blends. Four, because that is one texel. */
+export const TERRAIN_SPLAT_CHANNELS = 4;
+
+/** `b` for a `REMAP_CHANNEL` node: the semantic's index in `REMAP_SEMANTICS`, then the component. */
+function remapOperand(semantic: (typeof REMAP_SEMANTICS)[number], component: number): number {
+  const index = REMAP_SEMANTICS.indexOf(semantic);
+  if (index < 0) throw new Error(`terrainTexture: ${semantic} is not a remappable semantic`);
+  return (index << 4) | component;
+}
+
+/** A decode program that samples one latent and applies one channel convention. */
+function oneChannelGraph(semantic: (typeof REMAP_SEMANTICS)[number]): DecodeGraph {
+  const graph = createDecodeGraph(2);
+  addDecodeNode(graph, DECODE_OP.SAMPLE_LATENT, 0, 0, 0);
+  addDecodeNode(graph, DECODE_OP.REMAP_CHANNEL, 0, remapOperand(semantic, 0), 1);
+  graph.result = 1;
+  /* Clamped, not wrapped: a field has an edge, and a query past it answers the edge. */
+  graph.addressMode = 0;
+  return graph;
+}
+
+export interface TerrainHeightLayer {
+  readonly graph: DecodeGraph;
+  readonly resources: DecodeResources;
+  /** Samples across x and z, which is also the latent's size in texels. */
+  readonly width: number;
+  readonly depth: number;
+  /** Metres at the bottom of the encoded range. */
+  readonly minM: number;
+  /** Metres the encoded range spans. Zero for a flat field. */
+  readonly rangeM: number;
+  /** Metres between samples, carried so a rebuilt terrain cannot be given a different one. */
+  readonly spacingM: number;
+  /** World position of sample `(0, 0)`, carried for the same reason. */
+  readonly origin: Float32Array;
+}
+
+/**
+ * Encode a terrain's samples into a height layer.
+ *
+ * The range is the field's own, not a fixed world range: a valley two metres deep quantised
+ * against a range of four kilometres is a staircase, and terrain is where that is most visible
+ * because a shallow slope magnifies a step in height into a wide flat shelf.
+ */
+export function encodeTerrainHeights(terrain: Terrain): TerrainHeightLayer {
+  const count = terrain.width * terrain.depth;
+  let minM = Infinity;
+  let maxM = -Infinity;
+  for (let at = 0; at < count; at += 1) {
+    const h = terrain.heights[at] as number;
+    if (h < minM) minM = h;
+    if (h > maxM) maxM = h;
+  }
+  if (!Number.isFinite(minM)) {
+    minM = 0;
+    maxM = 0;
+  }
+  const rangeM = maxM - minM;
+
+  const data = new Float32Array(count);
+  for (let at = 0; at < count; at += 1) {
+    /* A flat field has no range to divide by, and every sample is the minimum. */
+    const normalised = rangeM === 0 ? 0 : ((terrain.heights[at] as number) - minM) / rangeM;
+    data[at] = Math.round(normalised * (TERRAIN_HEIGHT_LEVELS - 1)) / (TERRAIN_HEIGHT_LEVELS - 1);
+  }
+  const latent: LatentImage = { data, width: terrain.width, height: terrain.depth, channels: 1 };
+
+  return {
+    graph: oneChannelGraph('height-linear'),
+    resources: { latents: [latent], blocks: [], networks: [] },
+    width: terrain.width,
+    depth: terrain.depth,
+    minM,
+    rangeM,
+    spacingM: terrain.spacingM,
+    origin: Float32Array.from(terrain.origin),
+  };
+}
+
+/**
+ * The most a decoded height can differ from the one encoded.
+ *
+ * **Half a quantisation step plus one float32 step of the range, and the second term is not
+ * padding.** The normalised value is stored in the latent as a float32, so the code is exact but
+ * `code / 65535` is not — and the decode multiplies that representation error back up by the whole
+ * range. Written as half a step alone, this function is wrong by about a part in a thousand, which
+ * is exactly enough for a tolerance assertion to fail on a field somebody did not choose
+ * carefully: measured 4.6372e-5 against a half-step of 4.6314e-5 over a range of six metres.
+ *
+ * Stated as a function of the layer rather than as a constant, since it is the field's own range
+ * that sets both terms.
+ */
+export function terrainHeightTolerance(layer: TerrainHeightLayer): number {
+  /* 2⁻²⁴, written as a division because `**` is `Math.pow` to the determinism scan — and that
+     scan is right to refuse it: an engine is free to round `Math.pow` differently, and a
+     tolerance that differs by an ulp between two peers is a replay that disagrees. */
+  const FLOAT32_STEP = 1 / 16777216;
+  return layer.rangeM * (0.5 / (TERRAIN_HEIGHT_LEVELS - 1) + FLOAT32_STEP);
+}
+
+/** Decode every sample of a height layer into `out`, in metres, row-major with x fastest. */
+export function decodeTerrainHeights(layer: TerrainHeightLayer, out: Float32Array): void {
+  const registers = createDecodeRegisters();
+  const sample = new Float32Array(4);
+  for (let z = 0; z < layer.depth; z += 1) {
+    for (let x = 0; x < layer.width; x += 1) {
+      /* Lattice coordinates: the decoder maps `u` across `width - 1`, so a sample lands on its own
+         texel exactly and the bilinear filter contributes nothing to a sample-aligned read. */
+      const u = layer.width === 1 ? 0 : x / (layer.width - 1);
+      const v = layer.depth === 1 ? 0 : z / (layer.depth - 1);
+      decodeCpu(layer.graph, layer.resources, u, v, 0, sample, registers);
+      out[z * layer.width + x] = layer.minM + (sample[0] as number) * layer.rangeM;
+    }
+  }
+}
+
+/**
+ * The terrain a layer describes: the same class every consumer already queries, built from the
+ * decoded samples.
+ *
+ * **This is the whole answer to "collision and rendering read the same height".** They read the
+ * same object, because the layer produces exactly one.
+ */
+export function terrainFromHeightLayer(layer: TerrainHeightLayer): Terrain {
+  const heights = new Float32Array(layer.width * layer.depth);
+  decodeTerrainHeights(layer, heights);
+  return new Terrain({
+    width: layer.width,
+    depth: layer.depth,
+    spacingM: layer.spacingM,
+    heights,
+    origin: layer.origin,
+  });
+}
+
+export interface TerrainSplatLayer {
+  readonly graph: DecodeGraph;
+  readonly resources: DecodeResources;
+  readonly width: number;
+  readonly depth: number;
+}
+
+/**
+ * Encode four material weights per sample.
+ *
+ * Refuses a map whose weights do not already sum to one, rather than normalising it on the way in.
+ * A weight map nobody filled in sums to zero at every texel, and a normalisation applied quietly
+ * turns that into "material zero, everywhere" — a whole world of one texture, shipped, with no
+ * error anywhere. The caller's own weights are a statement about the ground and this does not
+ * edit it.
+ */
+export function encodeTerrainSplat(
+  width: number,
+  depth: number,
+  weights: ArrayLike<number>,
+): TerrainSplatLayer {
+  const count = width * depth;
+  if (weights.length !== count * TERRAIN_SPLAT_CHANNELS) {
+    throw new Error(
+      `encodeTerrainSplat: ${width} by ${depth} needs ${count * TERRAIN_SPLAT_CHANNELS} weights, ` +
+        `got ${weights.length}`,
+    );
+  }
+  const data = new Float32Array(count * TERRAIN_SPLAT_CHANNELS);
+  for (let at = 0; at < count; at += 1) {
+    let sum = 0;
+    for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) {
+      sum += weights[at * TERRAIN_SPLAT_CHANNELS + c] as number;
+    }
+    if (Math.abs(sum - 1) > 1e-3) {
+      throw new Error(
+        `encodeTerrainSplat: the weights at sample ${at} sum to ${sum.toFixed(4)} and must sum to one`,
+      );
+    }
+    for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) {
+      const raw = weights[at * TERRAIN_SPLAT_CHANNELS + c] as number;
+      data[at * TERRAIN_SPLAT_CHANNELS + c] =
+        Math.round(raw * (TERRAIN_SPLAT_LEVELS - 1)) / (TERRAIN_SPLAT_LEVELS - 1);
+    }
+  }
+  const latent: LatentImage = { data, width, height: depth, channels: TERRAIN_SPLAT_CHANNELS };
+  const graph = createDecodeGraph(1);
+  addDecodeNode(graph, DECODE_OP.SAMPLE_LATENT, 0, 0, 0);
+  graph.result = 0;
+  graph.addressMode = 0;
+  return { graph, resources: { latents: [latent], blocks: [], networks: [] }, width, depth };
+}
+
+const SPLAT_REGISTERS = createDecodeRegisters();
+const SPLAT_SAMPLE = new Float32Array(4);
+
+/**
+ * Sample the four weights at a field coordinate, renormalised so they sum to one.
+ *
+ * **The renormalisation is not tidiness.** Four weights each rounded to eight bits sum to anywhere
+ * between 0.994 and 1.006, and a shader that trusts the sum draws a hillside slightly too bright
+ * or slightly too dark — smoothly, so it reads as lighting rather than as a texture bug. The
+ * alternative, storing three weights and deriving the fourth, puts the entire error on one
+ * material and is worse for the same total.
+ */
+export function decodeTerrainSplat(
+  layer: TerrainSplatLayer,
+  u: number,
+  v: number,
+  out: Float32Array,
+): void {
+  decodeCpu(layer.graph, layer.resources, u, v, 0, SPLAT_SAMPLE, SPLAT_REGISTERS);
+  let sum = 0;
+  for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) sum += SPLAT_SAMPLE[c] as number;
+  if (sum <= 0) {
+    /* Unreachable through `encodeTerrainSplat`, which refuses a map that could produce it. Kept
+       because a caller may build a layer another way, and dividing by zero here would answer NaN
+       weights that a shader turns into a black patch of ground. */
+    for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) out[c] = c === 0 ? 1 : 0;
+    return;
+  }
+  for (let c = 0; c < TERRAIN_SPLAT_CHANNELS; c += 1) out[c] = (SPLAT_SAMPLE[c] as number) / sum;
+}