This version of documentation is OUTDATED! Please switch to the latest one.

# 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. They are very fast and memory efficient. Simple primitives should be used whenever possible.
• Complex collision shapes composed of triangles. These shapes are slower and more memory demanding.

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.

Programming realization:

## Shape Parameters

All shapes regardless of their type have the following common 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. NoticeIn 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) NoticeIn 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.

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.

## 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.

For a shape to fit your object, you can adjust the Radius and the Height 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.

For a shape to fit your object, you can adjust the Radius and the Height 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.

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.

## 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.

To generate a convex hull specify an approximation error value:

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.

 Approximation error = 0 Approximation error = 0.1

## Autogenerated

To approximate a complex concave object and exlude cavities from its volume, use a set of autogenerated 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:

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