How to add Libbulletjme to an existing project

Adding Libbulletjme to an existing Java project is a 7-step process:

  1. Add the JVM library to the classpath.

  2. Download an appropriate native library.

  3. Load the native library.

  4. Create and configure a physics space.

  5. Create and configure collision objects and add them to the physics space.

  6. Simulate the physics space.

  7. Test and tune as necessary.

Add JVM library to classpath

Gradle-built projects

Add to the project’s "build.gradle" or "build.gradle.kts" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:Libbulletjme:21.2.1")
}

For some older versions of Gradle, it’s necessary to replace implementation with compile.

Maven-built projects

Add to the project’s "pom.xml" file:

<repositories>
    <repository>
      <id>mvnrepository</id>
      <url>https://repo1.maven.org/maven2/</url>
    </repository>
</repositories>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>Libbulletjme</artifactId>
  <version>21.2.1</version>
</dependency>

Ant-built projects

Download the Libbulletjme library from GitHub:

You’ll definitely need the class JAR ("Libbulletjme-21.2.1.jar") and probably the "-sources" and "-javadoc" JARs as well.

Open the project’s properties in the NetBeans IDE:

  1. Right-click on the project (not its assets) in the "Projects" window.

  2. Select Properties to open the "Project Properties" dialog.

  3. Under "Categories:", click on Libraries.

  4. Click on the Compile tab.

  5. Add the Heart class JAR:

    1. Click on the Add JAR/Folder button.

    2. Navigate to the download directory.

    3. Select the "Libbulletjme-21.2.1" file.

    4. Click on the Open button.

  6. (optional) Add JARs for javadoc and sources:

    1. Click on the Edit button.

    2. Click on the Browse…​ button to the right of "Javadoc:"

    3. Select the "Libbulletjme-21.2.1-javadoc.jar" file.

    4. Click on the Open button.

    5. Click on the Browse…​ button to the right of "Sources:"

    6. Select the "Libbulletjme-21.2.1-sources.jar" file.

    7. Click on the Open button button again.

    8. Click on the OK button to close the "Edit Jar Reference" dialog.

  7. Click on the OK button to exit the "Project Properties" dialog.

Download a native library

Pre-built native libraries can be downloaded from GitHub:

You don’t need all 56 native libraries. Start with the "DebugSp" library for your development environment, for instance:

  • "Linux64DebugSp_libbulletjme.so" for Linux on x86_64

  • "Windows64DebugSp_libbulletjme.so" for 64-bit Windows

Load the native library

Load Libbulletjme’s native library before instantiating any physics objects:

import com.jme3.system.NativeLibraryLoader;
NativeLibraryLoader.loadLibbulletjme(true, downloadDirectory, "Debug", "Sp");

Create a physics space

There are many constructors and options. Here’s the simplest way:

import com.jme3.bullet.PhysicsSpace;
PhysicsSpace physicsSpace = new PhysicsSpace(PhysicsSpace.BroadphaseType.DBVT);

Create and add objects

Collision objects come in many different types:

  • bodies (PhysicsBody)

    • soft bodies (PhysicsSoftBody)

      • deformables (ReducedDeformableBody)

    • rigid bodies (PhysicsRigidBody)

      • vehicles (PhysicsVehicle)

  • ghost objects (PhysicsGhostObject)

  • characters (PhysicsCharacter)

  • colliders (MultiBodyCollider)

Here’s a code fragment that creates 2 objects, a ghost object and a rigid body that share a common shape:

float radius = 2f;
CollisionShape sphere2 = new SphereCollisionShape(radius);
PhysicsGhostObject ghost1 = new PhysicsGhostObject(sphere2);
float mass = 1f;
PhysicsRigidBody body1 = new PhysicsRigidBody(sphere2, mass);

Collision objects aren’t simulated unless they’re added to a physics space. The best way is to use addCollisionObject():

physicsSpace.addCollisionObject(ghost1);
physicsSpace.addCollisionObject(body1);

Simulate the physics space

To simulate a single 20-millisecond step:

float timeStep = 0.02f; // in seconds
int maxSteps = 0; // for a single step of the specified duration
physicsSpace.update(timeStep, maxSteps);

In real-time simulation, the interval between updates will vary. However, it’s best to use steps of equal size.

To attempt simulation of a specific time interval using the configured step size:

physicsSpace.update(intervalSeconds);

HelloLibbulletjme

HelloLibbulletjme (also in Kotlin) is a complete console application (no graphics) that serves as a starting point for using Libbulletjme.

It illustrates:

  1. loading a native library from the "~/Downloads" directory

  2. creating a PhysicsSpace

  3. creating 2 collision objects and adding them to the space

  4. simulating 50 steps

HelloLibbulletjme is the first in a series of tutorial apps designed for hands-on learning. I expect you to not only study the source code, but to actually run the app as well. Take time now to set up a software development environment for this purpose!

For instance, if you install Git and a Java Development Kit, you should be able to launch tutorial apps from a command shell, like so:

  1. git clone https://github.com/stephengold/LbjExamples.git

  2. cd LbjExamples

  3. ./gradlew :apps:HelloLibbulletjme

Summary

  • Two libraries are required: a JVM library and a native library.

  • Collision objects aren’t simulated unless they’re added to a space.