How to Make an Ammo.js Character Controller Jump

Implementing a jump mechanic with the btKinematicCharacterController in ammo.js (the WebIDL/Emscripten port of Bullet Physics) requires utilizing the controller’s built-in physics methods rather than manually applying forces. This article provides a direct guide and code examples demonstrating how to properly configure gravity, set jump velocity, and trigger a jump using the ammo.js API.

1. Set Up the Kinematic Character Controller

To enable jumping, you must first have a functioning btKinematicCharacterController paired with a btPairCachingGhostObject. During initialization, you must set the gravity and the jump speed for the character.

// Configuration variables
const stepHeight = 0.35;
const upAxis = 1; // 1 is the Y-axis

// Create the ghost object and shape
const ghostObject = new Ammo.btPairCachingGhostObject();
ghostObject.setWorldTransform(transform);
const shape = new Ammo.btCapsuleShape(radius, height);
ghostObject.setCollisionShape(shape);
ghostObject.setCollisionFlags(16); // CF_CHARACTER_OBJECT

// Create the character controller
const character = new Ammo.btKinematicCharacterController(
    ghostObject, 
    shape, 
    stepHeight, 
    upAxis
);

// Add to the physics world
physicsWorld.addCollisionObject(ghostObject, 32, -1); // Filter groups
physicsWorld.addAction(character);

2. Configure Jump Parameters

Before triggering a jump, you must define the gravity affecting the character and the initial vertical velocity of the jump. If gravity is not explicitly set on the character controller, the jump mechanic will not function correctly, as the controller handles its own gravity independently of the main physics world.

// Set gravity (typically matching your world gravity)
const gravity = 9.8 * 3; // Scale up for a less floaty feel
character.setGravity(gravity);

// Set the jump speed (initial upward velocity)
const jumpSpeed = 10.0; 
character.setJumpSpeed(jumpSpeed);

3. Triggering the Jump

To execute the jump, call the .jump() method. The btKinematicCharacterController handles the ground check internally. However, it is best practice to verify if the character is currently on the ground using .canJump() before calling the jump method to prevent infinite jumping in mid-air.

// Call this function inside your input listener or update loop
function handleJumpInput() {
    if (keysPressed['Space'] || controller.jumpRequested) {
        if (character.canJump()) {
            character.jump();
        }
    }
}

4. Updating the Physics World

Ensure your simulation step is running in your main render loop. The character controller will automatically update its position based on gravity and jump velocity during the physics step.

function update(deltaTime) {
    // Step the physics world
    physicsWorld.stepSimulation(deltaTime, 10);

    // Update your graphic mesh position to match the ghost object
    const ms = ghostObject.getWorldTransform();
    const origin = ms.getOrigin();
    const rotation = ms.getRotation();

    mesh.position.set(origin.x(), origin.y(), origin.z());
    mesh.quaternion.set(rotation.x(), rotation.y(), rotation.z(), rotation.w());
}