Bounce Character Controller

This project is a reference Typescript implementation of a character controller created using the Bounce physics library.

This implementation is heavily inspired by Jolt's reference character controller implementation, and has the following features:

• collision detection and resolution against all bounce shape and body types (e.g. height map, trimesh, etc)
• character applies forces to dynamic bodies (and vice versa)
• character can go up and down stairs
• character can go up and down slopes while sticking to floor
• character can jump while on the ground (air movement control is optional)

This library provides only the character controller logic and physics integration. Rendering and input handling are outside the scope of this library. You can find an example implementation that uses this library alongside basic keyboard + mouse input handling and rendering using ThreeJS at https://codeberg.org/perplexdotgg/bounce-character-controller-example/.

Although this is a fairly robust implementation, this is not intended as a game-ready implementation, rather it is intended as a starting point or reference for one.

Installation

For serious use, please fork and modify this library's source code. This package exists as a library mostly for prototyping convenience.

npm install @perplexdotgg/bounce-character-controller

Assumes you already have @perplexdotgg/bounce installed.

Usage

// initialization code
import { World } from '@perplexdotgg/bounce';
import CharacterController from '@perplexdotgg/bounce-character-controller';

const physicsWorld = new World();

const character = new CharacterController(physicsWorld, {
  inertiaDecayRate: 100,
  gravityScale: 1,
  walkingSpeed: 9,
  jumpingSpeed: 6,
  canControlMovementDuringJump: true,
  shouldCharacterStickToFloor: true,
});

const characterRadius = .4;
const characterHeight = .9;
const characterShape = physicsWorld.createCapsule({ radius: characterRadius, height: characterHeight });

// create the character
const characterBody = physicsWorld.createKinematicBody({
  shape: characterShape,
  position: [0, 10, 0],
  orientation: [0, 0, 0],
  belongsToGroups: NoneFlag,
  collidesWithGroups: NoneFlag,
});

character.setBody(characterBody);


// later, in your update function
// movementX and movementY should be in the range [-1, 1], representing the desired movement direction on the XZ plane
// (movementX, movementY) should already be normalized
character.setTargetMovement(movementX, movementY, isJumping);
character.update(deltaInSeconds);

// after the update(), you would put your code for updating your character mesh to the new position/orientation (i.e. copy from characterBody.position and characterBody.orientation)
characterMesh.position.copy(characterBody.position);
characterMesh.quaternion.copy(characterBody.orientation);

Default option values

{
  walkingSpeed: 30,
  jumpingSpeed: 15,
  gravity: { x: 0, y: -25, z: 0 },
  gravityScale: 1,
  inertiaDecayRate: 10,

  canControlMovementDuringJump: true,
  shouldCharacterStickToFloor: true,
  stickToFloorStepDownSpeed: 30,
  stickToFloorStepDownDistance: 0.5,

  shouldCharacterWalkStairs: false,
  walkStairsStepUpDistance: 0.4,
  walkStairsStepUpAmount: 0.4,
  walkStairsMinStepForward: 0.02,
  walkStairsStepForwardTest: 0.15,
  walkStairsCosAngleForwardContact: Math.cos(degreesToRadians(75)),
}

How to contribute

If you like this project and would like to support our work, please consider contributing code via pull requests, or donating via open collective. Contributions are greatly appreciated!