Bullet Physics In Unity 3D

The high performance open source Bullet Physics library now available within Unity. Wanting more flexibility than I could get using PhysX, I started this Unity port of the open source BulletSharp project. Bullet Physics is compiled as a native plugin and accessed from unity scripts using C# PInvoke wrappers.

Thanks for this project goes to Andres Tracks, the author of the BulletSharp wrappers that wrap the Bullet Physics library so that it can be accessed from C# code. Thanks also to the original author of Bullet Physics, Erwin Coumans.

Quickstart

You can access the Bullet Physics For Unity project in github:

Latest Bleeding Edge Build:

https://github.com/Phong13/BulletSharpUnity3d

It is also available as a free asset in the Unity Asset Store:

Bullet Physics For Unity

The project contains:

Native Bullet Physics plugins for x86, x64, iOS, Android, OSX
C# wrappers for the native plugins
Demos
Unity Bullet Components (WIP)

Bullet Unity Contains Two APIs

BulletSharp – Located in Plugins/BulletSharp is a low level set of C# wrappers for the native bullet libraries. These wrappers are not integrated with Unity in any way. Simulations can be run that are not synchronized with Unity’s game loop. The demos in BulletUnity/Examples/Scenes/BulletSharpDemos use this API.
BulletUnity – Located in BulletUnity/Scripts is a set of Unity Components similar to the PhysX components. These components use the lower level BulletSharp API. These components are synchronized with Unity’s FixedUpdate loop.

Sources Of Information

The BULLET PHYSICS MANUAL (download it from the Bullet Physics project on github). This can be read in about 1 hour, and will set you up well for working with Bullet Physics.

The Bullet Physics Wiki has a lot of good information http://bulletphysics.org/mediawiki-1.5.8/index.php/Main_Page.

The Bullet Physics Forums http://www.bulletphysics.org/Bullet/phpBB3/

The Bullet Physics Examples (ported to C#, then ported to Unity) located in the BulletUnity/Examples/Scenes/BulletSharpDemos folder. More are available in the https://github.com/Phong13/BulletSharpPInvoke project.

DON’T BE AFRAID TO LOOK AT THE BULLET PHYSICS SOURCE CODE. I know it sounds intimidating, but it is much easier than you think. If you are not sure what an API call or class does or what a member variable is for, then search for it in the bullet sourcecode. Even if you are not a C++ programmer you can probably deduce
what it does. I recently spent a few hours on google trying to find good information explaining the difference between btGhostObject and btPairCachingGhostObject. Eventually I opened the btGhostObject.cpp source file and had a look. The entire sourcecode for both classes is only 170 lines. In about 10 minutes I had a complete understanding how both classes worked. Much better than an online tutorial.

It is possible to debug from Unity into the Bullet Physics library native code with Visual Studio (probably possible with other IDEs but I havn’t tried). To do this you need to clone the https://github.com/Phong13/BulletSharpPInvoke project. Build a debug, x64 version of libbulletc for windows. Copy the .dll and .pdb file to Unity project (Plugins/Native/x64. Then launch Unity from the Visual Studio as described here https://msdn.microsoft.com/en-us/library/605a12zt.aspx.

Important Differences From Unity’s PHYSX

Do NOT try to move the rigid bodies by writing to myRigidBody.transform.position or .rotation. Bullet Physics is not as tightly integrated with Unity as PhysX. Consider the transform to be completely under the control of Bullet Physics (for non-kinematic RigidBodies) and translate/rotate your rigidBodies using the Bullet Physics API calls.

Be careful of localScale. It is almost completely ignored by Bullet Physics. There are only a few CollisionShapes that can be scaled in the Bullet API (at the time of writing these have not been implemented in Unity). Modify the shape of the CollisionShape and leave localScale at 1,1,1. You can add your MeshRender as a child of
the CollisionShape and scale that.

Don’t try to nest Rigid Bodies. Bullet Unity has no control over the order that bullet updates the transforms of objects each simulation step. If the child RigidBodies get updated before the parent RigidBodies then the child will jitter terribly.

WRONG