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

@ src/core/Engine.js:294

Matter.Engine._bodiesClearForces

(bodies)

private

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

Parameters

@ src/core/Engine.js:277

Matter.Engine._bodiesUpdate

(bodies, deltaTime, timeScale, correction, worldBounds)

private

Applys Body.update to all given bodies.

Parameters

The amount of time elapsed between updates

The Verlet correction factor (deltaTime / lastDeltaTime)

@ src/core/Engine.js:320

Matter.Engine.clear

(engine)

Clears the engine including the world, pairs and broadphase.

Parameters

@ src/core/Engine.js:259

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

Engineengine

@ src/core/Engine.js:30

Matter.Engine.merge

(engineA, engineB)

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

Parameters

@ src/core/Engine.js:235

Matter.Engine.run

(engine)

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

Parameters

@ src/core/Engine.js:343

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

  • [delta=16.666] Numberoptional
  • [correction=1] Numberoptional

@ src/core/Engine.js:98

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.Engine.create and for objects passed to it via the options argument.

Engine.broadphase

Grid

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

Default: a Matter.Grid instance

@ src/core/Engine.js:485

Engine.constraintIterations

Number

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

@ src/core/Engine.js:426

Engine.enableSleeping

Boolean

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

@ src/core/Engine.js:436

Engine.plugin

An object reserved for storing plugin-specific properties.

@ src/core/Engine.js:501

Engine.positionIterations

Number

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

@ src/core/Engine.js:408

Engine.render

Renderdeprecated

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

@ src/core/Engine.js:472

Engine.timing

Object

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

@ src/core/Engine.js:445

Engine.timing.timeScale

Number

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

@ src/core/Engine.js:452

Engine.timing.timestamp

Number

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

@ src/core/Engine.js:463

Engine.velocityIterations

Number

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

@ src/core/Engine.js:417

Engine.world

World

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

Default: a Matter.World instance

@ src/core/Engine.js:493

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:

An event object

The engine.timing.timestamp of the event

  • source

The source object of the event

  • name

The name of the event

@ src/core/Engine.js:359

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

Fired just before an update

Event Payload:

An event object

The engine.timing.timestamp of the event

  • source

The source object of the event

  • name

The name of the event

@ src/core/Engine.js:349

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:

An event object

  • pairs

List of affected pairs

The engine.timing.timestamp of the event

  • source

The source object of the event

  • name

The name of the event

@ src/core/Engine.js:380

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:

An event object

  • pairs

List of affected pairs

The engine.timing.timestamp of the event

  • source

The source object of the event

  • name

The name of the event

@ src/core/Engine.js:391

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:

An event object

  • pairs

List of affected pairs

The engine.timing.timestamp of the event

  • source

The source object of the event

  • name

The name of the event

@ src/core/Engine.js:369