This page has been translated automatically.
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
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
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.

Shapes

While a body simulates various types of physical behavior, a shape represents the volume of space occupied by a physical body. A physically simulated object usually has one body and one or several shapes which allow objects to collide with each other (therefore, shapes are often referred as collision shapes). Objects with shapes also fall under gravity, bounce off static surfaces or slide along them. A body without a single shape assigned behaves as a dummy body that can be connected to other bodies using joints, but does not collide and is immune to gravity.

Basic shape types are as follows:

Simple primitives make collision calculations easier while keeping performance high and accuracy acceptable. Convex hulls provide higher precision, however, continuous collision detection is not available for this type of shape. Therefore, convex hulls should not be used for fast-moving objects.

Notice

A shape doesn't have to duplicate the mesh it approximates. It is recommended to use simple primitives. Even though they are not precise, in the majority of cases they provide acceptable results.

The number of shapes should be kept as low as possible. Otherwise, heavy physics calculations will decrease the performance.

A shape cannot be created without a body and does not have its own position in world coordinates. It is always assigned to a body and positioned relative to it.

See also

Programming realization:

Shape Parameters

All shapes regardless of their type have the following common parameters

Shape parameters

Enabled A flag indicating if a shape is enabled.
Mass Mass of the shape. Changing the mass influences the density, which is calculated by dividing the mass by shape volume. In case if there are several shapes assigned to a body (e.g. a set of convex hulls)
Density Density of the shape. Changing the density influences the mass, which is calculated by multiplying shape volume by density.
Friction Coefficient of friction of the shape. Defines how rough the shape's surface is. The higher the value, the less tendency the shape has to slide.
Notice
In case if an object contains a surface and a shape, both with specified friction parameter, only the shape's parameter will be used.
Restitution Coefficient of restitution of the shape. Defines how bouncy the shape is when colliding.
  • The minimum value of 0 indicates inelastic collisions (a piece of soft clay hitting the floor)
  • The maximum value of 1 represents highly elastic collisions (a rubber ball bouncing off a wall)
Notice
In case if an object contains a surface and a shape, both with specified restitution parameter, only the shape's parameter will be used.
Position Position of the shape in the coordinates of the body.
Rotation Rotation of the shape in the coordinates of the body.
Intersection mask Intersection bit mask of the shape.
Collision mask Collision bit mask of the shape. This mask is used to specify collisions of the shape with other ones.
Exclusion mask Exclusion bit mask of the shape. This mask is used to prevent collisions of the shape with other ones.

Adding a Shape

To add a shape via UnigineEditor, perform the following steps:

You can enable visualization of shapes by checking Helpers panel -> Physics item -> Shapes option (Visualizer should be enabled).

Sphere

A sphere is the simplest and the fastest shape, as it has only one parameter: a radius. Continuous collision detection is available for spherical shapes. Therefore, passing through other objects even when moving at a high speed is avoided.

Using the spherical shape for any arbitrary mesh ensures that its collisions will always be detected.

Sphere shapes

For a shape to fit your object, you can adjust the Radius of the sphere.

Radius of the Sphere

Capsule

A capsule is also a very fast collision shape with continuous collision detection available. Capsules are convenient for approximation of elongated objects (pillars, etc.) as well as humanoid characters, because it allows them to go up and down the stairs smoothly, without stumbling at each step (if the steps are not too high). It also ensures that character's limb will not get stuck somewhere unexpectedly.

Capsule shapes

For a shape to fit your object, you can adjust the Radius and the Height of the capsule.

Height and Radius of the Capsule

Cylinder

A cylinder can be used to approximate elongated shapes with flat ends (e.g. a shafts, pylons, etc.). It is similar to a box shape.

Cylinder shapes

For a shape to fit your object, you can adjust the Radius and the Height of the cylinder.

Height and Radius of the Cylinder

Box

A box is a cuboid shape which can be used for approximation of volume of various objects. it is suitable for walls, doors, stairs, parts of mechanisms, car bodies, and many other things. The length of a box shape in each dimension can be chosen arbitrarily.

Box shapes

For a shape to fit your object, you can adjust the size of the box along each axis: Size X, Size Y, and Size Y.

Size of the Box

Convex Hull

Convex hull is the slowest of all shapes and is used for objects having complex geometry. The created shape will always be convex, that is, holes and cavities of the mesh are ignored when generating a convex hull. Instead, they are included into the shape volume. Convex shape is the smallest shape that can enclose vertices of the approximated mesh.

Convex shapes

To generate a convex hull specify an approximation error value:

Convex shape

Approximation error makes it possible to reduce the number of vertices of the created shape. Simple and rough convex hulls with small number of vertices are processed faster, therefore, it is recommended to keep the number of vertices as low as possible.

  • By the value of 0, the shape precisely duplicates the mesh; the whole volume of it is enclosed.
  • The higher the value, the less vertices there are in the created shape, but the more details are skipped.

Zero Approximation Error
Approximation error = 0
  Higher value of Approximation Error
Approximation error = 0.1

Autogenerated

To approximate a complex concave object and exlude cavities from its volume, use a set of autogenerated convex hulls.

Autogenerated set of convex hulls

A complex concave object approximated by a single convex hull (left) and an autogenerated set of convex hulls (right)

To add an autogenerated set of shapes specify the following parameters:

Convex shapes

Recursion depth determines the degree of mesh decomposition. If 0 or a negative value is provided, only one shape will be created. The higher the value, the more convex shapes are to be generated

Approximation error makes it possible to reduce the number of vertices of generated shapes. Simple and rough convex hulls with small number of vertices are processed faster, therefore, it is recommended to keep the number of vertices as low as possible.

  • By the value of 0, the shape precisely duplicates the mesh; the whole volume of it is enclosed.
  • The higher the value, the less vertices there are in the created shape, but the more details are skipped.

Merging threshold determines the volume threshold for merging convex shapes after decomposition and can be used to reduce the number of generated shapes: the higher the value, the less convex shapes are to be generated.

Last update: 2017-12-21
Build: ()