Environment

The environment is what changes the water from place to place and over time: the sea state (how high the waves are), the wind (direction and speed, used by sails) and the mood (for example dark and murky water around an evil island). Every location has an FPulseWaterEnvironmentSample:

Field Meaning
SeaStateScale Scales the wave amplitudes. 1 = the wave set as authored, 0 = flat water, > 1 = rough sea.
WindDirection Direction the wind blows to (normalized, XY).
WindSpeed Wind speed in cm/s.
MoodDarkness 0 = normal, 1 = dark. The shipped materials use it for darker colors, foam and underwater fog.
CustomParams Free values for your own materials.

Where the environment comes from

  1. The environment provider (IPulseWaterEnvironmentProvider, set with UPulseWaterSubsystem::SetEnvironmentProvider). Without one, Default Environment of the project settings is used everywhere.
  2. Environment zones on top of it (see below).

UPulseWaterSubsystem::SampleEnvironment returns the combined result. Water queries use it at the queried location, so the waves a boat rides on are the waves of the sea state at its position.

The environment must be deterministic: the same location and time must give the same sample on the server and on every client. Compute it from replicated or generated data (for example the seed and the state of an island), never from local randomness.

Environment zones

UPulseWaterEnvironmentZoneComponent changes the environment in a circle around itself, without any code: a storm area, a calm bay, the dark sea around an island.

  • Radius and FalloffDistance: full effect inside Radius - FalloffDistance, smooth falloff to nothing at Radius.
  • Environment plus bAffectSeaState, bAffectWind, bAffectMood, bAffectCustomParams: which values the zone sets.
  • Priority: zones with a higher priority are applied later and win where zones overlap.
  • Strength (SetStrength): fades the whole zone, e.g. an island that turns from dark to bright when it is freed.
  • LiquidType and WaterTags: where the zone weighs at least 0.5, the ocean is made of its liquid and queries get its tags (a lava sea, a fishing ground, a dark sea); see Liquids.

Zones are part of the water queries, so they must exist on every machine with the same values: place them in the level, or spawn them on every machine from replicated state. A zone that only exists on the server makes the client predict boats on different waves.

How materials see the environment

Materials cannot call the provider, so the subsystem samples it on a coarse grid around the camera (the environment grid) and uploads it as a texture:

  • Environment Grid Resolution x Environment Grid Cell Size (default 64 x 64 m) around the camera. Farther water uses the values at the edge of the grid.
  • Materials interpolate the grid bilinearly (PulseWater_SampleEnvironment in PulseWaterEnvironment.ush), so the ocean shows the same sea state as the queries as long as the environment changes smoothly over a cell.
  • The grid moves with the camera and resamples Environment Grid Refresh Per Frame points every frame, so changes over time (weather, a zone that fades) reach the materials within a few frames.
  • With a provider that supports parallel sampling (below), the grid is sampled in a background task and the materials get it one frame later; the game thread only copies the zones.

PW_Wind, PW_Darkness and PW_EnvironmentCustom still hold the values at the camera, for materials that do not need them per pixel (the underwater post process uses PW_Darkness).

The settings are listed in Getting started.

Writing a provider

Implement IPulseWaterEnvironmentProvider on any UObject (C++) and return the sample for a location and water time:

FPulseWaterEnvironmentSample UMyWeather::SampleWaterEnvironment(const FVector& InLocation, double InWaterTime) const
{
	FPulseWaterEnvironmentSample sample;
	sample.SeaStateScale = GetStormStrength(InLocation, InWaterTime) * 2.f + 0.5f;
	sample.WindDirection = FVector2D(1., 0.5).GetSafeNormal();
	sample.WindSpeed = 800.f;
	return sample;
}

Keep it cheap: it runs for every water query and for the grid points that are resampled each frame.

Return true from SupportsParallelSampling if SampleWaterEnvironment may run on worker threads: no side effects, nothing that could crash when the game thread changes it meanwhile (reading a value that changes is fine for the grid of the materials). Then large query batches are split over worker threads (the game thread waits for them) and the environment grid is sampled in the background. The default provider (UPulseWaterConstantEnvironmentProvider) does.


This site uses Just the Docs, a documentation theme for Jekyll.