This page has been translated automatically.
Setting Up Development Environment
High-Level Systems
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
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.


While a body simulates various types of physical behavior, a shape represents the volume that a rigid body occupies in space. A physically simulated object usually has one body and one or several collision shapes which allow objects to collide with each other. Objects with shapes also fall under gravity, bounce off static surfaces or slide along them. If a body has no shapes assigned, it will behave as a mere dummy body that can be jointed to other bodies, but does not collide and can be hung in the air.

Shapes approximate the physical space the object occupies as follows:

  • Simple primitives. They are very fast and memory efficient. Simple primitives should be used whenever possible.
    • Sphere (uses CCD)
    • Capsule (uses CCD)
    • Cylinder
    • Box
  • Collision shape composed of triangles. It is slower and more memory demanding.
    • Convex hull
    • A number of autogenerated convex hulls

Simple primitives make collision calculations much more simple. They also deliver accurate enough results with less performance cost. Convex hulls introduce simulation with higher precision do not provide continuous collision detection and therefore are unappropriate when objects move at high speed.

Shapes do not need to duplicate the mesh. Use simple primitives even if they are not precise. For plausible physics, such rough approximation suffices.
Keep the number of shapes as low as possible. Otherwise, heavy physics calculations will decrease the performance.

Shapes do not cannot be created in their own do not have position in world coordinates. They are assigned to bodies and are positioned relative to it.

See also

Adding a Shape

To add a shape, perform the following steps:

  • Assign a physical body to the mesh: a rigid body or a dummy body.
  • Go to the Shapestab. Choose an appropriate type of shape and clickAdd.

You can enable visualization of shapes by checking Tools panel -> Show tab -> Physics shapes option. (Visualizer should be enabled). It will show shapes when physical objects collide.


A sphere is the simplest and the fastest shape, because its only property is a radius. For spherical shapes continuous collision detection is calculated. Due to that, it will not pass through other physical objects even when moving at a high speed.
As a trick, you can use sphere shapes even for edgy objects. In this case all 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


A capsule is also a very fast collision primitive with continuous collision detection. Capsules are convenient for approximating not only elongated shapes (poles and such), but also humanoid characters, because it allows them to go up and down the stairs smoothly, without stumbling at each step, of course as long as the steps are not too high. It also ensures that a limb of the character 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


A cylinder can be used to approximate elongated shapes with flat ends. 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


A box is used for cubes or can be resized into any rectangular prism with arbitral length in each dimension. Box shapes are really universal when it comes to approximating volume of various objects: it is suitable for walls, doors, stairs, parts of mechanisms, car hull in a vehicle and many other things.

Box shapes

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

Size of the Box

Convex Hull

Convex hull is used for shapes that are more complex than simple primitives. Convex hulls are the slowest of all shapes. 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

Approximation error allows to reduce the number of vertices of the created shape. It allows to create a simpler, cruder but faster convex hull.

  • By the value of 0, the shape precisely duplicates the mesh; the whole volume of it is enclosed. It is strongly recommended to create shapes with such
  • 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
Last update: 2017-07-03
Build: ()