Show:

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

Applys a mass dependant force to all given bodies.

Parameters

Matter.Engine.bodiesClearForces

(bodies)
private

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

Parameters

Matter.Engine.clear

(engine)

Clears the engine including the world, pairs and broadphase.

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)

An alias for Runner.run, see Matter.Runner for more information.

Parameters

Matter.Engine.update

(engine, [delta=16.666], [correction=1])

Moves the simulation forward in time by delta ms. The correction argument is an optional Number that specifies the time correction factor to apply to the update. This can help improve the accuracy of the simulation in cases where delta is changing between updates. The value of correction is defined as delta / lastDelta, i.e. the percentage change of delta over the last step. Therefore the value is always 1 (no correction) when delta constant (or when no correction is desired, which is the default). See the paper on Time Corrected Verlet for more information.

Triggers beforeUpdate and afterUpdate events. Triggers collisionStart, collisionActive and collisionEnd events.

Parameters

Matter.Engine.updateAll

(bodies, deltaTime, timeScale, correction, worldBounds)
private

Applys Body.update to all given bodies.

Parameters

  • bodies Body[]
  • deltaTime Number

    The amount of time elapsed between updates

  • timeScale Number
  • correction Number

    The Verlet correction factor (deltaTime / lastDeltaTime)

  • worldBounds Bounds

Item Index

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.

Properties

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

An instance of a broadphase controller. The default value is a Matter.Grid instance created by Engine.create.

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 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.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

deprecated

Deprecated: see Demo.js for an example of creating a renderer

An instance of a Render controller. The default value is a Matter.Render instance created by Engine.create. One may also develop a custom renderer module based on Matter.Render and pass an instance of it to Engine.create via options.render.

A minimal custom renderer object must define at least three functions: create, clear and world (see Matter.Render). It is also possible to instead pass the module reference via options.render.controller and Engine.create will instantiate one for you.

Default: a Matter.Render instance

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

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

World

A World composite object that will contain all simulated bodies and constraints.

Default: a Matter.World instance

Events

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

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

Fired after engine update and all collision events

Event Payload:

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      The name of the event

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

Fired just before an update

Event Payload:

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      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)

Event Payload:

  • event Object

    An event object

    • pairs

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      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)

Event Payload:

  • event Object

    An event object

    • pairs

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      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)

Event Payload:

  • event Object

    An event object

    • pairs

      List of affected pairs

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      The name of the event

0.13.0