Umi Water — scripting
Namespace FatalBug.Water. The rule: your code asks the water through WaterSurface and writes to it only with Displace. It never reads the mesh or the shader, so a change of wave model (Gerstner, FFT, shore, river) does not change your code.
Asking for the water
using FatalBug.Water;
// One point, any water body in the scene (the highest one over the point).
if (WaterSurface.TrySampleAny(position, out WaterSample sample, out WaterSurface surface))
{
float height = sample.Height; // world Y
Vector3 normal = sample.Normal;
Vector3 velocity = sample.Velocity; // current + wave motion, m/s
}
// One known surface.
if (mySurface.TrySample(position, out WaterSample s)) { … }
TrySampleAnyreturnsfalsewhere there is no water. Do not pass NaN or infinite positions (the result is NaN).- Many points per frame:
WaterSurface.SampleAny(ReadOnlySpan<Vector3> positions, Span<WaterSample> samples, Span<WaterSurface> surfaces)evaluates them in Burst jobs on all cores and returns how many are over water.Buoyancyand the boat hulls sample this way. - Both calls include the surface's ripples and shore waves (Umi Water Pro); pass
withoutWakes: trueto leave out the ripples of bodies that report their push as a wake (long hulls use it so they do not ride their own waves). - Physics code calls them from
FixedUpdate.
Pushing the water
surface.Displace(worldPosition, radius, volume); // a splash: pushes water aside (ripples need Umi Water Pro)
surface.Displace(worldPosition, radius, volume, wake: true);
Displace does nothing without Pro's WaterRipples. For characters, paddles and kinematic objects prefer the WaterInteractor component: it also makes foam, spray and a splash.
The wave clock
WaterTime is the one clock for the shader and physics. Waves must not use Time.time.
WaterTime.Push(provider); // an IWaterTimeProvider { double Seconds { get; } }, e.g. the server's time
WaterTime.Push(WaterTime.Smoothed(provider)); // smoothed: removes network jitter
WaterTime.Offset = 12.5; // a shared start phase
WaterTime.GameTime / WaterTime.UnscaledTime // the built-in providers
var hold = new WaterTimeHold(10.0); // freezes the waves at a time (pause, replay, cutscene)
WaterSurface.WaveTime (static) is the wave time the shader and physics use now.
Quality
WaterQuality.Level is the level in effect (from the Quality Settings level: the lowest third of the levels is Low, the middle third Medium, the rest High). WaterQuality.Override = WaterQualityLevel.Low fixes it from code; null goes back to the Quality Settings. Physics is the same at every level.
Building water from code
It works in players too. Empty material and shader fields are filled from the modules' resources.
var go = new GameObject("Sea");
var surface = go.AddComponent<WaterSurface>();
surface.Profile = myWaveProfile;
go.AddComponent<WaterInfinite>(); // open sea (Core)
// Umi Water Pro: go.AddComponent<WaterOcean>().Spectrum = mySpectrum; go.AddComponent<WaterRipples>();
Your own water shader
With Pro components on the surface the material needs the Umi/Water Pro shader (or your own shader with the "WaterPro" = "True" subshader tag); otherwise they warn in the console, since physics would feel what the water does not show. WaterInfinite needs a shader that draws its patches (instanced, morphed between levels): both package shaders do; yours needs the "WaterLOD" = "True" subshader tag and the same vertex code (WaterVertexPosition in Shaders/WaterShading.hlsl).
- Underwater fog: the surface draws it with the material's
UnderwaterFogAbsorb/UnderwaterFogScatterpasses (light modeWaterUnderwaterFog); a shader without them gets none. - Low quality: add
#pragma multi_compile _ WATER_QUALITY_LOWto the forward pass for the cheap path ofWaterShading.hlsl. - Motion vectors (TAA, STP, motion blur): the material's
WaterMotionVectorspass (light modeWaterMotionVectors, the same vertex displacement as the forward pass at the time in_WaterPrevious); a shader without it shows the motion of the scene behind the water. - Depth:
DepthWriteon the surface puts the water's depth into the camera depth texture for depth of field (defaultAuto: while post processing reads depth, not at Low quality).
Your own render extension
Derive from WaterSurfaceExtension (same GameObject as the WaterSurface) and override its render hooks: SetShaderData(MaterialPropertyBlock) and SetShaderData(Camera, MaterialPropertyBlock) feed the water material data of your own (for your own shader or a material variant), OnBeforeRender runs before the surface draws for a camera, OnRendered after it (for example to enqueue a screen pass; WaterMask tells water pixels apart). These hooks do not change the surface physics sees: waves, rest height and the ripple overlay come from the Umi components (WaveProfile, WaterOcean, WaterShore, WaterRipples).