Matter.js Body timeScale Property Explained

The timeScale property on a specific body in Matter.js is a local modifier that controls the speed of simulation for that individual physics body relative to the rest of the world. While the engine typically updates all bodies uniformly, setting a unique timeScale on a single body allows developers to create localized slow-motion, fast-forward, or freeze effects without altering the global physics timing. This article explains how the body.timeScale property works, how to implement it, and the technical considerations to keep in mind.

How body.timeScale Works

In Matter.js, every rigid body created via Matter.Bodies or Matter.Body.create inherits a set of default properties, including timeScale. By default, this value is set to 1, meaning the body updates at normal speed synchronized with the physics engine.

When you modify this property, it scales the integration step for that specific body:

• 1.0 (Default): The body moves at normal speed.
• < 1.0 (e.g., 0.5): The body moves in slow motion, updating position and velocity at half the standard rate.
• > 1.0 (e.g., 2.0): The body accelerates through time, moving twice as fast as other objects.
• 0: The body effectively pauses in place relative to motion updates, though it still participates in collisions.

Code Example

You can set the timeScale during body instantiation or adjust it dynamically during runtime:

// Setting timeScale at creation
const slowMovingBox = Matter.Bodies.rectangle(400, 200, 80, 80, {
    timeScale: 0.5
});

// Modifying timeScale dynamically
Matter.Body.set(slowMovingBox, 'timeScale', 0.2);

// Or direct assignment
slowMovingBox.timeScale = 1.5;

Global vs. Local Time Scaling

Matter.js provides two levels of temporal control:

1. engine.timing.timeScale: Affects the entire simulation globally. Changing this slows down or speeds up every body, constraint, and collision resolution simultaneously.
2. body.timeScale: Affects only the specified body's linear and angular velocity integration. Other bodies in the scene continue to update at their standard rates.

When both are used, the effects compound. For example, if engine.timing.timeScale is 0.5 and a body’s timeScale is 0.5, that specific body effectively updates at 0.25 times the normal speed.

Limitations and Considerations

While body.timeScale is useful for visual effects like "bullet time" on a player character or creating low-gravity-style floating objects, it has limitations:

• Numerical Stability: Modifying the time scale alters the numerical integration steps. High time scales can cause tunneling (passing through objects) or jittery collision responses because the body moves further between collision checks.
• Collision Dynamics: When two bodies with different timeScale values collide, momentum and impulse resolution can behave unnaturally because the objects do not share the same physical time step.
• Constraints and Joints: If a body with a custom timeScale is connected via constraints to another body with a default timeScale, the constraint solver may produce stiff or unpredictable behavior.