cannon-es Documentation

Bodies in cannon-es behave differently based on their mass and type:

1. Dynamic Bodies: Have a mass greater than 0. They are affected by forces (like gravity) and velocity.
2. Static Bodies: Have a mass of 0 (or are explicitly set to CANNON.Body.STATIC). They are not affected by forces or velocity and remain fixed in position.
3. Kinematic Bodies: Are not affected by forces but can have a velocity and move around manually.

To create a static body, you can either set mass: 0 or use the type property:

const groundBody = new CANNON.Body({
  type: CANNON.Body.STATIC,
  shape: new CANNON.Plane(),
})

You can install cannon-es using yarn:

yarn add cannon-es

cannon-es only computes physics math and does not handle rendering. To visualize bodies, you must manually sync the position and rotation of a three.js mesh with the CANNON.Body every frame.

1. Create a corresponding mesh in three.js (e.g., THREE.Mesh).
2. In your animation loop, after calling world.fixedStep(), copy the body's position and quaternion to the mesh.

// Inside the animation loop
function animate() {
  requestAnimationFrame(animate)

  // 1. Step the physics world
  world.fixedStep()

  // 2. Copy physics data to the visual mesh
  sphereMesh.position.copy(sphereBody.position)
  sphereMesh.quaternion.copy(sphereBody.quaternion)

  // 3. Render the three.js scene
  renderer.render(scene, camera)
}

You can import cannon-es using standard ESM imports. If you are using a bundler like Webpack, you can import the entire namespace to take advantage of tree shaking.

For specific imports:

import { World } from 'cannon-es'

// ...

For namespace imports (Webpack compatible):

import * as CANNON from 'cannon-es'

// ...

To start a simulation, create a new CANNON.World instance. You can configure the global gravity using a CANNON.Vec3. Note that cannon-es uses SI units (meters, kilograms, seconds).

const world = new CANNON.World({
  gravity: new CANNON.Vec3(0, -9.82, 0), // m/s²
})

The RaycastVehicle class is a helper for simulating vehicles by casting rays from wheel positions towards the ground to apply suspension and friction forces. It requires a chassisBody (a Body instance) and allows you to define the vehicle's orientation using axis indices.

To use it, instantiate the class with a chassis body, add wheels using addWheel(), and then add the vehicle to the physics World using addToWorld(world). This automatically registers a preStep listener to update the vehicle's physics every frame.

Note on Rendering: During each simulation step, wheel transforms are updated before the chassis. To ensure wheels are rendered at their correct positions, you must call updateWheelTransform(wheelIndex) for each wheel manually before your rendering loop.

The World class extends EventTarget, allowing you to listen for collision events.

Body Collision

• collide: Dispatched on a Body when it collides with another body.

Contact Events

• beginContact: Dispatched when two bodies start colliding.
• endContact: Dispatched when two bodies stop colliding.
• beginShapeContact: Dispatched when two specific shapes start colliding.
• endShapeContact: Dispatched when two specific shapes stop colliding.

Event Data Structure:

• beginContact / endContact events provide bodyA and bodyB properties.
• beginShapeContact / endShapeContact events provide bodyA, bodyB, shapeA, and shapeB properties.

To optimize performance, cannon-es allows bodies to "sleep" when they are not moving significantly.

Sleep States

• Body.AWAKE: The body is actively being simulated.
• Body.SLEEPY: The body's speed is below sleepSpeedLimit but it hasn't been sleepy long enough to fall asleep.
• Body.SLEEPING: The body has been sleepy for longer than sleepTimeLimit and is now stationary/immovable.

Controlling Sleep

• wakeUp(): Manually wakes a sleeping body.
• sleep(): Manually forces a body into the sleeping state.
• allowSleep: A boolean property to enable/disable automatic sleeping.

The Body.type determines how the object behaves in the physics simulation:

• Body.DYNAMIC: Fully simulated. Responds to forces and collisions. Must have a finite, non-zero mass. Can collide with all body types.
• Body.STATIC: Does not move during simulation (behaves as if it has infinite mass). Can be moved manually by setting its position. Velocity is always zero. Does not collide with other static or kinematic bodies.
• Body.KINEMATIC: Moves according to its velocity but does not respond to forces. Behaves as if it has infinite mass. Can be moved manually. Does not collide with other static or kinematic bodies.

Rigid Bodies are the entities simulated in the world. You define them using the CANNON.Body class, specifying a mass and a shape (such as CANNON.Sphere, CANNON.Box, or CANNON.Plane). After creation, you must add them to the world using world.addBody(body).

const radius = 1 // m
const sphereBody = new CANNON.Body({
  mass: 5, // kg
  shape: new CANNON.Sphere(radius),
})
sphereBody.position.set(0, 10, 0) // m
world.addBody(sphereBody)