@driftengine/core 3.61.0

package/dist/render/visibility.d.ts

@@ -0,0 +1,22 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Bounds } from '../math/bounds.ts';
+import type { Frustum } from '../math/frustum.ts';
+/**
+ * Whether a mesh placed by a model matrix is anywhere inside a frustum.
+ *
+ * Shared by both backends rather than written twice, for the reason the resource table is: two
+ * copies of a decision are two chances to answer it differently, and a culling disagreement
+ * between backends is an object that is present on one and missing on the other.
+ *
+ * **Scale is the trap, and it is why this is not two lines at each call site.** A bounding sphere
+ * put through a scaling matrix is a sphere of a different size, so the world radius is the local
+ * radius times the *largest* of the three axis scales. Taking the average, or the x scale, or
+ * forgetting entirely, culls an enlarged object while it is plainly on screen — and the failure
+ * looks like a threshold to tune rather than a factor that is missing.
+ *
+ * Non-uniform scale makes the transformed shape an ellipsoid, and the largest axis is the sphere
+ * that contains it. Conservative, which is the only direction a cull may err in.
+ *
+ * Allocates nothing.
+ */
+export declare function boundsVisible(frustum: Frustum, bounds: Bounds, model: ReadonlyMat4): boolean;

package/dist/render/visibility.js

@@ -0,0 +1,47 @@
+import { sphereInFrustum } from '../math/frustum.js';
+/**
+ * Whether a mesh placed by a model matrix is anywhere inside a frustum.
+ *
+ * Shared by both backends rather than written twice, for the reason the resource table is: two
+ * copies of a decision are two chances to answer it differently, and a culling disagreement
+ * between backends is an object that is present on one and missing on the other.
+ *
+ * **Scale is the trap, and it is why this is not two lines at each call site.** A bounding sphere
+ * put through a scaling matrix is a sphere of a different size, so the world radius is the local
+ * radius times the *largest* of the three axis scales. Taking the average, or the x scale, or
+ * forgetting entirely, culls an enlarged object while it is plainly on screen — and the failure
+ * looks like a threshold to tune rather than a factor that is missing.
+ *
+ * Non-uniform scale makes the transformed shape an ellipsoid, and the largest axis is the sphere
+ * that contains it. Conservative, which is the only direction a cull may err in.
+ *
+ * Allocates nothing.
+ */
+export function boundsVisible(frustum, bounds, model) {
+    const cx = bounds.centre[0] ?? 0;
+    const cy = bounds.centre[1] ?? 0;
+    const cz = bounds.centre[2] ?? 0;
+    /* The centre through the model matrix. Column-major, so a column is four consecutive entries. */
+    const m0 = model[0] ?? 0;
+    const m1 = model[1] ?? 0;
+    const m2 = model[2] ?? 0;
+    const m4 = model[4] ?? 0;
+    const m5 = model[5] ?? 0;
+    const m6 = model[6] ?? 0;
+    const m8 = model[8] ?? 0;
+    const m9 = model[9] ?? 0;
+    const m10 = model[10] ?? 0;
+    const x = m0 * cx + m4 * cy + m8 * cz + (model[12] ?? 0);
+    const y = m1 * cx + m5 * cy + m9 * cz + (model[13] ?? 0);
+    const z = m2 * cx + m6 * cy + m10 * cz + (model[14] ?? 0);
+    /*
+     * The length of each basis vector is that axis' scale, rotation included: a rotation preserves
+     * length, so this reads the scale out of a matrix that also rotates without having to
+     * decompose it.
+     */
+    const sx = Math.sqrt(m0 * m0 + m1 * m1 + m2 * m2);
+    const sy = Math.sqrt(m4 * m4 + m5 * m5 + m6 * m6);
+    const sz = Math.sqrt(m8 * m8 + m9 * m9 + m10 * m10);
+    const radius = bounds.radius * Math.max(sx, sy, sz);
+    return sphereInFrustum(frustum, x, y, z, radius);
+}

package/dist/render/waterDraw.d.ts

@@ -0,0 +1,57 @@
+import type { Vec3 } from '../math/color.ts';
+import type { WaterBody } from './waterRenderer.ts';
+/**
+ * Where the sheet is laid and how hard it is blowing on it, decided for both backends.
+ *
+ * **The interesting half of `WaterRenderer.draw` is arithmetic, not binding.** Snapping the
+ * ocean to whole cells, choosing a sea state from the wind or from an authored agitation,
+ * falling back to a bearing in a dead calm — each is a rule with a reason, and a second copy
+ * of any of them is a sea that behaves differently depending on which backend drew it. That is
+ * the 2026-08-13 rule in `AGENTS.md`.
+ */
+/**
+ * Everything the water shader needs that is not a colour, a matrix or the medium.
+ *
+ * **The three extents are pairs, and were single numbers until 2026-08-28.** A body bounded by one
+ * number is a square, and the shape a consumer actually has is a channel: long in one axis, narrow
+ * in the other. Each is measured along the body's **own** axes, which `forward` then turns into the
+ * world — so the rim and the wave fade follow the rectangle however it is laid, and the ocean passes
+ * the same number twice and is unchanged.
+ */
+export interface ResolvedWater {
+    /** Where the sheet is centred: snapped under the camera, or the body's own middle. */
+    readonly origin: Float32Array;
+    /** Metres per unit of the sheet's own grid, per axis. The ocean's grid is metres, so (1, 1). */
+    readonly span: Float32Array;
+    /** How far the sheet carries out, per axis. */
+    readonly half: Float32Array;
+    /** What the wave fade is measured against, so a bowl is flat at its rim. */
+    readonly nearHalf: Float32Array;
+    /** The body's own +z in world XZ, unit length. (0, 1) for anything unturned. */
+    readonly forward: Float32Array;
+    /** Unit wind bearing, or the authored fallback in a dead calm. */
+    readonly windDir: Float32Array;
+    waveGain: number;
+    foamGain: number;
+    /** Whether this body is a bounded patch rather than the ocean. */
+    bounded: boolean;
+}
+export declare function createResolvedWater(): ResolvedWater;
+/**
+ * Lay the sheet and settle the sea, into a target the caller owns.
+ *
+ * `cellSize`, `nearHalfExtent` and `farHalfExtent` come from the grid the renderer built, so
+ * they differ per renderer rather than being global — which is why they are arguments.
+ */
+export declare function resolveWater(settings: WaterBody, cameraX: number, cameraZ: number, cellSize: number, nearHalfExtent: number, farHalfExtent: number, windX: number, windZ: number, out: ResolvedWater): ResolvedWater;
+/** The body's own colours and scalars, read the same way by both backends. */
+export interface WaterAppearance {
+    readonly deepColor: Vec3;
+    readonly shallowColor: Vec3;
+    readonly level: number;
+    readonly nadirOpacity: number;
+    readonly visibility: number;
+    readonly mirror: number;
+}
+/** Defaults applied once, so neither backend invents its own. */
+export declare function waterAppearance(settings: WaterBody): WaterAppearance;

package/dist/render/waterDraw.js

@@ -0,0 +1,102 @@
+import { seaStateForAgitation, seaStateForWind } from './seaState.js';
+export function createResolvedWater() {
+    return {
+        origin: new Float32Array(2),
+        span: new Float32Array([1, 1]),
+        half: new Float32Array(2),
+        nearHalf: new Float32Array(2),
+        forward: new Float32Array([0, 1]),
+        windDir: new Float32Array([1, 0]),
+        waveGain: 0,
+        foamGain: 0,
+        bounded: false,
+    };
+}
+/**
+ * Lay the sheet and settle the sea, into a target the caller owns.
+ *
+ * `cellSize`, `nearHalfExtent` and `farHalfExtent` come from the grid the renderer built, so
+ * they differ per renderer rather than being global — which is why they are arguments.
+ */
+export function resolveWater(settings, cameraX, cameraZ, cellSize, nearHalfExtent, farHalfExtent, windX, windZ, out) {
+    const bounds = settings.bounds;
+    out.bounded = bounds !== undefined;
+    if (bounds === undefined) {
+        /*
+         * Snapped to whole cells. Anything else re-samples the wave field as the camera moves,
+         * which reads as the surface swimming rather than as the camera travelling over it.
+         */
+        out.origin[0] = Math.floor(cameraX / cellSize) * cellSize;
+        out.origin[1] = Math.floor(cameraZ / cellSize) * cellSize;
+        out.span[0] = 1;
+        out.span[1] = 1;
+        out.half[0] = farHalfExtent;
+        out.half[1] = farHalfExtent;
+        out.nearHalf[0] = nearHalfExtent;
+        out.nearHalf[1] = nearHalfExtent;
+        out.forward[0] = 0;
+        out.forward[1] = 1;
+    }
+    else {
+        out.origin[0] = bounds.centreX;
+        out.origin[1] = bounds.centreZ;
+        /*
+         * **`halfM` is the square shorthand and a per-axis extent overrides it on that axis alone.**
+         * The rule is applied here and nowhere else, which is what makes two spellings of a square
+         * affordable: a second place resolving them is where they would begin to disagree. A body given
+         * none of the three is zero-sized and draws nothing, which is a defined state and the right
+         * one — the other reading of "no extent" is the unbounded ocean, and omitting `bounds` already
+         * says that.
+         */
+        const halfX = bounds.halfX ?? bounds.halfM ?? 0;
+        const halfZ = bounds.halfZ ?? bounds.halfM ?? 0;
+        out.span[0] = halfX;
+        out.span[1] = halfZ;
+        out.half[0] = halfX;
+        out.half[1] = halfZ;
+        /* The wave fade measures against this, so a bounded body is flat at its own rim. */
+        out.nearHalf[0] = halfX;
+        out.nearHalf[1] = halfZ;
+        /*
+         * The direction the body's own +z takes, normalised here so that no backend has to.
+         *
+         * A direction of no length is read as unturned instead of divided by: the basis the shader
+         * builds from this places every vertex of the sheet, so a NaN here is not a wrong sheet, it is
+         * a sheet that is nowhere. `Math.sqrt` and not `Math.hypot`, as everywhere else here.
+         */
+        const fx = bounds.forwardX ?? 0;
+        const fz = bounds.forwardZ ?? 1;
+        const length = Math.sqrt(fx * fx + fz * fz);
+        out.forward[0] = length > 1e-6 ? fx / length : 0;
+        out.forward[1] = length > 1e-6 ? fz / length : 1;
+    }
+    const windSpeed = Math.hypot(windX, windZ);
+    /*
+     * **`agitation` is an override, not an addition.** Wind builds waves, which is right under
+     * the sky and wrong for a cistern, a flooded corridor or a tank below deck — those have a
+     * surface that moves with no wind to explain it, and tying them to the weather means a gale
+     * outside makes the water in a sealed room choppy.
+     */
+    const sea = settings.agitation === undefined
+        ? seaStateForWind(windSpeed)
+        : seaStateForAgitation(settings.agitation);
+    const inv = windSpeed > 1e-5 ? 1 / windSpeed : 0;
+    /* Falls back to the authored bearing in a dead calm rather than collapsing every wave
+       direction onto zero. */
+    out.windDir[0] = inv === 0 ? 1 : windX * inv;
+    out.windDir[1] = inv === 0 ? 0 : windZ * inv;
+    out.waveGain = sea.steepness * (settings.waveScale ?? 1);
+    out.foamGain = sea.foam;
+    return out;
+}
+/** Defaults applied once, so neither backend invents its own. */
+export function waterAppearance(settings) {
+    return {
+        deepColor: settings.deepColor,
+        shallowColor: settings.shallowColor,
+        level: settings.level,
+        nadirOpacity: settings.density ?? 0.22,
+        visibility: settings.visibility ?? 1,
+        mirror: settings.mirror ?? 0,
+    };
+}

package/dist/render/waterGrid.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The ocean's tessellation: a near sheet that carries waves, and a ringed skirt
+ * that carries distance.
+ *
+ * These are two different problems and one mesh cannot serve both.
+ *
+ * The near sheet must be *uniform* and snapped to whole cells. That combination
+ * is what makes the wave lattice invariant in world space: shifting by exactly
+ * one cell lands every vertex where its neighbour was, so the reconstructed
+ * surface does not change as the camera moves. Break the uniformity — grade the
+ * cells to buy reach, say — and that invariance goes with it. Cells wider than
+ * the snap quantum are re-sampled at a new phase on every snap, and the surface
+ * visibly swims underfoot.
+ *
+ * The skirt carries no displacement, so its tessellation cannot distort
+ * anything, and it can stretch to tens of kilometres. That reach is not
+ * decoration: a sheet that stops short ends in a straight line with a corner in
+ * it, and no alpha ramp hides that. At eye height the horizon of a flat plane is
+ * at infinity, so a fade measured in world metres compresses into a pixel or two
+ * of skyline and the corner survives. The rim has to be too small to resolve.
+ *
+ * But the skirt cannot be a single leap to the far edge either, even though its
+ * *shape* would be identical. Fog is evaluated per fragment from world position,
+ * so one triangle spanning 150 m to 30 km squeezes the entire fog gradient into
+ * the handful of pixels that triangle covers — which puts a hard line right back
+ * at the near sheet's rim, in exactly the place the skirt was meant to hide. So
+ * the skirt is a set of concentric rings whose radii grow geometrically, giving
+ * the gradient somewhere to happen. They are cheap: being flat, they need only
+ * enough vertices per side to stay a square.
+ */
+export interface WaterGrid {
+    /** Grid-local xz pairs, metres from the camera-snapped origin. */
+    readonly offsets: Float32Array;
+    readonly indices: Uint32Array;
+    /**
+     * Cell size of the near sheet. The grid origin snaps to whole multiples of
+     * this — see above for why that must equal the cell size exactly.
+     */
+    readonly cellSize: number;
+    /** Half-width of the wave-bearing near sheet. */
+    readonly nearHalfExtent: number;
+    /** Half-width of the outermost ring, i.e. how far the ocean reaches. */
+    readonly farHalfExtent: number;
+}
+export declare function buildWaterGrid(resolution: number, nearExtent: number, farHalfExtent: number): WaterGrid;
+/**
+ * Cells per side of the bounded-body patch.
+ *
+ * Exported so neither backend keeps its own copy: a patch built at two resolutions is two
+ * different meshes for the same pool, and nothing would raise.
+ */
+export declare const PATCH_RESOLUTION = 24;
+/**
+ * A flat square sheet in [-1, 1], for any body of water with edges.
+ *
+ * Here rather than in `waterRenderer.ts` because both backends build the same patch, and a
+ * second copy of a mesh generator is a bounded body whose triangles differ per backend.
+ */
+export declare function buildUnitSheet(resolution: number): {
+    offsets: Float32Array;
+    indices: Uint32Array;
+};

package/dist/render/waterGrid.js

@@ -0,0 +1,151 @@
+/**
+ * The ocean's tessellation: a near sheet that carries waves, and a ringed skirt
+ * that carries distance.
+ *
+ * These are two different problems and one mesh cannot serve both.
+ *
+ * The near sheet must be *uniform* and snapped to whole cells. That combination
+ * is what makes the wave lattice invariant in world space: shifting by exactly
+ * one cell lands every vertex where its neighbour was, so the reconstructed
+ * surface does not change as the camera moves. Break the uniformity — grade the
+ * cells to buy reach, say — and that invariance goes with it. Cells wider than
+ * the snap quantum are re-sampled at a new phase on every snap, and the surface
+ * visibly swims underfoot.
+ *
+ * The skirt carries no displacement, so its tessellation cannot distort
+ * anything, and it can stretch to tens of kilometres. That reach is not
+ * decoration: a sheet that stops short ends in a straight line with a corner in
+ * it, and no alpha ramp hides that. At eye height the horizon of a flat plane is
+ * at infinity, so a fade measured in world metres compresses into a pixel or two
+ * of skyline and the corner survives. The rim has to be too small to resolve.
+ *
+ * But the skirt cannot be a single leap to the far edge either, even though its
+ * *shape* would be identical. Fog is evaluated per fragment from world position,
+ * so one triangle spanning 150 m to 30 km squeezes the entire fog gradient into
+ * the handful of pixels that triangle covers — which puts a hard line right back
+ * at the near sheet's rim, in exactly the place the skirt was meant to hide. So
+ * the skirt is a set of concentric rings whose radii grow geometrically, giving
+ * the gradient somewhere to happen. They are cheap: being flat, they need only
+ * enough vertices per side to stay a square.
+ */
+/** Concentric rings between the near sheet and the far edge. */
+const SKIRT_RINGS = 12;
+/** Vertices per side of each ring. A flat square needs very few. */
+const SKIRT_SEGMENTS_PER_SIDE = 8;
+/**
+ * Point at parameter `t` (in [0, 4)) around a square of the given half-width,
+ * walked anticlockwise from the -x/-z corner. Consistent ordering across rings
+ * is what lets consecutive rings be stitched by index arithmetic alone.
+ */
+function squarePerimeter(t, radius) {
+    const side = Math.floor(t) % 4;
+    const u = t - Math.floor(t);
+    const span = radius * 2;
+    if (side === 0)
+        return [-radius + span * u, -radius];
+    if (side === 1)
+        return [radius, -radius + span * u];
+    if (side === 2)
+        return [radius - span * u, radius];
+    return [-radius, radius - span * u];
+}
+export function buildWaterGrid(resolution, nearExtent, farHalfExtent) {
+    const side = resolution + 1;
+    const cellSize = nearExtent / resolution;
+    const nearHalfExtent = nearExtent * 0.5;
+    const perimeter = SKIRT_SEGMENTS_PER_SIDE * 4;
+    const nearVertices = side * side;
+    const skirtVertices = (SKIRT_RINGS + 1) * perimeter;
+    const offsets = new Float32Array((nearVertices + skirtVertices) * 2);
+    for (let z = 0; z < side; z++) {
+        const gz = z * cellSize - nearHalfExtent;
+        for (let x = 0; x < side; x++) {
+            const v = (z * side + x) * 2;
+            offsets[v] = x * cellSize - nearHalfExtent;
+            offsets[v + 1] = gz;
+        }
+    }
+    // Geometric radii: each ring is the same factor wider than the last, so the
+    // fog gradient gets roughly equal screen space in every band.
+    const growth = (farHalfExtent / nearHalfExtent) ** (1 / SKIRT_RINGS);
+    for (let ring = 0; ring <= SKIRT_RINGS; ring++) {
+        const radius = ring === SKIRT_RINGS ? farHalfExtent : nearHalfExtent * growth ** ring;
+        for (let i = 0; i < perimeter; i++) {
+            const [px, pz] = squarePerimeter(i / SKIRT_SEGMENTS_PER_SIDE, radius);
+            const v = (nearVertices + ring * perimeter + i) * 2;
+            offsets[v] = px;
+            offsets[v + 1] = pz;
+        }
+    }
+    const indices = new Uint32Array(resolution * resolution * 6 + SKIRT_RINGS * perimeter * 6);
+    let i = 0;
+    for (let z = 0; z < resolution; z++) {
+        for (let x = 0; x < resolution; x++) {
+            const a = z * side + x;
+            const b = a + 1;
+            const c = a + side;
+            const d = c + 1;
+            indices[i++] = a;
+            indices[i++] = c;
+            indices[i++] = b;
+            indices[i++] = b;
+            indices[i++] = c;
+            indices[i++] = d;
+        }
+    }
+    for (let ring = 0; ring < SKIRT_RINGS; ring++) {
+        const inner = nearVertices + ring * perimeter;
+        const outer = inner + perimeter;
+        for (let k = 0; k < perimeter; k++) {
+            const next = (k + 1) % perimeter;
+            indices[i++] = inner + k;
+            indices[i++] = outer + k;
+            indices[i++] = inner + next;
+            indices[i++] = inner + next;
+            indices[i++] = outer + k;
+            indices[i++] = outer + next;
+        }
+    }
+    return { offsets, indices, cellSize, nearHalfExtent, farHalfExtent };
+}
+/**
+ * Cells per side of the bounded-body patch.
+ *
+ * Exported so neither backend keeps its own copy: a patch built at two resolutions is two
+ * different meshes for the same pool, and nothing would raise.
+ */
+export const PATCH_RESOLUTION = 24;
+/**
+ * A flat square sheet in [-1, 1], for any body of water with edges.
+ *
+ * Here rather than in `waterRenderer.ts` because both backends build the same patch, and a
+ * second copy of a mesh generator is a bounded body whose triangles differ per backend.
+ */
+export function buildUnitSheet(resolution) {
+    const side = resolution + 1;
+    const offsets = new Float32Array(side * side * 2);
+    let v = 0;
+    for (let z = 0; z < side; z++) {
+        for (let x = 0; x < side; x++) {
+            offsets[v++] = (x / resolution) * 2 - 1;
+            offsets[v++] = (z / resolution) * 2 - 1;
+        }
+    }
+    const indices = new Uint32Array(resolution * resolution * 6);
+    let i = 0;
+    for (let z = 0; z < resolution; z++) {
+        for (let x = 0; x < resolution; x++) {
+            const a = z * side + x;
+            const b = a + 1;
+            const c = a + side;
+            const d = c + 1;
+            indices[i++] = a;
+            indices[i++] = c;
+            indices[i++] = b;
+            indices[i++] = b;
+            indices[i++] = c;
+            indices[i++] = d;
+        }
+    }
+    return { offsets, indices };
+}

package/dist/render/waterRenderer.d.ts

@@ -0,0 +1,163 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+import type { Atmosphere } from './atmosphere.ts';
+import type { PlanarReflection } from './planarReflection.ts';
+import type { PointLightSet } from './lightBudget.ts';
+/**
+ * An endless wave surface. Game-agnostic: it takes a height, colours and a
+ * lighting environment, and knows nothing about what the water is for.
+ *
+ * The mesh is a fixed grid that follows the camera and is snapped to whole
+ * cells in the vertex shader, so a bounded vertex budget covers an unbounded
+ * ocean without the surface sliding underfoot. Displacement is Gerstner, so
+ * crests are sharp and troughs broad rather than a rolling sine blanket.
+ */
+/**
+ * A body of water: the sea, a fountain's basin, a tank, a puddle.
+ *
+ * One description and one material for all of them. The sea is not a special
+ * case with a shader of its own — it is this, unbounded and dense, and a
+ * fountain is this, bounded and clear. The first attempt gave a basin its own
+ * faked surface, and the correction was the right one: water should be a single
+ * configurable concept — density, visibility, up to fully transparent — rather
+ * than a trick per body of water. The sea is water too, and it gets the same
+ * reusable component with the same abilities.
+ *
+ * So every body gets the waves, the Fresnel, the specular, the fog and the
+ * planar reflection, and differs only in these numbers.
+ */
+export interface WaterBody {
+    /** Resting height of the surface. */
+    level: number;
+    deepColor: Vec3;
+    shallowColor: Vec3;
+    /**
+     * How much of what lies beneath it the water hides, looked straight down,
+     * 0 to 1. A sea hides its own floor; a fountain shows the tiles at the bottom
+     * of it; zero is glass. Only this end is configurable — at a grazing angle
+     * every water surface goes reflective, which is Fresnel rather than a property
+     * of the liquid.
+     */
+    density?: number;
+    /** The surface's overall visibility, 0 to 1. Zero draws nothing. */
+    visibility?: number;
+    /**
+     * How much it mirrors regardless of viewing angle, 0 to 1.
+     *
+     * Zero is physics — reflection by Fresnel alone, which is what an ocean does and
+     * what leaves a basin looking blank from directly above, since at that angle the
+     * Fresnel term is a few percent. A pool is looked *into*, so it is allowed to
+     * cheat; the sea is not, and keeps zero.
+     */
+    mirror?: number;
+    /**
+     * How built-up its waves are, as a multiple of what the wind is doing.
+     *
+     * One is the open sea. A basin wants a fraction of it: the same wave field at
+     * a scale where it reads as a surface breathing rather than as a swell rolling
+     * through somebody's fountain.
+     */
+    waveScale?: number;
+    /**
+     * How worked-up this body is on its own, 0 to 1, ignoring the wind entirely.
+     *
+     * For water the weather cannot reach: a cistern, a flooded corridor, a tank. Zero is
+     * as near still as this surface goes — never glass, because dead-flat water reads as a
+     * mirror rather than as calm — and one matches a fully developed sea.
+     *
+     * Omitted, the body takes its state from the wind it is drawn with, which is what an
+     * ocean, a lake or a fountain in a courtyard should do.
+     */
+    agitation?: number;
+    /**
+     * A bounded body: where it is, how far it reaches along each of its own axes, and which way
+     * those axes point.
+     *
+     * Omitted, the body is the endless ocean — the camera-following sheet the sea has always been.
+     * Given, it is a fixed rectangle of water sitting exactly where it was put.
+     *
+     * **It was a centre and one half-extent until 2026-08-28, and a square cannot bound a channel.**
+     * Reported from outside: a 3 by 21 metre ditch bounded by the square that contains it floods
+     * eighteen metres of field either side, so the workaround was a single *unbounded* body at the
+     * ditches' water level with the world's whole ground raised above it — a technically flooded
+     * world, held up by a rule nobody can see, that nothing anywhere may be drawn below the water
+     * line. It cost that consumer one bug already: a distant ground plane 1.6 m down, correct for its
+     * own reasons, put the village in a lake.
+     *
+     * **What this cannot do is bend.** A canal that turns is one body per straight run, and where two
+     * runs meet at a corner their sheets overlap and the blend doubles there. That is cheap to place
+     * and honest about what it draws; **what would change it** is a consumer measuring that seam as
+     * the problem, which is the day `bounds` grows a polyline and a width.
+     */
+    bounds?: WaterBounds;
+}
+/**
+ * Where a bounded body sits, how far it reaches and which way it faces.
+ *
+ * **Extents are measured along the body's own axes**, `x` across and `z` along `forward`, which is
+ * how `addOrientedBox` measures a box: one convention for an oriented thing in this engine, so a
+ * reader who has met one has met both.
+ */
+export interface WaterBounds {
+    centreX: number;
+    centreZ: number;
+    /**
+     * Half-extent along both axes, metres: the shorthand for a square.
+     *
+     * A pool, a tank and a puddle are square often enough to be worth one number, and this is that
+     * number. `halfX` and `halfZ` override it **per axis**, so `{ halfM: 9, halfX: 2 }` is two metres
+     * across and nine along. The cost is two ways to say one square; the rule is stated here and
+     * applied in exactly one place, `resolveWater`.
+     */
+    halfM?: number;
+    /** Half-extent across the body, metres. A channel is narrow in this one. */
+    halfX?: number;
+    /** Half-extent along `forward`, metres. A channel is long in this one. */
+    halfZ?: number;
+    /**
+     * Which way the body's own +z points, in world XZ. Unset, it points along world +z.
+     *
+     * **A direction and not an angle**, because a consumer bounding a channel, a ditch or a gutter
+     * arrives holding the direction the run takes — from a road graph, a spline's tangent, two
+     * endpoints — and converting that to radians and back is arithmetic nobody needs. It is
+     * normalised on the way in, so a length here is not a scale, and a direction of no length at all
+     * is read as unturned instead of producing a sheet at NaN.
+     */
+    forwardX?: number;
+    forwardZ?: number;
+}
+/** @deprecated The old name for an unbounded {@link WaterBody}. */
+export type WaterSettings = WaterBody;
+/** Vertices per side of a bounded body's sheet. A pool is not an ocean. */
+export declare class WaterRenderer {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    /** A unit sheet, scaled per draw: every bounded body shares this one mesh. */
+    private readonly patchVao;
+    private readonly patchIndexCount;
+    private readonly buffers;
+    private readonly indexCount;
+    private readonly cellSize;
+    private readonly nearHalfExtent;
+    private readonly farHalfExtent;
+    private readonly reflectionFilterTaps;
+    /** Refilled per draw rather than allocated; see `createResolvedWater`. */
+    private readonly resolved;
+    /**
+     * @param resolution cells per side of the wave-bearing near sheet.
+     * @param nearExtent total width of that sheet, in world metres.
+     * @param farHalfExtent how far the flat skirt carries the ocean out. There is
+     *   no point setting this far beyond the camera's far plane — geometry past it
+     *   is clipped, not drawn — so this only has to outrun the fog. See
+     *   `buildWaterGrid` for why these are two meshes and not one.
+     */
+    constructor(gl: WebGL2RenderingContext, resolution?: number, nearExtent?: number, farHalfExtent?: number, reflectionFilterTaps?: import("./renderQuality.ts").WaterReflectionFilterTaps);
+    /**
+     * Draw the surface. Call *after* the sky: water writes depth and is occluded
+     * by geometry in front of it, but its far edge fades out, and that fade needs
+     * the sky already behind it to blend into.
+     */
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, settings: WaterBody, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, reflection: PlanarReflection | null, lights?: PointLightSet | null, lightFalloff?: 'smooth' | 'inverseSquare', windX?: number, windZ?: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}