Lumberyard
User Guide (Version 1.15)

Water Volume

This feature is in preview release and is subject to change.

You can use the Water Volume component to add small and medium bodies of water to your level. Use the following properties to adjust the water volume's physical attributes, aesthetic, and complex interactions.

To use the Water Volume component, you must enable the Water gem for your game project and then rebuild the project. For more information, see Enabling Gems.

Water Volume Component Properties

The Water Volume component has the following properties:

Material

Specifies the water material to use. The material must have the Water shader added.

Minimum Spec

Sets the minimum engine specification for the volume to render.

Default: Low

Surface U Scale

Specifies how much to tile the water surface texture on the u-axis.

Default: 1.0

Range: 0.0 to (infinity)

Surface V Scale

Specifies how much to tile the water surface texture on the v-axis.

Default: 1.0

Range: 0.0 to

View Distance Multiplier

Adjusts the maximum view distance. The default value is 1.0. To specify a maximum view distance that is 10% further than the default, use 1.1.

Default: 1.0

Range: 0.0 to

Fog

Density

Sets the density of the water fog.

Default: 0.5

Range: 0.0 to

Color

Sets the color of the water fog.

Default: Deep blue (RGB 0.005, 0.01, 0.02)

Color Multiplier

Multiplies this value by the Color parameter to produce the final fog color.

Default: 1.0

Range: 0.0 to

Color Affected by Sun

Determines whether the sky color affects the water's fog color. This property is useful for outdoor water volumes.

Default: True

Shadowing

Specifies how much shadows affect the water's fog color.

Default: 0.5

Range: 0.0 to 1

Cap at Volume Depth

Determines whether fog is rendered when the player is under the volume.

Default: False

Caustics

Enabled

Enables water caustics.

Default: True

Intensity

Affects the brightness and visibility of caustics.

Default: 1.0

Range: 0.0 to

Tiling

Affects the number of caustics that are rendered.

Default: 1.0

Range: 0.0 to

Height

Determines how far above the surface caustics are rendered.

Default: 0.5

Range: 0.0 to

Advanced

Spillable Volume

Specifies the volume quantity that can spill into a container below.

Default: 0.0

Range: 0.0 to

Volume Accuracy

Specifies the accuracy of the surface level of the spilled volume.

Default: 0.001

Range: 0.0 to

Extrude Border

Specifies the border amount to add to the spilled volume.

Default: 0.0

Range: 0.0 to

Convex Border

Determines whether the convex hull of the container should be considered.

Default: false

Object Size Limit

Sets the minimum volume that an object must have to affect the water surface.

Default: 0.001

Range: 0.0 to

Wave Simulation

Surface Cell Size

Specifies the size of wave simulation cells.

Default: 0.0

Range: 0.0 to

Speed

Specifies how fast each wave moves.

Default: 100.0

Range: 0.0 to

Dampening

Specifies how much dampening force to apply during simulation.

Default: 0.2

Range: 0.0 to

Timestep

Specifies the frequency of wave simulation ticks.

Default: 0.02

Range: 0.0 to

Sleep Threshold

Sets the lowest velocity for a cell to rest.

Default: 0.01

Range: 0.0 to

Depth Cell Size

Specifies the size of the depth cell.

Default: 8.0

Range: 0.0 to

Height Limit

Sets the highest and lowest heights that the surface can be deformed.

Default: 7.0

Range: 0.0 to

Force

Specifies the strength of the wave force.

Default: 10.0

Range: 0.0 to

Simulation Area Growth

Adds space if the water simulation causes expansion.

Default: 0.0f

Range: 0.0 to

EBus Request Bus Interface

Use the following request functions with the EBus interface to communicate with other components of your game. You can use this EBus to communicate to an entity with a Water Volume component attached. The EBus is available at game time and editing and can be accessed from C++, Lua, and the Script Canvas editor.

For more information about using the event bus (EBus) interface, seeWorking with the Event Bus (EBus) System.

SetSurfaceUScale

Sets how much to tile the surface texture horizontally (u-axis of the UV map). The surface texture is often defined as a bump or normal map.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetSurfaceUScale

Returns how much to tile the surface texture horizontally (u-axis of the UV map).

Parameters

None

Return

Type: Float

Scriptable

Yes

SetSurfaceVScale

Sets how much to tile the surface texture vertically (v-axis of the UV map). The surface texture is often defined as a bump or normal map.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetSurfaceVScale

Returns how much to tile the surface texture vertically.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetFogDensity

Sets the density of the underwater fog in the volume. A lower value produces clearer water, and a higher value produces murkier water.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetFogDensity

Returns the fog density in the water volume.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetFogColor

Sets the color of the underwater fog in the volume. The FogColorMultiplier parameter modifies the fog color before rendering.

Parameters

AZ::Color

Return

None

Scriptable

Yes

GetFogColor

Returns the color of the underwater fog in the volume. The FogColorMultiplier parameter does not affect the returned value.

Parameters

None

Return

AZ::Color

Scriptable

Yes

SetFogColorMultiplier

Sets the value to multiply with the FogColor parameter before rendering. A higher value produces brighter underwater fog.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetFogColorMultiplier

Returns the value to multiply with the FogColor parameter before rendering.

Parameters

None

Return

Type: float

Scriptable

Yes

SetFogColorAffectedBySun

Sets whether the sun affects the underwater fog in the volume. If true, the SunColor value affects the fog color. You can set the SunColor in the Time of Day Editor. For outdoor water volumes, use true. For indoor water volumes, use false.

Parameters

Type: Boolean

Return

None

Scriptable

Yes

GetFogColorAffectedBySun

Returns whether the sun affects the underwater fog in the volume.

Parameters

None

Return

Type: Boolean

Scriptable

Yes

SetFogShadowing

Sets the strength of the shadows that fall on the water volume. If 0.0, shadows have no effect on the water volume. If 1.0, a dark shadow falls on the water volume. You must set r_FogShadowsWater to 1 for the parameter to have any effect.

Parameters

Type: Float

Return

None

Scriptable

Yes

Valid values

0.0 to 1.0

GetFogShadowing

Returns the strength of the shadows that fall on the water volume. Valid values are 0.0 to 1.0. However, this property returns the value for the FogShadowing parameter, regardless of the valid range.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetCapFogAtVolumeDepth

Sets whether the underwater fog effect caps at the volume depth. If false, underwater fog renders despite the distance of the camera below the water volume.

Parameters

Type: Boolean

Return

None

Scriptable

Yes

GetCapFogAtVolumeDepth

Returns whether the underwater fog effect caps at the volume depth.

Parameters

None

Return

Type: Boolean

Scriptable

Yes

SetCausticsEnabled

Sets whether the water volume produces caustics. You must set r_WaterVolumeCaustics to 1 for the water caustic settings to have any effect. To display caustics, set the water volume to a world height of 1 or higher.

Parameters

Type: Boolean

Return

None

Scriptable

Yes

GetCausticsEnabled

Returns whether the water volume produces caustics.

Parameters

None

Return

Type: Boolean

Scriptable

Yes

SetCausticIntensity

Sets the intensity of the caustics for the water volume. This property scales the normal map when rendering to the caustic map to produce a stronger caustic effect.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetCausticIntensity

Returns the intensity of the caustics for the water volume.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetCausticTiling

Sets a multiplier to use for tiling the water volume's caustics. This value is multiplied with the tiling that's applied to the surface normals. You can then scale the caustic tiling separately from the material.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetCausticTiling

Returns the value that is multiplied to the surface's normal tiling during caustic generation.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetCausticHeight

Sets the allowable height to cast caustics above the water's surface. If 0.0, caustics render only beneath the water's surface. If you use a value greater than 0, caustics can cast on nearby surfaces that are not in the water volume.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetCausticHeight

Returns the allowable height to cast caustics above the water's surface.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetSpillableVolume

Sets how much volume can spill. Volumes can spill into a container but cannot spill onto terrain. A higher value allows more of the container volume to fill with water. If greater than 0, the water volume raycasts onto nearby geometry and attempts to spill into it. The geometry must have a concave mesh on a mesh component.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetSpillableVolume

Returns how much volume can spill.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetVolumeAccuracy

Sets the accuracy of the water level for the spilled water volume. The water level for spilled volume is iteratively calculated until the value is within the distance to the water level expected by the water volume. A higher value requires more iterations to calculate the water level. If 0.0, the water level iterations will reach a hard-coded limit of 100 iterations.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetVolumeAccuracy

Returns the accuracy of the water level for the spilled water volume.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetExtrudeBorder

Sets how much to increase the border of the water volume when spilled. If 0, wave simulation may cause the open edges of a water volume's surface to be visible. This is useful for wave simulation.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetExtrudeBorder

Returns how much to increase the border of the water volume when spilled.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetConvexBorder

Sets whether the water volume should look for a convex border when spilling. This is useful if the volume spills into a container that has multiple contours. Because water volumes don't support multiple contours, this property uses logic to break the volume into multiple volumes that can fit the contoured container.

Parameters

Type: Boolean

Return

None

Scriptable

Yes

GetConvexBorder

Sets whether the water volume should look for a convex border when spilling.

Parameters

None

Return

Type: Boolean

Scriptable

Yes

SetObjectSizeLimit

Sets the minimum volume that is required for an object to experience volume displacement. Objects that have a volume that is smaller than this value will not deform the surface.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetObjectSizeLimit

Returns the minimum volume that is required for an object to experience volume displacement.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveSurfaceCellSize

Sets the size of each wave simulation cell. The number of wave simulation cells is determined by the size of the volume and the individual size of the cells. This affects the water surface mesh.

  • A large water volume with a small cell size produces a high number of cells and a large, complicated surface mesh. This type of mesh can make it difficult to evaluate wave simulation, unless you tune other parameters.

  • A small water volume with a large cell size produces a low number of cells and a small, simple surface mesh.

Use the p_draw_helpers a_g console variable to see the tessellated surface mesh. You may need to move the editor's viewport camera closer to the volume for the mesh to render.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveSurfaceCellSize

Returns the size of each wave simulation cell.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveSpeed

Sets how fast the waves move.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveSpeed

Returns how fast the waves move.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveDampening

Sets how much to dampen the wave simulation. A higher value produces waves that lose velocity more quickly.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveDampening

Returns how much to dampen the wave simulation.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveTimestep

Sets how often the wave simulation ticks. A lower value produces frequent simulation ticks, which resolves a simulation quickly.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveTimestep

Returns how often the wave simulation ticks.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveSleepThreshold

Sets the minimum velocity that is required for a cell to sleep. A cell is at rest and no longer applies force to its neighbors when the velocity reaches this threshold.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveSleepThreshold

Returns the minimum velocity that is required for a cell to sleep.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveDepthCellSize

Sets the size of each depth cell in a wave simulation. The number of wave simulation cells is determined by the size of the volume and the individual size of the cells. A smaller cell size produces more depth cells and an intensive wave simulation.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveDepthCellSize

Returns the size of each depth cell in a wave simulation.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveHeightLimit

Sets the height and depth limit for generated waves. A height limit of 3 means the cell deforms up three units and down three units.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveHeightLimit

Returns the height and depth limit for generated waves.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveForce

Sets the amount of force that wave simulation cells apply to each other. A low wave force produces high resistance between cells. A high wave force produces less resistance and transmits more energy between cells. More transmitted energy results in larger, more pronounced waves.

Parameters

Type: Float

Return

None

Scriptable

Yes

GetWaveForce

Returns the amount of force that wave simulation cells apply to one another.

Parameters

None

Return

Type: Float

Scriptable

Yes

SetWaveSimulationAreaGrowth

Sets the size boundary to add to a simulation area. This determines where the water volume simulation can move and grow outside the initial defined area. Increase the variable to add the size boundary to the simulation area. The p_draw_helpers a_gj console variable draws the wave simulation area as a checkerboard height field.

Parameters

None

Return

None

Scriptable

Yes

GetWaveSimulationAreaGrowth

Returns the size boundary to add to a simulation area.

Parameters

None

Return

None

Scriptable

Yes

Example Water Volume Component Request Bus

function example:OnActivate local waveForce = WaterVolumeComponentRequestBus.Event.GetWaveForce(self.entityId) WaterVolumeComponentRequestBus.Event.SetWaveForce(self.entityId, waveForce * 10) end

Setting up Volume to Spill

You can set water volumes to spill into container volumes. If the Spillable Volume parameter is a value above 0, the volume raycasts down and searches for a suitable container to spill into. This includes any mesh component with a concavity. A higher value for the Spillable Volume parameter produces a higher water level in the target container.

The spilled water volume behaves similarly to the source water volume and can simulate waves. The spilled volume is calculated iteratively, and the Volume Accuracy parameter determines the accuracy of the water level. Spilled water volumes are calculated once and should not incur a per-frame performance penalty due to volume calculation.

The following image shows water volume above a pool that does not allow spilling.


                Example Water Volume component with water that does not
                    spill.

The following image shows the water volume spilling 100 units into the pool.


                Example Water Volume component with water spilling at
                    100 units into the pool.

The following image shows the water volume spilling 1000 units into the pool.


                Example Water Volume component with water spilling at
                    1000 units into the pool.

Setting up Wave Simulation

You can use wave simulation to create the appearance of the water surface reacting to physical forces. This feature does not simulate ocean waves. Because wave simulation is an expensive task, consider the performance impact before you enable this feature.

To enable wave simulation on a water volume, set the Surface Cell Size parameter to a value above 0. For smaller water volumes, you can use a value of 2 or 3. A smaller cell size produces more cells and a longer evaluation time for the simulation.

Even without wave simulation the Water shader deforms the surface mesh to make the water appear in motion.

Example

The following image shows simple water volume without wave simulation.


                The Water Volume component does not have wave
                    simulation enabled.

Example

The following image shows water volume with wave simulation.


                The Water Volume component has wave simulation
                    enabled.