GPU liquids — v11, 2026-10-24

showGPUFluid(name, positions, count, radius, options)
Draw water from an existing GPU program's xyz f32 positions. It does not simulate
water. Supply the equations as ordered WGSL passes. count must match the buffer.
Rendering and simulation share GPU buffers; JavaScript need not read positions.
Uses MainCamera with URP opaque and depth textures. No additional camera.

Check gpuFluidSurface, fluidAnisotropy, fluidOptics and atomicProgramBuffers with
getGPUCapabilities(). This requires the WebGPU preview, not ordinary WebGL.

Options
radius: visual kernel radius in world units; separate from collision radius.
particleVolume: represented liquid volume per particle in cubic world units.
Use mass / restDensity for equal-mass particles. This normalizes accumulated
optical thickness when overlapping reconstruction kernels are larger than the
liquid volume they represent. Default 0 preserves legacy unnormalized thickness.
anisotropy: true uses neighbor-aware ellipsoids; false uses spheres.
particles: true shows original spheres without reconstruction or smoothing.
resolution: .25..1 (default .75), opacity: 0..1 (1), extent: render bounds half-size.
smoothing: .5..6 (3), smoothIterations: 1..4 (2).
tint: linear RGB {x,y,z}, each 0..1; default {.06,.32,.36}.
absorption: nonnegative RGB inverse-length coefficients; default {3,.65,.25}.
Higher absorption removes more of that channel with distance through water.
roughness: 0..1 (.12), ior: 1..3 (water 1.333).
refraction: 0..1 (.12); blend from no distortion to the estimated refracted path.
Reissue showGPUFluid to change appearance without resetting the simulation.
clearRun or removing the GPU program releases its buffers and renderer.

Rendering
Spatial hashing + weighted neighborhood covariance reconstruct bounded PCA
ellipsoids. Sparse droplets stay spherical. Depth and thickness intersect the
same ellipsoids. Narrow-range depth filtering, symmetric rejection and small
isotropic cleanup reconstruct normals; thickness is filtered separately.
V11 uses normalized optical thickness, Beer-Lambert absorption, IOR-dependent
Snell refraction, dielectric Fresnel reflectance, environment probe reflection,
and GGX direct-light highlights. Refraction rejects foreground scene samples.
This remains a screen-space thin-layer approximation: it cannot supply offscreen
refraction, true back-surface intersections, underwater rendering, caustics,
multiple dielectric bounces, foam or calibrated engineering optical accuracy.
A better shader cannot turn a sparse spray into a physically connected sheet.

Solver tools
compileGPUProgram accepts up to 32 ordered passes. Binding access "atomic" needs
a u32 buffer and exposes array<atomic<u32>>. Use atomicLoad/Store/Exchange/Add.
No floating-point atomics or duplicate buffer aliases within a pass.
Create separate producer/consumer passes; initialized scratch buffers may omit
values/integers (zero-filled). Initialize hash sentinels in a GPU pass before use.
showGPUSurface with style:"glass" draws a shell, not a physics collider. Match
solver collision boundaries to its vertices. The default style is scalar-field.

Pouring Water example: catalog/examples/pouring-water.js
9,600 equal-mass particles, 6.9083 kg total; rho0=1000 kg/m3, dt=.001 s.
Atomic linked-cell neighbor search; five position-based density iterations,
rebuilding the grid each iteration. Position corrections use a separate buffer.
Geometric projection handles moving vessel walls, receiving tray and outer bounds.
The prescribed vessel starts tilting at .6 seconds, reaches109 degrees at2s.
There is no timed stop. Pause/Resume are explicit; instability still stops playback.
Replay speed changes wall-clock pacing, not the fixed physical timestep. An
unresponsive GPU can slow simulated time; never hide it by increasing timestep.
Smoothness and Clarity sliders stage settings; Apply look updates the renderer.
Water / particles and two camera views let users compare reconstruction.

The solver includes artificial pressure, not calibrated surface tension or
viscosity. No air phase, wetting/contact angle, two-way vessel forces, arbitrary
GLB/SDF collider, ocean FFT, or fluid/soft-body coupling. Measure density and mass;
particle-count conservation alone does not establish incompressibility.
Atomic accumulation changes floating-point order; motion is not bit-identical.

Verification results are in fluid/surface-v11/RESULTS.txt. Native Unity testing
and Chrome WebGPU testing are separate requirements. Inspect pouring in motion
and from both views, and keep simulation running beyond the former four-second
stop; a paused frame alone does not verify water motion or settled-pool behavior.

References
Position Based Fluids: https://mmacklin.com/pbf_sig_preprint.pdf
Anisotropic kernels / reference implementation (MIT):
https://github.com/matsuoka-601/Particles4All
Narrow-range filtering: https://ttnghia.github.io/posts/narrow-range-filter/
MIT notice retained in Assets/Resources/CSScience/ThirdParty and server
worldbuilder-agent/fluid-third-party.txt.

Browser performance tuning: default four solver steps per displayed frame, target quarter-speed. This preserves the1ms physical timestep but may run slower than the target on a busy GPU. The earlier32-step budget produced about6FPS and was rejected. Four-step budget observed about40FPS on the developmentMac. Visual kernel2.2x contact radius, smoothing4/3iterations, roughness.18, clarity95 are current demonstration settings. They trade some silhouette/volume precision for continuous coverage; they are not solver parameters.

Optics grid toggles a reference plane behind the stream so clear-water refraction can be inspected. It is display geometry, not a collider or an addition to the fluid solver. Source remains fully stored in the editor.