Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
Setting Up Development Environment
Usage Examples
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
CIGI Client Plugin
Rendering-Related Classes

Physical Bodies

Bodies can be considered as physical approximations of objects. They describe object's behavior and represent a set of its physical parameters, such as mass, velocity, etc. It is the body that enables interaction of an object with other objects and with external physical forces as well. Each type of body is used for simulation of a specific type of object:

  • Rigid body (also requires a shape to be assigned) - enables simulation of objects in accordance with rigid body dynamics.
  • Ragdoll body (also requires a shape to be assigned for each bone) - provides bone-animated characters with procedural animation of a death sequence.
  • Fracture body - enables real-time simulation of destructible objects.
  • Rope body - enables physical simulation of varios types of ropes and wires.
  • Cloth body - enables physical simulation of various cloth types of cloth.
  • Water body - enables physical simulation of liquids of different density and viscous behavior including buoyancy effect and wave dynamics.

There are also two types of auxiliary bodies:

  • Dummy body - a static type of body without physical properties. It is used to attach other bodies via joints.
  • Path body - a static type of body without physical properties. It is a spline, along which an arbitrary rigid body can be moved.

Rigid Body Dynamics

Most physics simulations are based on rigid body dynamics. A rigid body is an ideal representation of a solid body, which occupies a finite volume of space. This volume of space is determined by a shape or a set of shapes assigned to the body. Rigid bodies cannot be deformed, i.e their geometry does not change no matter what happens with this body. Rigid body dynamics is applied to the following bodies with shapes assigned:

After being enabled, all of these bodies and their shapes that approximate object's volume share common properties of rigid objects obeying Newtonian mechanics.

Run Lola Run

Rag dolls and rigid bodies moving according to rigid bodies dynamics

Basic Concepts

A state of a rigid body at any moment is specified with its position, orientation in space (with respect to some reference point — center of mass) and velocity. There are two types of body motion and therefore two velocity components:

  • Linear motion. If we imagine that the orientation of the body is fixed, then the only movement the body can undergo is translation motion — change in linear position. This change is performed with a linear velocity.
  • Angular motion. On the other hand, if we freeze the center of mass of our body in space, the only movement the body will be able to perform is rotation, which is described by an angular velocity
Setting a body's linear or angular velocity will immediately make it move or rotate in a specified direction.

As the body moves, its linear and angular momenta change. The linear momentum can be thought of as an extent, to which the body will continue to move along a straight path. It is the product of the mass and linear velocity of the body:

p = m * v.

The body will keep on moving forever, unless affected by an external force or an impulse. Force equals mass of the body multiplied by acceleration:

F = m * a.

By causing the body to undergo an acceleration (i.e. to change its velocity over time), force controls its velocity and position indirectly.

Forces acting on a body do not affect it immediately, they are accumulated before each physics simulation frame, and during simulation the resulting force, if unbalanced, is applied. Then forces are reset to zero to be calculated anew for the next frame. The same is true for torques.

Impulse is the integral of force over time. It may be be regarded as the change in momentum of an object to which a resultant force is applied. For example, when two bodies collide, they exchange impulses that are equal and opposite, as Newton's third law applies, and in the result objects move apart.

Similarly to the linear momentum, the angular momentum is the measure of the "quantity of rotation motion" and can be thought of as an extent, to which the body will continue to rotate around an axis of symmetry. It is expressed as the product of the inertia tensor of the body and its angular velocity.

Rotation continues until torque, a rotational force, is exerted on this body. Torque is the cross product of the radius vector (a vector from the center of mass to the point where torque is applied) and the force vector (the magnitude of the force). Loosely speaking, it acts like a lever affecting rotational speed.

Forces and impulses can also be applied to an arbitrary point of the body and may cause body rotation, when this point is not the center of mass. In this case, force is computed as cross product of force vector and radius vector (from a center of mass to the necessary point) and is added to the torque. And the other way around, torque applied not to the center of mass increases force.

Unlike forces and torques, impulses immediately change body velocity as the physics is updated.

To sum it up, the movement is characterized by the following basic parameters:

Linear Motion Angular Motion
Mass (scalar) Inertia tensor (mat3)
Linear velocity (vec3) Angular velocity (vec3)

Impulse ( vec3)
Torque (vec3)

Adjustable body parameters, that determine its behavior in the framework of rigid body dynamics, are as follows:


Mass of the object multiplied by gravity specified for the world defines its weight:

W = m * g

The center of mass is automatically calculated as the mean location of mass of all the shapes that approximate the object. It serves as a reference point for linear motion and rotation, as well as application of external force and torque.

Mass parameters of the body can be set up manually or determined automatically using the shape-based parameters. It is convenient when a body has several shapes.


Density of the objects is defined as its mass per unit volume:

ρ = m / V

Density value evidently depends on the mass value and vice versa: the higher the values are, the heavier and more dense the object is.

Boxes of different mass and density

Buoyant boxes of different mass and density

Density determines buoyancy of the body in accordance with Archimedes' principle. The higher the density, the less tendency a body has to float.

Linear Damping and Angular Damping

When the object begins moving in a definite direction, the linear damping force slows it down up to a complete stop. Similar to linear damping, angular damping reduces angular velocity of objects over time, so that their rotation ceases. To the linear damping of the body the global Linear damp is added, and the exponential function is calculated. In exactly the same way, to angular damping of the body the global Angular damp is added.

These two parameters ensure that objects smoothly come to a stop and no calculations are done for unnecessary motion.

Maximum Linear Velocity and Maximum Angular Velocity

Maximum linear and angular velocity define the maximum possible velocities of the body. Velocities that exceed this limit will be clipped. For example, maximum linear velocity parameter can help to avoid tunneling (penetration) effect.

There are also global maximum linear and angular velocities thresholds. The global maximum is compared with the maximum set for the body, and the minimum value is chosen to clip the actual velocity.


Coefficient of friction allows to model more rough rubbing of surfaces and is opposite to the body's movement direction. Friction parameter of both surfaces being in contact are considered:

  • The higher the value, the less tendency the body has to slide.
The resulting calculated friction depends on the objects' masses and gravity, and the angle between contacting surfaces. E.g. if a body slides down an inclined plane, the friction is lower, because less is the force of gravity that is perpendicular to the face of the surface.

Friction is calculated on contact between physical bodies.

If the surface is assigned a surface_base property, which has a corresponding parameter, it also contributes to calculations.


Coefficient of restitution determines the degree of relative kinetic energy retained after a collision. It defines how bouncy the object is by contacting with another object. It depends on the elasticity of the materials of colliding bodies. The simulated restitution, like friction, considers the total value for both objects being in contact.

  • The maximum value of 1 models elastic collision. Objects bounce off according to the impulse they get by contact.
  • The minimum value of 0 models inelastic collision. Objects do not bounce at all.

Again, just like friction, restitution is calculated by the contact between physical bodies.

If the surface is assigned a surface_base property, which has a corresponding parameter, it also contributes to calculations.


When a body does not move and stays in the equilibrium for some time, it will most probably be immobile until an external force is exerted on it and urges it to move again. During this period of inactivity, there is actually no need to simulate it. This state is called freezing and it allows to save a great deal of computational resources.

Freezing can be applied only to the following bodies:

Frozen boxes     Simulation starts again as the impulse unfreezes boxes
Frozen blue and unfrozen red boxes. The impulse applied to the pyramid of boxes unfroze all but one.

The body is frozen, i.e. stops to be simulated, if:

  1. Its linear velocity is lower than Frozen linear velocity and its angular velocity is lower than Frozen angular velocity. At the same time both velocity values must be lower, otherwise, the simulation will not stop.

    There are also Frozen linear velocity and Frozen angular velocity thresholds set for the whole world. These global freezing thresholds are compared to the ones set for each body, and the highest value is chosen to freeze the body.

  2. Velocity values should stay lower than frozen velocities for the number of Frozen frames. This is done to ensure that the body has really terminated its motion.

When the body is frozen, its linear and angular velocity are set to 0. The simulation of the body starts again as another non-frozen object touches it or some force is applied to it.

Setting Body Parameters

The parameters of each body are determined by its type. To view or adjust these parameters via UnigineEditor perform the following steps:

  1. Select a node in the Scene Viewport or in the World Hierarchy window
  2. Go to the Physics tab in the Parameters window.
  3. Specify available body parameters.
Last update: 2018-04-26