/cannon.js

A lightweight 3D physics engine written in JavaScript.

Primary LanguageJavaScriptMIT LicenseMIT

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.