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.

Physical Bodies

To assign an object some physical properties so that it could participate in interactions between objects or external physical forces, it should have a body. Each body enables to simulate different types of objects:

Rigid Bodies 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 and has a particular shape. Such bodies cannot be deformed, i.e their geometrical shape does not change no matter what happens with this body. Rigid body physics is applied to the following bodies and their shapes:

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

Rag dolls and rigid bodies moving according to rigid bodies dynamics

Basic Concepts

A state of a rigid body in any moment is specified with its position, orientation in space (with respect to some reference point — center of mass) and velocity. 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. Setting a body's linear velocity will immediately get it moving in a specified direction.

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 with an angular velocity. The final velocity of the body consists of these two components, linear and angular.

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 acted up by an external force or an impulse. Force equals mass of the body multiplied by acceleration. By causing the body to undergo an acceleration (i.e. to change its velocity over time), force controls its velocity and position indirectly. Because of this, forces do not provide an immediate response. Instead, all the forces acting on a body 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.

Unlike the forces, impulse, which is the integral of force over time, immediately changes body velocity as the physics is updated. Impulse, just like force, is equal to the change in momentum. 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. The relation is same as for linear momentum, except that instead of the mass (a scalar value), an inertia tensor is used (a matrix). The inertia tensor describes the distribution of the mass over the body relative to the body's center of mass. Usually, the inertia tensor is automatically calculated for the given shapes of the body.

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 increasing or decreasing rotational speed. Similar to forces, torque values are accumulated to be set as a resulting value during update of physics.

Forces and impulses can also be applied not to the center of mass, but to a different point of the body and cause the body to rotate. 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 exerted on the body increases force. As for impulses, they will directly influence angular velocity.

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

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

Impulse (vec3)
Torque (vec3)

Other adjustable parameters are as follows:

Mass

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.

Density

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.

Buoyant boxes of different mass and density

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 dumping, 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. The body won't be able to gain faster speed or rotation, because velocity that exceeds the limit is clipped. For example, maximum linear velocity parameter can help to avoid tunneling (penetration) effect.

There exists also a global maximum linear and angular velocities thresholds. The global maximum is compared with the maximum set for the body, and the lowest value is chosen to clip the actual velocity, if it exceeds the threshold.

Friction

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.
However, the resulting calculated friction naturally depends on the objects' masses and gravity, as well as angle between contacting surfaces. For example, if the body slides down the tilted surface such as an inclined plane, the friction is less, because less is the force of gravity that is perpendicular to the face of the surface.

Friction is calculated on contact between physical bodies. Besides that, if the surface is assigned a surface_base property, which has a corresponding parameter, it also contributes to calculations.

Restitution

Coefficient of restitution defines how bouncy the object is by contacting with another object. The simulated restitution, like friction, considers the total restitution of both objects being in contact.

• The maximum value of 1 models elastic collision, when the total kinetic energy of the two objects after the encounter is equal to their total kinetic energy before the encounter. That means objects bounce off according to the impulse they get by contact.
• The minimum value of 0 models inelastic collision, when the impulse is decreased down to zero. The objects practically stop after collision loosing their kinetic energy and do not bounce at all.

Again, just like friction, restitution is calculated by the contact between physical bodies. Also if the surface is assigned a surface_base property, which has a corresponding parameter, it also contributes to calculations.

Frozen Linear Velocity and Frozen Angular Velocity

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.

 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. It is automatically starts simulating once again as another non-frozen object touches it or some force is applied to it.

Collision mask allows to filter particular shapes and bodies for physical interaction: only those will collide, that have a matching collision mask. If the masks do not match, shapes and bodies will simply ignore each other by going through.

Collision bit masking is a really flexible mechanism. After double clicking on the mask field, it is possible to specify a 32 bit mask for each shape or body. Each of 32 bits can either be turned on (1) or off (0) when clicking on the bit number. The resulting mask is displayed in the field as hexadecimal characters. After that, two masks are compared bitwise using binary operator and. If at least one pair of corresponding bits matches, objects will collide.

For example, we've got four bodies that need to collide in the following way:

 Body A Body B Body C Body D Body A Body B Body C Body D

For that, each colliding body should share 1 in the appropriate bit position: