@woosh/meep-engine 3.40.0 → 3.42.0

package/src/shade/renderer/water/surface/particles/GPUWaterParticles.d.ts

@@ -0,0 +1,60 @@
+/** The longest step a particle takes in one frame, seconds: a stalled tab does not fling fronts across a lake. */
+export const WATER_PARTICLE_STEP_LIMIT: number;
+/**
+ * The wave particles of every water body of a scene, on the device (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md
+ * §5.4): ping-pong particle arrays, and each frame's hash of them for the surface sampler. Counts never leave
+ * the GPU; every pass over particles is dispatched indirectly from the count the previous pass wrote.
+ */
+export class GPUWaterParticles {
+    /** @returns {GPUBuffer} the frame's hash: table size, then inclusive bucket offsets */
+    get offsets(): GPUBuffer;
+    /** @returns {GPUBuffer} the frame's entries, bucket by bucket, each bucket ordered by particle */
+    get entries(): GPUBuffer;
+    /** @returns {GPUBuffer} per wave row: occupied-level mask, then a height bound per level (f32 bits) */
+    get body_bounds(): GPUBuffer;
+    /** @returns {GPUBuffer} the live particles: count, then records */
+    get particles(): GPUBuffer;
+    get capacity(): number;
+    /**
+     * Allocate for a device, a capacity and a number of wave rows.
+     *
+     * When the rows grow, the bounds the last stepping frame wrote are carried into the larger buffer: a paused
+     * frame does not rebuild them, and every body's surface is culled and tessellated by them.
+     *
+     * @param {GPUDevice} device
+     * @param {number} capacity
+     * @param {number} rows
+     * @returns {function(import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext):void|null} when the
+     * rows grew, encodes the carry and releases the old buffer once it ran; encode it before this frame's passes
+     */
+    prepare(device: GPUDevice, capacity: number, rows: number): (arg0: import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext) => void | null;
+    dispose(): void;
+    /**
+     * The frame's particles (§5.4): when the frame steps, one step of every particle of a body simulated this frame (a
+     * paused body's stand still) and the splashes of the culling pass's emit list; then, every frame, the hash of the
+     * particles of the bodies simulated this frame, which the surface sampler gathers from, and their bounds. The hash
+     * is rebuilt on a frame that does not step too, since the bodies in view change with the camera.
+     *
+     * @param {object} options
+     * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {object} options.scene GPU scene context: database, geometries
+     * @param {GPUBuffer} options.steep per wave row: non-zero for a body that must stay calm
+     * @param {GPUBuffer} options.activity per wave row: the culling pass's {@link WaterActivity} bits
+     * @param {GPUBuffer} options.emit_rows the culling pass's emit list
+     * @param {GPUBuffer} options.commands the culling pass's commands
+     * @param {number} options.emit_command byte offset of the emit list's command in `commands`
+     * @param {number} options.dt seconds; zero for a frame that does not step
+     */
+    record({ graph, scene, steep, activity, emit_rows, commands, emit_command, dt }: {
+        graph: import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+        scene: object;
+        steep: GPUBuffer;
+        activity: GPUBuffer;
+        emit_rows: GPUBuffer;
+        commands: GPUBuffer;
+        emit_command: number;
+        dt: number;
+    }): void;
+    #private;
+}
+//# sourceMappingURL=GPUWaterParticles.d.ts.map

package/src/shade/renderer/water/surface/particles/GPUWaterParticles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUWaterParticles.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/GPUWaterParticles.js"],"names":[],"mappings":"AAuBA,kHAAkH;AAClH,+CAAgD;AAUhD;;;;GAIG;AACH;IAkBI,uFAAuF;IACvF,yBAAuC;IACvC,kGAAkG;IAClG,yBAAuC;IACvC,uGAAuG;IACvG,6BAA+C;IAC/C,mEAAmE;IACnE,2BAAyD;IACzD,uBAAyC;IAEzC;;;;;;;;;;;OAWG;IACH,qCALW,MAAM,QACN,MAAM,UACK,OAAO,8CAA8C,EAAE,sBAAsB,KAAE,IAAI,GAAC,IAAI,CA4C7G;IAED,gBAWC;IAED;;;;;;;;;;;;;;;OAeG;IACH;QATyG,KAAK,EAAnG,OAAO,iEAAiE,EAAE,UAAU;QACpE,KAAK,EAArB,MAAM;QACa,KAAK;QACL,QAAQ;QACR,SAAS;QACT,QAAQ;QACX,YAAY,EAA5B,MAAM;QACU,EAAE,EAAlB,MAAM;aA6EhB;;CACJ"}

package/src/shade/renderer/water/surface/particles/GPUWaterParticles.js

@@ -0,0 +1,228 @@
+import { assert } from "../../../../../core/assert.js";
+import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import {
+    build_indirect_compute_dispatch_command,
+    INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
+} from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { graph_import_buffer } from "../../../shader/graph/graph_import_buffer.js";
+import { WATER_PARTICLE_BODY_BOUNDS_STRIDE } from "../shader_water_waves_combine.js";
+import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
+import {
+    shader_water_particles_bin,
+    shader_water_particles_bounds,
+    shader_water_particles_emit,
+    shader_water_particles_finalize,
+    shader_water_particles_rank,
+    shader_water_particles_scatter,
+    shader_water_particles_split,
+    shader_water_particles_total,
+    shader_water_particles_update,
+    shader_water_particles_weigh,
+    WATER_PARTICLE_CORNERS
+} from "./shader_water_particles.js";
+
+/** The longest step a particle takes in one frame, seconds: a stalled tab does not fling fronts across a lake. */
+export const WATER_PARTICLE_STEP_LIMIT = 1 / 15;
+
+/**
+ * @param {number} value
+ * @returns {number} the smallest power of two at least value
+ */
+function power_of_two_at_least(value) {
+    return 2 ** Math.ceil(Math.log2(Math.max(value, 1)));
+}
+
+/**
+ * The wave particles of every water body of a scene, on the device (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md
+ * §5.4): ping-pong particle arrays, and each frame's hash of them for the surface sampler. Counts never leave
+ * the GPU; every pass over particles is dispatched indirectly from the count the previous pass wrote.
+ */
+export class GPUWaterParticles {
+    #device = null;
+    #capacity = 0;
+    #table_limit = 0;
+    #rows = 0;
+    #parity = 0;
+    #particles = [];
+    #children = null;
+    #buckets = null;
+    #slots = null;
+    #bucket_amplitude = null;
+    #bucket_weight = null;
+    #visible = null;
+    #staging = null;
+    #entries = null;
+    #body_bounds = null;
+    #commands = null;
+
+    /** @returns {GPUBuffer} the frame's hash: table size, then inclusive bucket offsets */
+    get offsets() { return this.#buckets; }
+    /** @returns {GPUBuffer} the frame's entries, bucket by bucket, each bucket ordered by particle */
+    get entries() { return this.#entries; }
+    /** @returns {GPUBuffer} per wave row: occupied-level mask, then a height bound per level (f32 bits) */
+    get body_bounds() { return this.#body_bounds; }
+    /** @returns {GPUBuffer} the live particles: count, then records */
+    get particles() { return this.#particles[this.#parity]; }
+    get capacity() { return this.#capacity; }
+
+    /**
+     * Allocate for a device, a capacity and a number of wave rows.
+     *
+     * When the rows grow, the bounds the last stepping frame wrote are carried into the larger buffer: a paused
+     * frame does not rebuild them, and every body's surface is culled and tessellated by them.
+     *
+     * @param {GPUDevice} device
+     * @param {number} capacity
+     * @param {number} rows
+     * @returns {function(import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext):void|null} when the
+     * rows grew, encodes the carry and releases the old buffer once it ran; encode it before this frame's passes
+     */
+    prepare(device, capacity, rows) {
+        assert.isNonNegativeInteger(capacity, 'capacity');
+        assert.greaterThan(capacity, 0, 'capacity');
+        if (device !== this.#device || capacity !== this.#capacity) {
+            this.dispose();
+            this.#device = device;
+            this.#capacity = capacity;
+            this.#table_limit = power_of_two_at_least(2 * WATER_PARTICLE_CORNERS * capacity);
+            const buffer = (label, size, usage = 0) => device.createBuffer({ label: `Water / particles ${label}`,
+                size: Math.max(16, size), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | usage });
+            const array_size = 16 + capacity * WATER_PARTICLE_STRUCT.size;
+            this.#particles = [buffer('a', array_size), buffer('b', array_size)];
+            this.#children = buffer('children', 16 + capacity * 4);
+            this.#buckets = buffer('buckets', 16 + this.#table_limit * 4);
+            this.#slots = buffer('slots', capacity * WATER_PARTICLE_CORNERS * 4);
+            this.#bucket_amplitude = buffer('bucket amplitude', this.#table_limit * 4);
+            this.#bucket_weight = buffer('bucket weight', this.#table_limit * 4);
+            this.#visible = buffer('visible', capacity * 4);
+            const entries = capacity * WATER_PARTICLE_CORNERS * WATER_PARTICLE_ENTRY_STRUCT.size;
+            this.#staging = buffer('staging', entries);
+            this.#entries = buffer('entries', entries);
+            this.#commands = [0, 1].map(i => device.createBuffer({ label: `Water / particles command ${i}`,
+                size: INDIRECT_COMPUTE_COMMAND_DESCRIPTOR.size, usage: INDIRECT_COMPUTE_COMMAND_DESCRIPTOR.usage }));
+            this.#rows = 0;
+            this.#parity = 0;
+        }
+        let carry = null;
+        if (rows > this.#rows || this.#body_bounds === null) {
+            const old = this.#body_bounds, old_rows = this.#rows;
+            this.#rows = Math.max(rows, 1);
+            const bounds = this.#body_bounds = device.createBuffer({ label: 'Water / particle body bounds',
+                size: this.#rows * WATER_PARTICLE_BODY_BOUNDS_STRIDE * 4,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+            if (old !== null) {
+                carry = encoder => {
+                    encoder.copyBufferToBuffer(old, 0, bounds, 0, old_rows * WATER_PARTICLE_BODY_BOUNDS_STRIDE * 4);
+                    encoder.done.then(() => old.destroy());
+                };
+            }
+        }
+        return carry;
+    }
+
+    dispose() {
+        for (const buffer of [...this.#particles, this.#children, this.#buckets, this.#slots, this.#bucket_amplitude,
+            this.#bucket_weight, this.#visible, this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) { buffer?.destroy(); }
+        this.#particles = [];
+        this.#children = this.#buckets = this.#slots = this.#bucket_amplitude = this.#staging = this.#entries = null;
+        this.#bucket_weight = this.#visible = null;
+        this.#body_bounds = null;
+        this.#commands = null;
+        this.#device = null;
+        this.#capacity = 0;
+        this.#rows = 0;
+    }
+
+    /**
+     * The frame's particles (§5.4): when the frame steps, one step of every particle of a body simulated this frame (a
+     * paused body's stand still) and the splashes of the culling pass's emit list; then, every frame, the hash of the
+     * particles of the bodies simulated this frame, which the surface sampler gathers from, and their bounds. The hash
+     * is rebuilt on a frame that does not step too, since the bodies in view change with the camera.
+     *
+     * @param {object} options
+     * @param {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {object} options.scene GPU scene context: database, geometries
+     * @param {GPUBuffer} options.steep per wave row: non-zero for a body that must stay calm
+     * @param {GPUBuffer} options.activity per wave row: the culling pass's {@link WaterActivity} bits
+     * @param {GPUBuffer} options.emit_rows the culling pass's emit list
+     * @param {GPUBuffer} options.commands the culling pass's commands
+     * @param {number} options.emit_command byte offset of the emit list's command in `commands`
+     * @param {number} options.dt seconds; zero for a frame that does not step
+     */
+    record({ graph, scene, steep, activity, emit_rows, commands, emit_command, dt }) {
+        assert.notNull(this.#device, 'prepare() first');
+        const stepping = dt > 0;
+        const step = Math.min(Math.max(dt, 0), WATER_PARTICLE_STEP_LIMIT);
+        const capacity = this.#capacity, table_limit = this.#table_limit;
+        const current = this.#particles[this.#parity];
+        // a frame that does not step bins the particles where they are
+        const next = stepping ? this.#particles[1 - this.#parity] : current;
+        if (stepping) { this.#parity = 1 - this.#parity; }
+        const [command_current, command_next] = this.#commands;
+        const geometries = scene.geometries;
+        let children = graph_import_buffer(graph, this.#children, 'Water / particle children');
+        let buckets = graph_import_buffer(graph, this.#buckets, 'Water / particle buckets');
+        const node = (name, execute, reads, writes) => {
+            const data = {};
+            const pass = graph.add(name, data, (d, resources, context) => execute(resources, context, d));
+            for (const [key, handle] of Object.entries(reads)) { data[key] = pass.read(handle); }
+            for (const [key, handle] of Object.entries(writes)) { data[key] = pass.write(handle); }
+            pass.make_side_effect();
+            return data;
+        };
+
+        if (stepping) {
+            // Each particle in place, and what it leaves.
+            children = node('Water / particles update', (resources, { encoder }) => {
+                encoder.copyBufferToBuffer(current, 0, this.#children, 0, 4);
+                build_indirect_compute_dispatch_command(64, encoder, current, 0, command_current, 0, true);
+                shader_water_particles_update.dispatchIndirect({ encoder, command: command_current, bindings: {
+                    frame: { dt: step, capacity }, particles: current, children: this.#children, activity,
+                    scene_database: scene.scene_database_buffer, geometries: geometries.buffer_metadata,
+                    blas_lookup: geometries.blas.buffer_metadata, blas_data: geometries.blas.buffer_data,
+                    meshlet_metadata: geometries.meshlets.buffer_metadata, meshlet_data: geometries.meshlets.buffer_data,
+                } });
+            }, {}, { children }).children;
+            children = graph_prefix_scan_csdldf({ graph, data: children, element_max_count: capacity });
+
+            // What they leave into the next array, then the frame's splashes after them.
+            node('Water / particles split and emit', (resources, { encoder }) => {
+                shader_water_particles_split.dispatchIndirect({ encoder, command: command_current, bindings: {
+                    capacity, particles: current, children: this.#children, next } });
+                shader_water_particles_total.dispatch({ encoder, bindings: { capacity, children: this.#children, next } });
+                shader_water_particles_emit.dispatchIndirect({ encoder, command: commands, command_offset: emit_command,
+                    bindings: { capacity, scene_database: scene.scene_database_buffer, emit_rows, steep, activity,
+                        particle_bounds: this.#body_bounds, next } });
+                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets } });
+            }, { children }, {});
+        }
+
+        // The frame's hash: how crowded each cell is, then each particle into the cells its support overlaps as far as
+        // its crowd leaves it drawn, offsets, entries in order.
+        buckets = node('Water / particles bin', (resources, { encoder }) => {
+            if (!stepping) {
+                // the table size the last stepping frame chose for these particles
+                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets } });
+            }
+            build_indirect_compute_dispatch_command(64, encoder, next, 0, command_next, 0, true);
+            encoder.clearBuffer(this.#buckets, 16, table_limit * 4);
+            encoder.clearBuffer(this.#bucket_amplitude);
+            encoder.clearBuffer(this.#bucket_weight);
+            shader_water_particles_weigh.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, bucket_weight: this.#bucket_weight } });
+            shader_water_particles_bin.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, buckets: this.#buckets, slots: this.#slots, bucket_amplitude: this.#bucket_amplitude,
+                body_bounds: this.#body_bounds, bucket_weight: this.#bucket_weight, visible: this.#visible } });
+        }, {}, { buckets }).buckets;
+        buckets = graph_prefix_scan_csdldf({ graph, data: buckets, element_max_count: table_limit });
+        node('Water / particles order and bound', (resources, { encoder }) => {
+            const bindings = { next, offsets: this.#buckets, slots: this.#slots };
+            shader_water_particles_scatter.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
+                visible: this.#visible, staging: this.#staging } });
+            shader_water_particles_rank.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
+                staging: this.#staging, entries: this.#entries } });
+            shader_water_particles_bounds.dispatchIndirect({ encoder, command: command_next, bindings: { next, activity,
+                offsets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, body_bounds: this.#body_bounds } });
+        }, { buckets }, {});
+    }
+}

package/src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One wave particle (Yuksel, House & Keyser 2007): a point of an expanding wave front carrying a small wave
+ * packet, in the metric local frame of the water body it lives on
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
+ *
+ * Its position is not stored; it is `origin + direction(angle) · group_speed(radius) · age`, so it moves
+ * without integration error and every particle of one front shares the origin and the age.
+ */
+export const WATER_PARTICLE_STRUCT: WebGPUStruct;
+/**
+ * A particle as one hash cell holds it for the surface sampler: everything its kernel needs at the frame's
+ * time, and the cell it was entered for, since one particle is entered in every cell its support overlaps and
+ * two cells may share a bucket.
+ */
+export const WATER_PARTICLE_ENTRY_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_PARTICLE_STRUCT.d.ts.map

package/src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_PARTICLE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iDAeoB;AAEpB;;;;GAIG;AACH,uDAeyB;6BA/CI,sCAAsC"}

package/src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.js

@@ -0,0 +1,49 @@
+import { f32, u32, vec2f, vec2i } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * One wave particle (Yuksel, House & Keyser 2007): a point of an expanding wave front carrying a small wave
+ * packet, in the metric local frame of the water body it lives on
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
+ *
+ * Its position is not stored; it is `origin + direction(angle) · group_speed(radius) · age`, so it moves
+ * without integration error and every particle of one front shares the origin and the age.
+ */
+export const WATER_PARTICLE_STRUCT = WebGPUStruct.from({
+    /** Centre of the front, or its mirror image after a reflection; metric local xz. */
+    origin: vec2f,
+    /** Propagation direction, radians from local +x towards +z. */
+    angle: f32,
+    /** Seconds the front has travelled from its origin. */
+    age: f32,
+    /** Signed ridge height at the packet's centre, metres. */
+    amplitude: f32,
+    /** Half the packet's wavelength, metres. */
+    radius: f32,
+    /** Angle to the neighbouring particle of the same front. */
+    dispersion: f32,
+    /** The water_waves row of the body it lives on. */
+    body: u32,
+}, 'WaterParticle');
+
+/**
+ * A particle as one hash cell holds it for the surface sampler: everything its kernel needs at the frame's
+ * time, and the cell it was entered for, since one particle is entered in every cell its support overlaps and
+ * two cells may share a bucket.
+ */
+export const WATER_PARTICLE_ENTRY_STRUCT = WebGPUStruct.from({
+    position: vec2f,
+    cell: vec2i,
+    angle: f32,
+    amplitude: f32,
+    radius: f32,
+    /** Tangential window: the distance to the front's neighbouring particle. */
+    width: f32,
+    /** Carrier phase lag of the crests behind the envelope, radians. */
+    phase: f32,
+    /** water_waves row << 4 | level */
+    key: u32,
+    /** Index of the particle, which orders a bucket. */
+    source: u32,
+    reserved: u32,
+}, 'WaterParticleEntry');

package/src/shade/renderer/water/surface/particles/chunk_water_particle.d.ts

@@ -0,0 +1,22 @@
+/** Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 64 m. */
+export const WATER_PARTICLE_LEVELS: 16;
+/** Cell size of level 0, metres. A particle sits at the smallest level whose cell is at least its support's diameter. */
+export const WATER_PARTICLE_LEVEL0_CELL: number;
+/**
+ * The physics of one wave particle as pure functions (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
+ *
+ * A particle of radius r carries a packet of wavelength 2r, k = π/r. Under the gravity–capillary
+ * dispersion relation the packet's envelope travels at the group speed and its crests at the phase speed
+ * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). It loses
+ * amplitude at the clean-surface viscous rate 2νk² plus the surface-film rate k√(νω)/(2√2) of natural
+ * water — so a raindrop's ripple is gone in a fraction of a second while a big splash crosses a bay.
+ *
+ * The particles of a front are W apart, W the front's arc between them; a cosine window of half-width W
+ * along the front is a partition of unity over them, so the front's height is the packet's amplitude
+ * whatever the spacing, and one front adds at most two particles at any point.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_particle: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_particle.d.ts.map

package/src/shade/renderer/water/surface/particles/chunk_water_particle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_particle.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle.js"],"names":[],"mappings":"AAKA,sFAAsF;AACtF,uCAAwC;AAExC,yHAAyH;AACzH,gDAAkD;AAElD;;;;;;;;;;;;;;GAcG;AACH,mCAFU,SAAS,CAsH6G;0BA9ItG,uCAAuC"}

package/src/shade/renderer/water/surface/particles/chunk_water_particle.js

@@ -0,0 +1,143 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { chunk_pcg3d } from "../../../shader/chunk/random/pcg/chunk_pcg3d.js";
+import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
+import { chunk_water_spectrum } from "../spectrum/chunk_water_spectrum.js";
+
+/** Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 64 m. */
+export const WATER_PARTICLE_LEVELS = 16;
+
+/** Cell size of level 0, metres. A particle sits at the smallest level whose cell is at least its support's diameter. */
+export const WATER_PARTICLE_LEVEL0_CELL = 1 / 256;
+
+/**
+ * The physics of one wave particle as pure functions (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
+ *
+ * A particle of radius r carries a packet of wavelength 2r, k = π/r. Under the gravity–capillary
+ * dispersion relation the packet's envelope travels at the group speed and its crests at the phase speed
+ * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). It loses
+ * amplitude at the clean-surface viscous rate 2νk² plus the surface-film rate k√(νω)/(2√2) of natural
+ * water — so a raindrop's ripple is gone in a fraction of a second while a big splash crosses a bay.
+ *
+ * The particles of a front are W apart, W the front's arc between them; a cosine window of half-width W
+ * along the front is a partition of unity over them, so the front's height is the packet's amplitude
+ * whatever the spacing, and one front adds at most two particles at any point.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_particle = CodeChunk.from(/* language=WGSL */ `
+const WATER_PARTICLE_LEVELS: u32 = ${WATER_PARTICLE_LEVELS}u;
+const WATER_PARTICLE_LEVEL0_CELL: f32 = ${WATER_PARTICLE_LEVEL0_CELL};
+// kinematic viscosity of water, m²/s
+const WATER_VISCOSITY: f32 = 1e-6;
+const WATER_PI: f32 = 3.14159265358979;
+
+fn water_particle_wavenumber(radius: f32) -> f32 {
+    return WATER_PI / radius;
+}
+
+// Phase speed of the particle's wavelength, m/s: how fast its crests move.
+fn water_particle_phase_speed(radius: f32) -> f32 {
+    let k = water_particle_wavenumber(radius);
+    return water_dispersion(k) / k;
+}
+
+// Group speed dω/dk of the particle's wavelength, m/s: how fast its packet moves.
+fn water_particle_group_speed(radius: f32) -> f32 {
+    let k = water_particle_wavenumber(radius);
+    return (WATER_GRAVITY + 3.0 * WATER_SURFACE_TENSION * k * k) / (2.0 * water_dispersion(k));
+}
+
+// Amplitude decay rate, 1/s: viscous plus surface film.
+fn water_particle_damping(radius: f32) -> f32 {
+    let k = water_particle_wavenumber(radius);
+    return 2.0 * WATER_VISCOSITY * k * k + k * sqrt(WATER_VISCOSITY * water_dispersion(k)) / (2.0 * sqrt(2.0));
+}
+
+fn water_particle_direction(angle: f32) -> vec2<f32> {
+    return vec2<f32>(cos(angle), sin(angle));
+}
+
+// Distance the front has travelled from its origin.
+fn water_particle_distance(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return water_particle_group_speed(particle.radius) * particle.age;
+}
+
+fn water_particle_position(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> vec2<f32> {
+    return particle.origin + water_particle_direction(particle.angle) * water_particle_distance(particle);
+}
+
+// The front's arc between neighbouring particles: the half-width of the tangential window.
+fn water_particle_width(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return max(particle.dispersion * water_particle_distance(particle), 1e-3 * particle.radius);
+}
+
+// How far the crests have slid through the envelope: k (c − c_g) age.
+fn water_particle_phase(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    let lag = (water_particle_phase_speed(particle.radius) - water_particle_group_speed(particle.radius)) * particle.age;
+    return water_particle_wavenumber(particle.radius) * lag;
+}
+
+// Radius of a circle around the particle holding its whole kernel: two radii across the front, the window along it.
+fn water_particle_support(radius: f32, width: f32) -> f32 {
+    return length(vec2<f32>(2.0 * radius, width));
+}
+
+// The smallest hash level whose cell is at least the support's diameter, so the support overlaps at most
+// the 2×2 cells around it.
+fn water_particle_level(support: f32) -> u32 {
+    let level = ceil(log2(max(2.0 * support / WATER_PARTICLE_LEVEL0_CELL, 1.0)));
+    return min(u32(level), WATER_PARTICLE_LEVELS - 1u);
+}
+
+fn water_particle_cell_size(level: u32) -> f32 {
+    return WATER_PARTICLE_LEVEL0_CELL * exp2(f32(level));
+}
+
+fn water_particle_bucket(body: u32, level: u32, cell: vec2<i32>, table_size: u32) -> u32 {
+    let bits = pcg3d(vec3<u32>((body << 4u) | level, bitcast<u32>(cell.x), bitcast<u32>(cell.y)));
+    return bits.x & (table_size - 1u);
+}
+
+struct WaterParticleField {
+    height: f32,
+    // ∂h/∂x, ∂h/∂z
+    slope: vec2<f32>,
+    displacement: vec2<f32>,
+    // columns ∂D/∂x and ∂D/∂z: (∂Dx/∂x, ∂Dz/∂x), (∂Dx/∂z, ∂Dz/∂z)
+    jacobian: mat2x2<f32>,
+}
+
+// The packet at offset d from its particle. u across the front, v along it: envelope E(u) over two radii,
+// window T(v) over the width, carrier phase φ = πu/r − phase. Height a·E·T·cos φ; horizontal displacement
+// −a·E·T·sin φ along the direction (Gerstner-like orbits, Yuksel's longitudinal sign); with derivatives.
+fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, width: f32, phase: f32) -> WaterParticleField {
+    var field: WaterParticleField;
+    let direction = water_particle_direction(angle);
+    let tangent = vec2<f32>(-direction.y, direction.x);
+    let u = dot(d, direction);
+    let v = dot(d, tangent);
+    if (abs(u) >= 2.0 * radius || abs(v) >= width) { return field; }
+    let eu = 0.5 * WATER_PI * u / radius;
+    let envelope = 0.5 * (1.0 + cos(eu));
+    let envelope_du = -0.25 * WATER_PI / radius * sin(eu);
+    let tv = WATER_PI * v / width;
+    let window = 0.5 * (1.0 + cos(tv));
+    let window_dv = -0.5 * WATER_PI / width * sin(tv);
+    let carrier = WATER_PI * u / radius - phase;
+    let c = cos(carrier);
+    let s = sin(carrier);
+    let k = WATER_PI / radius;
+    let z = amplitude * envelope * window * c;
+    let z_u = amplitude * window * (envelope_du * c - envelope * s * k);
+    let z_v = amplitude * envelope * window_dv * c;
+    let h = -amplitude * envelope * window * s;
+    let h_u = -amplitude * window * (envelope_du * s + envelope * c * k);
+    let h_v = -amplitude * envelope * window_dv * s;
+    let gradient_h = h_u * direction + h_v * tangent;
+    field.height = z;
+    field.slope = z_u * direction + z_v * tangent;
+    field.displacement = h * direction;
+    field.jacobian = mat2x2<f32>(direction * gradient_h.x, direction * gradient_h.y);
+    return field;
+}
+`, [chunk_water_spectrum, chunk_pcg3d, WATER_PARTICLE_STRUCT.declaration_chunk, WATER_PARTICLE_ENTRY_STRUCT.declaration_chunk]);

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.d.ts

@@ -0,0 +1,15 @@
+/** Seconds over which a packet that has fallen below the drawing threshold fades to a tenth of it, where it dies. */
+export const WATER_PARTICLE_FADE_SECONDS: 0.15;
+/**
+ * One frame of one wave particle (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.1): it ages, spreads over its
+ * widening front, damps, reflects off its body's authored outline, and dies or splits.
+ *
+ * Whether a point is over the body is a down-ray into the body's own BLAS, so the outline is exactly the
+ * authored mesh's, holes for islands included. Bindings: `geometries`, `blas_lookup`, `blas_data`,
+ * `meshlet_metadata`, `meshlet_data`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_particle_step: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_particle_step.d.ts.map

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAOA,qHAAqH;AACrH,+CAAgD;AAEhD;;;;;;;;;GASG;AACH,wCAFU,SAAS,CAsGsC;0BAxH/B,uCAAuC"}