@woosh/meep-engine 3.41.0 → 3.43.0

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

@@ -0,0 +1,268 @@
+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 256 m, which a 2 m splash's stretched
+ * packets reach before they die.
+ */
+export const WATER_PARTICLE_LEVELS = 18;
+
+/** Bits of a hash key that hold the level, below the body's row. */
+const WATER_PARTICLE_LEVEL_BITS = Math.ceil(Math.log2(WATER_PARTICLE_LEVELS));
+
+/** 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;
+
+/**
+ * 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 = [
+    0.9002, 0.9002, 0.8998, 0.8993, 0.8984, 0.8971, 0.8957, 0.8935, 0.8904, 0.8859, 0.8798, 0.8706, 0.8585, 0.8411, 0.8166,
+    0.7819, 0.7323, 0.6669, 0.5795, 0.461, 0.216, 0.0922, 0.064, 0.0723, 0.1089, 0.1877, 0.3427, 0.6145, 0.9295, 1.0417,
+    1.0734, 1.0739, 1.0622, 1.0469, 1.0313, 1.0175, 1.0059, 0.9969, 0.9899,
+];
+
+/** log₂(k/k_m) of the stretch table's first entry; entries are a quarter apart. */
+const WATER_PARTICLE_STRETCH_FIRST = -7;
+
+/**
+ * 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.from(/* language=WGSL */ `
+const WATER_PARTICLE_LEVELS: u32 = ${WATER_PARTICLE_LEVELS}u;
+const WATER_PARTICLE_LEVEL_BITS: u32 = ${WATER_PARTICLE_LEVEL_BITS}u;
+const WATER_PARTICLE_LEVEL0_CELL: f32 = ${WATER_PARTICLE_LEVEL0_CELL};
+const WATER_PARTICLE_STRETCH = array<f32, ${WATER_PARTICLE_STRETCH.length}>(${WATER_PARTICLE_STRETCH.join(', ')});
+const WATER_PARTICLE_STRETCH_FIRST: f32 = ${WATER_PARTICLE_STRETCH_FIRST}.0;
+// 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, at the particle's own radius: what the window spans there.
+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;
+}
+
+// How far from a splash's centre its ring starts: two radii, the packet's half-length, so it starts clear of the centre.
+fn water_particle_launch_distance(radius: f32) -> f32 {
+    return 2.0 * radius;
+}
+
+// How fast the packet's envelope stretches, as a fraction of its group speed (WATER_PARTICLE_STRETCH): interpolated in
+// log κ between quarter octaves of k against the wavenumber of the slowest crests.
+fn water_particle_stretch(radius: f32) -> f32 {
+    let octave = log2(water_particle_wavenumber(radius) * sqrt(WATER_SURFACE_TENSION / WATER_GRAVITY));
+    let last = f32(${WATER_PARTICLE_STRETCH.length}u - 1u);
+    let t = clamp(4.0 * (octave - WATER_PARTICLE_STRETCH_FIRST), 0.0, last);
+    let i = u32(min(floor(t), last - 1.0));
+    return exp2(mix(log2(WATER_PARTICLE_STRETCH[i]), log2(WATER_PARTICLE_STRETCH[i + 1u]), t - f32(i)));
+}
+
+// Half the length of the packet's envelope across its front, for a front that stands distance from its centre: 2r when
+// emitted, growing in quadrature with half the stretch over the distance travelled since. Held to half the largest support
+// the hash holds, so a window no wider keeps the packet within the coarsest cells.
+fn water_particle_half_length_at(radius: f32, distance: f32) -> f32 {
+    let travelled = max(distance - water_particle_launch_distance(radius), 0.0);
+    let stretched = length(vec2<f32>(2.0 * radius, 0.5 * water_particle_stretch(radius) * travelled));
+    return min(stretched, 0.5 * water_particle_support_limit());
+}
+
+fn water_particle_half_length(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return water_particle_half_length_at(particle.radius, water_particle_distance(particle));
+}
+
+// Radius of a circle around the particle holding its whole kernel: the envelope's half-length h across the front, and
+// along it the front's arc of half-angle β plus its outer edge's overhang. A point at radius ρ = D + u and angle ψ from
+// a particle at distance D lies |d|² = u² + 4ρD·sin²(ψ/2) ≤ h² + (D + h)Dβ² ≤ h² + ((D + h/2)β)² from it, and
+// width ≥ Dβ.
+fn water_particle_support(half_length: f32, width: f32, dispersion: f32) -> f32 {
+    return length(vec2<f32>(half_length, width + 0.5 * half_length * dispersion));
+}
+
+// The largest support the hash holds: half its coarsest cell.
+fn water_particle_support_limit() -> f32 {
+    return 0.5 * water_particle_cell_size(WATER_PARTICLE_LEVELS - 1u);
+}
+
+// Whether two particles are of one front: one splash's, neither reflected or faded apart, alike in all but angle.
+fn water_particle_same_front(a: ${WATER_PARTICLE_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> bool {
+    return a.body == b.body && all(a.origin == b.origin) && a.age == b.age && a.amplitude == b.amplitude
+        && a.radius == b.radius && a.dispersion == b.dispersion;
+}
+
+// How a particle is drawn, given its front's run of particles in the array and its place in it: 1 as itself; 0 not at
+// all, or a group of 3^g as one packet with 3^g times its window, when its front is whole. Whole is every particle
+// the front split into still there, in order and alike: as many as fill its circle. The step puts a particle's three
+// in its place, the middle at its own angle, so a group of 3^g is 3^g in a row and its middle stands at the angle
+// the group was emitted at; with curved crests the groups draw what the particles do. The largest group whose packet
+// the hash holds: the seven a front was emitted as, until their windows outgrow the coarsest cell.
+fn water_particle_group(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, members: u32, offset: u32) -> u32 {
+    if (members != u32(round(WATER_TAU / particle.dispersion))) { return 1u; }
+    var group = 1u;
+    for (var g = 0u; g < 20u && members % (3u * group) == 0u; g++) { group *= 3u; }
+    let distance = water_particle_distance(particle);
+    let half_length = water_particle_half_length_at(particle.radius, distance);
+    for (var g = 0u; g < 20u && group > 1u; g++) {
+        let dispersion = particle.dispersion * f32(group);
+        let width = max(dispersion * distance, 1e-3 * particle.radius);
+        if (water_particle_support(half_length, width, dispersion) <= water_particle_support_limit()) { break; }
+        group /= 3u;
+    }
+    return select(0u, group, offset % group == group / 2u);
+}
+
+// The particle as its group draws it: one packet with the group's window.
+fn water_particle_drawn(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, group: u32) -> ${WATER_PARTICLE_STRUCT.wgsl_ref} {
+    var drawn = particle;
+    drawn.dispersion *= f32(group);
+    return drawn;
+}
+
+// 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));
+}
+
+// A hash entry's body and level in one word.
+fn water_particle_key(body: u32, level: u32) -> u32 {
+    return (body << WATER_PARTICLE_LEVEL_BITS) | level;
+}
+
+fn water_particle_bucket(body: u32, level: u32, cell: vec2<i32>, table_size: u32) -> u32 {
+    let bits = pcg3d(vec3<u32>(water_particle_key(body, 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 gradient of the displacement's signed length along the radius: the slope a quarter carrier cycle on, so that
+    // ½(|slope|² + |this|²) is the slope's mean square over a cycle
+    displacement_gradient: vec2<f32>,
+}
+
+// The packet at offset d from its particle, which stands distance from its front's centre. ρ the radius from the
+// centre and u = ρ − distance across the front, ψ the angle around the centre from the particle's direction:
+// envelope E(u) over half_length either side, window T(ψ) over the dispersion β either side, carrier phase πu/r − phase.
+// Height a·E·T·cos; horizontal displacement −a·E·T·sin along the radius (Gerstner-like orbits, Yuksel's longitudinal
+// sign); with derivatives, ∇ψ = e_ψ/ρ.
+fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, half_length: f32, dispersion: f32, distance: f32,
+    phase: f32) -> WaterParticleField {
+    var field: WaterParticleField;
+    let direction = water_particle_direction(angle);
+    let tangent = vec2<f32>(-direction.y, direction.x);
+    let q = d + direction * distance;
+    let rho = length(q);
+    // ρ − distance, without the cancellation
+    let u = (dot(d, d) + 2.0 * distance * dot(d, direction)) / max(rho + distance, 1e-30);
+    if (abs(u) >= half_length || !(rho > 0.0)) { return field; }
+    let psi = atan2(dot(d, tangent), distance + dot(d, direction));
+    if (abs(psi) >= dispersion) { return field; }
+    let radial = q / rho;
+    let around = vec2<f32>(-radial.y, radial.x);
+    let eu = WATER_PI * u / half_length;
+    let envelope = 0.5 * (1.0 + cos(eu));
+    let envelope_du = -0.5 * WATER_PI / half_length * sin(eu);
+    let tv = WATER_PI * psi / dispersion;
+    let window = 0.5 * (1.0 + cos(tv));
+    let window_dpsi = -0.5 * WATER_PI / dispersion * 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_psi = amplitude * envelope * window_dpsi * c;
+    let h = -amplitude * envelope * window * s;
+    let h_u = -amplitude * window * (envelope_du * s + envelope * c * k);
+    let h_psi = -amplitude * envelope * window_dpsi * s;
+    let gradient_h = h_u * radial + (h_psi / rho) * around;
+    // the radius turns as the point moves around the centre: ∂e_ρ/∂x_j = e_ψ (e_ψ)_j / ρ
+    let turn = (h / rho) * around;
+    field.height = z;
+    field.slope = z_u * radial + (z_psi / rho) * around;
+    field.displacement = h * radial;
+    field.jacobian = mat2x2<f32>(radial * gradient_h.x + turn * around.x, radial * gradient_h.y + turn * around.y);
+    field.displacement_gradient = gradient_h;
+    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,20 @@
+/** 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, meets its body's authored outline, and dies or splits.
+ *
+ * At the outline the water shows the packet plus the shore's share of its mirror image in the outline (the image
+ * method, as Jeschke & Wojtan 2017 §4.4 keep a "ghost" of a reflected packet): the image is emitted the step the first
+ * of the packet's support leaves the body, and the packet carries on until the last of it has left it too. The body's
+ * outline clips what of either lies beyond it, so the water changes only as the two move.
+ *
+ * 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":"AAQA,qHAAqH;AACrH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAsN8E;0BA9OvE,uCAAuC"}

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

@@ -0,0 +1,239 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { BVH_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
+import { chunk_ray_query_blas_nearest } from "../../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+import { chunk_geometry_read_triangle_positions } from "../../../shader/chunk/geometry/format/chunk_geometry_read_triangle_positions.js";
+import { RAY_HIT_INFO } from "../../../shader/chunk/geometry/ray/RAY_HIT_INFO.js";
+import { WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
+import { chunk_water_particle } from "./chunk_water_particle.js";
+
+/** 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, meets its body's authored outline, and dies or splits.
+ *
+ * At the outline the water shows the packet plus the shore's share of its mirror image in the outline (the image
+ * method, as Jeschke & Wojtan 2017 §4.4 keep a "ghost" of a reflected packet): the image is emitted the step the first
+ * of the packet's support leaves the body, and the packet carries on until the last of it has left it too. The body's
+ * outline clips what of either lies beyond it, so the water changes only as the two move.
+ *
+ * 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.from(/* language=WGSL */ `
+const WATER_PARTICLE_FADE_SECONDS: f32 = ${WATER_PARTICLE_FADE_SECONDS};
+
+struct WaterParticleStep {
+    // the particle a step on
+    particle: ${WATER_PARTICLE_STRUCT.wgsl_ref},
+    // the mirror image it leaves, when it leaves one
+    image: ${WATER_PARTICLE_STRUCT.wgsl_ref},
+    // the particles it leaves, each split into three when they split: 0, 1, 2 (it, then its image), 3 or 6
+    children: u32,
+}
+
+// The body's surface under a point of its local xz, or a miss (t < 0) off its outline.
+fn water_particle_over_body(geometry_index: u32, local: vec2<f32>) -> ${RAY_HIT_INFO.wgsl_ref} {
+    let box = geometries[geometry_index].bounding_box;
+    let margin = max(1e-3, (box[4] - box[1]) * 1e-4);
+    let top = box[4] + margin;
+    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+    return ray_query_blas_nearest(Ray(vec3<f32>(local.x, top, local.y), vec3<f32>(0.0, -1.0, 0.0),
+        top - box[1] + margin), geometry_index, &stack, 0u);
+}
+
+// The points of a packet's support the step tests against the outline, on its arc ρ from its front's centre: the k-th
+// of its axis and its window's ends, β either side of it. The support is the annular sector of two radii either side of
+// the front and β either side of the axis, so a straight outline meets first the point of its leading arc whose
+// direction is nearest the outline's normal, an end unless the normal is within β of the axis, and leaves last the end
+// of its trailing arc farthest from it: at any incidence, these three find both, or within the arc's sagitta.
+fn water_particle_support_point(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, k: u32, rho: f32) -> vec2<f32> {
+    let turn = select(0.0, select(particle.dispersion, -particle.dispersion, k == 1u), k > 0u);
+    return particle.origin + water_particle_direction(particle.angle + turn) * rho;
+}
+
+// Whether a triangle seen from above holds a point strictly inside it, in the body's local xz.
+fn water_triangle_covers(a: vec2<f32>, b: vec2<f32>, c: vec2<f32>, point: vec2<f32>) -> bool {
+    let side = sign((b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x));
+    let ab = (b.x - a.x) * (point.y - a.y) - (b.y - a.y) * (point.x - a.x);
+    let bc = (c.x - b.x) * (point.y - b.y) - (c.y - b.y) * (point.x - b.x);
+    let ca = (a.x - c.x) * (point.y - c.y) - (a.y - c.y) * (point.x - c.x);
+    return side * ab > 0.0 && side * bc > 0.0 && side * ca > 0.0;
+}
+
+// The k-th tested point of a particle's leading arc once it has stepped dt on: what water_particle_advance tests.
+fn water_particle_leading_point(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, dt: f32, k: u32) -> vec2<f32> {
+    var stepped = particle;
+    stepped.age += dt;
+    return water_particle_support_point(stepped, k, water_particle_distance(stepped) + water_particle_half_length(stepped));
+}
+
+// What is already known of a particle's leading arc a step on, bit k for its k-th tested point: whether that is known,
+// and whether it is over the body; and the triangle under the axis's point when that is. Zero is nothing known. A
+// particle's window's ends are its neighbours' axis points when they are of its front, so the update pass hands each
+// what its neighbours in the subgroup found.
+struct WaterParticleArcHint {
+    known: u32,
+    over: u32,
+    triangle: u32,
+}
+
+// Whether any of an arc's tested points is over the body.
+fn water_particle_arc_over(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, geometry_index: u32, scale: vec2<f32>, rho: f32) -> bool {
+    for (var k = 0u; k < 3u; k++) {
+        if (water_particle_over_body(geometry_index, water_particle_support_point(particle, k, rho) / scale).t >= 0.0) { return true; }
+    }
+    return false;
+}
+
+// The line of the edge of a triangle nearest a point inside it, in the metric xz frame: a point on it and a
+// unit normal. Which side the normal points to does not matter: a mirror in a line is the same for either.
+struct WaterOutlineLine {
+    point: vec2<f32>,
+    normal: vec2<f32>,
+}
+
+fn water_outline_line(geometry_index: u32, triangle: u32, point: vec2<f32>, scale: vec2<f32>) -> WaterOutlineLine {
+    let vertices = geometry_read_triangle_vertices(geometries[geometry_index], triangle);
+    let corners = array<vec2<f32>, 3>(vertices.a.position.xz * scale, vertices.b.position.xz * scale, vertices.c.position.xz * scale);
+    var nearest = 3.0e38;
+    var line = WaterOutlineLine(point, vec2<f32>(0.0));
+    for (var edge = 0u; edge < 3u; edge++) {
+        let p = corners[edge];
+        let along = corners[(edge + 1u) % 3u] - p;
+        let t = clamp(dot(point - p, along) / max(dot(along, along), 1e-30), 0.0, 1.0);
+        let gap = length(point - (p + t * along));
+        if (gap < nearest) {
+            nearest = gap;
+            line = WaterOutlineLine(p, normalize(vec2<f32>(along.y, -along.x)));
+        }
+    }
+    return line;
+}
+
+// The particle's mirror image in a line of the outline: its front's centre and its direction mirrored. Not yet reflected.
+fn water_particle_mirrored(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, line: WaterOutlineLine) -> ${WATER_PARTICLE_STRUCT.wgsl_ref} {
+    var image = particle;
+    let direction = water_particle_direction(particle.angle);
+    let mirrored = direction - 2.0 * dot(direction, line.normal) * line.normal;
+    image.origin -= 2.0 * dot(particle.origin - line.point, line.normal) * line.normal;
+    image.angle = atan2(mirrored.y, mirrored.x);
+    image.reflected = 0u;
+    return image;
+}
+
+// Advance a particle by dt. scale turns the body's metric frame into its local one; reflection is the
+// outline's amplitude reflection coefficient; threshold is the steepness |a|/r below which it dies; hint is what is
+// already known of its leading arc.
+fn water_particle_advance(input: ${WATER_PARTICLE_STRUCT.wgsl_ref}, dt: f32, geometry_index: u32, scale: vec2<f32>,
+    reflection: f32, threshold: f32, hint: WaterParticleArcHint) -> WaterParticleStep {
+    var particle = input;
+    let distance_before = water_particle_distance(particle);
+    let half_length_before = water_particle_half_length(particle);
+    particle.age += dt;
+    let distance_after = water_particle_distance(particle);
+    // energy spread over the widening circumference and the lengthening envelope (Jeschke & Wojtan 2017 eq. 17), and the
+    // water's own damping
+    particle.amplitude *= sqrt(max(distance_before, 1e-30) / max(distance_after, 1e-30)
+        * half_length_before / water_particle_half_length(particle)) * exp(-water_particle_damping(particle.radius) * dt);
+    // below the threshold a packet fades out rather than vanishing: its amplitude decays on top of the water's own
+    // damping until it is a tenth of the threshold's height, where it dies
+    let floor = threshold * particle.radius;
+    if (!(abs(particle.amplitude) >= floor)) {
+        particle.amplitude *= exp(-dt / WATER_PARTICLE_FADE_SECONDS);
+        if (!(abs(particle.amplitude) >= 0.1 * floor)) { return WaterParticleStep(particle, particle, 0u); }
+    }
+    // its support: its envelope's half-length either side of its front, its window's angle either side of its axis
+    let reach = water_particle_half_length(particle);
+    // whether any of it may still be over the body
+    var remains = true;
+    var image = particle;
+    var mirrored = false;
+    if (particle.reflected == 0u) {
+        // which of its leading arc's tested points are over the body: what the hint knows, then the axis's by a down-ray,
+        // the ends by the triangle under it, which covers them away from the outline, and the rest by a down-ray each
+        let ahead = distance_after + reach;
+        var known = hint.known;
+        var over = hint.over & known;
+        var triangle = hint.triangle;
+        if ((known & 1u) == 0u) {
+            let hit = water_particle_over_body(geometry_index, water_particle_support_point(particle, 0u, ahead) / scale);
+            known |= 1u;
+            over |= select(0u, 1u, hit.t >= 0.0);
+            triangle = hit.triangle;
+        }
+        if ((over & 1u) != 0u && (known & 6u) != 6u) {
+            var a: vec3<f32>;
+            var b: vec3<f32>;
+            var c: vec3<f32>;
+            geometry_read_triangle_positions(&a, &b, &c, geometries[geometry_index], triangle);
+            for (var k = 1u; k < 3u; k++) {
+                if (((known >> k) & 1u) == 0u && water_triangle_covers(a.xz, b.xz, c.xz, water_particle_support_point(particle, k, ahead) / scale)) {
+                    known |= 1u << k;
+                    over |= 1u << k;
+                }
+            }
+        }
+        for (var k = 1u; k < 3u; k++) {
+            if (((known >> k) & 1u) == 0u
+                && water_particle_over_body(geometry_index, water_particle_support_point(particle, k, ahead) / scale).t >= 0.0) { over |= 1u << k; }
+        }
+        // the first of them to leave the body: one off it whose radius was over it where its trailing arc was when the
+        // step began. With none over it there, the point is not leaving the body but entering it, as a mirror image's
+        // do: every radius of one starts beyond its outline.
+        var crossing = 3u;
+        var back = vec2<f32>(0.0);
+        var last: ${RAY_HIT_INFO.wgsl_ref};
+        for (var k = 0u; k < 3u && crossing == 3u; k++) {
+            if (((over >> k) & 1u) != 0u) { continue; }
+            back = water_particle_support_point(particle, k, distance_before - reach);
+            last = water_particle_over_body(geometry_index, back / scale);
+            if (last.t >= 0.0) { crossing = k; }
+        }
+        if (crossing < 3u) {
+            // it is kept this step: if all of it has left the body too, it dies at the next, unseen beyond the outline
+            particle.reflected = 1u;
+            // where from there that radius leaves the body
+            let leading = water_particle_support_point(particle, crossing, ahead);
+            var lo = 0.0;
+            var hi = 1.0;
+            for (var halving = 0u; halving < 10u; halving++) {
+                let mid = 0.5 * (lo + hi);
+                let probe = water_particle_over_body(geometry_index, mix(back, leading, mid) / scale);
+                if (probe.t >= 0.0) { lo = mid; last = probe; } else { hi = mid; }
+            }
+            // the mirror image of its front in the outline's own line, wherever that was crossed
+            image = water_particle_mirrored(particle, water_outline_line(geometry_index, last.triangle, mix(back, leading, lo), scale));
+            image.amplitude *= reflection;
+            mirrored = abs(image.amplitude) >= 0.1 * floor;
+        } else if (over == 0u) {
+            // with none of them over the body and none leaving it, all of it is beyond the outline: a splash off the
+            // mesh, or a mirror image landing off it at a corner (one entering the body has the point it was mirrored
+            // from over it)
+            remains = false;
+        }
+    } else {
+        remains = water_particle_arc_over(particle, geometry_index, scale, distance_after - reach);
+    }
+    // Yuksel's subdivision, at a coarser spacing: the three windows of a third of the angle sum to the front's height
+    // as the parents' did, so the surface does not change. A window splits once its arc along the front is longer than
+    // its envelope is across it, so a packet's support stays about round, whatever its stretch. An image is as wide as
+    // its packet and splits with it.
+    let split = select(1u, 3u, water_particle_width(particle) > water_particle_half_length(particle));
+    // a reflected packet lives until the last of it has left the body
+    if (!remains) { return WaterParticleStep(particle, particle, 0u); }
+    if (mirrored) { return WaterParticleStep(particle, image, 2u * split); }
+    return WaterParticleStep(particle, particle, split);
+}
+
+// The death threshold: a packet flatter than the body's own wind waves is not drawn, and the fuller the pool,
+// the steeper a packet must be to stay.
+fn water_particle_threshold(slope_variance: f32, live: u32, capacity: u32) -> f32 {
+    let pressure = f32(live) / f32(max(capacity, 1u));
+    return max(0.003, 0.1 * sqrt(max(slope_variance, 0.0))) / max(1.0 - pressure, 0.05);
+}
+`, [chunk_water_particle, chunk_ray_query_blas_nearest, chunk_geometry_read_triangle_positions]);