Hello, World

Install the library

Or with npm:

npm install --save newton
var Newton = require('newton');

Create a simulation

The Simulator is responsible for integrating Particles, applying Forces, and resolving Constraints.

All the high-level and advanced functionality of Newton is based on these three simple steps.

var sim = Newton.Simulator();
sim.start();

Add a particle

Newton has three building blocks: Particles, Forces, and Constraints. Particles are points in space that have X and Y coordinates as well as mass (size).

var particle = Newton.Particle(10, 20);  // x, y
sim.add(particle);

Render the scene

Newton ships with a WebGL-based renderer for development and debugging. To use it, you'll need to create a canvas element on your page. In this case, we've called our canvas `#display`.

You can render anyway you like - canvas, webgl, DOM, SVG, etc. All renderers support a simple interface.

var display = document.getElementById('display');
var renderer = Newton.GLRenderer(display);
renderer.render(sim);

Demo: Hello, World

As you can see, we're up and running - but it's a little boring with just one Particle sitting still.

Movement

Forces

Forces are the second basic element of Newton. Each frame, the Simulator applies Forces to Particles in order to create movement.

Newton comes with a library of Forces, and you can easily add your own.

var gravity = Newton.LinearForce(1, Math.PI * 1.5);   // strength, direction
sim.add(gravity);

Constraints

Constraints are the third basic element of Newton and are one of its most powerful features.

They create rules that are applied to Particles after integration, like "All particles should stay within this rectangle," or "These two particles should be connected."

BoxConstraint is a location constraint that keeps a particle within a rectangular area. Newton comes with a library of Constraints.

var container = Newton.BoxConstraint(0, 0, 1000, 600);   // x, y, width, height
sim.add(container);

Demo: Rope

Now things are getting interesting. Our little rope has come to life!

We've given our Simulator a `solve` option. Newton uses an iterative, convergent solver, which means that constraints are run repeatedly each frame to converge at an approximate solution for the whole system. The `solve` option tells the Simulator which constraints are most important. Try changing the priority order to see how it affects the simulation.

Behavior

Bodies

When building a simulation, you frequently want to refer to a group of Particles, Forces, and Constraints as a single entity. Newton uses the concept of *Bodies* for grouping elements.

Sub-Bodies can be added to Bodies to build up more complex entities.

Keep in mind, Bodies are just for bookkeeping - logical groupings so your code can be readable. They have no impact on the simulation.

var rope = Newton.Body();

rope.add(Newton.Particle(500 + i * 20, 180));
rope.add(Newton.RopeConstraint(prev, current));

sim.add(rope);

Extending Body

That's a lot of typing for just making a rope. Instead, let's extend Newton's Body type to create a Rope constructor.

function Rope(x, y, length) {
  Newton.Body.call(this);   // call Body's constructor
}

Rope.prototype = Object.create(Newton.Body.prototype);  // extend Body's prototype

var rope = new Rope(225, 10, 300);

Extending Body allows you to create higher-level abstractions in your simulation. Since Bodies can include sub-Bodies, you can compose larger components out of smaller, simpler parts.

Interaction

Events

Demo: Interactive Rope