# Collision Shapes

Like graphical meshes, collision shapes allow one to collide a rich variety of different objects that one might encounter in the real world. Collision shapes don't have a world position, they are attached to collision objects or rigid bodies.

Many rigid bodies can each have the same collision shape, which helps to save memory. Unlike graphical meshes, collision shapes are not always composed of triangles, but they can be represented as a primitive such as box, cylinder. This page walks us through the various Bullet collision shapes and gives some advice about when to use each kind.

• Using convex collision shapes such as convex hulls and primitives such as a sphere, box and cylinder makes the collision algorithms much more simple and efficient.
• Collision shapes for dynamic rigid bodies should define a finite volume.
• Collision shapes with a finite volume can calculate an inertia tensor given a mass, which is needed for dynamic rigid bodies.
• Some collision shapes, such as a plane shape or static triangle mesh don't have a finite volume or an inertia tensor, so they should only be used with static rigid bodies.

Typically, one will define a large amount of static environment with btBvhTriangleMeshShape and maybe also btHeightfieldTerrainShape, although any of the other shapes can be used as well.

Dynamic rigid bodies will ideally be primitives or btConvexHull, but can also be compositions of such shapes and thus dynamic concave rigid bodies, e.g. aeroplanes and chairs are possible.

## Primitives

Primitives have specialist collision algorithms that are very fast. One should always attempt to use a primitive if it is the right shape. Another advantage of using a primitive is that in the case of rounded shapes like spheres and cylinders, objects roll properly without the bumpy behaviour that a polyhedral approximation would have.

btSphereShape
A very fast and simple shape.
Full documentation
btBoxShape
A cuboid shape, the length in each dimension can be chosen arbitrarily.
Full documentation
btCylinderShape
A cylinder much like the box shape.
Full documentation
btCapsuleShape
An elongated sphere, useful for modelling humanoid characters as it abstracts from details like limbs and gait, but can still skip up stairs so long as the steps are not too high.
Full documentation
btConeShape
A cone pointing along the given axis with the point at (0,0,0)
Full documentation
btMultiSphereShape
A convex shape defined by spheres. Useful for representing bevelled boxes or other shapes without sharp corners. Also since the spheres can be independently scaled in each of the 3 dimensions, a btMultiSphereShape containing just one sphere can be useful to create ellipsoids (squashed spheres), which is not possible with btSphereShape.
Full documentation

## Meshes

btConvexHullShape
This is the fastest kind of arbitrary shape. It is defined by a cloud of vertices but the shape formed is the smallest convex shape that encloses the vertices. For making a convex dynamic shape like a TV, this is ideal. Make sure to reduce the number of vertices below say 100. Reducing the number of vertices can be done automatically using the btShapeHull vertex reduction utility.
Full documentation
btConvexTriangleMeshShape
This is similar to the above but is specified using a conventional mesh composed of vertices and indices. A btConvexHull is more efficient.
Full documentation
btBvhTriangleMeshShape
A static mesh that is comprised of arbitrary triangles. These can have many triangles and still be fast because of the internal hierarchal implementation. Don't be afraid to batch static scenery geometry together to reduce the work in the Broadphase. Building the initial tree can take some time. If this becomes a problem the tree can be serialised to disk in advance and loaded quickly with btOptimizedBvh::deSerializeInPlace, see Demos/ConcaveDemo/ConcavePhysicsDemo.cpp
Full documentation
btHeightfieldTerrainShape
A static mesh that is optimised for and described by the surface of a height map.
Full documentation
btStaticPlaneShape
A static plane that is solid to infinity on one side. Several of these can be used to confine a convex space in a manner that completely prevents tunneling to the outside. The plane itself is specified with a normal and distance as is standard in mathematics.
Full documentation

## Compound

btCompoundShape
If a concave dynamic shape is required, then it may be specified by combining convex shapes (usually primitives and btConvexHull) in various configurations.
Full documentation

E.g. using just boxes, one can create a chair, and using spheres and cylinders, one can approximate a bowling pin with reasonable precision. Do not create rigid bodies inside each other if their shapes are compound, since a shape can be jammed between the two components of another shape. Rather than springing apart, the shapes will therefore be jammed inside each other, and the various components will generate lots of collision pairs, slowing everything down.

For those that want to specify arbitrary triangle geometry for dynamic collision shapes, The ConvexDecomposition demo shows how to procedurally break a concave shape up into a composition of convex shapes using some utility code in the Extras folder.

## Misc

btEmptyShape
A collision shape without actual collision detection shape, so most users should ignore this class.
Full documentation

## Todo

• gimpact, I've not used it and do not know its advantages
• softbody
• btMinkowskiSumShape, what's the point?
• btEmptyShape, just a placeholder?