Waves, time and large worlds
Gerstner waves
A wave set is a sum of Gerstner waves. For an undisplaced surface point P (XY) and wave i:
Theta = K * dot(Direction, P) - Omega * Time + Phase
XY += -Horizontal * Direction * sin(Theta)
Z += Amplitude * cos(Theta)
K = 2 PI / Wavelength.Omega = sqrt(Gravity * K) * TimeScale(deep water dispersion).Horizontal = Steepness * Amplitude, limited so that the summed horizontal steepness never exceedsMaxCombinedSteepness. Above 1, crests would loop.
Because the surface moves horizontally, the height at a world XY location is not the height of the undisplaced point at that location. Queries find the right undisplaced point with a few fixed point iterations (SurfaceSolverIterations in the settings).
Water time
All machines must use the same time, otherwise floating objects disagree. The subsystem uses the server clock of Pulse Foundation (UPulseClockSubsystem::GetTime(EPulseClock::Server), a double): the same on every machine, smoothed on clients so the waves don’t jitter, and never paused (waves keep moving while the game clock stands still).
Always use UPulseWaterSubsystem::GetWaterTime() for anything wave related. For tests or a photo mode, SetWaterTimeOverride freezes it.
The level editor has a water time of its own: the waves run without Play, and the time bar of the Pulse Water mode pauses, sets and speeds it up. Play in Editor and games always use the time of the server. How far a client is off the server shows on the Water page of the Pulse Debugger.
Large worlds
- CPU: phases are computed in double precision with absolute positions and time. Queries give the same result at the world origin and millions of meters away.
- GPU: shaders work in float. The subsystem keeps a render origin that snaps to
RenderOriginSnapSizearound the camera. For every wave it computes the phase at that origin in double precision and uploads it. The shader only addsK * dot(Direction, Local), whereLocalis the position relative to the render origin. When the origin moves, the phases change by exactly the right amount, so nothing visibly changes.
Environment
IPulseWaterEnvironmentProvider::SampleWaterEnvironment(Location, WaterTime) returns sea state, wind, mood and custom parameters. Set your provider with UPulseWaterSubsystem::SetEnvironmentProvider.
- It must be deterministic: the same input must give the same output on every machine.
SeaStateScalescales the wave amplitudes. Queries use the sample at the query location.- Materials currently get the sample at the camera location only. Keep the field smooth over hundreds of meters.