Bullet Physic Engine SDK

Bullet 2.80 Physics SDK Manual
Also check out the forums and wiki at bulletphysics.org
© 2012 Erwin Coumans
All Rights Reserved.

http://bulletphysics.org
©Erwin Coumans Bullet 2.80 Physics SDK Manual
- 2 -
Table of Contents
BULLET 2.80 PHYSICS SDK MANUAL ....................................................................................................................... 1
1 Introduction .................................................................................................................................................................. 5
Description of the library ................................................................................................................................................................ 5
Main Features ................................................................................................................................................................................ 5
Contact and Support ...................................................................................................................................................................... 5
2 What’s New .................................................................................................................................................................. 6
New in Bullet 2.80 .......................................................................................................................................................................... 6
New in Bullet 2.79 .......................................................................................................................................................................... 6
New in Bullet 2.78 .......................................................................................................................................................................... 6
New in Bullet 2.76 .......................................................................................................................................................................... 7
Maya Dynamica Plugin ................................................................................................................................................................... 7
3 Quickstart...................................................................................................................................................................... 8
Download ....................................................................................................................................................................................... 8
Building using Visual Studio ............................................................................................................................................................ 8
Building using CMake ..................................................................................................................................................................... 8
Building using autotools/automake ............................................................................................................................................... 8
Testing demos ................................................................................................................................................................................ 9
Integrating Bullet physics in your application .............................................................................................................................. 10
Integrate only the Collision Detection Library .............................................................................................................................. 10
Use snippets only, like the GJK Closest Point calculation. ............................................................................................................ 10
4 Library Overview ......................................................................................................................................................... 11
Introduction.................................................................................................................................................................................. 11
Software Design ........................................................................................................................................................................... 11
Rigid Body Physics Pipeline........................................................................................................................................................... 12
Integration overview .................................................................................................................................................................... 12
Basic Data Types and Math Library .............................................................................................................................................. 14
Memory Management, Alignment, Containers ............................................................................................................................ 14
Timing and Performance Profiling ................................................................................................................................................ 15
Debug Drawing ............................................................................................................................................................................. 16
5 Bullet Collision Detection ............................................................................................................................................ 17
Collision Detection ....................................................................................................................................................................... 17
Collision Shapes ............................................................................................................................................................................ 18
Convex Primitives ......................................................................................................................................................................... 18
Compound Shapes ........................................................................................................................................................................ 19
Convex Hull Shapes ...................................................................................................................................................................... 19
Concave Triangle Meshes ............................................................................................................................................................. 19
Convex Decomposition ................................................................................................................................................................. 19
Height field ................................................................................................................................................................................... 19
btStaticPlaneShape ....................................................................................................................................................................... 20
Scaling of Collision Shapes ............................................................................................................................................................ 20
Collision Margin ............................................................................................................................................................................ 20
Collision Matrix ............................................................................................................................................................................. 21
Registering custom collision shapes and algorithms .................................................................................................................... 21
6 Collision Filtering (selective collisions) ........................................................................................................................ 22
Filtering collisions using masks ..................................................................................................................................................... 22
Filtering Collisions Using a Broadphase Filter Callback ................................................................................................................. 22
Filtering Collisions Using a Custom NearCallback ......................................................................................................................... 23
Deriving your own class from btCollisionDispatcher .................................................................................................................... 23
7 Rigid Body Dynamics ................................................................................................................................................... 24
Introduction.................................................................................................................................................................................. 24
Static, Dynamic and Kinematic Rigid Bodies ................................................................................................................................. 24
Center of mass World Transform ................................................................................................................................................. 25

- 3 -
What's a MotionState? ................................................................................................................................................................. 25
Interpolation................................................................................................................................................................................. 25
So how do I use one? .................................................................................................................................................................... 26
DefaultMotionState ........................................................................................................................................................... 26
Kinematic Bodies .......................................................................................................................................................................... 26
Simulation frames and interpolation frames ................................................................................................................................ 27
8 Constraints .................................................................................................................................................................. 28
Point to Point Constraint .............................................................................................................................................................. 28
Hinge Constraint ........................................................................................................................................................................... 28
Slider Constraint ........................................................................................................................................................................... 29
Cone Twist Constraint .................................................................................................................................................................. 29
Generic 6 Dof Constraint .............................................................................................................................................................. 29
9 Actions: Vehicles & Character Controller .................................................................................................................... 31
Action Interface ............................................................................................................................................................................ 31
Raycast Vehicle ............................................................................................................................................................................. 31
Character Controller ..................................................................................................................................................................... 31
10 Soft Body Dynamics ................................................................................................................................................... 32
Introduction.................................................................................................................................................................................. 32
Construction from a triangle mesh ............................................................................................................................................... 32
Collision clusters ........................................................................................................................................................................... 32
Applying forces to a Soft body ...................................................................................................................................................... 33
Soft body constraints.................................................................................................................................................................... 33
11 Bullet Demo Description ............................................................................................................................................ 34
AllBulletDemos ............................................................................................................................................................................. 34
CCD Physics Demo ........................................................................................................................................................................ 34
BSP Demo ..................................................................................................................................................................................... 34
Vehicle Demo ............................................................................................................................................................................... 34
Fork Lift Demo .............................................................................................................................................................................. 34
12 Advanced Low Level Technical Demos ...................................................................................................................... 35
Collision Interfacing Demo ........................................................................................................................................................... 35
Collision Demo.............................................................................................................................................................................. 35
User Collision Algorithm ............................................................................................................................................................... 35
Gjk Convex Cast / Sweep Demo.................................................................................................................................................... 35
Continuous Convex Collision ........................................................................................................................................................ 35
Raytracer Demo ............................................................................................................................................................................ 35
Simplex Demo............................................................................................................................................................................... 36
13 Authoring Tools and Serialization ............................................................................................................................. 37
Dynamica Maya Plugin ................................................................................................................................................................. 37
Blender ......................................................................................................................................................................................... 37
Cinema 4D, Lightwave CORE, Houdini .......................................................................................................................................... 37
Serialization and the Bullet .bullet binary format......................................................................................................................... 38
COLLADA Physics format and viewer............................................................................................................................................ 38
14 General Tips .............................................................................................................................................................. 39
Avoid very small and very large collision shapes .......................................................................................................................... 39
Avoid large mass ratios (differences) ........................................................................................................................................... 39
Combine multiple static triangle meshes into one ....................................................................................................................... 39
Use the default internal fixed timestep ........................................................................................................................................ 39
For ragdolls use btConeTwistConstraint ....................................................................................................................................... 39
Don’t set the collision margin to zero .......................................................................................................................................... 40
Use less then 100 vertices in a convex mesh ................................................................................................................................ 40
Avoid huge or degenerate triangles in a triangle mesh ................................................................................................................ 40
The profiling feature btQuickProf bypasses the memory allocator .............................................................................................. 40
Per triangle friction and restitution value .................................................................................................................................... 41
Custom Constraint Solver ............................................................................................................................................................. 41
Custom Friction Model ................................................................................................................................................................. 41
15 Parallelism: OpenCL, Compute, SPU, multi thread .................................................................................................... 42
OpenCL and Direct Compute cloth simulation ............................................................................................................................. 42
Cell SPU / SPURS optimized version ............................................................................................................................................. 42

- 4 -
Unified multi threading ................................................................................................................................................................ 42
Win32 Threads, pthreads, sequential thread support ................................................................................................................. 42
16 Further documentation and references .................................................................................................................... 43
Online resources ........................................................................................................................................................................... 43
Authoring Tools ............................................................................................................................................................................ 43
Books ............................................................................................................................................................................................ 43
Contributions and people ............................................................................................................................................................. 44
Create Bullet Visual Studio projectfiles using CMake .................................................................................................... 45

- 5 -
1 Introduction
Description of the library
Bullet Physics is a professional open source collision detection, rigid body and soft dynamics library. The library is free for commercial use under the ZLib license.
Main Features
 Open source C++ code under Zlib license and free for any commercial use on all platforms including PLAYSTATION 3, XBox 360, Wii, PC, Linux, Mac OSX, Android and iPhone
 Discrete and continuous collision detection including ray and convex sweep test. Collision shapes include concave and convex meshes all basic primitives
 Fast and stable rigid body dynamics constraint solver, vehicle dynamics, character controller and slider, hinge, generic 6DOF and cone twist constraint for ragdolls
 Soft Body dynamics for cloth, rope and deformable volumes with two-way interaction with rigid bodies, including constraint support
 Maya Dynamica plugin, Blender integration, COLLADA physics import/export support
Contact and Support
 Public forum for support and feedback is available at http://bulletphysics.org
 PLAYSTATION 3 licensed developers can download an optimized version for Cell SPU through Sony PS3 Devnet from https://ps3.scedev.net/projects/spubullet

- 6 -
2 What’s New
New in Bullet 2.80
 GPU rigid body pipeline running 100% on the using OpenCL. This is a preview, Bullet 3.x will use this as a GPU backend. See Bullet/Extras/RigidBodyGpuPipeline. Requires very recent GPU and drivers (Radeon 5870 or NVIDIA 470 with 290.53 newer)
 Physics Effects rigid body pipeline, with Android/NEON optimizations. This is a preview, Bullet 3.x will use this as handheld backend. Sony provides a VITA optimized version. See Bullet/Extras/PhysicsEffects .
 Option to override the number of constraint solver iterations for individual constraints. See Bullet/Demos/VoronoiFractureDemo, setOverrideNumSolverIterations
 The open source Dynamica Bullet Maya plugin is now deterministic when restarting the simulation. Also it has preliminary cloth and convex decomposition (HACD) integration. See http://dynamica.googlecode.com for source and precompiled downloads.
 Check the issue tracker at http://bullet.googlecode.com for other improvements.
New in Bullet 2.79
 Bullet 2.79 is mainly a bugfix release. Speculative contacts are disabled, it introduced too many artifacts.
 Hierarchical Approximate Convex Decomposition library, thanks to Khaled Mamou. It can create a convex decomposition from 3D concave triangle mesh. replaces John Ratcliff’s ConvexDecomposition library. See Demos/ConvexDecomposition
 Premake build system to autogenerate Windows Visual Studio project files that can be redistributed. CMake cannot do this properly. We still keep autotools and support up-to-date. See Bullet/msvc
New in Bullet 2.78
 Fracture and glueing demo that can break or glue child shapes of a btCompoundShape when certain impulse thresholds are exceeded. See Bullet/Demos/FractureDemo
 Breakable constraints, based on an applied impulse threshold. See Bullet/Demos/ConstraintDemos

- 7 -
 Improved binary .bullet file format with soft body serialization and See Bullet/Demos/SerializeDemo
 Polyhedral contact clipping and optional separating axis test (SAT) as alternative to GJK/EPA and incremental contact manifold, for btPolyhedralConvexShape derived shapes such as btConvexHullShape See Demos/InternalEdgeDemo
 OpenCL and DirectCompute cloth simulation improvements: GPU kernels for capsule collision detection and OpenCL-OpenGL interop See Demos/OpenCLClothDemo and Demos/DX11ClothDemo
 Speculative/predictive contact constraints as a method to perform continuous collision response. See Demos/CcdPhysicsDemo
New in Bullet 2.76
 New binary .bullet file format support, with 32/64bit little/big endian compatibility. See Bullet/Demos/SerializeDemo
 New btCollisionWorld::contactTest and contactPairTest query for immediate collision queries with a contact point callback. See Bullet/Demos/CollisionInterfaceDemo
 New btInternalEdgeUtility to avoid unwanted collisions against internal triangle edges. See Bullet/Demos/InternalEdgeDemo
 Improved MiniCL support in preparation for Bullet 3.x OpenCL support. See Bullet/Demos/MiniCL_VectorAdd
 Improved CMake build system support, making Jam and other systems obsolete.
 Many enhancements and bug fixes, see the issue tracked at bullet.googlecode.com
Maya Dynamica Plugin
 Improved constraint authoring for all constraint types.
 Export to the new .bullet file format.

- 8 -
3 Quickstart
Download
Windows developers can download the zipped sources of Bullet from http://bullet.googlecode.com. Mac OS X, Linux and other developers should download the gzipped tar archive.
Building using Visual Studio
Bullet should compile out-of-the-box for all platforms, and includes dependencies.
Projectfiles for Windows Visual Studio are included in
Bullet/msvc/*/BULLET_PHYSICS.sln
Building using CMake
CMake adds support for many other build environments and platforms, including Microsoft Visual Studio, XCode for Mac OSX, KDevelop Linux and Unix Makefiles. Download install Cmake from http://cmake.org and use the CMake cmake-gui tool. See the Appendix for details. You can also use cmake command-line. Run cmake without arguments to see the list of build system generators for your platform. For example to generate Mac OSX Xcode project files , run
cmake . –G Xcode
or to generate Linux/Unix Makefiles, run
cmake . –G “Unix Makefiles”
or for Microsoft Visual Studio 8 2005, use
cmake . –G “Visual Studio 8 2005”
Building using autotools/automake
Open a shell terminal and go to the Bullet root directory. Then execute
./autogen.sh (this is optional and not needed for downloaded packages) ./configure make

- 9 -
Testing demos
Try to run and experiment with the Bullet demos in Bullet/Demos folder.

- 10 -
Integrating Bullet physics in your application
Check out CcdPhysicsDemo how to create a btDiscreteDynamicsWorld , btCollisionShape, btMotionState and btRigidBody. Each frame call the stepSimulation on the dynamics world, and synchronize the world transform for your graphics object. Requirements:
 #include “btBulletDynamicsCommon.h” in your source file
 Required include path: Bullet/src folder
 Required libraries: BulletDynamics, BulletCollision, LinearMath
The actual name and of the library might be different. For example Visual Studio compiler adds the .lib extension, Unix systems usually add a prefix and extension. When using CMake library is usually location in the lib folder of the build directory.
See the Appendix with details how to setup a Visual Studio and Mac OSX Xcode project.
Integrate only the Collision Detection Library
Bullet Collision Detection can also be used without the Dynamics/Extras. Check out the low level demo Collision Interface Demo, in particular the class btCollisionWorld. Requirements:
 #include “btBulletCollisionCommon.h” at the top of your file
 Add include path: Bullet/src folder
 Add libraries: BulletCollision, LinearMath
Use snippets only, like the GJK Closest Point calculation.
Bullet has been designed in a modular way keeping dependencies to minimum. The Demos/ConvexHullDistance demo demonstrates direct use of btGjkPairDetector.

- 11 -
4 Library Overview
Introduction
The main task of a physics engine is to perform collision detection, resolve collisions and other constraints, and provide the updated world transform1 for all the objects. This chapter will give a general overview of the rigid body dynamics pipeline as well basic data types and math library shared by all components.
Software Design
Bullet has been designed to be customizable and modular. The developer can
 use only the collision detection component
 use the rigid body dynamics component
without soft  use only small parts of a the library and extend the library in many ways
 choose to use a single precision or double version of the library
 use a custom memory allocator, hook up own performance profiler or debug drawer
The main components are organized as follows:
1 World transform of the center of mass for rigid bodies, transformed vertices for soft bodies
Linear Math
Memory, Containers
Collision
Detection
Rigid Body
Dynamics
Soft Body
Dynamics
Bullet
Multi Threaded
Extras:
Maya Plugin
hkx2dae
.bsp, .obj,
other tools

- 12 -
Rigid Body Physics Pipeline
Before going into detail, the following diagram shows the most important data structures and computation stages in the Bullet physics pipeline. This pipeline is executed from left to right, starting by applying gravity, and ending position integration, updating the world transform.
The entire physics pipeline computation and its data structures are represented in Bullet by a dynamics world. When performing ‘stepSimulation’ on the dynamics world, all above stages are executed. The default dynamics world implementation is the btDiscreteDynamicsWorld.
Bullet lets the developer choose several parts of the dynamics world explicitly, such as broadphase collision detection, narrowphase detection (dispatcher) and constraint solver.
Integration overview
If you want to use Bullet in your own 3D application, it is best to follow the steps HelloWorld demo, located in Bullet/Demos/HelloWorld. In a nutshell:
 Create a btDiscreteDynamicsWorld or btSoftRigidDynamicsWorld
These classes, derived from btDynamicsWorld , provide a high level interface that manages your physics objects and constraints. It also implements the update of all each frame.
 Create a btRigidBody and add it to the btDynamicsWorld
To construct a btRigidBody or btCollisionObject, you need to provide:
Forward Dynamics
Broadphase Collision Detection
Detect
Pairs
Compute
Contacts
Solve
constraints
Integrate
Position
Apply
Gravity
Collision
Shapes
Transform
Velocity
Rigid
Body
Mass,
Inertia
Over- lapping
Pairs
Constraint
contacts
joints
Object
AABBs
Collision Data
Dynamics Data
Compute
AABBs
Contact
Points
Predict
Transforms
Forward Dynamics
Narrowphase
Collision
Detection

- 13 -
 Mass, positive for dynamics moving objects
and 0 static  CollisionShape, like a Box, Sphere, Cone, Convex Hull or Triangle Mesh
 Material properties like friction and restitution
Update the simulation each frame:
 stepSimulation
Call the stepSimulation on the dynamics world. The btDiscreteDynamicsWorld automatically takes into account variable timestep by performing interpolation instead of simulation for small timesteps. It uses an internal fixed timestep of 60 Hertz. stepSimulation will perform collision detection and physics simulation. It updates the world transform for active objecs by calling btMotionState’s setWorldTransform.
The next chapters will provide more information about collision detection and rigid body dynamics. A lot of the details are demonstrated in Bullet/Demos. If you can’t find certain functionality, please visit the physics forum on the Bullet website at http://bulletphysics.org

- 14 -
Basic Data Types and Math Library
The basic data types, memory management and containers are located in Bullet/src/LinearMath.
 btScalar
A btScalar is a posh word for a floating point number. In order to allow to compile the library in
single floating point precision and double precision, we use the btScalar data type throughout the
library. By default, btScalar is a typedef to float. It can be double by defining
BT_USE_DOUBLE_PRECISION either in your build system, or at the top of the file
Bullet/src/LinearMath/btScalar.h.
 btVector3
3D positions and vectors can be represented using btVector3. btVector3 has 3 scalar x,y,z components.
It has, however, a 4th unused w component for alignment and SIMD compatibility reasons. Many
operations can be performed on a btVector3, such as add subtract and taking the length of a vector.
 btQuaternion and btMatrix3x3
3D orientations and rotations can be represented using either btQuaternion or btMatrix3x3.
 btTransform
btTransform is a combination of a position and an orientation. It can be used to transform points
and vectors from one coordinate space into the other. No scaling or shearing is allowed.
Bullet uses a right-handed coordinate system:
Y
X
Z
(0,0,0)
Figure 1 Right-handed coordinate system
btTransformUtil, btAabbUtil provide common utility functions for transforms and AABBs.
Memory Management, Alignment, Containers
Often it is important that data is 16-byte aligned, for example when using SIMD or DMA transfers on
Cell SPU. Bullet provides default memory allocators that handle alignment, and developers can
provide their own memory allocator. All memory allocations in Bullet use:

- 15 -
 btAlignedAlloc, which allows to specify size and alignment
 btAlignedFree, free the memory allocated by btAlignedAlloc.
To override the default memory allocator, you can choose between:
 btAlignedAllocSetCustom is used when your custom allocator doesn’t support alignment
 btAlignedAllocSetCustomAligned can be used to set your custom aligned memory allocator.
To assure that a structure or class will be automatically aligned, you can use this macro:
 ATTRIBUTE_ALIGNED16(type) variablename creates a 16-byte aligned variable
Often it is necessary to maintain an array of objects. Originally the Bullet library used a STL std::vector data structure for arrays, but portability and compatibility reasons we switched to our own array class.
 btAlignedObjectArray closely resembles std::vector. It uses the aligned allocator to guarantee alignment. It has methods to sort the array using quick or heap sort.
To enable Microsoft Visual Studio Debugger to visualize btAlignedObjectArray and btVector3, follow the instructions in Bullet/msvc/autoexp_ext.txt
Figure 2 MSVC Debug Visualization
Timing and Performance Profiling
In order to locate bottlenecks in performance, Bullet uses macros for hierarchical performance measurement.
 btClock measures time using microsecond accuracy.
 BT_PROFILE(section_name) marks the start of a profiling section.

- 16 -
 CProfileManager::dumpAll(); dumps a hierarchical performance output in the console. Call this after stepping the simulation.
 CProfileIterator is a class that lets you iterate through the profiling tree.
Note that the profiler doesn’t use memory allocator, so you might want to disable it when checking for memory leaks, or when creating a final release build of your software.
The profiling feature can be switched off by defining #define BT_NO_PROFILE 1 in Bullet/src/LinearMath/btQuickProf.h
Debug Drawing
Visual debugging the simulation data structures can be helpful. For example, this allows you to verify that the physics simulation data matches graphics data. Also scaling problems, bad constraint frames and limits show up.
btIDebugDraw is the interface class used for debug drawing. Derive your own and implement the virtual ‘drawLine’ and other methods.
Assign your custom debug drawer to the dynamics world using setDebugDrawer method.
Then you can choose to draw specific debugging features by setting the mode of debug drawer:
dynamicsWorld->getDebugDrawer()->setDebugMode(debugMode);
Every frame you can call the
debug drawing by calling world-> debugDrawWorld();2
Here are some debug modes
 btIDebugDraw::DBG_DrawWireframe
 btIDebugDraw::DBG_DrawAabb
 btIDebugDraw::DBG_DrawConstraints
 btIDebugDraw::DBG_DrawConstraintLimits
By default all objects are visualized for a given debug mode, and when using many this can clutter the display. You can disable debug drawing for specific objects by using
int f = objects->getCollisionFlags();
ob->setCollisionFlags(f|btCollisionObject::CF_DISABLE_VISUALIZE_OBJECT);
2 This feature is supported for both btCollisionWorld and btDiscreteDynamicsWorld

- 17 -
5 Bullet Collision Detection
Collision Detection
The collision detection provides algorithms and acceleration structures for closest point (distance penetration) queries as well ray and convex sweep tests. The main data structures are:
 btCollisionObject is the object that has a world transform and collision shape.
 btCollisionShape describes the collision shape of a object, such as box, sphere, convex hull or triangle mesh. A single collision shape can be shared among multiple collision objects.
 btGhostObject is a special btCollisionObject, useful for fast localized collision queries.
 btCollisionWorld stores all btCollisionObjects and provides an interface to perform queries.
The broadphase collision detection provides acceleration structure to quickly reject pairs of objects based on axis aligned bounding box (AABB) overlap. Several different broadphase acceleration structures are available:
 btDbvtBroadphase uses a fast dynamic bounding volume hierarchy based on AABB tree
 btAxisSweep3 and bt32BitAxisSweep3 implement incremental 3d sweep and prune
 btCudaBroadphase implements a fast uniform grid using GPU graphics hardware
The broadphase adds and removes overlapping pairs from a pair cache. The developer can choose the type of pair cache.
A collision dispatcher iterates over each pair, searches for a matching algorithm based on the types of objects involved and executes the collision algorithm computing contact points.
 btPersistentManifold is a contact point cache to store points for given pair of objects.

- 18 -
Collision Shapes
Bullet supports a large variety of different collision shapes, and it is possible to add your own. For best performance and quality it is important to choose the collision shape that suits your purpose. The following diagram can help making a decision:
Convex Primitives
Most primitive shapes are centered around the origin of their local coordinate frame:
btBoxShape : Box defined by the half extents (length) of its sides
btSphereShape : Sphere defined by its radius
btCapsuleShape: Capsule around the Y axis. Also btCapsuleShapeX/Z
btCylinderShape : Cylinder around the Y axis. Also btCylinderShapeX/Z.
btConeShape : Cone around the Y axis. Also btConeShapeX/Z.
Is is a moving object?
btBoxShape, btSphereShape, btCapsuleShape,
btCylinderShape,
btConeShape
btConvexHullShape
Can it be approximated by a single primitive, such as box, sphere, capsule, cone, cylinder?
Is it a 2D heightfield?
Can it be approximated by a convex hull of a triangle mesh?
Can it be approximated using multiple primitives, such as box, sphere etc?
btCompoundShape
btGimpactTriangleMeshShape
btHeightfield
TerrainShape
Are there shared scaled instances?
btScaledBvhTriangle
MeshShape
btBvhTriangle
MeshShape
NO
NO
YES
YES
YES
YES
YES
YES
NO
NO
NO
NO

- 19 -
btMultiSphereShape : Convex hull of multiple spheres, that can be used to create a Capsule (by passing 2 spheres) or other convex shapes.
Compound Shapes
Multiple convex shapes can be combined into a composite or compound shape, using the btCompoundShape. This is a concave shape made out of convex sub parts, called child shapes. Each child shape has its own local offset transform, relative to the btCompoundShape.
Convex Hull Shapes
Bullet supports several ways to represent a convex triangle meshes. The easiest way is to create a btConvexHullShape and pass in an array of vertices. In some cases the graphics mesh contains too many vertices to be used directly as btConvexHullShape. In that case, try to reduce the number of vertices.
Concave Triangle Meshes
For static world environment, a very efficient way to represent triangle meshes is use btBvhTriangleMeshShape. This collision shape builds an internal acceleration structure from a btTriangleMesh or btStridingMeshInterface. Instead of building the tree at run-time, it is also possible to serialize the binary tree disc. See Demos/ConcaveDemo how to save and load this btOptimizedBvh tree acceleration structure. When you have several instances of the same triangle mesh, but with different scaling, you can instance a btBvhTriangleMeshShape multiple times using the btScaledBvhTriangleMeshShape.
Convex Decomposition
Ideally, concave meshes should only be used for static artwork. Otherwise its convex hull should be used by passing the mesh to btConvexHullShape. If a single convex shape is not detailed enough, multiple convex parts can be combined into a composite object called btCompoundShape. Convex decomposition can be used to decompose the concave mesh into several convex parts. See the Demos/ConvexDecompositionDemo for an automatic way of doing convex decomposition.
Height field
Bullet provides support for the special case of a flat 2D concave terrain through btHeightfieldTerrainShape. See Demos/TerrainDemo for its usage.

- 20 -
btStaticPlaneShape
As the name suggests, btStaticPlaneShape can represent an infinite plane or half space. This shape can only be used for static, non-moving objects. This shape has been introduced mainly for demo purposes.
Scaling of Collision Shapes
Some collision shapes can have local scaling applied. Use btCollisionShape::setScaling(vector3). Non uniform scaling with different values for each axis, can be used for btBoxShape, btMultiSphereShape, btConvexShape, btTriangleMeshShape. Uniform scaling, using x value for all axis, can be used btSphereShape. Note that a non-uniform scaled sphere can be created by using a btMultiSphereShape with 1 sphere. As mentioned before, the btScaledBvhTriangleMeshShape allows to instantiate a btBvhTriangleMeshShape at different non-uniform scale factors. The btUniformScalingShape allows to instantiate convex shapes at different scales, reducing the amount of memory.
Collision Margin
Bullet uses a small collision margin for collision shapes, to improve performance and reliability of the collision detection. It is best not to modify the default margin, and if you do use a positive value: zero margin might introduce problems. By default this collision is set to 0.04, which is 4 centimeter if your units are in meters (recommended).
Dependent on which collision shapes, the margin has different meaning. Generally margin will expand the object. This create a small gap. To compensate for this, some shapes will subtract the margin from actual size. For example, btBoxShape subtracts the collision margin from the half extents. For a btSphereShape, the entire radius is collision margin so no gap will occur. Don’t override the collision margin for spheres. For convex hulls, cylinders and cones, the margin is added to the extents of object, so a gap will occur, unless you adjust graphics mesh or collision size. For convex hull objects, there is a method to remove the gap introduced by margin, by shrinking the object. See Demos/BspDemo for this advanced use.

- 21 -
Collision Matrix
For each pair of shape types, Bullet will dispatch a certain collision algorithm, by using the dispatcher. By default, the entire matrix is filled with following algorithms. Note that Convex represents convex polyhedron, cylinder, cone and capsule other GJK compatible primitives. stands for Gilbert, Johnson and Keerthi, the people behind this convex distance calculation algorithm. It is combined with EPA for penetration depth calculation. stands Expanding Polythope Algorithm by Gino van den Bergen. Bullet has its own free implementation of GJK and EPA.
box sphere convex,cylinder cone,capsule compound triangle mesh box
boxbox
spherebox
gjk
compound
concaveconvex sphere
spherebox
spheresphere
gjk
compound
concaveconvex convex, cylinder, cone, capsule
gjk
gjk
gjk
compound
concaveconvex compound
compound
compound
compound
compound
compound triangle mesh
concaveconvex
concaveconvex
concaveconvex
compound
gimpact
Registering custom collision shapes and algorithms
The user can register a custom collision detection algorithm and override any entry in this Collision Matrix by using the btDispatcher::registerCollisionAlgorithm. See Demos/UserCollisionAlgorithm for an example, that registers a SphereSphere collision algorithm.

- 22 -
6 Collision Filtering (selective collisions)
Bullet provides three easy ways to ensure that only certain objects collide with each other: masks, broadphase filter callbacks and nearcallbacks. It is worth noting that mask-based collision selection happens a lot further up the toolchain than callback do. In short, if masks are sufficient for your purposes, use them; they perform better and are a lot simpler to use.
Of course, don't try to shoehorn something into a mask-based selection system that clearly doesn't fit there just because performance may be a little better.
Filtering collisions using masks
Bullet supports bitwise masks as a way of deciding whether or not things should collide with other things, or receive collisions.
int myGroup = 1;
int collideMask = 4;
world->addCollisionObject(object,myGroup,collideMask);
During broadphase collision detection overlapping pairs are added to a pair cache, only when the mask matches the group of other objects (in needsBroadphaseCollision)
bool collides = (proxy0->m_collisionFilterGroup & proxy1->m_collisionFilterMask) != 0;
collides = && (proxy1->m_collisionFilterGroup & proxy0->m_collisionFilterMask);
If you have more types of objects than the 32 bits available to you in the masks, or some collisions are enabled or disabled based on other factors, then there are several ways to register callbacks that implements custom logic and only passes on collisions that are the ones you want:
Filtering Collisions Using a Broadphase Filter Callback
One efficient way is to register a broadphase filter callback. This callback called at very early stage in the collision pipeline, and prevents pairs from being generated.
struct YourOwnFilterCallback : public btOverlapFilterCallback
{
// return true when pairs need collision
virtual bool needBroadphaseCollision(btBroadphaseProxy* proxy0,btBroadphaseProxy* proxy1) const
{
bool collides = (proxy0->m_collisionFilterGroup & proxy1->m_collisionFilterMask) != 0;
collides = collides && (proxy1->m_collisionFilterGroup & proxy0->m_collisionFilterMask);
//add some additional logic here that modified 'collides'
return collides;
}
};
And then create an object of this class and register callback using:

- 23 -
btOverlapFilterCallback * filterCallback = new YourOwnFilterCallback();
dynamicsWorld->getPairCache()->setOverlapFilterCallback(filterCallback);
Filtering Collisions Using a Custom NearCallback
Another callback can be registered during the narrowphase, when all pairs are generated by broadphase. The btCollisionDispatcher::dispatchAllCollisionPairs calls this narrowphase nearcallback for each pair that passes the 'btCollisionDispatcher::needsCollision' test. You can customize this nearcallback:
void MyNearCallback(btBroadphasePair& collisionPair,
btCollisionDispatcher& dispatcher, btDispatcherInfo& dispatchInfo) {
// Do your collision logic here
// Only dispatch the Bullet collision information if you want the physics to continue
dispatcher.defaultNearCallback(collisionPair, dispatcher, dispatchInfo);
}
mDispatcher->setNearCallback(MyNearCallback);
Deriving your own class from btCollisionDispatcher
For even more fine grain control over the collision dispatch, you can derive your own class from btCollisionDispatcher and override one or more of the following methods:
virtual bool needsCollision(btCollisionObject* body0,btCollisionObject* body1);
virtual bool needsResponse(btCollisionObject* body0,btCollisionObject* body1);
virtual void dispatchAllCollisionPairs(btOverlappingPairCache* pairCache,const btDispatcherInfo& dispatchInfo,btDispatcher* dispatcher) ;

- 24 -
7 Rigid Body Dynamics
Introduction
The rigid body dynamics is implemented on top of the collision detection module. It adds forces, mass, inertia, velocity and constraints.
 btRigidBody is the main rigid body object, moving objects have non-zero mass and inertia. btRigidBody is derived from btCollisionObject, so it inherits its world transform, friction and restitution adds linear angular velocity.
 btTypedConstraint is the base class for rigid body constraints, including btHingeConstraint, btPoint2PointConstraint, btConeTwistConstraint, btSliderConstraint and btGeneric6DOFconstraint.
 btDiscreteDynamicsWorld is derived from btCollisionWorld, and is a container for rigid bodies and constraints. It provides the stepSimulation to proceed.
Static, Dynamic and Kinematic Rigid Bodies
There are 3 different types of objects in Bullet:
 Dynamic (moving) rigidbodies
 positive mass
 every simulation frame the dynamics will update its world transform
 Static rigidbodies
 zero mass
 cannot move but just collide
 Kinematic rigidbodies
 zero mass
 can be animated by the user, but there will only one-way interaction: dynamic objects will be pushed away but there is no influence from dynamics objects
All of them need to be added the dynamics world. The rigid body can assigned a collision shape. This shape can be used to calculate the distribution of mass, also called inertia tensor.

- 25 -
Center of mass World Transform
The world transform of a rigid body is in Bullet always equal to its center mass, and basis also defines its local frame for inertia. The inertia tensor depends on the shape, and the btCollisionShape class provides a method to calculate the local inertia, given mass.
This world transform has to be a rigid body transform, which means it should contain no scaling, shear etc. If you want an object to be scaled, can scale the collision shape. Other transformation, such as shear, can be applied (baked) into the vertices of a triangle mesh if necessary.
In case the collision shape is not aligned with center of mass transform, it can be shifted to match. For this, you can use a btCompoundShape, and use the child transform to shift collision shape.
What's a MotionState?
MotionStates are a way for Bullet to do all the hard work you getting world transform of objects being simulated into the rendering part of your program.
In most situations, your game loop would iterate through all the objects you're simulating before each frame rander. For each object, you would update the position of render object from physics body. Bullet uses something called MotionStates to save you this effort.
There are multiple other benefits of MotionStates:
 Computation involved in moving bodies around is only done for that have moved; no point updating the position of a render object every frame if it isn't moving.
 You don't just have to do render stuff in them. They could be effective for notifying network code that a body has moved and needs to be updated across the network.
 Interpolation is usually only meaningful in the context of something visible on-screen. Bullet manages body interpolation through MotionStates.
 You can keep track of a shift between graphics object and center of mass transform.
 They're easy
Interpolation
Bullet knows how to interpolate body movement for you. As mentioned, implemention of interpolation is handled through MotionStates.
If you attempt to ask a body for its position through btCollisionObject::getWorldTransform or btRigidBody::getCenterOfMassTransform, it will return the position at end of last

- 26 -
physics tick. That's useful for many things, but for rendering you will want some interpolation. Bullet interpolates the transform of body before passing value to setWorldTransform.
If you want the non-interpolated position of a body [which will be the as it was calculated at the end of last physics tick], use btRigidBody::getWorldTransform() and query body directly.
So how do I use one?
MotionStates are used in two places Bullet.
The first is when the body created. Bullet grabs initial position of the body from motionstate when the body enters simulation
Bullet calls getWorldTransform with a reference to the variable it wants you fill transform information
Bullet also calls getWorldTransform on kinematic bodies. Please see the section below
After the first update, during simulation Bullet will call motion state for a body to move that around
Bullet calls setWorldTransform with the transform of body, for you to update your object appropriately
To implement one, simply inherit btMotionState and override getWorldTransform setWorldTransform.
DefaultMotionState
Although recommended, it is not necessary to derive your own motionstate from btMotionState interface. Bullet provides a default motionstate that you can use for this. Simply construct it with the default transform of your body:
btDefaultMotionState* ms =new btDefaultMotionState();
There is an example for Ogre3D Motion State in Appendix.
Kinematic Bodies
If you plan to animate or move static objects, should flag them as kinematic. Also disable the sleeping/deactivation for them during the animation. This means Bullet dynamics world will get new worldtransform from the btMotionState every simulation frame.
body->setCollisionFlags( body->getCollisionFlags() | btCollisionObject::CF_KINEMATIC_OBJECT);
body->setActivationState(DISABLE_DEACTIVATION);

- 27 -
If you are using kinematic bodies, then getWorldTransform is called every simulation step. This means that your kinematic body's motionstate should have a mechanism to push the current position of the kinematic body into motionstate.
Simulation frames
and interpolation By default, Bullet physics simulation runs at an internal fixed framerate of 60 Hertz (0.01666). The game or application might have a different or even variable framerate. To decouple the application framerate from the simulation framerate, an automatic interpolation method is built into stepSimulation: when the application delta time, is smaller then internal fixed timestep, Bullet will interpolate the world transform, and send interpolated worldtransform to btMotionState, without performing physics simulation. If the application timestep is larger then 60 hertz, more 1 simulation step can be performed during each ‘stepSimulation’ call. The user can limit the maximum number of simulation steps by passing a maximum value as second argument.
When rigidbodies are created, they will retrieve the initial worldtransform from btMotionState, using btMotionState::getWorldTransform. When the simulation is running, using stepSimulation, the new worldtransform is updated for active rigidbodies using btMotionState::setWorldTransform.
Dynamic rigidbodies have a positive mass, and their motion is determined by the simulation. Static and kinematic rigidbodies have zero mass. Static objects should never be moved by the user.

- 28 -
8 Constraints
There are several constraints implemented in Bullet. See Demos/ConstraintDemo for an example of each of them. All constraints including the btRaycastVehicle are derived from btTypedConstraint. Constraint act between two rigidbodies, where at least one of them needs to be dynamic.
Point to Point Constraint
Point to point constraint limits the translation so that local pivot points of 2 rigidbodies match in worldspace. A chain of rigidbodies can be connected using this constraint.
btPoint2PointConstraint(btRigidBody& rbA,const btVector3& pivotInA); btPoint2PointConstraint(btRigidBody& rbA,rbB, const btVector3& pivotInA,btVector3& pivotInB);
Figure 3 Point to point constraint
Hinge Constraint
Hinge constraint, or revolute joint restricts two additional angular degrees of freedom, so the body can only rotate around one axis, the hinge axis. This can be useful to represent doors or wheels rotating around one axis. The user can specify limits and motor for the hinge.
btHingeConstraint(btRigidBody& rbA,const btTransform& rbAFrame, bool useReferenceFrameA = false);
btHingeConstraint(btRigidBody& rbA,const btVector3& pivotInA,btVector3& axisInA, bool useReferenceFrameA = false);
btHingeConstraint(btRigidBody& rbA,btRigidBody& rbB, const btVector3& pivotInA,const btVector3&
pivotInB, btVector3& axisInA,btVector3& axisInB, bool useReferenceFrameA = false);
btHingeConstraint(btRigidBody& rbA,btRigidBody& rbB, const btTransform& rbAFrame, const btTransform& rbBFrame, bool useReferenceFrameA = false);
Figure 4 Hinge Constraint

- 29 -
Slider Constraint
The slider constraint allows the body to rotate around one axis and translate along this axis.
btSliderConstraint(btRigidBody& rbA, btRigidBody& rbB, const btTransform& frameInA, const btTransform& frameInB ,bool useLinearReferenceFrameA);
Figure 5 Slider Constraint
Cone Twist Constraint
To create ragdolls, the conve twist constraint is very useful for limbs like the upper arm. It is a special point to point constraint that adds cone and twist axis limits. The x-axis serves as twist axis.
btConeTwistConstraint(btRigidBody& rbA,const btTransform& rbAFrame);
btConeTwistConstraint(btRigidBody& rbA,btRigidBody& rbB,const btTransform& rbAFrame, const btTransform& rbBFrame);
Generic 6 Dof Constraint
This generic constraint can emulate a variety of standard constraints, by configuring each of the 6 degrees of freedom (dof). The first 3 dof axis are linear axis, which represent translation rigidbodies, and the latter 3 dof axis represent angular motion. Each can be either locked, free or limited. On construction of a new btGeneric6DofConstraint, all axis are locked. Afterwards the can be reconfigured. Note that several combinations include free and/or limited angular degrees of freedom are undefined.
btGeneric6DofConstraint(btRigidBody& rbA, btRigidBody& rbB, const btTransform& frameInA, const btTransform& frameInB ,bool useLinearReferenceFrameA);
Following is convention:
btVector3 lowerSliderLimit = btVector3(-10,0,0);
btVector3 hiSliderLimit = btVector3(10,0,0);
btGeneric6DofConstraint* slider = new btGeneric6DofConstraint(*d6body0,*fixedBody1,frameInA,frameInB);
slider->setLinearLowerLimit(lowerSliderLimit);
slider->setLinearUpperLimit(hiSliderLimit);

- 30 -
For each axis:
 Lowerlimit == Upperlimit -> axis is locked.
 Lowerlimit > Upperlimit -> axis is free
 Lowerlimit < Upperlimit -> axis it limited in that range

- 31 -
9 Actions: Vehicles & Character Controller
Action Interface
In certain cases it is useful to process some custom physics game code inside the pipeline. Although it is possible to use a tick callback, when there are several objects be updated, it can more convenient to derive your custom class from btActionInterface. And implement the btActionInterface::updateAction(btCollisionWorld* world, btScalar deltaTime); There are built-in examples, btRaycastVehicle and btKinematicCharacterController, that are using this btActionInterace.
Raycast Vehicle
For arcade style vehicle simulations, it is recommended to use the simplified Bullet model as provided in btRaycastVehicle. Instead of simulation each wheel and chassis as separate rigid bodies, connected by constraints, it uses a simplified model. This model has many benefits, and is widely used in commercial driving games.
The entire vehicle is represented as a single rigidbody, the chassis. The collision detection of wheels is approximated by ray casts, and the tire friction a basic anisotropic model.
See src/BulletDynamics/Vehicle and Demos/VehicleDemo for more details, or check the Bullet forums.
Kester Maddock shared an interesting document about Bullet vehicle simulation here:
http://tinyurl.com/ydfb7lm
Character Controller
A player or NPC character can be constructed using a capsule shape, sphere or other shape. To avoid rotation, you can set the ‘angular factor’ to zero, which disables rotation effect during collisions and other constraints. See btRigidBody::setAngularFactor. Other options (that are less recommended) include setting the inverse inertia tensor to zero for up axis, or using a angular-only hinge constraint.
There is also an experimental3 btKinematicCharacterController as an example a non-physical character controller. It uses a btGhostShape to perform collision queries to create a character that can climb stairs, slide smoothly along walls etc. See src/BulletDynamics/Character and Demos/CharacterDemo for its usage.
3 btKinematicCharacterController has several outstanding issues.

- 32 -
10 Soft Body Dynamics
Preliminary documentation
Introduction
The soft body dynamics provides rope, cloth simulation and volumetric soft bodies, on top of the existing rigid body dynamics. There is two-way interaction between soft bodies, rigid bodies and collision objects.
 btSoftBody is the main soft body object. It derived from btCollisionObject. Unlike rigid bodies, soft bodies don’t have a single world transform: each node/vertex is specified in world coordinate.
 btSoftRigidDynamicsWorld is the container for soft bodies, rigid bodies and collision objects.
It is best to learn from Demos/SoftBodyDemo how to use soft body simulation.
Here are some basic guidelines in a nutshell:
Construction from a triangle mesh
The btSoftBodyHelpers::CreateFromTriMesh can automatically create a soft body from triangle mesh.
Collision clusters
By default, soft bodies perform collision detection using between vertices (nodes) and triangles (faces). This requires a dense tessellation, otherwise collisions might be missed. An improved method uses automatic decomposition into convex deformable clusters. To enable collision clusters, use:
psb->generateClusters(numSubdivisions);
//enable cluster collision between soft body
and rigid psb->m_cfg.collisions += btSoftBody::fCollision::CL_RS;
//enable cluster collision between soft body
and psb->m_cfg.collisions += btSoftBody::fCollision::CL_SS;
The Softbody and AllBulletDemos has a debug option to visualize the convex collision clusters.

- 33 -
Applying forces to a Soft body
There are methods to apply a force each vertex (node) or at an individual node:
softbody ->addForce(const btVector3& forceVector);
softbody ->addForce(const btVector3& forceVector,int node);
Soft body constraints
It is possible to fix one or more vertices (nodes), making it immovable:
softbody->setMass(node,0.f);
or to attach one more vertices of a soft body to rigid body:
softbody->appendAnchor(int node,btRigidBody* rigidbody, bool disableCollisionBetweenLinkedBodies=false);
It is also possible to attach two soft bodies using constraints, see Bullet/Demos/SoftBody.

- 34 -
11 Bullet Demo Description
Bullet includes several demos. They are tested on platforms and use OpenGL graphics Glut. Some shared functionality like mouse picking and text rendering is provided in the Demos/OpenGL support folder. This is implemented in the DemoApplication class. Each demo derives a class from DemoApplication and implements its own initialization of the physics in ‘initPhysics’ method.
AllBulletDemos
This is a combination of several demos. It includes demonstrations fork lift, ragdolls, cloth and soft bodies and several performance benchmarks.
CCD Physics Demo
This is a that shows how to setup physics simulation, add some objects, and step the simulation. It shows stable stacking, and allows mouse picking shooting boxes to collapse the wall. The shooting speed of the box can be changed, and for high velocities, CCD feature enabled to avoid missing collisions. Try out advanced features using the #defines at top of Demos/CcdPhysicsDemo/CcdPhysicsDemo.cpp
BSP Demo
Import a Quake .bsp files and convert the brushes into convex objects. This performs better then using triangles.
Vehicle Demo
This demo shows the use of build-in vehicle. The wheels are approximated by ray casts. This approximation works very well for fast moving vehicles.
Fork Lift Demo
A demo that shows how to use constraints like hinge and slider constraint build a fork lift vehicle.

- 35 -
12 Advanced Low Level Technical Demos
Collision Interfacing Demo
This demo shows how to use Bullet collision detection without the dynamics. It uses btCollisionWorld class, and fills this will btCollisionObjects. The performDiscreteCollisionDetection method is called and the demo shows how to gather contact points.
Collision Demo
This demo is more low level then previous Collision Interfacing Demo. It directly uses the btGJKPairDetector to query the closest points between two objects.
User Collision Algorithm
Shows how you can register your own collision detection algorithm that handles the detection for a certain pair of collision types. A simple sphere-sphere case overides the default GJK detection.
Gjk Convex Cast / Sweep Demo
This demo show how to performs a linear sweep between collision objects and returns the time of impact. This can be useful to avoid penetrations in camera and character control.
Continuous Convex Collision
Shows time of impact query using continuous collision detection, between two rotating and translating objects. It uses Bullet’s implementation of Conservative Advancement.
Raytracer Demo
This shows the use of CCD ray casting on collision shapes. It implements a tracer that can accurately visualize the implicit representation of collision shapes. This includes margin, convex hulls of implicit objects, minkowski sums and other shapes that are hard to visualize otherwise.

- 36 -
Simplex Demo
This is a very low level demo testing the inner workings of GJK sub distance algorithm. calculates the distance between a simplex and origin, which is drawn with a red line. A simplex contains 1 up to 4 points, the demo shows point case, a tetrahedron. The Voronoi simplex solver is used, as described by Christer Ericson in his collision detection book.

- 37 -
13 Authoring Tools and Serialization
Collision shapes, rigid body and constraints can be created in a 3D authoring tool and exported to a file format that Bullet can read.
Dynamica Maya Plugin
Walt Disney Animation Studios contributed their in-house Maya plugin to author Bullet collision shapes and rigid bodies as open source. Dynamica can simulation rigid body dynamica within Maya, and it can export to Bullet .bullet physics files and COLLADA Physics. The latest version has preliminary support for cloth/soft body.
There is more information in the Bullet wiki page. You can download a precompiled version of the Dynamica plugin for Windows or Mac OSX from http://bullet.googlecode.com.
The source code repository of Dynamica is under http://dynamica.googlecode.com
Blender
The open source 3D production suite Blender uses Bullet physics for animations and its internal game engine. See http://blender.org
Blender has an option to export COLLADA Physics files. There is also a project that can directly read any information from a Blender .blend file, including collision shape, rigid body and constraint information. See http://gamekit.googlecode.com
Blender 2.57 and later has an option to export to .bullet files directly from the game engine. This can be done using the exportBulletFile(“name.bullet”) Python command in the PhysicsConstraints module.
Cinema 4D, Lightwave CORE, Houdini
Cinema 4D 11.5 uses Bullet for the rigid body simulation, and there is a report that Lightwave CORE also plans to use Bullet.
For Houdini there is a DOP/plugin, see
http://code.google.com/p/bullet-physics-solver/

- 38 -
Serialization and the Bullet .bullet binary format
Bullet 2.76 onwards has the capability to save the dynamics world a binary dump. Saving the objects and shapes into a buffer is built-in, so no additional libraries are necessary. Here is an example how to save the dynamics world to a binary .bullet file:
btDefaultSerializer* serializer = new btDefaultSerializer();
dynamicsWorld->serialize(serializer);
FILE* file = fopen("testFile.bullet","wb");
fwrite(serializer->getBufferPointer(),serializer->getCurrentBufferSize(),1, file);
fclose(file);
You can press the ‘=’ key in most of Bullet demos to save a ‘testFile.bullet’. read .bullet files using the btBulletWorldImporter as implemented in Bullet/Demos/SerializationDemo.
Futher information about .bullet serialization is at
the Bullet wiki http://bulletphysics.org/mediawiki-1.5.8/index.php/Bullet_binary_serialization
COLLADA Physics format and viewer
COLLADA is rich 3D specification and XML based file format that includes collision physics information. Dynamica Maya plugin, Blender and other software can export/import this standard physics file format.
The Dynamica source repository at http://dynamica.googlecode.com provides example code to load and save COLLADA Physics files based on the COLLADA-DOM and libxml. See Dynamica/Demos/ColladaDemo.
The Dynamica/Extras/BulletColladaConverter class can be used as example for other COLLADA physics integrations.

- 39 -
14 General Tips
Avoid very small and large collision shapes
The minimum object size for moving objects is about 0.2 units, 20 centimeters for Earth gravity. If smaller objects or bigger gravity are manipulated, reduce the internal simulation frequency accordingly, using the third argument of btDiscreteDynamicsWorld::stepSimulation. By default it is 60Hz. For instance, simulating a dice throw (1cm-wide box with a gravity of 9.8m/s2) requires a frequency of at least 300Hz (1./300.). It is recommended to keep the maximum size of moving objects smaller then about 5 units/meters.
Avoid large mass ratios (differences)
Simulation becomes unstable when a heavy object is resting on very light object. It is best to keep the mass around 1. This means accurate interaction between a tank and very light object is not realistic.
Combine multiple static triangle meshes into one
Many small btBvhTriangleMeshShape pollute the broadphase. Better combine them.
Use the default internal fixed timestep
Bullet works best with a fixed internal timestep of at least 60 hertz (1/second).
For safety and stability, Bullet will automatically subdivide the variable timestep into fixed internal simulation substeps, up to a maximum number of substeps specified as second argument stepSimulation. When the timestep is smaller then internal substep, Bullet will interpolate motion.
This safety mechanism can be disabled by passing 0 as maximum number of substeps (second argument to stepSimulation): the internal timestep and substeps are disabled, actual timestep is simulated. It not recommended to disable this safety mechanism.
For ragdolls use btConeTwistConstraint
It is better to build a ragdoll out of btHingeConstraint and/or btConeTwistLimit for knees, elbows and arms.

- 40 -
Don’t set the collision margin to zero
Collision detection system needs some margin for performance and stability. If the gap is noticeable, please compensate the graphics representation.
Use less then 100 vertices in a convex mesh
It is best to keep the number of vertices in a btConvexHullShape limited. It is better for performance, and too many vertices might cause instability. Use the btShapeHull utility to simplify convex hulls.
Avoid huge or degenerate triangles in a triangle mesh
Keep the size of triangles reasonable, say below 10 units/meters. Also degenerate with large size ratios between each sides or close to zero area can better be avoided.
The profiling feature btQuickProf bypasses the memory allocator
If necessary, disable the profiler when checking for memory leaks, or creating final version of your software release. The profiling feature can be switched off by defining #define BT_NO_PROFILE 1 in Bullet/src/LinearMath/btQuickProf.h

- 41 -
Advanced Topics
Per triangle friction and restitution value
By default, there is only one friction value for rigidbody. You can achieve per shape or triangle friction for more detail. See the Demos/ConcaveDemo how to set the friction per triangle. Basically, add CF_CUSTOM_MATERIAL_CALLBACK to the collision flags or rigidbody, and register a global material callback function. To identify the triangle in mesh, both triangleID and partId of the mesh is passed to the material callback. This matches triangleId/partId of striding mesh interface.
An easier way is to use the btMultimaterialTriangleMeshShape. See the Demos/MultiMaterialDemo for usage.
Custom Constraint Solver
Bullet uses its btSequentialImpulseConstraintSolver by default. You can use a different constraint solver, by passing it into the constructor of your btDynamicsWorld. For comparison you can use the Extras/quickstep solver from ODE.
Custom Friction Model
If you want to have a different friction model for certain types of objects, you can register function in the constraint solver for certain body types. This feature is not compatible with cache friendly constraint solver setting.
See #define USER_DEFINED_FRICTION_MODEL in Demos/CcdPhysicsDemo.cpp.

- 42 -
15 Parallelism: OpenCL, Compute, SPU, multi thread
OpenCL and Direct Compute cloth simulation
Parts of the CPU intensive innerloop cloth and soft body library have been implemented using OpenCL and DirectX 11 DirectCompute kernels. See Demos/OpenCLClothDemo and Demos/DX11ClothDemo for examples.
Cell SPU / SPURS optimized version
Bullet collision detection and physics have been optimized for Cell SPU. This means collision code has been refactored to run on multiple parallel SPU processors. The collision detection code and data have been refactored to make it suitable for 256kb local store SPU memory. The user can activate the parallel optimizations by using a special collision dispatcher (SpuGatheringCollisionDispatcher) that dispatches the work to SPU. The shared public implementation is located in Bullet/src/BulletMultiThreaded.
Please contact Sony developer support on PS3 Devnet for a Playstation 3 optimized version of Bullet.
Unified multi threading
Efforts have been made to make it possible re-use the SPU parallel version in other multi threading environments, including multi core processors. This allows more effective debugging of SPU code under Windows, as well utilizing multi core processors. For non-SPU multi threading, the implementation performs fake DMA transfers using a memcpy, and each thread gets its own 256kb ‘local store’ working memory allocated. See Bullet/ThreadingDemo for an example.
Win32 Threads, pthreads, sequential thread support
Basic Win32 Threads, pthreads and sequential thread support is available to execute the parallel constraint solver and parallel collision dispatcher. See Demos/BulletMultiThreaded for an example.

- 43 -
16 Further documentation and references
Online resources
Visit the Bullet Physics website at http://bulletphysics.org for a discussion forum, wiki with frequently asked questions and tips download of the most recent version. The Wikipedia page lists some games and films using Bullet at http://en.wikipedia.org/wiki/Bullet_(software)
Authoring Tools
 Dynamica Maya plugin and Bullet COLLADA Physics support at http://dynamica.googlecode.com
 Blender 3D modeler includes Bullet and COLLADA physics support: http://www.blender.org
 COLLADA physics standard: http://www.khronos.org/collada
Books
 Realtime Collision Detection, Christer Ericson http://www.realtimecollisiondetection.net/ Bullet uses the discussed voronoi simplex solver for GJK
 Collision Detection in Interactive 3D Environments, Gino van den Bergen http://www.dtecta.com also website for Solid collision detection library Discusses GJK and other algorithms, very useful to understand Bullet
 Physics Based Animation, Kenny Erleben http://www.diku.dk/~kenny/ Very useful to understand Bullet Dynamics and constraints

- 44 -
Contributions and people
The Bullet Physics library is under active development in collaboration with many professional game developers, movie studios, as well academia, students and enthusiasts.
Main author and project lead is Erwin Coumans, former Havok employee now working on this project at Sony Computer Entertainment America US R&D.
Some people that contributed source code to Bullet:
Roman Ponomarev, SCEA, constraints, CUDA and OpenCL research
John McCutchan, SCEA, ray cast, character control, several improvements
Nathanael Presson, Havok: initial author of Bullet soft body dynamics and EPA
Gino van den Bergen, Dtecta: LinearMath classes, various collision detection ideas
Christer Ericson, SCEA: voronoi simplex solver
Phil Knight, Disney Avalanche Studios: multiplatform compatibility, BVH serialization
Ole Kniemeyer, Maxon: various general patches, btConvexHullComputer
Simon Hobbs, SCEE: 3d axis sweep and prune and parts of btPolyhedralContactClipping
Pierre Terdiman, NVIDIA: various work related to separating axis test, sweep and prune
Dirk Gregorius, Factor 5 : discussion and assistance with constraints
Erin Catto, Blizzard: accumulated impulse
in sequential Francisco Leon : GIMPACT Concave collision
Eric Sunshine: jam + msvcgen buildsystem (replaced by cmake since Bullet 2.76)
Steve Baker: GPU physics and general implementation improvements
Jay Lee, TrionWorld: double precision support
KleMiX, aka Vsevolod Klementjev, managed version, C# port to XNA
Marten Svanfeldt, Starbreeze: parallel constraint solver and other improvements optimizations
Marcus Hennix, Starbreeze: btConeTwistConstaint etc.
Arthur Shek, Nicola Candussi, Lawrence Chai, Disney Animation: Dynamica Maya Plugin
Many more people have contributed to Bullet, thanks everyone on the Bullet forums.
(please get in touch if your name should be this list)

- 45 -
Create Bullet Visual Studio projectfiles using CMake
First, download Bullet from http://bullet.googlecode.com and CMake from http://cmake.org
1. Run CMake-gui
2. Choose the location where you unzipped Bullet source code, and build binaries for your own project and press Configure

- 46 -
3. Choose the compiler, such as Microsoft Visual Studio 2008
4. Review the settings and press Configure again

- 47 -
5. Make sure the Run-time library is the same as your project (by default it set to Run-time library DLL) and press Generate
6. Optionally, you could open the generated project solution (in our case C:developtutorialBulletBuildBULLET_PHYSICS.sln) and build the library and demos, but this is not necessary
See also the Bullet Wiki on how to create your own project using Visual Studio
http://bulletphysics.org/mediawiki-1.5.8/index.php/Creating_a_project_from_scratch

Bullet Physic Engine SDK

More Related Content

What's hot (19)

Viewers also liked (11)

Similar to Bullet Physic Engine SDK (20)

More from ナム-Nam Nguyễn (10)

Recently uploaded (20)

Bullet Physic Engine SDK