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 throughGet 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:
- Shading Model Single Layer Water, Tangent Space Normal off, one sided (see the pitfalls below).
- The vertex function:
WorldPositionOffsetto World Position Offset,Undisplacedinto the pixel function. Normal,Jacobian,MoodandWindof the pixel function,Undisplacedof the vertex function andRippleofMF_PulseWater_RipplesintoMF_PulseWater_Shading;CrestBreakup1 for waves (ocean, lakes), 0 (the default) where the foam has patches of its own (rivers, fluid bakes).- Its outputs to Base Color, Roughness, Opacity and Normal, and
ScatteringandAbsorptionto the Single Layer Water Material output. - The ocean only: blend mode Masked and
MF_PulseWater_OceanMaskto 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.
PhaseGandColorScaleBehindWaterconnected 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).