How to Stop a Matter.Runner in Matter.js

This guide explains how to properly pause or stop the physics simulation loop in Matter.js by halting the Matter.Runner. You will learn the primary built-in method used to cancel the update cycle, inspect a straightforward code example, and see how to resume the engine when necessary.

Using Matter.Runner.stop

The direct way to stop a simulation loop managed by Matter.Runner is by calling Matter.Runner.stop(runner). This method cancels the internal requestAnimationFrame loop associated with that specific runner instance, immediately freezing the physics updates.

Basic Implementation

// 1. Create engine and runner
const engine = Matter.Engine.create();
const runner = Matter.Runner.create();

// 2. Start the runner
Matter.Runner.run(runner, engine);

// 3. Stop the runner when needed (e.g., on a pause event)
function pauseSimulation() {
    Matter.Runner.stop(runner);
}

Resuming the Runner

If you need to resume the physics calculations after stopping, pass the existing runner and engine instances back into Matter.Runner.run():

function resumeSimulation() {
    Matter.Runner.run(runner, engine);
}

Stopping the Renderer Alongside the Runner

If you are using the built-in Matter.Render module to draw your canvas, stopping the runner alone halts physics calculations but leaves the rendering loop active. To halt rendering as well, call Matter.Render.stop:

// Stop both physics and rendering
Matter.Runner.stop(runner);
Matter.Render.stop(render);

// Resume both
Matter.Runner.run(runner, engine);
Matter.Render.run(render);

Calling Matter.Runner.stop(runner) ensures that CPU cycles are not wasted running physics steps when your application is paused, navigating away, or unmounting a view.