Built-In Physics Module

The most commonly used type of body that enables simulation of physical bodies according to rigid body dynamics. Rigid bodies cannot be deformed — their geometry does not change no matter what happens.

This type of body enables inverse kinematics and procedural animation for bone-animated characters. Essentially, this is a set of Rigid bodies, representing the character's bones connected by joints. These joints restrict the movement of the bones relative to each other, providing a realistic look.

To assign the Ragdoll body to the object, you should create a physical Ragdoll. You can automatically generate it based on the specified parameters or create it manually by preparing a Rigid body for each bone and then saving the bones hierarchy to a *.node file.

For proper automatic Ragdoll generation, the mesh should be in the Reference Pose (T-pose for human-like characters).

It enables real-time persuasive destruction of objects. A Fracture body is procedurally fractured into pieces when it collides with another body. Moreover, you can keep breaking these pieces until achieving the desired level of destruction.

The Fracture body (along with all the pieces it fractures into) is, in fact, a Rigid body that moves according to rigid body dynamics. When the body fractures, its mass is distributed among the pieces.

There are three patterns of fracturing: slicing, cracking, and shattering. You should choose the appropriate one depending on the mechanical properties of the material used to create the object.

The fracture patterns are specified in the code.

It allows for the physical simulation of ropes, cables, and wires that can be torn. You can pin the ropes to the Rigid, Ragdoll, and Dummy bodies.

To attach a rope to another body, use the Particles joint.

It enables physical simulation of different types of textiles that can be torn. You can pin a Cloth body to the Rigid, Ragdoll, and Dummy bodies.

Polygon triangulation of the mesh, for which the Cloth body is generated, should be as illustrated! Otherwise, it may not stretch properly and evenly in all directions.

To pin a cloth to a body so it would hang like a cape or a curtain, use the Particles joint.

It enables the physical simulation of liquids of different densities and viscosities. It also allows creation of the buoyancy effect and wave dynamics.

A mesh to which the Water body is assigned should meet several requirements:

• The mesh should be flat and have a uniform grid.
• The mesh should be oriented strictly along the axes.
• The mesh should have the UV map.

It is a static body that does not move and has no physical properties. It can be used as a prop when connecting other bodies using joints.

For example, by using a Dummy body assigned to a Dummy object, you can fix a physical cloth (a Cloth body) so it can hang without any visible attachments. If the Dummy body does not have any Collision shape assigned, it will not fall or interact with other physical bodies.

It is also a type of body without physical properties: it represents a spline along which an arbitrary rigid body can move. It can be used, for example, to create a physically simulated train moving along a rail track.

To connect a Rigid body to a Path body, use a Path joint.

A sphere is the simplest and the fastest shape, as it has only one parameter — a radius. For this shape type, continuous collision detection is available. So, you can be sure it will not go through other objects, even if it moves at high speed (we will learn about that later).

Using the spherical shape for any arbitrary mesh ensures collision detection.

To make the shape fit your object, you can adjust the sphere Radius:

A capsule is another fast collision shape with continuous collision detection available. You can use capsule shapes to approximate elongated objects like pillars or even human-like characters. These shapes help the characters go up and down the stairs smoothly, without stumbling at each step, as long as the steps are not too high. Capsule shapes also ensure that the character's arms or legs do not get stuck unexpectedly.

To make the shape fit your object, you can adjust the capsule Radius and Height:

A cylinder can be used to approximate elongated shapes with flat ends (for example, shafts, or pylons).

To make the shape fit your object, you can adjust the cylinder Radius and Height:

A box is a cuboid shape that can approximate the volume of various objects: walls, doors, stairs, parts of mechanisms, car bodies, and many other things. You can choose the size of a box shape in each dimension arbitrarily.

To make the shape fit your object, you can adjust the box size (Size X, Size Y, Size Z):

A convex hull is the slowest of all shapes. Usually, it is used for objects with complex geometry. This shape is the smallest one that can enclose vertices of the approximated mesh. At that, it includes holes and cavities of the mesh in the shape volume.

To generate a convex hull, specify the Approximation Error value that allows reducing the number of vertices of the created shape. Note that simple and rough convex hulls with a small number of vertices are processed faster, so we recommend keeping the number of vertices as low as possible.

The higher the error value, the fewer vertices in the generated shape, but the more mesh details are skipped.

Approximation error = 0

Approximation error = 0.1

An autogenerated shape is a set of convex hulls that can approximate a complex concave object and exclude cavities from its volume.

In the picture below, you can see a complex concave object. On the left, it's approximated with a single convex hull. And on the right — with an autogenerated set of convex hulls.

When generating this type of shape, you should specify the following beside the Approximation Error value:

• Recursion Depth that sets the degree of mesh decomposition.
• Merging Threshold that determines the volume threshold for merging convex shapes after decomposition.

The values you specify affect how many shapes are generated and how well they fit the object.

A fixed joint connects two bodies in a manner that strictly preserves their positions relative to each other. An example of such a connection in real life is welding or gluing two objects together.

A hinge joint allows the connected bodies to rotate along the joint's axis at the anchor point. The joint has an angular motor attached. Hinge joints are used for doors and the arms and legs of characters.

A ball joint provides a point around which the connected objects can rotate. It is similar to the hip joint. You can limit rotation by using the corresponding parameters.

These joints are similar — they both allow movement along the joint axis, which can be used for piston simulation. The cylindrical joint has an additional degree of freedom — rotation around the joint axis.

Prismatic Joint	Cylindrical Joint

Hinge, Ball, Cylindrical, and Prismatic joints are used to create connections in mechanisms with the specific restrictions of the movement of bodies relative to each other. In addition to these main types of joints, UNIGINE also provides auxiliary ones.

These joints are intended to simulate vehicles and the interaction of vehicle wheels with the ground.

They both simulate wheel suspension and have angular motors attached. The main difference is that the suspension joint operates with the physical shape of the wheel, which serves for accurate collision detection. While the wheel joint handles a virtual wheel and checks for intersections with the ground via ray-casting. This approach is faster and provides an acceptable result on smooth terrain. In case of a stepped ground surface, it is better to use the suspension joint.

A Particles joint allows pinning a Cloth or Rope body to a Rigid, Ragdoll, or Dummy body. For example, you can use it to hang a flag or attach a cloth to a character.

A Path joint is used to attach a Rigid body to a Path body and to make the Rigid body move along this path.

Physical Wind is a cuboid-shaped object simulating wind blowing within its volume.

The wind only affects objects placed inside the Physical Wind box and having physical bodies assigned.

The wind differently affects objects with different physical properties. So, besides changing the Physical Wind parameters, you should adjust the parameters of the physical body.

For example, if you place an object with the Cloth body inside the Physical Wind volume, the way it "waves in the wind" will vary depending on the Cloth body mass, rigidity, and other parameters.

When you set up the wind, you can change the size of the volume in which the wind blows, specify the wind velocity, attenuation threshold, and damping of the linear and angular velocities of the objects when they get inside the wind volume.

You can also choose which physical bodies are affected by the wind. For example, you can make only one flag flutter in the wind while the others stay still. For this purpose, there is the Physical mask — it must match the Physical mask of the physical body affected by the wind.

The Physical Force and Physical Noise are objects for creating force fields.

The Physical Force is a spherical object with a force that is applied to its center and attenuates within a specified radius. Objects within the sphere can pull up to or away from the center and rotate around it.

You can control the attenuation of the force affecting the object that moves away from the force center. In addition, you can adjust the intensity of the attraction and rotation forces that define the speed and direction of rotation.

The Physical Noise is a cuboid-shaped area that adds a distribution flow based on a volumetric noise texture. This effect simulates a force field that affects particles and physical bodies.

The direction of the force affecting particles and physical bodies within the Physical Noise volume is stored in the Noise texture — a 3D texture, where each texel stores the force direction.

To be sure that the force at the current point affects the physical body entering the Physical Noise volume according to the Noise texture, you need to provide the texture generation and sampling parameters for the Noise texture, along with the Force multiplier.

The Physical Water is a cuboid-shaped object that allows the simulation of water interaction effects within its volume.

This effect is helpful for the simulation of physical interactions of bodies with the Water Global, as this water object doesn't support the Water body because of large-scale computations. You can use the Physical Water to simulate the floating physical bodies within a certain area.

To add the Physical Water to your scene, select Create → Water → Physical Water in the Menu Bar of UnigineEditor.

The bodies with different physical properties act differently in the Physical Water. So, besides changing the Physical Water parameters, you should adjust the parameters of the physical body as well.

You can also create additional water effects with Physical Water — for example, foam on the water surface or water splashes — by generating particles in the contacts between the Rigid bodies and Physical Water. Add your Particles object as a child to Physical Water to implement the required effect.

The Physical Trigger is an effect that fires callbacks when physical objects get inside or outside its volume.

The trigger can be of the box, sphere, capsule, or cylinder shape.

To add the Physical Trigger to your scene, select Create → Logic → Physical Trigger in the Menu Bar of UnigineEditor.

To be detected by the trigger, a physical object must have both:

• A physical body with the Physical mask that matches the Physical mask of the trigger.
• A shape with the Collision mask that matches the Collision mask of the trigger.

You can obtain the physical bodies participating in the contact with the Physical Trigger and their collision shapes via API. In addition, you can get values such as the depth of penetration of the body into the trigger, the coordinates of the contact point and the normal to it.

To define actions to be performed when the body enters and leaves the trigger, do the following:

1. In UnigineEditor, create a C# component and open it.
2. Implement handler functions for the Enter and Leave events receiving a Body as the first argument.
3. In the Init() function, get the instance of the Physical Trigger and subscribe for the Enter or Leave event via the Connect method specifying the corresponding implemented handler function.
4. Assign the implemented component to the Physical Trigger node in UngineEditor.

// event handler functions
void trigger_enter(Body body){...}
void trigger_leave(Body body){...}

PhysicalTrigger physicalTrigger;
EventConnections trigger_event_connections = new EventConnections();

private void Init()
{
	// cast the node to the PhysicalTrigger type
	physicalTrigger = node as PhysicalTrigger;

	if (physicalTrigger != null)
	{
	   // subscribe for the Enter event with a function to be called when the body enters the trigger volume
	   physicalTrigger.EventEnter.Connect(trigger_event_connections, trigger_enter);

	   // subscribe for the Leave event with a function to be called when the body leaves the trigger volume
	   physicalTrigger.EventLeave.Connect(trigger_event_connections, trigger_leave);
	}
}

private void ShutDown()
{
	// remove the subscriptions for Enter and Leave events
	trigger_event_connections.DisconnectAll();
}