@woosh/meep-engine 3.42.0 → 3.43.0

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

@@ -10,7 +10,7 @@ import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
  * 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. */
+    /** 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,
@@ -24,6 +24,11 @@ export const WATER_PARTICLE_STRUCT = WebGPUStruct.from({
     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');
 
 /**
@@ -37,13 +42,16 @@ export const WATER_PARTICLE_ENTRY_STRUCT = WebGPUStruct.from({
     angle: f32,
     amplitude: f32,
     radius: f32,
-    /** Tangential window: the distance to the front's neighbouring particle. */
-    width: 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 << 4 | level */
+    /** water_waves row and level, as water_particle_key packs them */
     key: u32,
     /** Index of the particle, which orders a bucket. */
     source: u32,
-    reserved: 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

@@ -1,19 +1,40 @@
-/** Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 64 m. */
-export const WATER_PARTICLE_LEVELS: 16;
+/**
+ * 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). 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.
+ * (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 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.
+ * 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}
  */

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

@@ -1 +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"}
+{"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"}

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

@@ -3,30 +3,65 @@ 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;
+/**
+ * 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). 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.
+ * (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 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.
+ * 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;
@@ -66,7 +101,7 @@ fn water_particle_position(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> vec2<
     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.
+// 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);
 }
@@ -77,9 +112,79 @@ fn water_particle_phase(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
     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));
+// 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
@@ -93,8 +198,13 @@ 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>((body << 4u) | level, bitcast<u32>(cell.x), bitcast<u32>(cell.y)));
+    let bits = pcg3d(vec3<u32>(water_particle_key(body, level), bitcast<u32>(cell.x), bitcast<u32>(cell.y)));
     return bits.x & (table_size - 1u);
 }
 
@@ -105,39 +215,54 @@ struct WaterParticleField {
     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. 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 {
+// 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 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 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.25 * WATER_PI / radius * sin(eu);
-    let tv = WATER_PI * v / width;
+    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_dv = -0.5 * WATER_PI / width * sin(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_v = amplitude * envelope * window_dv * c;
+    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_v = -amplitude * envelope * window_dv * s;
-    let gradient_h = h_u * direction + h_v * tangent;
+    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 * direction + z_v * tangent;
-    field.displacement = h * direction;
-    field.jacobian = mat2x2<f32>(direction * gradient_h.x, direction * gradient_h.y);
+    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

@@ -2,7 +2,12 @@
 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.
+ * 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`,

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

@@ -1 +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"}
+{"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

@@ -1,6 +1,7 @@
 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";
@@ -10,7 +11,12 @@ 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.
+ * 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`,
@@ -22,8 +28,11 @@ 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},
-    // 0 dies, 1 lives on, 3 splits into three
+    // 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,
 }
 
@@ -37,6 +46,50 @@ fn water_particle_over_body(geometry_index: u32, local: vec2<f32>) -> ${RAY_HIT_
         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 {
@@ -62,54 +115,119 @@ fn water_outline_line(geometry_index: u32, triangle: u32, point: vec2<f32>, scal
     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.
+// 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) -> WaterParticleStep {
+    reflection: f32, threshold: f32, hint: WaterParticleArcHint) -> WaterParticleStep {
     var particle = input;
-    let before = water_particle_position(particle);
     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 water's own damping
-    particle.amplitude *= sqrt(max(distance_before, 1e-30) / max(distance_after, 1e-30))
-        * exp(-water_particle_damping(particle.radius) * dt);
-    let after = water_particle_position(particle);
-    if (water_particle_over_body(geometry_index, after / scale).t < 0.0) {
-        let start = water_particle_over_body(geometry_index, before / scale);
-        if (!(reflection > 0.0) || start.t < 0.0) { return WaterParticleStep(particle, 0u); }
-        // where along this frame's step it left the mesh
-        var lo = 0.0;
-        var hi = 1.0;
-        var last = start;
-        for (var halving = 0u; halving < 6u; halving++) {
-            let mid = 0.5 * (lo + hi);
-            let probe = water_particle_over_body(geometry_index, mix(before, after, 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 along the step it was crossed
-        let line = water_outline_line(geometry_index, last.triangle, mix(before, after, lo), scale);
-        let normal = line.normal;
-        let direction = water_particle_direction(particle.angle);
-        let reflected = direction - 2.0 * dot(direction, normal) * normal;
-        particle.origin -= 2.0 * dot(particle.origin - line.point, normal) * normal;
-        particle.angle = atan2(reflected.y, reflected.x);
-        particle.amplitude *= reflection;
-        // a corner can send the mirror image off the mesh too
-        if (water_particle_over_body(geometry_index, water_particle_position(particle) / scale).t < 0.0) {
-            return WaterParticleStep(particle, 0u);
-        }
-    }
+    // 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, 0u); }
+        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 window along the front keeps its height
-    if (water_particle_width(particle) > 2.0 * particle.radius) { return WaterParticleStep(particle, 3u); }
-    return WaterParticleStep(particle, 1u);
+    // 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,
@@ -118,4 +236,4 @@ fn water_particle_threshold(slope_variance: f32, live: u32, capacity: u32) -> f3
     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_water_particle, chunk_ray_query_blas_nearest, chunk_geometry_read_triangle_positions]);