cannon.js

Lightweight 3D physics for the web

Inspired by three.js and ammo.js, and driven by the fact that the web lacks a physics engine, here comes cannon.js.

Demos - Documentation - Rendering hints - NPM package

Usage

Download the library and include it in your html. Alternatively, build the library yourself (see Makefile).

<script src="cannon.js"></script>

The code below creates a sphere on a plane, steps the simulation, and prints the sphere simulation to the console.

// Setup our world
var world = new CANNON.World();
world.gravity.set(0,0,-9.82);
world.broadphase = new CANNON.NaiveBroadphase();
    
// Create a sphere
var mass = 5, radius = 1;
var sphereShape = new CANNON.Sphere(radius);
var sphereBody = new CANNON.RigidBody(mass,sphereShape);
sphereBody.position.set(0,0,10);
world.add(sphereBody);
    
// Create a plane
var groundShape = new CANNON.Plane();
var groundBody = new CANNON.RigidBody(0,groundShape);
world.add(groundBody);
    
// Step the simulation
setInterval(function(){
  world.step(1.0/60.0);
  console.log("Sphere z position: " + sphereBody.position.z);
}, 1000.0/60.0);

If you want to know how to use cannon.js with a rendering engine, for example Three.js, see the Examples.

Supported contact shape pairs

	Sphere	Plane	Box	Compound	Convex¹	Particle
Sphere	Yes	Yes	Yes	Yes	Yes	Yes
Plane	-	-	Yes	Yes	Yes	Yes
Box	-	-	Yes	Yes	Yes	Yes
Compound	-	-	-	Yes	Yes	Yes
Convex¹	-	-	-	-	Yes	Yes
Particle	-	-	-	-	-	-

¹ including Cylinder

Change log

Current

Changed API for adding forces and impulses to a body. See RigidBody.addImpulse and RigidBody.addForce.
Removed World.collision_matrix and instead added World.collisionMatrix and World.collisionMatrixPrevious. They both now work with body indices instead of body IDs.
Added SPHSystem.
Renamed RigidBody.calculateAABB to .computeAABB. Added RigidBody.aabbNeedsUpdate.
Added Broadphase.useBoundingBoxes, .doBoundingBoxBroadphase and .intersectionTest.
ConvexPolyhedron constructor now calculates normals instead of taking them as a parameter.
Added Body.collisionFilterGroup and Body.collisionFilterMask.
Added GridBroadphase, though it only supports Plane and Sphere for now.
Removed World.temp.
Reuse of various event objects to minimize object creation in the step loop.
Removed unused class ContactPoint.
Changed the signature of Broadphase.collisionPairs to Broadphase.collisionPairs(world,pairs1,pairs2), removing the need of an array return value.

0.5.0

Changed unit of sleep properties in Particle to seconds instead of milliseconds, made Particle.sleepState public. (schteppe,airbaggins).
Changed property Shape.boundingSphereRadius to being a number, added method Shape.computeBoundingSphereRadius and .boundingSphereRadiusNeedsUpdate
Removed Box.getCorners
Added properties to ContactMaterial: .contactEquationStiffness, .contactEquationRegularizationTime, .frictionEquationStiffness, .frictionEquationRegularizationTime to be able to control settings for the on-the-fly created contact constraints
Renamed the solver parameter "damping" to "regularizationTime", since it is a more correct name.
Solver parameters (stiffness, damping etc) were moved from Solver to Equation. Now you control the solver parameters per constraint instead of globally.
Added HingeConstraint and its Constraint base class
Added contact support for all possible Shape.types (see table above).
Fixed convex contact bugs.
Added method ConvexPolyhedron.getAveragePointLocal.
Added method ConvexPolyhedron.transformAllPoints.
Added SplitSolver.
Removed use of typed arrays, since they are slower than ordinary ones.
Corrected applying of linear and angular damping, should now be physically correct and independent of timestep size.
Renamed Solver to GSSolver, made Solver a base class instead.
Added method Mat3.setTrace
ContactGenerator now produces ContactEquation instead of ContactPoint
Added property Solver.tolerance
Changed default Solver parameter values
Improved Solver algorithm, the parameters .a, .b, .k, .d, .eps do not have the same effect anymore.
Rewrote Solver, Equation and Constraint totally, broke backward compatibility.
Added property World.enableImpulses - still an experimental feature
Added PointToPointConstraint
Added Cylinder.
Added method RigidBody.applyImpulse
Added "iterator" method Box.forEachWorldCorner
Added "abstract method" Shape.calculateWorldAABB and implemented it in subclasses.
Removed Plane.normal in favor of RigidBody.quaternion. One way to rotate a plane is enough.

0.4.3

World now dispatches "preStep" and "postStep" events.
Introduced Body and Particle. New inheritance: Body -> Particle -> RigidBody.
Added Quaternion.toAxisAngle()
Added Ray. Basic hit testing for ConvexPolyhedra.
RigidBody now dispatches the following events: "collide", "sleep", "sleepy", "wakeup"
Added Solver.setSpookParams(k,d) and removed SPOOK param things from World.
Sleep functionality for RigidBody

0.4.2 2012-08-06

Code seem stable enough to start a change log.

Todo

The simpler todos are marked with @todo in the code. Github Issues can and should also be used for todos.

Help

Create an issue on here if you need help.