Bodies

Bodies follow the Factory Pattern. Please read about the factory pattern to learn about creation, declaration, and extending 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 point, circle, or convex-polygon, are available as extensions.

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

See also: API Reference for Bodies

Geometry

Bodies themselves don't oversee calculations about the shape. Instead all bodies have a geometry that represents a shape in local coordinates. This way, different body types may easily share geometries. The geometry for a body can be accessed via the .geometry variable.

Geometries also follow the Factory Pattern.

Configuration options

Configuration options can be reviewed in the API Documentation for Bodies.

Properties

Bodies have several properties that govern their behavior and interactions. These can be set via the configuration options upon calling the factory function, or they can be set on the body instance itself.

The information regarding position, velocity, and acceleration (linear and angular) are stored in a .state property. The .state variables of a body can be modified directly.

The following is an excerpt from the body source code. It reveals the state properties available.

this.state = {
    pos: vector( options.x, options.y ),
    vel: vector( options.vx, options.vy ),
    acc: vector(),
    angular: {
        pos: options.angle || 0.0,
        vel: options.angularVelocity || 0.0,
        acc: 0.0
    },
    old: {
        pos: vector(),
        vel: vector(),
        acc: vector(),
        angular: {
            pos: 0.0,
            vel: 0.0,
            acc: 0.0
        }
    }
};

The .state.old object holds the state variables from the previous integration step.

When updating the state of a body that is sleeping, if one is to see the effect of the update in the next step, and all steps thereafter, invoke the body's sleep function, passing it false: .sleep(false). For example, when doing something like:

ball.state.vel.set(1, -1); // make the ball travel 45º to the right and up
ball.sleep(false); //awake the ball

Alternatively, if you prefer to not have the world's bodies go to sleep, set the world's sleepDisabled: true, as per new Physics.world().

Recalculating

Modification of some body properties might cause a need for the body to recalculate its data. This will depend on the body. Generally this is necessary for any modifications to the geometry or mass after creation.

Example:

ball.mass = 2; // changed mass...
ball.recalc();

Points

Points are equivalent to the base type, and all other bodies naturally extend from them. Other bodies will include the same configuration options and methods unless otherwise specified.

Circles

In addition to the options included with the base type, circles also have a "radius" property.

// radius of the circle
radius: 1.0

Rectangles

In addition to the options included with the base type, rectangles also have a "width" and "height" property.

// width of the rectangle
width: 1.0
// height of the rectangle
height: 1.0

Convex Polygons

In addition to the options included with the base type, convex polygons also have a "vertices" property.

// array of points describing the hull. Clockwise or Counterclockwise
vertices: null

The vertices parameter is passed straight to the polygon geometry factory. It should be an array of vector-like values that represent the vertices of the polygon. The vertices can be defined with respect to whatever origin you like, because once they are passed they are converted to the center-of-mass frame (IE: all vertices will be automatically defined with respect to the center of mass).

Here is an example of the declaration of a square:

var square = Physics.body('convex-polygon', {
    // place the center of the square at (0, 0)
    x: 0,
    y: 0,
    vertices: [
        { x: 0, y: 0 },
        { x: 0, y: 20 },
        { x: 20, y: 20 },
        { x: 20, y: 0 }
    ]
});