@yali-engine/water 0.11.0 → 0.13.0

package/dist/water.js

@@ -1,8 +1,40 @@
+import { bakeShore, toHalf } from "./shore.js";
 import { waterSurface } from "./water-shaders.gen.js";
 import { WaterWaves } from "./waves.js";
+/**
+ * The surface grid's index buffer (ADR-0222): quad (r, s) of the (rings + 1) × (segments + 1) lattice as (r, s) (r+1, s)
+ * (r+1, s+1) and (r, s) (r+1, s+1) (r, s+1).
+ */
+function gridIndices(device, rings, segments) {
+    const w = segments + 1;
+    const idx = new Uint32Array(rings * segments * 6);
+    let k = 0;
+    for (let r = 0; r < rings; r++) {
+        for (let s = 0; s < segments; s++) {
+            const a = r * w + s;
+            const b = (r + 1) * w + s;
+            idx[k++] = a;
+            idx[k++] = b;
+            idx[k++] = b + 1;
+            idx[k++] = a;
+            idx[k++] = b + 1;
+            idx[k++] = a + 1;
+        }
+    }
+    const buf = device.createBuffer({ label: 'yali:water:grid', size: idx.byteLength, usage: 0x10 | 0x08 });
+    device.queue.writeBuffer(buf, 0, idx);
+    return buf;
+}
+const TIERS = { high: 2, medium: 1, low: 0 };
 /** Bytes of `SurfaceParams` (`shaders/water/surface.wesl`): 4 cascades + 8 vectors. */
-const PARAMS_BYTES = (4 + 8) * 16;
+const PARAMS_BYTES = (4 + 8 + 4) * 16;
+/** The motion uniform (ADR-0210): this frame's and last frame's view-projections (unjittered), the eye's move, a flag. */
+const MOTION_BYTES = 16 * 4 * 2 + 16;
 /** The first ring's spacing (m) and how much wider each next ring is. */
+/** The surf field's texels a side (ADR-0223): 0.5 m over the demo's 256 m shore field. */
+const SURF_TEXELS = 512;
+/** Spray sprites (`SPRAY_SIDE`² in surface.wesl, ADR-0218). */
+const SPRAY_SPRITES = 192 * 192;
 const FIRST_RING = 0.12;
 const RING_GROWTH = 0.036;
 /**
@@ -39,18 +71,91 @@ export class Water {
     debugMirror = false;
     /** Off: nothing is drawn or computed (live). */
     enabled = true;
+    /** The waves' own motion for TAA (ADR-0210; live): off, TAA sees the surface as still (the camera's motion only). */
+    motion = true;
+    /** The surf's height in deep water, metres (ADR-0213; live). */
+    surfHeight;
+    /** The breaking ratio γ: a wave breaks when it is taller than γ × the depth (0.78, live). */
+    surfBreaking;
+    /** How far crests lean shoreward before they break (Gerstner's Q, 0–1, live). */
+    surfLean;
+    /** The depth (m) at which the surf rises out of the sea, and over which the open sea's waves calm (live). */
+    surfStart;
+    surfCalm;
+    /** The surf's period, seconds: set before `setSeabed` (the crests' phase is baked for it). */
+    surfPeriod;
+    /**
+     * How much waves differ (ADR-0218; live, 0–1): 1 = swell in sets, each crest's height varying along the shore so it breaks
+     * in sections; 0 = every wave alike.
+     */
+    surfVariety;
+    /** How far a crest that starts to break throws its lip forward (ADR-0218; live, 0–1). */
+    surfLip;
+    /** Spray thrown up by breaking waves (ADR-0218; live, 0 = none, 1 = default). */
+    spray;
+    /** The ripples finer than the cascades (ADR-0223; live, 0 none, 1 Cox & Munk's slope for the wind). */
+    ripples = 1;
+    #quality = 'high';
+    /**
+     * The quality tier (ADR-0220; live): `high` everything; `medium` the coarse foam pattern only, 16 reflection steps, half
+     * the spray; `low` no caustics, no scene reflections, no spray. Setting it sets those knobs (they stay live after).
+     */
+    get quality() {
+        return this.#quality;
+    }
+    set quality(q) {
+        if (!(q in TIERS))
+            throw Object.assign(new Error(`WATER_INVALID: quality ${q} is not high, medium or low`), { code: 'WATER_INVALID', path: 'quality' });
+        this.#quality = q;
+        this.reflectionSteps = q === 'high' ? 24 : 16;
+        this.reflections = q === 'low' ? 0 : 40;
+        this.spray = q === 'high' ? 1 : q === 'medium' ? 0.5 : 0;
+    }
+    #prevSurfTime = 0;
+    #shoreField = null;
+    #shoreTexture;
+    #spillTexture;
+    #prevClock = 0;
     rings;
     segments;
     #pipeline;
+    #sprayPipeline = null;
+    #sprayGroups = [null, null];
+    #sprayKey = '';
+    /**
+     * The surf field (ADR-0223): A (displacement, broken) and D (front, phase, height factor, carried whitewater) in
+     * ping-pong pairs, B (slope, face, onset) and C (fresh foam, swash cover, wet, film); `SURF_TEXELS`² over the shore field.
+     */
+    #surfA = [];
+    #surfB = null;
+    #surfC = null;
+    #surfD = [];
+    #surfPipeline = null;
+    #surfGroups = [null, null];
+    /** Which half of each pair this frame's surf field wrote. */
+    #surfParity = 0;
+    #motionPipeline = null;
+    #motionGroups = [null, null];
+    #motionParams;
+    #motionData = new Float32Array(MOTION_BYTES / 4);
+    #prevVP = new Float32Array(16);
+    #prevEye = new Float64Array(3);
+    /** Frames with last frame's waves kept (motion needs two). */
+    #motionFrames = 0;
+    /** Last frame's displacement, for the waves' motion (ADR-0210); made when TAA asks for motion. */
+    #prevDisplacement = null;
+    #scene = null;
     #copyDepth;
     #depthGroup = null;
     #under = false;
     #inv = 1;
     #params;
+    /** The grid's triangles (ADR-0222): two a quad over the (rings + 1) × (segments + 1) lattice of points. */
+    #indices;
     #data = new Float32Array(PARAMS_BYTES / 4);
     #sampler;
     #clamp;
-    #group = null;
+    #groups = [null, null];
     #groupKey = '';
     #depthKey = -1;
     #seconds = 0;
@@ -70,9 +175,26 @@ export class Water {
         this.shoreFoam = o.shoreFoam ?? 0.12;
         this.reflections = o.reflections ?? 40;
         this.reflectionSteps = o.reflectionSteps ?? 24;
+        this.surfHeight = o.surf?.height ?? 0.9;
+        this.surfBreaking = o.surf?.breaking ?? 0.78;
+        this.surfLean = o.surf?.lean ?? 0.55;
+        this.surfStart = o.surf?.start ?? 7;
+        this.surfCalm = o.surf?.calm ?? 4;
+        this.surfPeriod = o.surf?.period ?? 8;
+        this.surfVariety = o.surf?.variety ?? 1;
+        this.surfLip = o.surf?.lip ?? 1;
+        this.spray = o.surf?.spray ?? 1;
+        this.#shoreTexture = device.createTexture({ label: 'yali:water:shore', size: [1, 1], format: 'rgba16float', usage: 0x04 | 0x02 });
+        this.#spillTexture = device.createTexture({ label: 'yali:water:spill', size: [1, 1], format: 'rg16float', usage: 0x04 | 0x02 });
+        if (o.quality)
+            this.quality = o.quality;
         this.rings = o.rings ?? 240;
         this.segments = o.segments ?? 384;
         this.#params = device.createBuffer({ label: 'yali:water:surface', size: PARAMS_BYTES, usage: 0x40 | 0x08 });
+        this.#indices = gridIndices(device, this.rings, this.segments);
+        // Stand-ins until a seabed brings the surf (the shaders name the field's bindings either way).
+        this.#makeSurfField(1);
+        this.#motionParams = device.createBuffer({ label: 'yali:water:motion', size: MOTION_BYTES, usage: 0x40 | 0x08 });
         this.#clamp = device.createSampler({ label: 'yali:water:clamp', magFilter: 'linear', minFilter: 'linear' });
         this.#sampler = device.createSampler({ label: 'yali:water:wrap', addressModeU: 'repeat', addressModeV: 'repeat', magFilter: 'linear', minFilter: 'linear', mipmapFilter: 'linear' });
     }
@@ -88,12 +210,35 @@ export class Water {
             }),
             this.waves.init(cache),
             cache.compute({ label: 'yali:water:copy-depth', compute: { shader: waterSurface, entryPoint: 'copy_depth' } }).then((p) => (this.#copyDepth = p)),
+            // The surf field (ADR-0223).
+            cache.compute({ label: 'yali:water:surf-field', compute: { shader: waterSurface, entryPoint: 'surf_field' } }).then((p) => (this.#surfPipeline = p)),
+            // Spray (ADR-0218): soft sprites over the surface, premultiplied, depth-tested, never written.
+            cache
+                .render({
+                label: 'yali:water:spray',
+                vertex: { shader: waterSurface, entryPoint: 'vs_spray' },
+                fragment: { shader: waterSurface, entryPoint: 'fs_spray', targets: [{ format, blend: { color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' }, alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' } } }] },
+                primitive: { topology: 'triangle-list', cullMode: 'none' },
+                depthStencil: { format: 'depth32float', depthWriteEnabled: false, depthCompare: 'greater' },
+            })
+                .then((p) => (this.#sprayPipeline = p)),
+            // The waves' motion for TAA (ADR-0210): the same grid drawn into the motion target.
+            cache
+                .render({
+                label: 'yali:water:motion',
+                vertex: { shader: waterSurface, entryPoint: 'vs_motion' },
+                fragment: { shader: waterSurface, entryPoint: 'fs_motion', targets: [{ format: 'rgba16float' }] },
+                primitive: { topology: 'triangle-list', cullMode: 'none' },
+                depthStencil: { format: 'depth32float', depthWriteEnabled: true, depthCompare: 'greater' },
+            })
+                .then((p) => (this.#motionPipeline = p)),
         ]);
         this.#pipeline = pipeline;
     }
     prepare(f) {
         this.#seconds = this.frozenAt ?? f.seconds;
         this.#env = f.environment;
+        this.waves.foamThreshold = this.foamThreshold;
         const d = this.#data;
         const eye = f.camera.eye;
         const n = this.waves.tiles.length;
@@ -111,17 +256,239 @@ export class Water {
         d.set([this.level - eye[1], n, this.foamThreshold, this.foam], 20);
         d.set([...this.bodyColor, this.roughness], 24);
         d.set([...this.subsurfaceColor, this.subsurface], 28);
-        d.set([this.waves.size, 0, 0, 0], 32);
+        d.set([this.waves.size, this.spray, f.environment.cloudPanorama ? 1 : 0, TIERS[this.#quality]], 32);
         d.set([...this.absorption, this.refraction], 36);
         // The scene behind is read at the pre-exposure it was written with (this frame's).
         this.#inv = 1 / Math.max(1e-6, f.scene.preExposure);
-        d.set([this.shoreFoam, this.#under ? 1 : 0, this.#inv, 0], 40);
+        // The ripples finer than the cascades (ADR-0223) make up the slope variance Cox & Munk measured for this wind
+        // (0.003 + 0.00512 U in all, half an axis) that the cascades leave out; their gain over the finest cascade's own.
+        const sv = this.waves.slopeVariance;
+        const have = sv.reduce((a, b) => a + b, 0);
+        const missing = Math.max(0, (0.003 + 0.00512 * this.waves.wind) / 2 - have);
+        const ripples = this.ripples * Math.min(8, Math.sqrt(missing / Math.max(1e-9, sv[sv.length - 1] * 0.74)));
+        d.set([this.shoreFoam, this.#under ? 1 : 0, this.#inv, ripples], 40);
         d.set([this.reflections, this.reflectionSteps, 0.6, this.debugMirror ? 1 : 0], 44);
+        // The surf (ADR-0213): the eye on the shore field (f64 here, small after), the crest clock now and last frame.
+        const sf = this.#shoreField;
+        const period = this.surfPeriod;
+        const clock = 2 * Math.PI * ((((this.#seconds % period) + period) % period) / period);
+        if (sf) {
+            const extent = sf.size * sf.cell;
+            d.set([(eye[0] - sf.origin[0] + sf.cell / 2) / extent, (eye[2] - sf.origin[1] + sf.cell / 2) / extent, 1 / extent, 1], 48);
+        }
+        else
+            d.set([0, 0, 0, 0], 48);
+        d.set([this.surfHeight, period, this.surfBreaking, this.surfLean], 52);
+        d.set([clock, this.surfCalm, this.surfStart, this.#prevClock], 56);
+        this.#prevClock = clock;
+        // The surf's time (ADR-0218), wrapped at 4096 periods: with the arrival time it numbers each wave.
+        const span = period * 4096;
+        const surfTime = ((this.#seconds % span) + span) % span;
+        d.set([surfTime, this.surfVariety, this.surfLip, this.#prevSurfTime], 60);
+        this.#prevSurfTime = surfTime;
         this.device.queue.writeBuffer(this.#params, 0, d);
+        if (this.enabled)
+            this.#runSurfField();
+        if (this.#prevDisplacement) {
+            // Motion: this frame's view-projection (camera-relative, unjittered: `camera.uniform`), last frame's, and how far
+            // the eye moved (last frame's camera-relative points are this frame's plus it).
+            const m = this.#motionData;
+            const vp = f.camera.uniform;
+            for (let i = 0; i < 16; i++)
+                m[i] = vp[i];
+            m.set(this.#prevVP, 16);
+            for (let i = 0; i < 3; i++)
+                m[32 + i] = eye[i] - this.#prevEye[i];
+            // Until last frame's waves exist (two frames), the waves count as still: the camera's motion only.
+            m[35] = this.motion && this.#motionFrames >= 2 && this.frozenAt === null ? 1 : 0;
+            this.device.queue.writeBuffer(this.#motionParams, 0, m);
+            for (let i = 0; i < 16; i++)
+                this.#prevVP[i] = vp[i];
+            for (let i = 0; i < 3; i++)
+                this.#prevEye[i] = eye[i];
+        }
+    }
+    /** The surf field's textures (ADR-0223), made with the seabed: four rgba16float targets, A and D in pairs. */
+    #makeSurfField(texels) {
+        for (const t of [...this.#surfA, ...this.#surfD, this.#surfB, this.#surfC])
+            t?.destroy();
+        const make = (label) => this.device.createTexture({ label, size: [texels, texels], format: 'rgba16float', usage: 0x08 | 0x04 });
+        this.#surfA = [make('yali:water:surf-a0'), make('yali:water:surf-a1')];
+        this.#surfB = make('yali:water:surf-b');
+        this.#surfC = make('yali:water:surf-c');
+        this.#surfD = [make('yali:water:surf-d0'), make('yali:water:surf-d1')];
+    }
+    /** The surf field as the surface, motion and spray passes read it: this frame's half `p` and last frame's. */
+    #surfEntries(p) {
+        if (!this.#surfB)
+            return [];
+        return [
+            { binding: 17, resource: this.#surfA[p].createView() },
+            { binding: 18, resource: this.#surfB.createView() },
+            { binding: 19, resource: this.#surfC.createView() },
+            { binding: 20, resource: this.#surfD[p].createView() },
+            // Last frame's displacement (the motion pass's; auto layouts keep it wherever `surf_tex` is compiled in). Last
+            // frame's whitewater (22) only the surf field reads.
+            { binding: 21, resource: this.#surfA[1 - p].createView() },
+        ];
+    }
+    /**
+     * The surf field for this frame (ADR-0223), in its own submission before the frame's passes (TAA's motion pass may come
+     * before a feature's own): `surf_field` writes A and D's other half from last frame's D.
+     */
+    #runSurfField() {
+        if (!this.#surfPipeline || !this.#surfB || !this.#shoreField)
+            return;
+        const p = 1 - this.#surfParity;
+        this.#surfParity = p;
+        this.#surfGroups[p] ??= this.device.createBindGroup({
+            label: 'yali:water:surf-field',
+            layout: this.#surfPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 2, resource: { buffer: this.#params } },
+                { binding: 9, resource: this.#clamp },
+                { binding: 14, resource: this.#shoreTexture.createView() },
+                { binding: 15, resource: this.#spillTexture.createView() },
+                { binding: 22, resource: this.#surfD[1 - p].createView() },
+                { binding: 23, resource: this.#surfA[p].createView() },
+                { binding: 24, resource: this.#surfB.createView() },
+                { binding: 25, resource: this.#surfC.createView() },
+                { binding: 26, resource: this.#surfD[p].createView() },
+            ],
+        });
+        const enc = this.device.createCommandEncoder({ label: 'yali:water:surf-field' });
+        const pass = enc.beginComputePass({ label: 'yali:water:surf-field' });
+        pass.setPipeline(this.#surfPipeline);
+        pass.setBindGroup(0, this.#surfGroups[p]);
+        pass.dispatchWorkgroups(SURF_TEXELS / 8, SURF_TEXELS / 8);
+        pass.end();
+        this.device.queue.submit([enc.finish()]);
+    }
+    /**
+     * The surf field's GPU cost, ms a frame (ADR-0223): one submission of `frames` + 1 dispatches less one of 1, over
+     * `frames`, each timed to `onSubmittedWorkDone` (the render loop's own frames land in either window, and the difference
+     * cancels them; the field runs in its own submission, which the frame graph's timers do not see). Null without a seabed.
+     *
+     * @example
+     * const ms = await ocean.measureSurf();
+     */
+    async measureSurf(frames = 20) {
+        const p = this.#surfParity;
+        const group = this.#surfGroups[p];
+        if (!this.#surfPipeline || !group)
+            return null;
+        const run = async (n) => {
+            const enc = this.device.createCommandEncoder({ label: 'yali:water:surf-measure' });
+            const pass = enc.beginComputePass();
+            pass.setPipeline(this.#surfPipeline);
+            pass.setBindGroup(0, group);
+            for (let i = 0; i < n; i++)
+                pass.dispatchWorkgroups(SURF_TEXELS / 8, SURF_TEXELS / 8);
+            pass.end();
+            await this.device.queue.onSubmittedWorkDone();
+            const t0 = performance.now();
+            this.device.queue.submit([enc.finish()]);
+            await this.device.queue.onSubmittedWorkDone();
+            return performance.now() - t0;
+        };
+        await run(2);
+        const small = await run(1);
+        return Math.max(0, (await run(frames + 1)) - small) / frames;
+    }
+    /**
+     * The seabed under the water (ADR-0213): bakes the shore field (`bakeShore`: depth, the crests' arrival phase for
+     * `surfPeriod`, their direction) and uploads it; the surf then rises, bends to the beach and breaks. Call again after
+     * changing `surfPeriod` or the seabed.
+     *
+     * @example
+     * ocean.setSeabed({ heights, size: 256, cell: 1, origin: [-128, -198] });
+     */
+    setSeabed(seabed) {
+        const field = bakeShore(seabed, this.level, this.surfPeriod);
+        const half = new Uint16Array(field.data.length);
+        for (let i = 0; i < half.length; i++)
+            half[i] = toHalf(field.data[i]);
+        this.#shoreTexture.destroy();
+        this.#shoreTexture = this.device.createTexture({ label: 'yali:water:shore', size: [field.size, field.size], format: 'rgba16float', usage: 0x04 | 0x02 });
+        this.device.queue.writeTexture({ texture: this.#shoreTexture }, half, { bytesPerRow: field.size * 8 }, [field.size, field.size]);
+        // The lowest passes to the sea (ADR-0216), clamped to what a half float holds, and the crests' arrival time (s): with
+        // the exact phase it numbers each wave, so waves come in sets and break in sections (ADR-0218).
+        const spill = new Uint16Array(field.spill.length * 2);
+        for (let i = 0; i < field.spill.length; i++) {
+            spill[i * 2] = toHalf(Math.min(field.spill[i], 6e4));
+            const t = field.arrival[i];
+            spill[i * 2 + 1] = toHalf(Number.isFinite(t) ? Math.min(t, 6e4) : 0);
+        }
+        this.#spillTexture.destroy();
+        this.#spillTexture = this.device.createTexture({ label: 'yali:water:spill', size: [field.size, field.size], format: 'rg16float', usage: 0x04 | 0x02 });
+        this.device.queue.writeTexture({ texture: this.#spillTexture }, spill, { bytesPerRow: field.size * 4 }, [field.size, field.size]);
+        this.#shoreField = field;
+        this.#groups = [null, null];
+        this.#groupKey = '';
+        this.#motionGroups = [null, null];
+        this.#sprayGroups = [null, null];
+        this.#surfGroups = [null, null];
+        this.#makeSurfField(SURF_TEXELS);
+        return field;
+    }
+    /** The baked shore field, or null before `setSeabed`. */
+    get shoreField() {
+        return this.#shoreField;
+    }
+    addMotionPasses(graph, motion, depth) {
+        const disp = this.waves.displacement;
+        this.#prevDisplacement ??= this.device.createTexture({ label: 'yali:water:displacement-prev', size: [disp.width, disp.height, disp.depthOrArrayLayers], format: disp.format, usage: 0x04 | 0x02 });
+        this.#motionGroups = [null, null];
+        graph.addPass({
+            name: 'water.motion',
+            kind: 'render',
+            reads: ['water.waves'],
+            color: { target: motion, clear: { r: 0, g: 0, b: 0, a: 0 }, load: true },
+            depth: { target: depth, clear: 0, load: true, store: true },
+            execute: (pass) => {
+                if (!this.enabled || !this.#motionPipeline || !this.#scene)
+                    return;
+                const mp = this.#surfParity;
+                this.#motionGroups[mp] ??= this.device.createBindGroup({
+                    label: 'yali:water:motion',
+                    layout: this.#motionPipeline.getBindGroupLayout(0),
+                    entries: [
+                        { binding: 0, resource: { buffer: this.#scene.cameraBuffer } },
+                        { binding: 2, resource: { buffer: this.#params } },
+                        { binding: 3, resource: disp.createView({ dimension: '2d-array' }) },
+                        { binding: 5, resource: this.#sampler },
+                        { binding: 12, resource: this.#prevDisplacement.createView({ dimension: '2d-array' }) },
+                        { binding: 13, resource: { buffer: this.#motionParams } },
+                        { binding: 9, resource: this.#clamp },
+                        { binding: 14, resource: this.#shoreTexture.createView() },
+                        { binding: 15, resource: this.#spillTexture.createView() },
+                        ...this.#surfEntries(mp),
+                    ],
+                });
+                pass.setPipeline(this.#motionPipeline);
+                pass.setBindGroup(0, this.#motionGroups[mp]);
+                pass.setIndexBuffer(this.#indices, 'uint32');
+                pass.drawIndexed(this.rings * this.segments * 6);
+            },
+        });
+        // After TAA has read this frame's motion, keep this frame's waves for the next frame's.
+        graph.addPass({
+            name: 'water.keepWaves',
+            kind: 'encoder',
+            reads: ['water.motion'],
+            writes: [motion],
+            execute: (encoder) => {
+                if (!this.enabled)
+                    return;
+                encoder.copyTextureToTexture({ texture: disp }, { texture: this.#prevDisplacement }, [disp.width, disp.height, disp.depthOrArrayLayers]);
+                this.#motionFrames++;
+            },
+        });
     }
     addPasses(graph, color, depth, scene) {
         // What the surface looks through (ADR-0199): the opaque scene's colour and depth, copied before it draws.
         this.#under = true;
+        this.#scene = scene;
         graph.transientTexture('water.under', { format: 'rgba16float', usage: 0x02 | 0x04 });
         graph.transientTexture('water.depth', { format: 'r32float', usage: 0x08 | 0x04 });
         graph.addPass({
@@ -171,10 +538,15 @@ export class Water {
                 const env = this.#env;
                 if (!this.enabled || !env)
                     return;
-                const key = `${env.version}:${ctx.generation}`;
-                if (!this.#group || key !== this.#groupKey) {
+                const pano = env.cloudPanorama;
+                const key = `${env.version}:${ctx.generation}:${pano ? pano.label : '-'}`;
+                const gp = this.#surfParity;
+                if (key !== this.#groupKey) {
                     this.#groupKey = key;
-                    this.#group = this.device.createBindGroup({
+                    this.#groups = [null, null];
+                }
+                if (!this.#groups[gp]) {
+                    this.#groups[gp] = this.device.createBindGroup({
                         label: 'yali:water:surface',
                         layout: this.#pipeline.getBindGroupLayout(0),
                         entries: [
@@ -188,15 +560,185 @@ export class Water {
                             { binding: 7, resource: ctx.view('water.under') },
                             { binding: 8, resource: ctx.view('water.depth') },
                             { binding: 9, resource: this.#clamp },
+                            { binding: 14, resource: this.#shoreTexture.createView() },
+                            { binding: 15, resource: this.#spillTexture.createView() },
+                            // The clouds' panorama (ADR-0219), or a stand-in the shader never reads (size.z = 0).
+                            { binding: 16, resource: (pano ?? this.#spillTexture).createView() },
+                            ...this.#surfEntries(gp),
                         ],
                     });
                 }
                 pass.setPipeline(this.#pipeline);
-                pass.setBindGroup(0, this.#group);
-                pass.draw(this.rings * this.segments * 6);
+                pass.setBindGroup(0, this.#groups[gp]);
+                pass.setIndexBuffer(this.#indices, 'uint32');
+                pass.drawIndexed(this.rings * this.segments * 6);
+            },
+        });
+        // Spray over the surface (ADR-0218): drawn only with a seabed (the surf), one instance per sprite.
+        graph.addPass({
+            name: 'water.spray',
+            kind: 'render',
+            reads: ['water.waves', 'water.depth'],
+            color: { target: color, clear: { r: 0, g: 0, b: 0, a: 0 }, load: true },
+            depth: { target: depth, clear: 0, load: true, store: true },
+            execute: (pass, ctx) => {
+                if (!this.enabled || this.spray <= 0 || !this.#shoreField || !this.#sprayPipeline)
+                    return;
+                const key = `${ctx.generation}`;
+                const sq = this.#surfParity;
+                if (key !== this.#sprayKey) {
+                    this.#sprayKey = key;
+                    this.#sprayGroups = [null, null];
+                }
+                if (!this.#sprayGroups[sq]) {
+                    this.#sprayGroups[sq] = this.device.createBindGroup({
+                        label: 'yali:water:spray',
+                        layout: this.#sprayPipeline.getBindGroupLayout(0),
+                        entries: [
+                            { binding: 0, resource: { buffer: scene.cameraBuffer } },
+                            { binding: 1, resource: { buffer: scene.lightingBuffer } },
+                            { binding: 2, resource: { buffer: this.#params } },
+                            { binding: 8, resource: ctx.view('water.depth') },
+                            { binding: 9, resource: this.#clamp },
+                            { binding: 14, resource: this.#shoreTexture.createView() },
+                            { binding: 15, resource: this.#spillTexture.createView() },
+                            ...this.#surfEntries(sq),
+                        ],
+                    });
+                }
+                pass.setPipeline(this.#sprayPipeline);
+                pass.setBindGroup(0, this.#sprayGroups[sq]);
+                pass.draw(6, SPRAY_SPRITES);
             },
         });
     }
+    /**
+     * Its agent tools (ADR-0204): `water.state` reads the sea, `water.set` turns its knobs, `water.sea` makes a new sea.
+     * Errors carry the argument's `path`.
+     */
+    tools() {
+        const bad = (path, message) => Object.assign(new Error(`WATER_INVALID: ${path} ${message}`), { code: 'WATER_INVALID', path, message: `${path} ${message}` });
+        const num = (args, k, min, max = Number.POSITIVE_INFINITY) => {
+            const v = args[k];
+            if (v === undefined)
+                return undefined;
+            if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max)
+                throw bad(k, `must be a number from ${min}${Number.isFinite(max) ? ` to ${max}` : ''}`);
+            return v;
+        };
+        const state = () => ({
+            enabled: this.enabled,
+            quality: this.#quality,
+            level: this.level,
+            choppiness: this.waves.choppiness,
+            foam: this.foam,
+            refraction: this.refraction,
+            shoreFoam: this.shoreFoam,
+            reflections: this.reflections,
+            reflectionSteps: this.reflectionSteps,
+            frozenAt: this.frozenAt,
+            cascades: this.waves.tiles.length,
+            tiles: [...this.waves.tiles],
+            size: this.waves.size,
+            gpuBytes: this.gpuBytes,
+            surf: { seabed: !!this.#shoreField, height: this.surfHeight, period: this.surfPeriod, breaking: this.surfBreaking, lean: this.surfLean, start: this.surfStart, calm: this.surfCalm, variety: this.surfVariety, lip: this.surfLip, spray: this.spray },
+        });
+        return [
+            { name: 'water.state', description: 'The water: on or off, its level, knobs (choppiness, foam, refraction, shore foam, reflections), whether its waves are held still, its cascades and GPU bytes.', input: { type: 'object', properties: {} }, run: state },
+            {
+                name: 'water.set',
+                description: "Turns the water's live knobs; only the arguments given change. Returns the new state.",
+                input: {
+                    type: 'object',
+                    properties: {
+                        enabled: { type: 'boolean', description: 'Draw and compute the water at all.' },
+                        quality: { type: 'string', description: 'The quality tier, high, medium or low: high everything, medium for laptops, low the cheapest (no caustics, reflections or spray).' },
+                        choppiness: { type: 'number', description: 'Horizontal crest sharpening, 0 to 1.5.' },
+                        foam: { type: 'number', description: 'Whitecap amount, 0 or more.' },
+                        refraction: { type: 'number', description: 'How far the bed is bent by the waves, pixels, 0 or more.' },
+                        shoreFoam: { type: 'number', description: 'Water depth under which the shore foams, metres, 0 or more.' },
+                        reflections: { type: 'number', description: 'How far screen-space reflections reach, metres, 0 (off) or more.' },
+                        freeze: { type: 'number', description: 'Hold the waves at this time, seconds (0 or more).' },
+                        surfHeight: { type: 'number', description: 'The height of the surf in deep water, metres, 0 to 4 (needs a seabed: setSeabed).' },
+                        surfBreaking: { type: 'number', description: 'Breaking ratio: a wave breaks when taller than this × the depth, 0.3 to 1.2.' },
+                        surfLean: { type: 'number', description: 'How far crests lean shoreward before breaking, 0 to 1.' },
+                        surfVariety: { type: 'number', description: 'How much waves differ: sets and sections along the shore, 0 (all alike) to 1.' },
+                        surfLip: { type: 'number', description: 'How far a breaking crest throws its lip forward, 0 to 1.' },
+                        spray: { type: 'number', description: 'Spray thrown up by breaking waves, 0 (none) to 4; 1 is the default.' },
+                        follow: { type: 'boolean', description: 'true: the waves follow the app clock again.' },
+                    },
+                },
+                run: (args) => {
+                    if (args.enabled !== undefined)
+                        this.enabled = !!args.enabled;
+                    if (args.quality !== undefined) {
+                        if (args.quality !== 'high' && args.quality !== 'medium' && args.quality !== 'low')
+                            throw bad('quality', 'must be high, medium or low');
+                        this.quality = args.quality;
+                    }
+                    const c = num(args, 'choppiness', 0, 1.5);
+                    if (c !== undefined)
+                        this.waves.choppiness = c;
+                    const f = num(args, 'foam', 0);
+                    if (f !== undefined)
+                        this.foam = f;
+                    const r = num(args, 'refraction', 0);
+                    if (r !== undefined)
+                        this.refraction = r;
+                    const s = num(args, 'shoreFoam', 0);
+                    if (s !== undefined)
+                        this.shoreFoam = s;
+                    const m = num(args, 'reflections', 0);
+                    if (m !== undefined)
+                        this.reflections = m;
+                    const t = num(args, 'freeze', 0);
+                    if (t !== undefined)
+                        this.frozenAt = t;
+                    if (args.follow === true)
+                        this.frozenAt = null;
+                    const sh = num(args, 'surfHeight', 0, 4);
+                    if (sh !== undefined)
+                        this.surfHeight = sh;
+                    const sb = num(args, 'surfBreaking', 0.3, 1.2);
+                    if (sb !== undefined)
+                        this.surfBreaking = sb;
+                    const sl = num(args, 'surfLean', 0, 1);
+                    if (sl !== undefined)
+                        this.surfLean = sl;
+                    const sv = num(args, 'surfVariety', 0, 1);
+                    if (sv !== undefined)
+                        this.surfVariety = sv;
+                    const sp = num(args, 'surfLip', 0, 1);
+                    if (sp !== undefined)
+                        this.surfLip = sp;
+                    const sr = num(args, 'spray', 0, 4);
+                    if (sr !== undefined)
+                        this.spray = sr;
+                    return state();
+                },
+            },
+            {
+                name: 'water.sea',
+                description: 'A new sea on the same cascades: the wind speed (m/s), its fetch (m) and direction (radians from +x). The waves change next frame.',
+                input: {
+                    type: 'object',
+                    properties: {
+                        wind: { type: 'number', description: 'Wind speed 10 m up, m/s, above 0 (5 calm, 11 breeze, 19 gale).' },
+                        fetch: { type: 'number', description: 'Distance the wind has blown over water, m, above 0 (default 200,000).' },
+                        direction: { type: 'number', description: 'Wind direction, radians from +x (default 0).' },
+                    },
+                    required: ['wind'],
+                },
+                run: (args) => {
+                    const wind = num(args, 'wind', 0.1, 60);
+                    const fetch = num(args, 'fetch', 1) ?? 200_000;
+                    const direction = num(args, 'direction', -Math.PI * 4, Math.PI * 4) ?? 0;
+                    this.waves.reseed({ wind, fetch, direction });
+                    return { wind, fetch, direction, ...state() };
+                },
+            },
+        ];
+    }
     /** What the sea holds on the GPU (its waves; the surface has no buffers). */
     get gpuBytes() {
         return this.waves.gpuBytes;
@@ -204,6 +746,13 @@ export class Water {
     destroy() {
         this.waves.destroy();
         this.#params.destroy();
+        this.#indices.destroy();
+        for (const t of [...this.#surfA, ...this.#surfD, this.#surfB, this.#surfC])
+            t?.destroy();
+        this.#motionParams.destroy();
+        this.#shoreTexture.destroy();
+        this.#spillTexture.destroy();
+        this.#prevDisplacement?.destroy();
     }
 }
 //# sourceMappingURL=water.js.map