Draft documentation, this section is being expanded upon! 🙂

The height of the water surface, as it is animated through Waves and Dynamic Effects, is entirely determined by shader-based effects (GPU). These live in a different domain from C# scripts (CPU).

Being able to read out the water’s height at a given position in the world is crucial for implementing physics-based buoyancy.

This system facilitates such functionality, through 2 different methods.

CPU (Wave pattern replication)

Whilst the wave animations takes place entirely in the shader, the exact same wave pattern can be reproduce in C#.

Pro’s
✅ Performance efficient
✅ Values are returned instantaneously

Cons
❌ Limited to flat water surfaces (requires a specific water level)
❌ Only returns the wave animation height, never any Dynamic Effects

Caveats
⚠️ Vertex color wave flattening cannot be taken into account

GPU (Async height readback)

This method renders the water’s height values into an off-screen render texture and reads from it in select locations.

Pro’s
✅ Returns the water’s height exactly as it appears, including curved geometry (eg. rivers)
✅ Supports Dynamic Effects

Cons
❌ Consumes more resources (additional rendering pass and processing of queries)

Caveats
⚠️ Waves with a high steepness value can produces slightly inaccurate results
⚠️ You cannot have hundreds of individual scripts each requesting just 1 sample, this is highly inefficient
⚠️ This functionality requires Compute Shader support. Therefor WebGL is not supported (use WebGPU instead).