Libgdx Bullet Physics

libGDX Bullet Physics Wrapper

Quick reference for the libGDX Bullet extension (com.badlogic.gdx.physics.bullet.*). This is a JNI wrapper around the C++ Bullet Physics library. All bt* objects are backed by native memory — the Java GC does NOT free them. Manual dispose() is mandatory.

Not supported on HTML5/GWT.

Gradle Dependencies

// core
api "com.badlogicgames.gdx:gdx-bullet:$gdxVersion"
// desktop
implementation "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-desktop"
// android (all four)
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-armeabi-v7a"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-arm64-v8a"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-x86"
natives "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-x86_64"
// ios
implementation "com.badlogicgames.gdx:gdx-bullet-platform:$gdxVersion:natives-ios"

Initialization

Bullet.init();  // MUST call before any bt* class. Loads native library. Segfault otherwise.

Three overloads:

Bullet.init()                                   // useRefCounting=false, logging=true
Bullet.init(boolean useRefCounting)              // logging=true
Bullet.init(boolean useRefCounting, boolean logging)

Call once in create(), guard against double-init. Reference counting enables automatic obtain()/release() on shared objects (e.g., btCompoundShape child shapes).

Dynamics World Setup

Five objects, created in this order:

btDefaultCollisionConfiguration collisionConfig = new btDefaultCollisionConfiguration();
btCollisionDispatcher dispatcher = new btCollisionDispatcher(collisionConfig);
btDbvtBroadphase broadphase = new btDbvtBroadphase();
btSequentialImpulseConstraintSolver solver = new btSequentialImpulseConstraintSolver();
btDiscreteDynamicsWorld world = new btDiscreteDynamicsWorld(
    dispatcher, broadphase, solver, collisionConfig);
world.setGravity(new Vector3(0, -10f, 0));  // takes libGDX Vector3, NOT btVector3

Constructor: btDiscreteDynamicsWorld(btDispatcher, btBroadphaseInterface, btConstraintSolver, btCollisionConfiguration). Parameter order is dispatcher, broadphase, solver, config.

Stepping

// 3-arg form (recommended):
world.stepSimulation(delta, maxSubSteps, fixedTimeStep);
// delta: frame time; maxSubSteps: catch-up limit; fixedTimeStep: physics tick (1/60f typical)

// Return value: int — number of substeps performed
float delta = Math.min(1f / 30f, Gdx.graphics.getDeltaTime());
world.stepSimulation(delta, 5, 1f / 60f);

DO NOT use the 1-arg form stepSimulation(delta) — it defaults maxSubSteps=1, so any frame taking longer than 1/60s loses simulation time. Always pass all three arguments.

Adding / Removing Bodies

world.addRigidBody(body);
world.addRigidBody(body, collisionGroup, collisionMask);  // group/mask are int (bit flags)
world.removeRigidBody(body);

There is NO removeAndDestroyBody() — you must remove then dispose separately.

Collision Shapes

All in com.badlogic.gdx.physics.bullet.collision. Constructors take libGDX Vector3 (not btVector3).

| Shape | Constructor | Notes | |---|---|---| | btBoxShape | (Vector3 halfExtents) | Half-extents, not full size | | btSphereShape | (float radius) | | | btCapsuleShape | (float radius, float height) | Y-axis. Also btCapsuleShapeX, btCapsuleShapeZ | | btCylinderShape | (Vector3 halfExtents) | Y-axis. Also btCylinderShapeX, btCylinderShapeZ | | btConeShape | (float radius, float height) | Y-axis. Also btConeShapeX, btConeShapeZ | | btConvexHullShape | () then addPoint(Vector3) | Or (FloatBuffer) — must be direct buffer | | btBvhTriangleMeshShape | (Array) | Static concave meshes only. libGDX convenience | | btCompoundShape | () | addChildShape(Matrix4 localTransform, btCollisionShape) |

Gotchas:

• btBvhTriangleMeshShape is for static geometry only — do not use for dynamic bodies.
• btConvexHullShape(FloatBuffer) requires a direct buffer (ByteBuffer.allocateDirect()).
• Capsule/Cylinder/Cone default to Y-axis. Use the X/Z suffixed classes for other axes.
• btCompoundShape.addChildShape() calls obtain() on child shapes when reference counting is enabled.

calculateLocalInertia

Vector3 localInertia = new Vector3();
shape.calculateLocalInertia(mass, localInertia);  // output parameter — writes into localInertia

On btCollisionShape. Must call for dynamic bodies (mass > 0). Static bodies use Vector3.Zero.

Rigid Bodies

Static vs Dynamic vs Kinematic

| Type | Mass | Inertia | Flags | Moved by | |---|---|---|---|---| | Static | 0 | Vector3.Zero | (auto CF_STATIC_OBJECT) | Nothing | | Dynamic | > 0 | calculateLocalInertia() | (none needed) | Physics | | Kinematic | 0 | Vector3.Zero | CF_KINEMATIC_OBJECT | Application code via MotionState |

Construction

Two patterns — both work. Direct construction bypasses the info object:

// Pattern 1: via ConstructionInfo (reusable for multiple bodies)
Vector3 localInertia = new Vector3();
shape.calculateLocalInertia(mass, localInertia);
btRigidBody.btRigidBodyConstructionInfo info =
    new btRigidBody.btRigidBodyConstructionInfo(mass, motionState, shape, localInertia);
info.setRestitution(0.5f);
info.setFriction(0.8f);
btRigidBody body = new btRigidBody(info);
info.dispose();  // can dispose after body creation

// Pattern 2: direct
btRigidBody body = new btRigidBody(mass, motionState, shape, localInertia);

btRigidBodyConstructionInfo is an inner class of btRigidBody. Constructor: (float mass, btMotionState motionState, btCollisionShape shape, Vector3 localInertia). The motionState parameter can be null — set it later via body.setMotionState().

Kinematic Body Setup

btRigidBody body = new btRigidBody(0f, motionState, shape, Vector3.Zero);
body.setCollisionFlags(body.getCollisionFlags()
    | btCollisionObject.CollisionFlags.CF_KINEMATIC_OBJECT);
body.setActivationState(Collision.DISABLE_DEACTIVATION);  // CRITICAL

Without DISABLE_DEACTIVATION, Bullet stops calling getWorldTransform() on the MotionState after the body sleeps — your kinematic body freezes.

Key btRigidBody Methods

// Forces (accumulated, applied at next step, cleared by clearForces)
body.applyCentralForce(Vector3 force);
body.applyForce(Vector3 force, Vector3 relPos);
body.applyTorque(Vector3 torque);
body.clearForces();

// Impulses (instant velocity change)
body.applyCentralImpulse(Vector3 impulse);
body.applyImpulse(Vector3 impulse, Vector3 relPos);

// Velocity
body.setLinearVelocity(Vector3 vel);
body.setAngularVelocity(Vector3 vel);

// Axis locking (e.g., 2D physics: lock Z axis)
body.setLinearFactor(new Vector3(1, 1, 0));
body.setAngularFactor(new Vector3(0, 0, 1));

// Damping
body.setDamping(float linearDamping, float angularDamping);

// Sleeping
body.setSleepingThresholds(float linear, float angular);
body.activate();  // wake up a sleeping body

btCollisionObject (base class)

body.setWorldTransform(Matrix4 transform);
body.getWorldTransform(Matrix4 out);    // output parameter form
Matrix4 t = body.getWorldTransform();   // allocating form

body.setUserValue(int value);           // int stored on native side — survives GC
int v = body.getUserValue();
body.userData = myObject;               // Java-only Object field — NOT on native side

body.setCollisionFlags(int flags);
body.setActivationState(int state);
body.isStaticOrKinematicObject();

Collision Flags (btCollisionObject.CollisionFlags)

| Constant | Value | Use | |---|---|---| | CF_STATIC_OBJECT | 1 | Auto-set for mass=0 bodies | | CF_KINEMATIC_OBJECT | 2 | Must set manually for kinematic | | CF_NO_CONTACT_RESPONSE | 4 | Trigger/sensor (detects but no physics response) | | CF_CUSTOM_MATERIAL_CALLBACK | 8 | Required for onContactAdded | | CF_CHARACTER_OBJECT | 16 | For character controllers |

Activation States (com.badlogic.gdx.physics.bullet.collision.Collision)

| Constant | Value | |---|---| | Collision.ACTIVE_TAG | 1 | | Collision.ISLAND_SLEEPING | 2 | | Collision.WANTS_DEACTIVATION | 3 | | Collision.DISABLE_DEACTIVATION | 4 | | Collision.DISABLE_SIMULATION | 5 |

MotionState

Syncs physics transform with render transform. Bullet calls setWorldTransform after simulating dynamic bodies, and getWorldTransform for kinematic bodies.

static class MyMotionState extends btMotionState {
    private final Matrix4 transform;  // share with ModelInstance.transform

    public MyMotionState(Matrix4 transform) {
        this.transform = transform;
    }

    @Override
    public void getWorldTransform(Matrix4 worldTrans) {
        worldTrans.set(transform);  // Bullet reads from your transform (kinematic)
    }

    @Override
    public void setWorldTransform(Matrix4 worldTrans) {
        transform.set(worldTrans);  // Bullet writes its result (dynamic)
    }
}

// Usage — share the ModelInstance's transform matrix:
MyMotionState motionState = new MyMotionState(modelInstance.transform);
btRigidBody body = new btRigidBody(mass, motionState, shape, localInertia);

btDefaultMotionState also exists (com.badlogic.gdx.physics.bullet.linearmath) but the custom pattern above is standard in libGDX because it shares the Matrix4 directly with ModelInstance.

Gotcha: MotionState takes com.badlogic.gdx.math.Matrix4 — the wrapper converts to/from native Bullet transforms automatically.

Contact Detection

ContactListener

com.badlogic.gdx.physics.bullet.collision.ContactListener — instantiate to enable globally. Only one overload per callback event.

Four event types, each with multiple overloads (btCollisionObject, userValue int, or btCollisionObjectWrapper variants). The int userValue variants are fastest (no JNI object mapping).

ContactListener contactListener = new ContactListener() {
    @Override
    public boolean onContactAdded(int userValue0, int partId0, int index0,
            boolean match0, int userValue1, int partId1, int index1, boolean match1) {
        // match0/match1 = true if that object's flag matched the other's filter
        if (match0) { /* userValue0's object was matched */ }
        return true;
    }
};

Filtering setup:

body.setContactCallbackFlag(1  instances` keyed by native pointer. This keeps Java wrappers alive while Bullet references them. Disposal removes the entry.

`userData` is a Java-only `Object` field — invisible to native code. Use `setUserValue(int)` for data that must survive on the native side (e.g., entity array index for fast ContactListener lookups).

### Reference Counting (optional)

```java
Bullet.init(true);  // enable ref counting
shape.obtain();     // +1
shape.release();    // -1, auto-disposes at 0

btCompoundShape.addChildShape() auto-calls obtain() on child shapes when enabled.

Advanced Topics (brief)

Constraints: btPoint2PointConstraint, btHingeConstraint, btConeTwistConstraint, btSliderConstraint, btGeneric6DofConstraint, btGeneric6DofSpringConstraint, btGeneric6DofSpring2Constraint, btFixedConstraint. Add via world.addConstraint(constraint, disableCollisionBetweenBodies). Remove before disposing world.

Character controller: btKinematicCharacterController with btPairCachingGhostObject. Requires btGhostPairCallback registered on the broadphase's overlapping pair cache (broadphase.getOverlappingPairCache().setInternalGhostPairCallback(new btGhostPairCallback())). Works with any broadphase including btDbvtBroadphase. Added to world via world.addAction(controller).

Collision-only world: Use btCollisionWorld (3-arg constructor: dispatcher, broadphase, config — no solver) for collision detection without dynamics.

InternalTickCallback: Override onInternalTick(btDynamicsWorld, float timeStep) for per-substep callbacks. Attach as pre-tick or post-tick.

Soft bodies, vehicles: Available in the wrapper but advanced — consult the Bullet C++ documentation.

Common Mistakes

1. Forgetting Bullet.init() — Any bt* class instantiated before init() causes a segfault. Call it once in create().
2. Not disposing bt* objects — Native memory leak. Every bt* object, ray callback, MotionState, and ConstructionInfo needs dispose(). Java GC does NOT free the native allocation reliably.
3. Wrong disposal order — Disposing the world while bodies are still in it, or disposing shapes while bodies reference them, causes crashes. Remove all bodies first, then dispose in reverse creation order.
4. Skipping calculateLocalInertia() for dynamic bodies — Body will have zero inertia and won't rotate or respond to off-center forces correctly. Always call shape.calculateLocalInertia(mass, outVector) when mass > 0.
5. Using 1-arg stepSimulation(delta) — Defaults maxSubSteps to 1. Any frame longer than 1/60s loses simulation time. Always use the 3-arg form.
6. Forgetting DISABLE_DEACTIVATION on kinematic bodies — Bullet deactivates the body and stops calling getWorldTransform(). The kinematic body appears frozen.
7. Not resetting ray callbacks before reuse — ClosestRayResultCallback retains state from the previous test. Must call setCollisionObject(null) and setClosestHitFraction(1f) before each rayTest().
8. Disposing ConstructionInfo with shared MotionState/shape references — btRigidBodyConstructionInfo does NOT take ownership. The MotionState and shape must outlive the body. Dispose the info early if you want, but keep the shape and MotionState alive.
9. Expecting Box2D-style pixels-per-meter scaling — Bullet uses real-world units (meters). No PPM conversion needed. A 1-unit box is 1 meter.
10. Sharing btBvhTriangleMeshShape with dynamic bodies — Concave triangle mesh shapes are static-only. Use btConvexHullShape or btCompoundShape for dynamic bodies.
11. Forgetting CF_CUSTOM_MATERIAL_CALLBACK for onContactAdded — The callback silently never fires. At least one colliding body must have this flag set.
12. Storing Java references only in userData — This field is Java-only. For ContactListener performance, use setUserValue(int) to store an entity index, then look up your game object from an array.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kyu-n
• Source: kyu-n/gdx-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.