Matter.Body

Defined in: src/body/Body.js:1

The Matter.Body module contains methods for creating and manipulating body models. A Matter.Body is a rigid body that can be simulated by a Matter.Engine. Factories for commonly used body configurations (such as rectangles, circles and other polygons) can be found in the module Matter.Bodies.

See the included usage examples.

Methods

Matter.Body._initProperties

(body, [options])

private

Initialises body properties.

Parameters

@ src/body/Body.js:121

Matter.Body._totalProperties

(body)

→ private

Returns the sums of the properties of all compound parts of the parent body.

Parameters

Returns

@ src/body/Body.js:654

Matter.Body.applyForce

(body, position, force)

Applies a force to a body from a given world-space position, including resulting torque.

Parameters

@ src/body/Body.js:640

Matter.Body.create

(options)

→ Body

Creates a new rigid body model. The options parameter is an object that specifies any properties you wish to override the defaults. All properties have default values, and many are pre-calculated automatically based on other properties. Vertices must be specified in clockwise order. See the properties section below for detailed information on what you can pass via the options object.

Parameters

Returns

Bodybody

@ src/body/Body.js:30

Matter.Body.nextCategory

()→ Number

Returns the next unique category bitfield (starting after the initial default category 0x0001). There are 32 available. See body.collisionFilter for more information.

Returns

NumberUnique category bitfield

@ src/body/Body.js:110

Matter.Body.nextGroup

([isNonColliding=false])

→ Number

Returns the next unique group index for which bodies will collide. If isNonColliding is true, returns the next unique group index for which bodies will not collide. See body.collisionFilter for more information.

Parameters

  • [isNonColliding=false] Booloptional

Returns

NumberUnique group index

@ src/body/Body.js:95

Matter.Body.rotate

(body, rotation, [point])

Rotates a body by a given angle relative to its current angle, without imparting any angular velocity.

Parameters

@ src/body/Body.js:494

Matter.Body.scale

(body, scaleX, scaleY, [point])

Scales the body, including updating physical properties (mass, area, axes, inertia), from a world-space point (default is body centre).

Parameters

@ src/body/Body.js:519

Matter.Body.set

(body, settings, value)

Given a property and a value (or map of), sets the property(s) on the body, using the appropriate setter functions if they exist. Prefer to use the actual setter functions in performance critical situations.

Parameters

A property name (or map of properties and values) to set on the body.

The value to set if settings is a single property name.

@ src/body/Body.js:164

Matter.Body.setAngle

(body, angle)

Sets the angle of the body instantly. Angular velocity, position, force etc. are unchanged.

Parameters

@ src/body/Body.js:436

Matter.Body.setAngularVelocity

(body, velocity)

Sets the angular velocity of the body instantly. Position, angle, force etc. are unchanged. See also Body.applyForce.

Parameters

@ src/body/Body.js:472

Matter.Body.setDensity

(body, density)

Sets the density of the body. Mass and inertia are automatically updated to reflect the change.

Parameters

@ src/body/Body.js:293

Matter.Body.setInertia

(body, inertia)

Sets the moment of inertia (i.e. second moment of area) of the body of the body. Inverse inertia is automatically updated to reflect the change. Mass is not changed.

Parameters

@ src/body/Body.js:304

Matter.Body.setMass

(body, mass)

Sets the mass of the body. Inverse mass, density and inertia are automatically updated to reflect the change.

Parameters

@ src/body/Body.js:277

Matter.Body.setParts

(body, [body], [autoHull=true])

Sets the parts of the body and updates mass, inertia and centroid. Each part will have its parent set to body. By default the convex hull will be automatically computed and set on body, unless autoHull is set to false. Note that this method will ensure that the first part in body.parts will always be the body.

Parameters

parts

  • [autoHull=true] Booloptional

@ src/body/Body.js:353

Matter.Body.setPosition

(body, position)

Sets the position of the body instantly. Velocity, angle, force etc. are unchanged.

Parameters

@ src/body/Body.js:416

Matter.Body.setStatic

(body, isStatic)

Sets the body as static, including isStatic flag and setting mass and inertia to Infinity.

Parameters

  • isStatic Bool

@ src/body/Body.js:229

Matter.Body.setVelocity

(body, velocity)

Sets the linear velocity of the body instantly. Position, angle, force etc. are unchanged. See also Body.applyForce.

Parameters

@ src/body/Body.js:458

Matter.Body.setVertices

(body, vertices)

Sets the body's vertices and updates body properties accordingly, including inertia, area and mass (with respect to body.density). Vertices will be automatically transformed to be orientated around their centre of mass as the origin. They are then automatically translated to world space based on body.position.

The vertices argument should be passed as an array of Matter.Vector points (or a Matter.Vertices array). Vertices must form a convex hull, concave hulls are not supported.

Parameters

@ src/body/Body.js:316

Matter.Body.translate

(body, translation)

Moves a body by a given vector relative to its current position, without imparting any velocity.

Parameters

@ src/body/Body.js:484

Matter.Body.update

(body, deltaTime, timeScale, correction)

Performs a simulation step for the given body, including updating position and angle using Verlet integration.

Parameters

@ src/body/Body.js:583

Item Index

Methods

Properties

The following properties are specified for objects created by <span class="prefix">Matter.</span>.create and for objects passed to it via the options argument.

Events

Properties

The following properties are specified for objects created by Matter.Body.create and for objects passed to it via the options argument.

Body.angle

Number

A Number specifying the angle of the body, in radians.

Default: 0

@ src/body/Body.js:773

Body.angularSpeed

Number

A Number that measures the current angular speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.angularVelocity).

Default: 0

@ src/body/Body.js:830

Body.angularVelocity

Number

A Number that measures the current angular velocity of the body after the last Body.update. It is read-only. If you need to modify a body's angular velocity directly, you should apply a torque or simply change the body's angle (as the engine uses position-Verlet integration).

Default: 0

@ src/body/Body.js:849

Body.area

String

A Number that measures the area of the body's convex hull, calculated at creation by Body.create.

@ src/body/Body.js:1176

Body.axes

Vector[]

An array of unique axis vectors (edge normals) used for collision detection. These are automatically calculated from the given convex hull (vertices array) in Body.create. They are constantly updated by Body.update during the simulation.

@ src/body/Body.js:1167

Body.bounds

Bounds

A Bounds object that defines the AABB region for the body. It is automatically calculated from the given convex hull (vertices array) in Body.create and constantly updated by Body.update during simulation.

@ src/body/Body.js:1184

Body.collisionFilter

Object

An Object that specifies the collision filtering properties of this body.

Collisions between two bodies will obey the following rules:

  • If the two bodies have the same non-zero value of collisionFilter.group, they will always collide if the value is positive, and they will never collide if the value is negative.
  • If the two bodies have different values of collisionFilter.group or if one (or both) of the bodies has a value of 0, then the category/mask rules apply as follows:Each body belongs to a collision category, given by collisionFilter.category. This value is used as a bit field and the category should have only one bit set, meaning that the value of this property is a power of two in the range [1, 2^31]. Thus, there are 32 different collision categories available.

Each body also defines a collision bitmask, given by collisionFilter.mask which specifies the categories it collides with (the value is the bitwise AND value of all these categories).

Using the category/mask rules, two bodies A and B collide if each includes the other's category in its mask, i.e. (categoryA & maskB) !== 0 and (categoryB & maskA) !== 0 are both true.

@ src/body/Body.js:998

Body.collisionFilter.category

Object

A bit field that specifies the collision category this body belongs to. The category value should have only one bit set, for example 0x0001. This means there are up to 32 unique collision categories available. See body.collisionFilter for more information.

Default: 1

@ src/body/Body.js:1033

Body.collisionFilter.group

Object

An Integer Number, that specifies the collision group this body belongs to. See body.collisionFilter for more information.

Default: 0

@ src/body/Body.js:1024

Body.collisionFilter.mask

Object

A bit mask that specifies the collision categories this body may collide with. See body.collisionFilter for more information.

Default: -1

@ src/body/Body.js:1044

Body.density

Number

A Number that defines the density of the body, that is its mass per unit area. If you pass the density via Body.create the mass property is automatically calculated for you based on the size (area) of the object. This is generally preferable to simply setting mass and allows for more intuitive definition of materials (e.g. rock has a higher density than wood).

Default: 0.001

@ src/body/Body.js:903

Body.force

Vector

A Vector that specifies the force to apply in the current step. It is zeroed after every Body.update. See also Body.applyForce.

Default: { x: 0, y: 0 }

@ src/body/Body.js:805

Body.friction

Number

A Number that defines the friction of the body. The value is always positive and is in the range (0, 1). A value of 0 means that the body may slide indefinitely. A value of 1 means the body may come to a stop almost instantly after a force is applied.

The effects of the value may be non-linear. High values may be unstable depending on the body. The engine uses a Coulomb friction model including static and kinetic friction. Note that collision response is based on pairs of bodies, and that friction values are combined with the following formula:

  1. Math.min(bodyA.friction, bodyB.friction)

Default: 0.1

@ src/body/Body.js:959

Body.frictionAir

Number

A Number that defines the air friction of the body (air resistance). A value of 0 means the body will never slow as it moves through space. The higher the value, the faster a body slows when moving through space. The effects of the value are non-linear.

Default: 0.01

@ src/body/Body.js:987

Body.frictionStatic

Number

A Number that defines the static friction of the body (in the Coulomb friction model). A value of 0 means the body will never 'stick' when it is nearly stationary and only dynamic friction is used. The higher the value (e.g. 10), the more force it will take to initially get the body moving when nearly stationary. This value is multiplied with the friction property to make it easier to change friction and maintain an appropriate amount of static friction.

Default: 0.5

@ src/body/Body.js:976

Body.id

Number

An integer Number uniquely identifying number generated in Body.create by Common.nextId.

@ src/body/Body.js:721

Body.inertia

Number

A Number that defines the moment of inertia (i.e. second moment of area) of the body. It is automatically calculated from the given convex hull (vertices array) and density in Body.create. If you modify this value, you must also modify the body.inverseInertia property (1 / inertia).

@ src/body/Body.js:929

Body.inverseInertia

Number

A Number that defines the inverse moment of inertia of the body (1 / inertia). If you modify this value, you must also modify the body.inertia property.

@ src/body/Body.js:938

Body.inverseMass

Number

A Number that defines the inverse mass of the body (1 / mass). If you modify this value, you must also modify the body.mass property.

@ src/body/Body.js:921

Body.isSensor

Boolean

A flag that indicates whether a body is a sensor. Sensor triggers collision events, but doesn't react with colliding body physically.

Default: false

@ src/body/Body.js:868

Body.isSleeping

Boolean

A flag that indicates whether the body is considered sleeping. A sleeping body acts similar to a static body, except it is only temporary and can be awoken. If you need to set a body as sleeping, you should use Sleeping.set as this requires more than just setting this flag.

Default: false

@ src/body/Body.js:876

Body.isStatic

Boolean

A flag that indicates whether a body is considered static. A static body can never change position or angle and is completely fixed. If you need to set a body as static after its creation, you should use Body.setStatic as this requires more than just setting this flag.

Default: false

@ src/body/Body.js:859

Body.label

String

An arbitrary String name to help the user identify and manage bodies.

Default: "Body"

@ src/body/Body.js:737

Body.mass

Number

A Number that defines the mass of the body, although it may be more appropriate to specify the density property instead. If you modify this value, you must also modify the body.inverseMass property (1 / mass).

@ src/body/Body.js:913

Body.motion

Number

A Number that measures the amount of movement a body currently has (a combination of speed and angularSpeed). It is read-only and always positive. It is used and updated by the Matter.Sleeping module during simulation to decide if a body has come to rest.

Default: 0

@ src/body/Body.js:885

Body.parent

Body

A self reference if the body is not a part of another body. Otherwise this is a reference to the body that this is a part of. See body.parts.

@ src/body/Body.js:764

Body.parts

Body[]

An array of bodies that make up this body. The first body in the array must always be a self reference to the current body instance. All bodies in the parts array together form a single rigid compound body. Parts are allowed to overlap, have gaps or holes or even form concave bodies. Parts themselves should never be added to a World, only the parent body should be. Use Body.setParts when setting parts to ensure correct updates of all properties.

@ src/body/Body.js:745

Body.plugin

An object reserved for storing plugin-specific properties.

@ src/body/Body.js:757

Body.position

Vector

A Vector that specifies the current world-space position of the body.

Default: { x: 0, y: 0 }

@ src/body/Body.js:797

Body.render

Object

An Object that defines the rendering properties to be consumed by the module Matter.Render.

@ src/body/Body.js:1071

Body.render.fillStyle

String

A String that defines the fill style to use when rendering the body (if a sprite is not defined). It is the same as when using a canvas, so it accepts CSS style property values.

Default: a random colour

@ src/body/Body.js:1149

Body.render.lineWidth

Number

A Number that defines the line width to use when rendering the body outline (if a sprite is not defined). A value of 0 means no outline will be rendered.

Default: 0

@ src/body/Body.js:1140

Body.render.opacity

Number

Sets the opacity to use when rendering.

Default: 1

@ src/body/Body.js:1086

Body.render.sprite

Object

An Object that defines the sprite properties to use when rendering, if any.

@ src/body/Body.js:1094

Body.render.sprite.texture

String

An String that defines the path to the image to use as the sprite texture, if any.

@ src/body/Body.js:1101

Body.render.sprite.xOffset

Number

A Number that defines the offset in the x-axis for the sprite (normalised by texture width).

Default: 0

@ src/body/Body.js:1124

Body.render.sprite.xScale

Number

A Number that defines the scaling in the x-axis for the sprite, if any.

Default: 1

@ src/body/Body.js:1108

Body.render.sprite.yOffset

Number

A Number that defines the offset in the y-axis for the sprite (normalised by texture height).

Default: 0

@ src/body/Body.js:1132

Body.render.sprite.yScale

Number

A Number that defines the scaling in the y-axis for the sprite, if any.

Default: 1

@ src/body/Body.js:1116

Body.render.strokeStyle

String

A String that defines the stroke style to use when rendering the body outline (if a sprite is not defined). It is the same as when using a canvas, so it accepts CSS style property values.

Default: a random colour

@ src/body/Body.js:1158

Body.render.visible

Boolean

A flag that indicates if the body should be rendered.

Default: true

@ src/body/Body.js:1078

Body.restitution

Number

A Number that defines the restitution (elasticity) of the body. The value is always positive and is in the range (0, 1). A value of 0 means collisions may be perfectly inelastic and no bouncing may occur. A value of 0.8 means the body may bounce back with approximately 80% of its kinetic energy. Note that collision response is based on pairs of bodies, and that restitution values are combined with the following formula:

  1. Math.max(bodyA.restitution, bodyB.restitution)

Default: 0

@ src/body/Body.js:946

Body.sleepThreshold

Number

A Number that defines the number of updates in which this body must have near-zero velocity before it is set as sleeping by the Matter.Sleeping module (if sleeping is enabled by the engine).

Default: 60

@ src/body/Body.js:895

Body.slop

Number

A Number that specifies a tolerance on how far a body is allowed to 'sink' or rotate into other bodies. Avoid changing this value unless you understand the purpose of slop in physics engines. The default should generally suffice, although very large bodies may require larger values for stable stacking.

Default: 0.05

@ src/body/Body.js:1053

Body.speed

Number

A Number that measures the current speed of the body after the last Body.update. It is read-only and always positive (it's the magnitude of body.velocity).

Default: 0

@ src/body/Body.js:821

Body.timeScale

Number

A Number that allows per-body time scaling, e.g. a force-field where bodies inside are in slow-motion, while others are at full speed.

Default: 1

@ src/body/Body.js:1063

Body.torque

Number

A Number that specifies the torque (turning force) to apply in the current step. It is zeroed after every Body.update.

Default: 0

@ src/body/Body.js:813

Body.type

String

A String denoting the type of object.

Default: "body"

@ src/body/Body.js:728

Body.velocity

Vector

A Vector that measures the current velocity of the body after the last Body.update. It is read-only. If you need to modify a body's velocity directly, you should either apply a force or simply change the body's position (as the engine uses position-Verlet integration).

Default: { x: 0, y: 0 }

@ src/body/Body.js:839

Body.vertices

Vector[]

An array of Vector objects that specify the convex hull of the rigid body. These should be provided about the origin (0, 0). E.g.

  1. [{ x: 0, y: 0 }, { x: 25, y: 50 }, { x: 50, y: 0 }]
  2.

When passed via Body.create, the vertices are translated relative to body.position (i.e. world-space, and constantly updated by Body.update during simulation). The Vector objects are also augmented with additional properties required for efficient collision detection.

Other properties such as inertia and bounds are automatically calculated from the passed vertices (unless provided via options). Concave hulls are not currently supported. The module Matter.Vertices contains useful methods for working with vertices.

@ src/body/Body.js:781

Events

The following events are emitted by objects created by <span class="prefix">Matter.</span>Body.create to objects that have subscribed using Matter.Events.on.

Events.on(Body, "sleepEnd", callback)

Fired when a body ends sleeping (where this is the body).

Event Payload:

An event object

  • source

The source object of the event

  • name

The name of the event

@ src/body/Body.js:705

Events.on(Body, "sleepStart", callback)

Fired when a body starts sleeping (where this is the body).

Event Payload:

An event object

  • source

The source object of the event

  • name

The name of the event

@ src/body/Body.js:695