Bullet Physics and jBullet Physics Engine

 

Bullet Physics

Bullet Physics is an open-source collision detection, rigid body and soft body dynamics library. It can be used as the physics engine in a complex 3D game or animation, complimentary the game engine. The mother site is http://bulletphysics.org/wordpress/. The main task of physics engine is perform collision detection, resolve collisions and other constraints, and update the states for all the objects.

How to Install and Get Started

Step 1: Download and Unzip - From http://bulletphysics.org ⇒ Download ⇒ Select the ZIP source file ⇒ Download and unzip into a directory of your choice, e.g., d:\myproject. Bullet physics shall be unzipped into "d:\myproject\bullet-2.xx". I shall refer to this directory as the Bullet Physics installed directory.

Step 2: Read - Read the "User Manual" available at the installed directory.

Step3: Install CMake - We need CMake to build the Bullet Physics. Get Cmake from http://cmake.org ⇒ Download ⇒ Choose "Binary distributions" ⇒ Window ZIP ⇒ Unzip in a directory of your choice (e.g., d:\myproject).

Step 4: Build Bullet Physics using CMake

  1. Run "cmake-gui.exe" (under the CMake "bin" directory).
  2. In "Where is the source code", click "Browse source" and select the Bullet Physics installed directory (NOT src).
  3. In "Where to build the binaries", select a directory (e.g., d:\myproject\bullet-physics-2.xx-cmake_vc9) ⇒ Configure.
  4. In "Specify the generator for this project", choose your target platform, e.g., "Visual Studio 9 2008" ⇒ Finish.
  5. Set your "CMAKE_INSTALL_PREFIX", e.g., d:\myproject\bullet-physics-2.xx-cmake_vc9, "LIBRARY_OUTPUT_DIRECTORY", d:\myproject\bullet-physics-2.xx-cmake_vc9\lib ⇒ Configure ⇒ Generate ⇒ Close CMake.
  6. In CMake build target (bullet-physics-2.xx-cmake_vc9), start "BULLET_PHYSICS.sln" (double-click to launch the VC) ⇒ Build ⇒ Build Solution. The ".lib" will built under bullet-physics-2.xx-cmake_vc9\bin\debug.

Step 5: Write a Hello-world Bullet Physics Program

  1. Create a new solution/project: Launch VC ⇒ File ⇒ New Project ⇒ In "Project Types", select "Win32" ⇒ In "Templates", select "Win32 Console Application" ⇒ In "Location", select your working directory ⇒ In "Solution Name", enter "TestBulletPhysics", and check "Create directory for solution" ⇒ In "Name", enter "Helloworld" ⇒ Next ⇒ In "Application Type", choose "Console application" ⇒ In "Additional options", choose "Empty project".
  2. Create a new source file: Right-click on "Source Files" ⇒ Add ⇒ New Item... ⇒ In "Name", enter "Helloworld.cpp". Look for "Helloworld.cpp" from the demos (under "bullet-2.xx\Demos\HelloWorld"), and copy all the codes.
  3. Specify the include-path for header "btBulletDynamicsCommon.h": Right-click on the project ⇒ Properties ⇒ Configuration Properties ⇒ C/C++ ⇒ General ⇒ Additional Include Directories ⇒ Enter bullet's source directory (e.g., d:\myproject\bullet-2.77\src - you can see that the header needed is kept here).
  4. Include the bullet's libraries (BulletCollision, BulletDynamics and LinearMath): Two ways:
    1. Add the CMake generated project files: File ⇒ Add ⇒ Existing Project... ⇒ select CMake target's src/BulletCollision/BulletCollision.vcproj, src/BulletDynamics/BulletDynamics.vcproj and src/LinearMath/LinearMath.vcproj ⇒ Right-click on the project "Helloworld" ⇒ Project Dependencies ⇒ Check the above three projects.
    2. Use the libraries generated: Right-click on the project ⇒ Properties ⇒ Configuration Properties ⇒ Linker ⇒ General ⇒ In "Additional Library directories", enter d:\myproject\bullet-2.xx-cmake-vc9\lib\Debug (the libraries built in the earlier step) ⇒ In "Use Library Dependency Inputs", select "Yes". In Linker ⇒ Input ⇒ In "Additional Dependencies", enter "BulletCollision.lib BulletDynamics.lib LinearMath.lib" (VS requires ".lib" extension; Unixes do not).
  5. Build the project, and run the program.

Try other demos source provided, in particular, BasicDemo, which requires many more libraries.

jBullet

jBullet is a Java port of Bullet Physics. The mother site is at http://jbullet.advel.cz.

How to Install and Get Started

Step 1: Download and Unzip - Download jBullet from http://jbullet.advel.cz, and upzip into a directory of your choice, e.g., d:\myproject. jBullet shall be unzipped into d:\myproject\jbullet-2010xxxx.

Step 2: Try the Demo: To run the demo program in Eclipse:

  1. Create a New Project ⇒ Create a package called com.bulletphysics.demos, copy all the demo codes (all the directories under d:\myproject\jbullet-2010xxxx\src\com\bulletphysics\demos) under this package.
  2. Include External JAR Files: Right-click on the project ⇒ Build Path ⇒ Add External Archives ⇒ Navigate to select the distributed JAR files under the "lib" directory (d:\myproject\jbullet-20101010\lib). You should include asm-all-3.1.jar, stack-alloc.jar, jinput.jar, lwjgl.jar, lwjgl_util.jar, swing-layout-1.0.3.jar and vecmath.jar.
  3. Include Native Libraries for lwjgl.jar: Right-click on the lwjgl.jar ⇒ Build Path ⇒ Configure Build Path... ⇒ Open lwjgl.jar node ⇒ Select "Native Library Location" ⇒ Edit ⇒ In "Location Path", enter "d:/project/jbullet-20101010/lib/lwjgl/win32".

Using jStackAlloc

jBullet author also created a library called jStackAlloc, which allocates objects on the method's stack instead of program heap. This improves real-time performance by reducing the frequency of garbage collection. jStackAlloc uses a JDK 1.5 feature called Instrument to modify the bytecodes.

Writing a Program that uses jStackAlloc:

  1. Create a project. Add External Archive jstack-alloc.jar, asm-all-3.1.jar, vecmath.jar and ant.jar (select from the Eclipse plug-in).
  2. Write a test program as follows: 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
    		 
    package mytest;
import javax.vecmath.Vector3f;
import cz.advel.stack.Stack;
 
public class TestJStackAlloc {
 
   public static void main(String[] args) {
      Vector3f tmp = Stack.alloc(Vector3f.class);
      tmp.set(1, 2, 3);
      System.out.println(tmp.x);
      System.out.println(tmp.y);
      System.out.println(tmp.z);
   }
}
    The above program allocate Vector3f (of javax.vecmath) in stack, instead of the heap. You can also use your own class instead of Vector3f (with some restrictions on the class design - see jStackAlloc documentation).
  3. You cannot run the program directly, as jStackAlloc need to perform so-called instrumentation, which modifies the byte-code. You can then run the modified bytecodes. Write a ANT build file (build.xml) as follows, which invoke the Instrumentation task on the compiled classes and then run from the instrumented-classes. 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    		 
    <?xml version="1.0" encoding="UTF-8"?>
<project name="javabullet" default="run" basedir=".">
   <path id="myclasspath">
       <pathelement path="bin"/>
       <pathelement location="d:\myproject\jbullet-20101010\lib\jstackalloc\stack-alloc.jar/" />
       <pathelement location="d:\myproject\jbullet-20101010\lib\ASM3.1\asm-all-3.1.jar" />
       <pathelement location="d:\myproject\jbullet-20101010\lib\vecmath\vecmath.jar" />
   </path>
 
   <target name="instrument-classes" >
      <taskdef name="instrument-stack"
         classname="cz.advel.stack.instrument.InstrumentationTask"
         classpathref="myclasspath" >
      </taskdef>
      <instrument-stack dest="bin" packageName="mytest">
         <fileset dir="bin" includes="**/*.class" />
      </instrument-stack>
   </target>
 
   <target name="run" depends="instrument-classes">
      <java classname="mytest.TestJStackAlloc"
         classpathref="myclasspath"
         fork="true" failonerror="true" >
      </java>
   </target>
</project>

Using jBullet on Android

JBullet works on Android.

[TODO] Helloworld

[TODO] BasicDemo

 

REFERENCES & RESOURCES

Latest version tested: Bullet Physics 2.77, JBullet 20101010
Last modified: November, 2010