# Shapes


While a [body](../../../principles/physics/bodies/index.md) 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](../../../principles/physics/collision/index.md) 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](../../../principles/physics/bodies/dummy/index.md) that can be connected to other bodies using [joints](../../../principles/physics/joints/index.md), but does not collide and is immune to gravity.


> **Notice:** The maximum number of collision shapes for one body is limited to 32768.


Basic shape types are as follows:


- **Simple primitives**. They are very fast and memory efficient. Simple primitives should be used whenever possible.

  - *[Sphere](#sphere)* (uses [continuous collision detection](../../../principles/physics/collision/index.md#discrete_continuous))
  - *[Capsule](#capsule)* (uses [continuous collision detection](../../../principles/physics/collision/index.md#discrete_continuous))
  - *[Cylinder](#cylinder)*
  - *[Box](#box)*
- **Complex collision shapes** composed of triangles. These shapes are slower and more memory demanding.

  - [Convex hull](#convex)
  - A set of [autogenerated](#autogen) convex hulls


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 implementation:


- [*Shape*](../../../api/library/physics/class.shape_cpp.md) class
- [*ShapeSphere*](../../../api/library/physics/class.shapesphere_cpp.md) class
- [*ShapeCapsule*](../../../api/library/physics/class.shapecapsule_cpp.md) class
- [*ShapeCylinder*](../../../api/library/physics/class.shapecylinder_cpp.md) class
- [*ShapeBox*](../../../api/library/physics/class.shapebox_cpp.md) class
- [*ShapeConvex*](../../../api/library/physics/class.shapeconvex_cpp.md) class
- A fragment of [video tutorial on physics](https://youtu.be/w_GJrE-6HtI?t=351s) illustrating the concept of shape.


## Shape Parameters


Shapes are configured by a set of parameters, some of which are shape-dependent:


![Shape parameters](shape_parameters.png)


| **Edit Size** | Toggles the editing mode for the shape in the scene. When the button is pressed, the widget manipulator is available. Each dimension is color-coded in accordance with the axis color. To change the shape along the required axis, drag the corresponding color spot. After editing the shape, click the button once again to exit the editing mode. |
|---|---|
| **Type** | Type of the shape. It can be changed after creation, while the name will remain unchanged. |
| **Continuous** | A flag indicating if the continuous collision detection is enabled for the shape. > **Notice:** Continuous collision detection is available for sphere and capsule shapes only. |
| **Physics Intersection** | *[Physics Intersection](../../../principles/bit_masking/index.md#physics_intersection_mask)* bit mask of the shape. |
| **Collision** | Collision bit mask of the shape. This mask is used to specify collisions of the shape with other ones. |
| **Exclusion** | Exclusion bit mask of the shape. This mask is used to prevent collisions of the shape with other ones. |
| **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](../../../start/index.md#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](../../../start/index.md#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](../../../principles/physics/bodies/index.md). |
| **Rotation** | Rotation of the shape in the coordinates of the [body](../../../principles/physics/bodies/index.md). |
| **Radius** | Radius of the shape in units (for sphere and capsule shapes). |
| **Height** | Height of the cylinder and cylindrical part of the capsule shape. |
| **Size** | Length, width and height of the box shape. |


To organize the shapes, the following options are available:


![](organize_shapes.png)


| ![](add.png) | Adds a new shape. |
|---|---|
| ![](copy_clone.png) | Opens the drop-down menu that provides the options to clone the selected shape(s) or copy them and paste into another list of shapes. |
| ![](move.png) | A pair of buttons to move the shape up or down in the list. |
| ![](delete.png) | Deletes the selected shape(s). |


To disable a shape, uncheck the checkbox:


![](disabled_shape.png)


Our video tutorial on physics contains an overview of the [shape parameters](https://youtu.be/w_GJrE-6HtI?t=435s) and clarification on how to use the [*Exclusion* and *Collision masks*](https://youtu.be/w_GJrE-6HtI?t=470s).


## Adding a Shape


To add a shape via [UnigineEditor](../../../editor2/index.md), perform the following steps:


- Open the *[*World Hierarchy*](../../../editor2/interface/index.md#world_hierarchy)* window
- Select an [object](../../../objects/objects/index.md) you want to assign a physical shape to.
- Go to the ***Physics*** tab in the *[*Parameters*](../../../editor2/interface/index.md#parameters)* window and assign a physical [body](../../../principles/physics/bodies/index.md) to the selected object: a [rigid body](../../../principles/physics/bodies/rigid/index.md), [ragdoll body](../../../principles/physics/bodies/ragdoll/index.md) or a [dummy body](../../../principles/physics/bodies/dummy/index.md). ![Adding a body](../bodies/add_body.jpg)
- In the ***Shapes*** section below click ![](add_sign.png) and choose an appropriate type of shape. ![Adding a shape](add_shape.jpg)
- Set necessary [shape parameters](#shape_params).


You can enable visualization of shapes by checking *[Helpers](../../../editor2/using_visual_helpers/index.md)* 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](sphere.jpg)


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


![Radius of the Sphere](sphere_dimensions.png)


## 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](capsule.jpg)


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


![Height and Radius of the Capsule](capsule_dimensions.png)


## 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](cylinder.jpg)


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


![Height and Radius of the Cylinder](cylinder_dimensions.png)


## 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](box.jpg)


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


![Size of the Box](box_dimensions.png)


## 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](convex.jpg)


To generate a convex hull specify an approximation error value:


![Convex shape parameters](shape_convex_param.jpg)


The ***Approximation error*** parameter 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](convex_approx0.jpg) *Approximation error = 0* | � | ![Higher value of Approximation Error](convex_approx1.jpg) *Approximation error = 0.1* |
|---|---|---|


## Autogenerated


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


![](concave.jpg)

*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:


![Autogeneration parameters](shape_autogen.jpg)


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