Libbulletjme project overview

Libbulletjme is a 3-D physics simulation library for Java.

Use it to:

  • add solidity to walls, characters, projectiles, landscapes, and vehicles,

  • detect collisions between complex shapes,

  • perform contact, ray, and sweep tests,

  • simulate characters and buildings collapsing in real time, and

  • simulate cloth, rope, and deformable volumes, including their interactions with rigid bodies and each other.

Tutorials and example apps are provided to help you get started.

All software in the Libbulletjme project is free and open-source, including the JVM library, the native libraries, the demo and tutorial apps, and the software used to build, test, and run them.

The underlying simulation software comes from Bullet, a mature real-time physics simulator. But although Bullet is written in C++, you won’t need any knowledge of C++ to use Libbulletjme.

Libbulletjme also incorporates source code from the V-HACD project and the SimMath library.

Caveats

Libbulletjme’s focus is on simulating classical mechanics in just enough detail to add verisimilitude to 3-D games. It’s not intended for 2-D platformers, nor for scientific research. For 2-D physics, consider using dyn4j instead.

Libbulletjme and its documentation assume a certain level of proficiency with the Java programming language. This project isn’t aimed at non-programmers, nor developers without prior Java experience. Similarly, some familiarity with 3-D graphics and vector math is assumed.

While an understanding of classical mechanics is assumed, many of its technical terms are linked (at first use) to the relevant article in the English Wikipedia.

The library’s mixed open-source license disclaims liability for defects. Please don’t use this software in safety-critical applications.

Starting with version 16.1.0, Libbulletjme is no longer compatible with old versions of the "libc" library found on systems such as CentOS 7 and Ubuntu 16.04 (Xenial).

What’s missing

Bullet is a large project, and Libbulletjme doesn’t yet provide access to all its features. In particular:

  • btRigidBodyConstructionInfo

  • "additional damping" for rigid bodies

  • Bullet’s debug drawer (but see the SPORT and V-Sport graphics engines)

  • serialization (file loader) for classes other than btOptimizedBvh

  • certain constraints:

    • btFixedConstraint

    • btUniversalConstraint

  • certain collision shapes:

    • btCompoundFromGimpactShape

    • btConvexPointCloudShape

    • btConvexTriangleMeshShape

    • btGImpactCompoundShape

    • btMultimaterialTriangleMeshShape

    • btScaledBvhTriangleMeshShape

    • btSdfCollisionShape

    • btTriangleShape

    • btUniformScalingShape

  • certain world types:

    • btSimpleDynamicsWorld

    • btSoftMultiBodyDynamicsWorld

  • inverse dynamics

  • Bullet v3

  • Bullet extras, examples, and tests (but see the Java examples in LbjExamples)

Furthermore, Libbulletjme hasn’t yet been ported to the following platforms:

  • the FreeBSD and iOS operating systems

  • Windows-on-ARM

  • MIPS, POWER, RISC-V, and System Z architectures

We welcome suggestions concerning the future development of Libbulletjme.

Getting help

For self-help, make use of the tutorials, the javadoc, and the source code.

For issues that are best handled privately, contact Stephen by e-mail. His personal e-mail address appears on his homepage and in the source code.

The name

The project’s (somewhat awkward) name reflects that fact that it was originally created for the JMonkeyEngine (JME) game engine.

Despite its history, Libbulletjme is self-contained; it doesn’t depend on JME. If you’re seeking a physics engine that’s integrated with JME, please consider Minie.

Next steps

If you’re curious how Libbulletjme works, proceed to the Implementation page.

To gain hands-on experience, proceed to the first tutorial page.