@woosh/meep-engine 3.41.0 → 3.43.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":"AA+BA,kHAAkH;AAClH,+CAAgD;AAUhD;;;;GAIG;AACH;IAuBI,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,CAuD7G;IAED,gBAcC;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;aAgGhB;;CACJ"}

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

@@ -0,0 +1,274 @@
+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_clear,
+    shader_water_particles_emit,
+    shader_water_particles_finalize,
+    shader_water_particles_fronts,
+    shader_water_particles_groups,
+    shader_water_particles_nest,
+    shader_water_particles_rank,
+    shader_water_particles_runs,
+    shader_water_particles_scatter,
+    shader_water_particles_share,
+    shader_water_particles_split,
+    shader_water_particles_total,
+    shader_water_particles_update,
+    shader_water_particles_weigh,
+    WATER_PARTICLE_CORNERS,
+    WATER_PARTICLE_CROWD_WORDS,
+    WATER_PARTICLE_NEST_WORDS
+} 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;
+    #images = null;
+    #fronts = null;
+    #runs = null;
+    #draw = null;
+    #buckets = null;
+    #slots = null;
+    #bucket_amplitude = null;
+    #bucket_weight = null;
+    #bucket_nest = 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);
+            // per particle the mirror image the step left beside it at the outline
+            this.#images = buffer('images', capacity * WATER_PARTICLE_STRUCT.size);
+            // per particle the scanned run it is in; per run its first particle and its share; per particle its run
+            // and how it is drawn
+            this.#fronts = buffer('fronts', 16 + capacity * 4);
+            this.#runs = buffer('runs', capacity * 8);
+            this.#draw = buffer('draw', capacity * 8);
+            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);
+            // the summed steepness, the largest front and front complement entered, and the entries; then the most a point
+            // under it reads, and its entries by key
+            this.#bucket_weight = buffer('bucket weight', this.#table_limit * WATER_PARTICLE_CROWD_WORDS * 4);
+            this.#bucket_nest = buffer('bucket nest', this.#table_limit * WATER_PARTICLE_NEST_WORDS * 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);
+            // the particles' this frame and next, and the clear of the frame's table
+            this.#commands = [0, 1, 2].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.#images, this.#fronts, this.#runs, this.#draw, this.#buckets, this.#slots,
+            this.#bucket_amplitude, this.#bucket_weight, this.#bucket_nest, this.#visible, this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) {
+            buffer?.destroy();
+        }
+        this.#particles = [];
+        this.#children = this.#images = this.#buckets = this.#slots = this.#bucket_amplitude = this.#staging = this.#entries = null;
+        this.#fronts = this.#runs = this.#draw = null;
+        this.#bucket_weight = this.#bucket_nest = 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, command_table] = 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');
+        let fronts = graph_import_buffer(graph, this.#fronts, 'Water / particle fronts');
+        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, images: this.#images, 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, images: this.#images, 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,
+                    table_command: command_table } });
+            }, { children }, {});
+        }
+
+        // Each front's run of particles, so that a whole one is drawn as the seven it was emitted as.
+        fronts = node('Water / particles fronts', (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,
+                    table_command: command_table } });
+            }
+            build_indirect_compute_dispatch_command(64, encoder, next, 0, command_next, 0, true);
+            encoder.copyBufferToBuffer(next, 0, this.#fronts, 0, 4);
+            shader_water_particles_fronts.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts } });
+        }, {}, { fronts }).fronts;
+        fronts = graph_prefix_scan_csdldf({ graph, data: fronts, element_max_count: capacity });
+
+        // The frame's hash: how each particle is drawn, how crowded each cell is and so how much of each run its crowd
+        // leaves drawn, then each packet drawn into the cells its support overlaps, offsets, entries in order.
+        buckets = node('Water / particles bin', (resources, { encoder }) => {
+            const draw = this.#draw, runs = this.#runs;
+            shader_water_particles_runs.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts, runs } });
+            shader_water_particles_groups.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts, runs, draw } });
+            shader_water_particles_clear.dispatchIndirect({ encoder, command: command_table, bindings: {
+                buckets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, bucket_weight: this.#bucket_weight,
+                bucket_nest: this.#bucket_nest } });
+            shader_water_particles_weigh.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, draw, bucket_weight: this.#bucket_weight, body_bounds: this.#body_bounds } });
+            shader_water_particles_nest.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, draw, body_bounds: this.#body_bounds, bucket_weight: this.#bucket_weight,
+                bucket_nest: this.#bucket_nest } });
+            shader_water_particles_share.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, bucket_weight: this.#bucket_weight, bucket_nest: this.#bucket_nest,
+                body_bounds: this.#body_bounds, draw, runs } });
+            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, draw, runs, visible: this.#visible } });
+        }, { fronts }, { 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, draw: this.#draw };
+            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, draw: this.#draw, 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,iDAoBoB;AAEpB;;;;GAIG;AACH,uDAkByB;6BAvDI,sCAAsC"}

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

@@ -0,0 +1,57 @@
+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 the mirror image of it for 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,
+    /**
+     * 1 once the first of its support has left its body's outline, or that of the particle it split from: its mirror
+     * image was emitted then, and it dies once the last of it has left too. 0 from emission.
+     */
+    reflected: 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,
+    /** Half-angle of the window around the front's centre: the angle to the front's neighbouring particle. */
+    dispersion: f32,
+    /** Carrier phase lag of the crests behind the envelope, radians. */
+    phase: f32,
+    /** water_waves row and level, as water_particle_key packs them */
+    key: u32,
+    /** Index of the particle, which orders a bucket. */
+    source: u32,
+    /** How far the particle stands from its front's centre, metres. */
+    distance: f32,
+    /** Half the length of its envelope across its front, metres. */
+    half_length: f32,
+}, 'WaterParticleEntry');

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

@@ -0,0 +1,43 @@
+/**
+ * Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 256 m, which a 2 m splash's stretched
+ * packets reach before they die.
+ */
+export const WATER_PARTICLE_LEVELS: 18;
+/** 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;
+/**
+ * How fast a packet's envelope stretches as it disperses, as a fraction κ of its group speed, by its wavenumber k against
+ * k_m = √(g/(σ/ρ)), the wavenumber of the slowest crests (λ = 1.71 cm): from x = log₂(k/k_m) = -7 in steps of a quarter,
+ * held at both ends.
+ *
+ * Its half-length h, 2r when emitted, grows as h² = (2r)² + (κD/2)² over the distance D its front has travelled since:
+ * the spread of an unchirped packet's energy grows as the spread of its group speeds times time, in quadrature with
+ * where it began (Jeschke & Wojtan 2017 grow it linearly, eq. 14, its far limit). Each κ is the one whose peak
+ * √(2r/h) best matches exact linear theory, ω² = gk + (σ/ρ)k³, for the emitted packet at 5 to 225 wavelengths (FFT,
+ * worst ratio minimised): within 2% for capillary waves up to r = 8.5 mm and gravity waves from r = 6 cm, where κ
+ * tends to 1 and 0.9, and 5% from 4 cm. Between, around the slowest group speed (λ = 4.4 cm), a broad band's energy
+ * gathers at that speed and the peak falls as t^(−1/3), which no κ draws: up to 16% below r = 12 mm, 27% at 3 cm.
+ */
+export const WATER_PARTICLE_STRETCH: 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). The packet holds a
+ * band of wavelengths around 2r, which the same relation moves apart: its envelope, two radii either side when emitted,
+ * stretches as it travels and its height falls to keep its energy (WATER_PARTICLE_STRETCH), as a splash's single ring
+ * becomes a widening train of ripples. 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 β apart in angle around its centre, and a packet's crests are arcs around that
+ * centre; a cosine window of half-angle β is a partition of unity over them at every radius, so the front's
+ * height is the packet's amplitude whatever the spacing, splitting a front changes none of it, 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;;;GAGG;AACH,uCAAwC;AAKxC,yHAAyH;AACzH,gDAAkD;AAElD;;;;;;;;;;;;GAYG;AACH,8CAIE;AAKF;;;;;;;;;;;;;;;;;;GAkBG;AACH,mCAFU,SAAS,CAmN6G;0BA3QtG,uCAAuC"}