Hello, World
Install the library
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.