Matter.Engine.update vs Matter.Runner in Matter.js

In Matter.js, the primary difference between Matter.Engine.update and Matter.Runner lies in manual versus automated execution. Matter.Engine.update is a low-level method that advances the physics world by a single, specified time step, while Matter.Runner is a higher-level loop utility that automatically calls this update method on every animation frame using the browser's requestAnimationFrame API. Understanding this distinction is essential for choosing between out-of-the-box convenience and full control over your application's game loop.

What is Matter.Engine.update?

Matter.Engine.update(engine, [delta], [correction]) is a single-step function. When invoked, it calculates collisions, resolves constraints, and moves bodies forward by a given time increment (delta).

Key characteristics include:

• Manual Execution: It does not run continuously on its own. You must call it manually inside your own update or render loop.
• Deterministic Control: Because you specify the exact delta (time step in milliseconds) per invocation, you can enforce fixed time-step physics.
• Custom Integration: It is the ideal choice when integrating Matter.js into existing game frameworks (such as PixiJS, Three.js, or Phaser) that already provide their own render loop.

Example usage:

function gameLoop(timestamp) {
    // Manually advance physics by a fixed 16.66ms (approx. 60fps)
    Matter.Engine.update(engine, 1000 / 60);

    // Custom rendering logic goes here
    requestAnimationFrame(gameLoop);
}
requestAnimationFrame(gameLoop);

What is Matter.Runner?

Matter.Runner is an optional, self-contained loop controller designed to handle the timing and execution of Matter.Engine.update for you.

Key characteristics include:

• Automated Ticking: It creates and manages a requestAnimationFrame loop, invoking Engine.update automatically at the monitor's refresh rate.
• Dynamic Time Scaling: By default, it calculates the elapsed time between frames and adjusts the delta passed to the engine, helping maintain consistent real-world speeds during frame drops.
• Lifecycle Controls: It provides built-in methods such as Runner.start(runner, engine) and Runner.stop(runner) to pause and resume the physics simulation cleanly.

Example usage:

// Create a runner instance
const runner = Matter.Runner.create();

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

// Pause or stop the simulation
// Matter.Runner.stop(runner);

Core Differences at a Glance

When to Use Each

Use Matter.Runner if you are building standard web-based demos, quick prototypes, or standalone physics sketches where you want the simulation up and running with minimal boilerplate code.

Use Matter.Engine.update if you are building a complex game, synchronizing physics over a network, running simulations in headless Node.js environments, or using an external rendering engine that requires a single master loop.