Matter.Engine
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
Applies gravitational acceleration to all bodies.
This models a uniform gravitational field, similar to near the surface of a planet.
Matter.Engine._bodiesClearForces
Zeroes the body.force and body.torque force buffers.
Parameters
-
bodiesBody[]
Matter.Engine._bodiesUpdateVelocities
Applies Body.updateVelocities to all given bodies.
Parameters
-
bodiesBody[]
Matter.Engine.create
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
-
[options]Object optional
Returns
engine
Matter.Engine.merge
Merges two engines by keeping the configuration of engineA but replacing the world with the one from engineB.
Matter.Engine.run
A deprecated alias for Runner.run, use Matter.Runner.run(engine) instead and see Matter.Runner for more information.
Parameters
-
engineEngine
Matter.Engine.update
Moves the simulation forward in time by delta milliseconds.
Triggers beforeUpdate, beforeSolve and afterUpdate events.
Triggers collisionStart, collisionActive and collisionEnd events.
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
Replaced by and now alias for engine.grid.
Default: a Matter.Grid instance
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
A Matter.Detector instance.
Default: a Matter.Detector instance
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
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 gravitational direction normal x component, to be multiplied by gravity.scale.
Default: 0
The gravitational direction normal y component, to be multiplied by gravity.scale.
Default: 1
A Matter.Grid instance.
Default: a Matter.Grid instance
Engine.plugin
An object reserved for storing plugin-specific properties.
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
An Object containing properties regarding the timing systems of the engine.
Engine.timing.lastDelta
Number
A Number that represents the delta value used in the last engine update.
Default: 0
Engine.timing.lastElapsed
Number
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
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
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
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
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
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
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
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
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)