Basic Usage

Hello, world - Setting the stage

The foundation for all physics simulations is a world object. You must create a world,
add objects and behaviors, and then advance the simulation.

There are several ways to create a world object, all of which involve calling Physics
as a function. The following three worlds are equivalent:

varworld=Physics();

Physics(function(world){// use "world"});

Physics(function(){varworld=this;// use "world"});

The return value, the function argument, and the “this” variable all
refer to the same world. The benefit of using the last two methods is
that it encourages a coding style that does not polute the global scope.
Many worlds can be created this way which will be properly scoped and modular.

Configure your world

Several configuration options are settable when constructing a world. To set
any options, pass in a configuration object as the first argument to Physics.

Example:

Physics({// set the timesteptimestep:1000.0/160,// maximum number of iterations per stepmaxIPF:16,// set the integrator (may also be set with world.add())integrator:'verlet'},function(world){// use "world"});

Making things “go” - Advancing the simulation

In order to advance the simulation by one frame, simply call the .step() method
with the current time as a parameter. This can be done in any way you like,
but usually this will be called inside an animation loop, using
window.requestAnimationFrame or similar.

A helper is provided with PhysicsJS to facilitate animation loops:
Physics.util.ticker. The ticker methods will use requestAnimationFrame so
you will need to polyfill it if necessary. To use the ticker,
just call .on() to subscribe to the event, and call the start() method.

Example:

// subscribe to the tickerPhysics.util.ticker.on(function(time){world.step(time);});// start the tickerPhysics.util.ticker.start();

Add things to the world

The “Swiss Army Knife” method of the world, is world.add(). This method
will accept several types of “things” that can be added or replaced in the
world: bodies (objects), behaviors, renderers, and integrators.

Any number of bodies and behaviors may be added to the world, but
only one renderer and one integrator can be added to any one world
at any one time.

Bodies

Bodies are the “what” of a physics simulation. They represent physical objects that
can be rendered as DOM Elements, or drawn on canvas, or however you’d like to display
them. They are not by default tied to any particular “view” or visual representation.

Bodies, like points, circles, or convex polygons, are available as extensions.

Creating a body is done using the Physics.body() factory function.

Example:

varball=Physics.body('circle',{x:50,// x-coordinatey:30,// y-coordinatevx:0.2,// velocity in x-directionvy:0.01,// velocity in y-directionradius:20});// add the circle to the worldworld.add(ball);

Behaviors (or Behaviours)

Behaviors (or Behaviours) are the “how” of a physics simulation. They are rules applied
to the world that act on bodies during every timestep to simulate specific physical laws.
A world without any behaviors will act as an infinite, frictionless vacuum.
(No behaviors are included in the core library)

The most familiar example of a behavior is adding “gravity” to a simulation. What is most often
meant by “gravity” is a constant acceleration in the downward (positive “y”) direction.
Because of the frequent need for this, a “constant-acceleration” behavior is available
as an extra.

Example:

// add some gravityvargravity=Physics.behavior('constant-acceleration',{acc:{x:0,y:0.0004}// this is the default});world.add(gravity);// later... flip the world upside down!gravity.setAcceleration({x:0,y:-0.0004});

Some behaviors act as “detectors”, which don’t modify bodies directly. Instead
they detect specific events and announce them to the world’s pubsub
system so other behaviors can take appropriate actions. One example of this is
collision detection and response. There are separate behaviors
for collision detection, collision response, and even so-called “sweep and prune”
optimization algorithms.

Integrators

An integrator is the mathematical workhorse of a simulation. An integrator
will numerically integrate
the physical properties of the bodies. In other words, it will move them to
their next positions and velocities every “tick”.