Matter.js Engine Time Scaling Explained

This article explores how Matter.js manages simulation speed using its internal time-scaling mechanics. In physics simulations, altering the passage of time is essential for effects like slow-motion, fast-forwarding, or smooth pausing. Matter.js accomplishes this primarily through the timeScale property located on the engine's timing object, scaling the discrete time step applied during each physics calculation cycle without breaking the underlying integration logic.

The Core Mechanism: engine.timing.timeScale

Matter.js controls simulation speed via the engine.timing.timeScale property. By default, this value is set to 1.

When Engine.update(engine, delta) runs on every frame, Matter.js calculates the effective time step by multiplying the frame's elapsed time (delta) by engine.timing.timeScale. The Verlet integration steps that determine body velocities, accelerations, and constraint resolutions then execute using this scaled delta value.

• Normal Speed (timeScale = 1.0): The simulation progresses in real-time according to the delta provided by the render loop.
• Slow Motion (timeScale < 1.0): A value such as 0.5 cuts the effective delta in half, causing bodies to move at 50% of their normal speed.
• Fast Forward (timeScale > 1.0): A value such as 2.0 doubles the movement speed per frame update.
• Paused (timeScale = 0): Setting the value to 0 halts all physical movement and collision reactions, while allowing the render loop and user interaction events to continue functioning.

Practical Implementation

Setting the time scale is directly handled through the engine instance:

// Create an engine
const engine = Matter.Engine.create();

// Slow down time by half
engine.timing.timeScale = 0.5;

// Speed up time
engine.timing.timeScale = 1.5;

// Reset to standard speed
engine.timing.timeScale = 1.0;

Physical Stability and Tunneling

Altering timeScale directly impacts the numerical stability of the Verlet integrator:

• Decreasing timeScale increases precision: When time slows down, the distance objects travel between steps decreases. This results in tighter collision resolution, more accurate constraint behavior, and negligible risk of tunneling (objects passing through one another).
• Increasing timeScale decreases precision: Accelerating time forces objects to travel larger distances in a single calculation step. If velocities become too high relative to body thickness, objects may phase through colliders. To maintain simulation stability at higher time scales, you must either increase position and velocity iterations (engine.positionIterations, engine.velocityIterations) or manually split the update into multiple smaller sub-steps.

Time Scaling vs. Frame Rate

Matter.js separates frame delta management from the physical simulation rate. If you are using Matter.Runner, it automatically measures actual elapsed time and passes it into Engine.update. The timeScale multiplier is applied internally after this measurement. Consequently, fluctuating display refresh rates (e.g., 60Hz vs. 144Hz) are compensated for by the runner, ensuring that engine.timing.timeScale remains a uniform scalar independent of hardware performance.