Water waves and materials

This chapter covers wave assets, interactive ripples, surface materials, and how Quality Tier gates GPU features.

.waterwaves assets

Wave spectra live in Gems/Water/Assets/Waves/ (extension .waterwaves). Assign via the body’s Waves field. Empty = still water (detail normals / flow only).

Gerstner mode

Up to 16 components (Registry MaxGerstnerComponents can only lower the cap):

Asset load validates steepness sum and quantizes angular frequencies so waterTime can wrap every 3600 s without phase pops.

Spectrum mode (FFT)

Analytic Phillips / JONSWAP parameters drive a GPU IFFT cascade (default sizes 512 / 64 / 8 m). Inspector fields:

Buoyancy and CPU queries use a �?6-component Gerstner approximation sampled at load time (same WaveEvaluator API). Only one Spectrum ocean drives the FFT chain; additional Spectrum oceans fall back to the CPU approx for rendering displacement.

Registry (/O3DE/Gems/Water/Fft/):

Interactive ripples

When ripples and FFT are enabled, body-enter events inject particles into the finest FFT cascade slice. Registry /O3DE/Gems/Water/Ripples/:

Low tier / Gerstner-only paths disable ripple injection with the FFT chain.

Materials

Material type: Gems/Water/Assets/Materials/Types/WaterSurface.materialtype.

Assign via the body’s material path (empty �?type default). User-facing groups include:

Reflection preference: planar (High tier) > SSR > IBL. Scene-color refraction uses a half-resolution copy by default (SceneColorCopyFullRes can force full res).

Quality tiers

/O3DE/Gems/Water/QualityTier: High / Medium / Low.

CPU buoyancy always samples the full validated wave table; the tier only trims GPU upload. Related Registry gates: CausticsEnabled, PlanarReflectionEnabled, UnderwaterDoF/Enabled.

Rendering features (user view)

TransparentPass
    └── WaterParent
            ├── SceneColorCopy (refraction source)
            ├── WaterSurface (+ optional FFT / InfoMap / ripples)
            ├── PlanarReflection (High)
            └── Caustics (fullscreen additive)

• WaterInfoMap: top-down still-water height / depth / flow for shore foam and underwater split fog.
• Motion vectors: Gerstner prev-time displacement for TAA (DrawList motion).
• Underwater: camera hysteresis (~0.05 m) + DeferredFog parameter override; half-immersed cameras can split fog per pixel when InfoMap is available.

Next steps

• Buoyancy and gameplay �?how floaters sample the same waves.
• Authoring �?bake flow maps that materials consume.
• Debugging �?tier readout on the diagnostics overlay.