Matter.Runner
The Matter.Runner module is an optional utility that provides a game loop for running a Matter.Engine inside a browser environment.
A runner will continuously update a Matter.Engine whilst synchronising engine updates with the browser frame rate.
This runner favours a smoother user experience over perfect time keeping.
This runner is optional and is used for development and debugging but could be useful as a starting point for implementing some games and experiences.
Alternatively see Engine.update to step the engine directly inside your own game loop implementation as may be needed inside other environments.
See the included usage examples.
Methods
Matter.Runner._cancelNextFrame
Cancels the last callback scheduled by Runner._onNextFrame on this runner.
Parameters
-
runnerRunner
Matter.Runner._mean
Returns the mean of the given numbers.
Parameters
-
valuesNumber[]
Returns
the mean of given values.
Matter.Runner._onNextFrame
Schedules the callback on this runner for the next animation frame.
Returns
frameRequestId
Matter.Runner.create
Creates a new Runner.
See the properties section below for detailed information on what you can pass via the options object.
Parameters
-
optionsObject
Matter.Runner.run
Runs a Matter.Engine whilst synchronising engine updates with the browser frame rate.
See module and properties descriptions for more information on this runner.
Alternatively see Engine.update to step the engine directly inside your own game loop implementation.
Returns
runner
Matter.Runner.stop
Ends execution of Runner.run on the given runner by canceling the frame loop.
Alternatively to temporarily pause the runner, see runner.enabled.
Parameters
-
runnerRunner
Matter.Runner.tick
Performs a single runner tick as used inside Runner.run.
See module and properties descriptions for more information on this runner.
Alternatively see Engine.update to step the engine directly inside your own game loop implementation.
Properties / Options
The following properties if specified below are for objects created by Matter.Runner.create and may be passed to it as options.
The fixed timestep size used for Engine.update calls in milliseconds, known as delta.
This value is recommended to be 1000 / 60 ms or smaller (i.e. equivalent to at least 60hz).
Smaller delta values provide higher quality results at the cost of performance.
You should usually avoid changing delta during running, otherwise quality may be affected.
For smoother frame pacing choose a delta that is an even multiple of each display FPS you target, i.e. 1000 / (n * fps) as this helps distribute an equal number of updates over each display frame.
For example with a 60 Hz delta i.e. 1000 / 60 the runner will on average perform one update per frame on displays running 60 FPS and one update every two frames on displays running 120 FPS, etc.
Where as e.g. using a 240 Hz delta i.e. 1000 / 240 the runner will on average perform four updates per frame on displays running 60 FPS and two updates per frame on displays running 120 FPS, etc.
Therefore Runner.run will call multiple engine updates (or none) as needed to simulate the time elapsed between browser frames.
In practice the number of updates in any particular frame may be restricted to respect the runner's performance budgets. These are specified by runner.maxFrameTime and runner.maxUpdates, see those properties for details.
Default: 1000 / 60
A flag that can be toggled to enable or disable tick calls on this runner, therefore pausing engine updates and events while the runner loop remains running.
Default: true
Runner.frameDelta
Number
The measured time elapsed between the last two browser frames measured in milliseconds.
This is useful e.g. to estimate the current browser FPS using 1000 / runner.frameDelta.
Runner.frameDeltaSmoothing
Boolean
Enables averaging to smooth frame rate measurements and therefore stabilise play rate.
Default: true
Runner.frameDeltaSnapping
Boolean
Rounds measured browser frame delta to the nearest 1 Hz.
This option can help smooth frame rate measurements and simplify handling hardware timing differences e.g. 59.94Hz and 60Hz displays.
For best results you should also round your runner.delta equivalent to the nearest 1 Hz.
Default: true
Runner.maxFrameTime
Number
A performance budget that limits execution time allowed for this runner per browser frame in milliseconds.
To calculate the effective browser FPS at which this throttle is applied use 1000 / runner.maxFrameTime.
This performance budget is intended to help maintain browser interactivity and help improve framerate recovery during temporary high CPU usage.
This budget only covers the measured time elapsed executing the functions called in the scope of the runner tick, including Engine.update and its related user event callbacks.
You may also reduce this budget to allow for any significant additional processing you perform on the same thread outside the scope of this runner tick, e.g. rendering time.
See also runner.maxUpdates.
Default: 1000 / 30
Runner.maxUpdates
Number
An optional limit for maximum engine update count allowed per frame tick in addition to runner.maxFrameTime.
Unless you set a value it is automatically chosen based on runner.delta and runner.maxFrameTime.
See also runner.maxFrameTime.
Default: null
Runner.timeBuffer
Number
The accumulated time elapsed that has yet to be simulated in milliseconds.
This value is clamped within certain limits (see Runner.tick code).
Default: 0
Runner.timeLastTick
Number
The timestamp of the last call to Runner.tick used to measure frameDelta.
Default: 0
Events
The following events are emitted by objects created by Matter.Runner.create and received by objects that have subscribed using Matter.Events.on.
Events.on(Runner, "afterTick", callback)
Fired once at the end of the browser frame, after beforeTick, tick and after any engine updates.
Callback Parameters
Events.on(Runner, "afterUpdate", callback)
Fired after each and every engine update in this browser frame (if any). There may be multiple engine update calls per browser frame (or none) depending on framerate and timestep delta.
Callback Parameters
Events.on(Runner, "beforeTick", callback)
Fired once at the start of the browser frame, before any engine updates.
Callback Parameters
Events.on(Runner, "beforeUpdate", callback)
Fired before each and every engine update in this browser frame (if any). There may be multiple engine update calls per browser frame (or none) depending on framerate and timestep delta.
Callback Parameters
Events.on(Runner, "tick", callback)
Fired once at the start of the browser frame, after beforeTick.