Show:
API

Matter.Engine

Defined in: src/core/Engine.js:1

The Matter.Engine module contains methods for creating and manipulating engines. An engine is a controller that manages updating the simulation of the world. See Matter.Runner for an optional game loop utility.

See the included usage examples.

Methods

Matter.Engine._bodiesApplyGravity

(bodies, gravity)
private

Applies gravitational acceleration to all bodies. This models a uniform gravitational field, similar to near the surface of a planet.

Parameters

Matter.Engine._bodiesClearForces

(bodies)
private

Zeroes the body.force and body.torque force buffers.

Parameters

Matter.Engine._bodiesUpdate

(bodies, delta)
private

Applies Body.update to all given bodies.

Parameters

  • bodies Body[]
  • delta Number

    The amount of time elapsed between updates

Matter.Engine._bodiesUpdateVelocities

(bodies)
private

Applies Body.updateVelocities to all given bodies.

Parameters

Matter.Engine.clear

(engine)

Clears the engine pairs and detector.

Parameters

Matter.Engine.create

([options])
Engine

Creates a new engine. 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. See the properties section below for detailed information on what you can pass via the options object.

Parameters

Returns

Engine

engine

Matter.Engine.merge

(engineA, engineB)

Merges two engines by keeping the configuration of engineA but replacing the world with the one from engineB.

Parameters

Matter.Engine.run

(engine)
deprecated

Deprecated: use Matter.Runner.run(engine) instead

A deprecated alias for Runner.run, use Matter.Runner.run(engine) instead and see Matter.Runner for more information.

Parameters

Matter.Engine.update

(engine, [delta=16.666])

Moves the simulation forward in time by delta milliseconds. Triggers beforeUpdate, beforeSolve and afterUpdate events. Triggers collisionStart, collisionActive and collisionEnd events.

Parameters

Properties / Options

The following properties if specified below are for objects created by Matter.Engine.create and may be passed to it as options.

Engine.broadphase

Grid
deprecated

Deprecated: replaced by `engine.detector`

Replaced by and now alias for engine.grid.

Default: a Matter.Grid instance

An integer Number that specifies the number of constraint iterations to perform each update. The higher the value, the higher quality the simulation will be at the expense of performance. The default value of 2 is usually very adequate.

Default: 2

A Matter.Detector instance.

Default: a Matter.Detector instance

A flag that specifies whether the engine should allow sleeping via the Matter.Sleeping module. Sleeping can improve stability and performance, but often at the expense of accuracy.

Default: false

Engine.gravity

Object

An optional gravitational acceleration applied to all bodies in engine.world on every update.

This models a uniform gravitational field, similar to near the surface of a planet. For gravity in other contexts, disable this and apply forces as needed.

To disable set the scale component to 0.

This is split into three components for ease of use:
a normalised direction (x and y) and magnitude (scale).

The magnitude of the gravitational acceleration.

Default: 0.001

Engine.gravity.x

Object

The gravitational direction normal x component, to be multiplied by gravity.scale.

Default: 0

Engine.gravity.y

Object

The gravitational direction normal y component, to be multiplied by gravity.scale.

Default: 1

Engine.grid

Grid
deprecated

Deprecated: replaced by `engine.detector`

A Matter.Grid instance.

Default: a Matter.Grid instance

Engine.plugin

An object reserved for storing plugin-specific properties.

An integer Number that specifies the number of position iterations to perform each update. The higher the value, the higher quality the simulation will be at the expense of performance.

Default: 6

Engine.timing

Object

An Object containing properties regarding the timing systems of the engine.

A Number that represents the delta value used in the last engine update.

Default: 0

A Number that represents the total execution time elapsed during the last Engine.update in milliseconds. It is updated by timing from the start of the last Engine.update call until it ends.

This value will also include the total execution time of all event handlers directly or indirectly triggered by the engine update.

Default: 0

A Number that specifies the global scaling factor of time for all bodies. A value of 0 freezes the simulation. A value of 0.1 gives a slow-motion effect. A value of 1.2 gives a speed-up effect.

Default: 1

A Number that specifies the current simulation-time in milliseconds starting from 0. It is incremented on every Engine.update by the given delta argument.

Default: 0

An integer Number that specifies the number of velocity iterations to perform each update. The higher the value, the higher quality the simulation will be at the expense of performance.

Default: 4

Engine.world

Composite

The root Matter.Composite instance that will contain all bodies, constraints and other composites to be simulated by this engine.

Default: a Matter.Composite instance

Events

The following events are emitted by objects created by Matter.Engine.create and received by objects that have subscribed using Matter.Events.on.

Events.on(Engine, "afterUpdate", callback)

Fired after engine update and all collision events

Callback Parameters

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event

Events.on(Engine, "beforeSolve", callback)

Fired after bodies updated based on their velocity and forces, but before any collision detection, constraints and resolving etc.

Callback Parameters

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event

Events.on(Engine, "beforeUpdate", callback)

Fired just before an update

Callback Parameters

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event

Events.on(Engine, "collisionActive", callback)

Fired after engine update, provides a list of all pairs that are colliding in the current tick (if any)

Callback Parameters

  • event Object

    An event object

    • pairs Pair[]

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event

Events.on(Engine, "collisionEnd", callback)

Fired after engine update, provides a list of all pairs that have ended collision in the current tick (if any)

Callback Parameters

  • event Object

    An event object

    • pairs Pair[]

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event

Events.on(Engine, "collisionStart", callback)

Fired after engine update, provides a list of all pairs that have started to collide in the current tick (if any)

Callback Parameters

  • event Object

    An event object

    • pairs Pair[]

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • delta Number

      The delta time in milliseconds value used in the update

    • source Engine

      The source object of the event

    • name String

      The name of the event