Umi WaterOverviewGetting startedSamplesComponentsScriptingFAQLimitsCore vs ProChangelog

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)) { … }

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).

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).