This page has been translated automatically.
Setting Up Development Environment
High-Level Systems
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
Double Precision Coordinates
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Water Body

Water body allows for physical simulation of liquids of different density and viscous behavior. It also models the appropriate buoyant force on submerged objects and wave dynamics as two-way interaction is calculated. By that, in deep and shallow waters circular waves and splashes from physical bodies are generated and dispersed differently. Approximation of water is visually pleasant and fast enough, so can be used within a game environment; however, if the mesh is big and dense, it can be become quite costly.

Water body can be assigned either to a water mesh or a dynamic mesh object. In case of an arbitrary mesh, water will not have appropriate shading but all physical properties will still be present.

See also

Mesh Requirements

A mesh, to which a water body is assigned, should meet the requirements given here. The requirements are the same for meshes of both the dynamic mesh and the water mesh objects.

Grid Simulation Model

The water body is modeled as a two-dimensional grid with point particles positioned in the vertices of the mesh. The particle movement is restricted to two directions: it can be lifted upwards or dragged downwards. In the case of changing its position, the particle acquires a velocity that advects the neighboring particles and thus describes the grid of water body at each physics time step. That is how the waves are generated when physical bodies get into the water or a particle is directly assigned new velocity.

Water Grid Changes During Physics Simulation


Liquidity defines the viscosity of water (or any other liquid): it determines how readily it splashes and the resulting shaping of the waves. It multiplies the speed with which water particles pass velocity vectors to the neighboring ones.

  • The higher the value is, the more viscous the water is and the smaller the waves risen by the objects. For example, tap water is made runny by setting a high value, while syrup would have a low liquidity value.
  • Be careful not to set too hight or too low values, because it may lead to unstable simulation and blowing up of the water. To regain stability, try to tweak Interaction.


Density of the water determines the buoyancy of objects according to Archimedes' principle. Based on the volume of the submerged part of the shape and its mass, buoyancy force is applied to its center of mass and thrusts the object upwards, whereto the mean normal of the grid covered by submerged shape points.

  • By the minimum value of 0, the objects will not float in the water, but rather fall through it not encountering any resistance.
  • Increasing the value dictates the greater buoyant force. If set too high, the immersed objects start to be pushed out in the air.

Physical Behavior of Objects in Water

Two-way dynamical interaction allows for simulation in the both physically and visually convincing way the waves from the physical bodies as they disturb the fluid. Imagine the moving boat that forms a wake behind it, or the character that ripples the water as the he wades through (see the picture above).

Interaction with Objects

Physical object that is submerged into the water (or any other liquid) has its velocity vector. On the other side, all the water particles that are covered by this physical body or surround it, are calculated their own integrated velocity vector that approximate the state of water. Interaction value is a coefficient that determines how much the object's velocity influences the velocities of water particles and thus generate waves.

  • By the minimum value of 0, an object produces no disturbances on the water surface, as its velocity does not influences water particles at all.
  • Increasing the value conditions that water surface is disturbed more intensely and the waves from moving objects become higher.
  • Too high values may blow the water up, as the law of conservation of energy does not constrain the system! Try decreasing damping values to regain stability.

Linear Damping and Angular Damping

Objects getting into the water are expected to slow down, as resistance of the water is higher than the drag in the air. Damping values work the other way around compared to Interaction coefficient:
Linear damping defines how much linear velocity of the submerged object is decreased over time when influenced by velocities of surrounding water particles. And similarly, angular damping defines the gradual decrease in the object's rotation. Both linear and angular damping forces are accumulated before being applied.

  • By the minimum value of 0, objects movement is not hindered by the water. As a result, there are waves in the water.
  • Increasing the value leads to the linear or angular velocities more damped, and object slowing down faster as they get into the water. Higher values also result in more pronounced waves from the objects, as the energy of the system increases.
  • The water may blow up in case the values are be very high. Try decreasing interaction value to regain stability.

Emission of Particles

An additional visual effect of small droplets, splashes or bubbles on the water when objects falls into it can be created. For that, particle system is made a child node to the water mesh and a spark emitter is chosen to spawn particles. They will be generated only when the object contacts the water surface, while already submerged bodies will float without spawning them.

Water Boundaries

The following parameters relating to water boundaries allow adding different types of basins in the game environment and flexibly setting up physical behavior of water in a big natural lakes, small pools, rivers and ponds.


Waves considerably differ in size depending on the water depth. When formed in the deep water, the waves fully develop in size, arise high and move fast. When formed over a shallow bottom, they only ripple water surface, slow and small in length. Defining different depth allows simulating either puddles and shoals, or profundity.

  • With the minimum value of 0, the objects raise no waves in the water.
  • Increasing the value simulates conditions of deeper bottom waters and moving objects will form higher waves.

Intersection with the Ground

Intersection of water with the underlying terrain is necessary, for example, to estimate the actual depth of the basin. To do so, the Intersection box should be checked, and the water mesh object made a child node of the terrain orstatic mesh .

Intersection is implemented in the following way: from the water mesh surface the rays are traced downwards, as far as the depth distance. If on that line intersection with the parent node has occurred, the obtained depth is used in calculations. If no intersection happened, or this option is not enabled, the depth is considered of the set value.

Intersection is also traced upward to check if the water is under terrain and there is no need to render it.


Absorption is an option that creates either an effect of open water surface that does not have marked boundaries or, on the contrary, of the limited basin.

  • If Absorption box is checked, the waves are dispersed along the mesh perimeter. Take notice, that in this case the water level at mesh edges will gradually fall down to zero level.
  • If unchecked, the backwash from the wall is simulated: the wave when reaching the brink of the water is reflected and returns in the direction it came from.

Distance of Simulation

To perform physical simulation for the water and not overwhelm either the CPU or the GPU, calculations are limited to the specified distance. When the water mesh is past this set limit, physical calculations are not done, though objects preserve their buoyancy.

  • If set to infinity (inf), there is no distant-dependent optimization for physics.
Last update: 2017-07-03
Build: ()