Water materials

Every PulseWater surface (ocean, lakes, rivers, fluid volumes) is built from the same material functions. The master materials only connect them, and every look is a parameter you change in a material instance, without touching a graph.

Adjusting a look

The project settings (Project Settings > Pulse > Water) use material instances of the plugin:

Water Instance (default) Master
Ocean MI_PulseWater_Ocean M_PulseWater_Ocean
Ocean seen from below MI_PulseWater_OceanUnderside (two sided, follows MI_PulseWater_Ocean)  
Lakes MI_PulseWater_Lake M_PulseWater_Lake
Rivers MI_PulseWater_River M_PulseWater_River
Fluid volumes MI_PulseWater_Fluid M_PulseWater_Fluid
Waterfalls MI_PulseWater_Waterfall M_PulseWater_Waterfall
Under water (post process) MI_PulseWater_Underwater M_PulseWater_Underwater

Edit an instance to change that water in the whole project. For a look of your own, create a material instance of the master (or of the plugin’s instance, so it keeps following it), change its parameters, and set it in the project settings or on a single water body (SurfaceMaterial). The parameters are grouped:

Live tuning in the editor. The water renders with dynamic material instances that each ocean, lake, river, fluid volume, waterfall, floating instances component and underwater post process makes from its material. In the editor they watch the material and its parents: when you change a parameter of MI_PulseWater_Ocean (or of any instance or master they are made from) in the material instance editor, they make their dynamic instances again and the level shows the change right away, without a restart or a rebuild of the water. Parameters set on a dynamic instance itself (by the plugin, or by your Blueprint through Get Ocean Material Instance) carry over to the new one. Only the editor does this: in a packaged game the dynamic instances are made once. Because the instance is a new object after an edit, get it again (Get Ocean Material Instance, Get Surface Material Instance) instead of keeping it across material edits.

Group Parameters
Water Color ScatteringCoefficients (the color of deep water), AbsorptionCoefficients (light absorbed per meter: red goes first, so deep water turns blue green), their dark versions DarkScatteringCoefficients and DarkAbsorptionCoefficients, Roughness
Foam FoamColor, DarkFoamColor, FoamJacobianStart and FoamJacobianEnd (crest foam where the waves compress the surface; lower values give less foam, the gap between them is the soft edge), FoamOpacity, FoamFadeStart and FoamFadeEnd (foam fades out with the distance, so it does not flicker), FoamBreakupScale, FoamBreakupStrength, FoamStreakStretch and FoamEdgeSoftness (crest foam on the ocean and lakes breaks up into whitecaps with torn, fading edges and streaks along the wind; the pattern rides with the surface, and even the densest foam keeps gaps), FoamDetailScale (near the camera a finer noise tears the foam into lace: holes inside dense foam, bubbles and threads at its edges; it fades out where its cells get smaller than a pixel, so distant foam stays a soft readable patch; 0 = no lace), FoamRoughness (foam is rough, the roughness follows the foam amount). FoamColor stays below white and FoamOpacity below 1, so foam takes the light of the water around it instead of flat white
Shore ShoreFoamWidth, ShoreFoamStrength: foam where the water in front of the ground is thin
Ripples RippleNormalStrength, RippleFoamStrength, RippleFoamStart, RippleFoamEnd: ripples of objects in the water
Surface MinNormalFacing: bends normals that face away from the camera back towards it, otherwise grazing wave backs reflect the lower hemisphere
Detail Waves rivers: RiverDetailScale; fluid volumes: FluidDetailStrength, FluidDetailScale (waves that flow with the water)
Set by PulseWater PW_*: the plugin sets them every frame, leave them

The dark versions blend in with the mood of the environment, e.g. for the dark sea around an island. Waterfalls have WaterColor, FoamColor, Opacity and Roughness; the underwater post process has FogColor, FogDensity, DepthDarkening and their dark versions.

Material functions

They are in /PulseWater/Materials/Functions (category PulseWater in the palette of the material editor):

Function What it does
MF_PulseWater_Space Positions relative to the render origin PW_Origin: the vertex without material offsets, the camera, the pixel
MF_PulseWater_OceanVertex, MF_PulseWater_LakeVertex, MF_PulseWater_RiverVertex, MF_PulseWater_FluidVertex Vertex part of each kind of water: WorldPositionOffset, and Undisplaced for the pixel part
MF_PulseWater_OceanPixel, MF_PulseWater_LakePixel, MF_PulseWater_RiverPixel, MF_PulseWater_FluidPixel Pixel part: Normal, wave Jacobian, Mood and Wind of the environment
MF_PulseWater_Ripples Ripples of objects in the water: normal tilt and foam
MF_PulseWater_Shading The look every surface shares (the groups above): BaseColor, Roughness, Opacity, Normal, Scattering, Absorption
MF_PulseWater_Wetness Not for water: wet clothes and hulls below the lines of a Wetness component
MF_PulseWater_OceanMask OpacityMask of the ocean: hidden under terrain (caves) and below water bodies at its level

A master material is built like this:

  1. Shading Model Single Layer Water, Tangent Space Normal off, one sided (see the pitfalls below).
  2. The vertex function: WorldPositionOffset to World Position Offset, Undisplaced into the pixel function.
  3. Normal, Jacobian, Mood and Wind of the pixel function, Undisplaced of the vertex function and Ripple of MF_PulseWater_Ripples into MF_PulseWater_Shading; CrestBreakup 1 for waves (ocean, lakes), 0 (the default) where the foam has patches of its own (rivers, fluid bakes).
  4. Its outputs to Base Color, Roughness, Opacity and Normal, and Scattering and Absorption to the Single Layer Water Material output.
  5. The ocean only: blend mode Masked and MF_PulseWater_OceanMask to Opacity Mask.

For a material of your own, e.g. a toon look, keep the vertex and pixel functions, they make the surface match the water queries, and replace MF_PulseWater_Shading. The HLSL behind the functions is in /Plugin/PulseWater/Private: PulseWaterOcean.ush, PulseWaterBody.ush, PulseWaterFluid.ush, PulseWaterSurface.ush and PulseWaterRipples.ush.

Parameters the plugin sets

The subsystem sets these on every water material instance every frame:

Parameter Type Meaning
PW_WaveData Texture Packed waves (2 texels per wave, for sea state 1) and wave events
PW_WaveCount Scalar Number of waves in PW_WaveData
PW_Origin Double vector Render origin (XY) and sea level (Z)
PW_Time Scalar Water time, wraps every hour. Only use it for scrolling textures.
PW_EnvironmentData Texture Environment grid around the camera: sea state, wind and mood per location (see Environment)
PW_EnvironmentInfo Vector Grid origin relative to PW_Origin (XY), 1 / cell size (Z), grid points per axis (W, 0 = no grid)
PW_Wind Vector Wind direction (XY) and speed in cm/s (Z) at the camera
PW_Darkness Scalar Mood darkness at the camera (0..1)
PW_EnvironmentCustom Vector Custom environment parameters at the camera
PW_TerrainDepth Texture Depth capture of the terrain from above
PW_TerrainInfo Vector Capture center relative to PW_Origin (XY), 1 / capture size (Z, 0 = no capture), capture height above the sea level (W)
PW_BodyMask Texture Calm surface heights of the water bodies around the camera (relative to the sea level)
PW_BodyMaskInfo Vector Mask center relative to PW_Origin (XY), 1 / mask size (Z, 0 = no bodies), level margin (W)
PW_RippleTexture, PW_RippleInfo Texture, vector Ripple height field around the camera and its area

Water bodies add PW_BodyWaveScale and PW_BodyCellSize (see Water bodies), fluid volumes the frames of their bake (PW_FluidFrameA, PW_FluidFrameB, PW_FluidBase, PW_FluidGrid, PW_FluidState, PW_FluidAxis, see Fluid simulation).

For other materials, e.g. a wet line on a boat hull, register their dynamic material instance with UPulseWaterSubsystem::RegisterMaterial and use PulseWater_GetApproximateWaveHeight from /Plugin/PulseWater/Private/PulseWaterWaves.ush (it uses the sea state at the camera).

Pitfalls with Single Layer Water

These caused a white, flickering haze over the whole image (bloom spreading invalid pixels from the far ocean near the horizon) when Temporal Super Resolution is used:

  • Two sided ocean material. Wave displacement turns many far triangles away from the camera at flat view angles; rendering their back faces as water produces invalid pixels. Keep the ocean material one sided.
  • PhaseG and ColorScaleBehindWater connected on the Single Layer Water output. Leave both unconnected (engine defaults) on the ocean material.

TAA does not show the haze, TSR does; turning off bloom hides it but does not remove the cause.

Brightness banding in stylized post processing

The far ocean has a very smooth brightness gradient that moves slowly with the waves and the sky. Post process materials that quantize brightness (cel shading, posterize or toon bands) turn that gradient into a straight, horizontal edge, and because the brightness sits right at a band border, the edge flips between two bands from frame to frame and looks like flickering. Exclude water from the banding, or use softer banding on it. Water pixels can be found in a post process material with the Scene Texture ShadingModelID (compare with SHADINGMODELID_SINGLELAYERWATER in a custom node).


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