How to Reset a Matter.js Simulation

Resetting a Matter.js physics simulation requires restoring the engine, world, and rigid bodies to their original parameters. Depending on your project's architecture, you can achieve this either by clearing the physics world and recreating the initial scene from scratch, or by manually resetting the position, rotation, and velocities of existing bodies. This guide details both methods so you can implement the approach best suited to your application's performance and complexity requirements.

Method 1: Clearing and Rebuilding the World (Recommended)

The cleanest and most reliable way to reset a simulation is to encapsulate your scene setup logic into a function, clear the existing world composite, and re-execute the initialization function. This approach ensures all dynamically generated bodies, constraints, and collision states are fully removed.

// Store references to the engine and world
const { Engine, Render, Runner, Composite } = Matter;

const engine = Engine.create();
const world = engine.world;

// Encapsulate initial scene creation
function initScene() {
    const boxA = Matter.Bodies.rectangle(400, 200, 80, 80);
    const ground = Matter.Bodies.rectangle(400, 610, 810, 60, { isStatic: true });
    Composite.add(world, [boxA, ground]);
}

// Initial setup
initScene();

// Function to reset the simulation
function resetSimulation() {
    // Remove all bodies, constraints, and composites from the world
    Composite.clear(world, false);

    // Clear any accumulated engine updates or forces
    Engine.clear(engine);

    // Re-populate the scene
    initScene();
}

Passing false as the second argument to Composite.clear(world, keepStatic) removes all bodies, including static obstacles. If your scene contains static boundaries that never move or change, pass true instead to retain them while removing only dynamic bodies.

Method 2: Manually Resetting Body Properties

If your simulation consists of a fixed set of bodies and recreating them causes performance overhead or garbage collection pauses, you can manually reset their physical properties back to their initial states.

When resetting bodies manually, you must clear both linear and angular velocities to prevent residual momentum from carrying over:

function resetBody(body, initialX, initialY, initialAngle = 0) {
    // 1. Reset position and orientation
    Matter.Body.setPosition(body, { x: initialX, y: initialY });
    Matter.Body.setAngle(body, initialAngle);

    // 2. Clear linear and angular velocity
    Matter.Body.setVelocity(body, { x: 0, y: 0 });
    Matter.Body.setAngularVelocity(body, 0);

    // 3. Clear accumulated forces and torques
    body.force = { x: 0, y: 0 };
    body.torque = 0;

    // 4. Wake up the body if it has fallen asleep
    Matter.Sleeping.set(body, false);
}

To use this method effectively across an entire scene:

1. Cache each body's initial position and angle during creation.
2. Iterate through your array of tracked bodies upon reset and pass the cached values to the resetBody function.

Handling the Runner and Render Loops

If your simulation uses Matter.Runner or Matter.Render, you generally do not need to restart these processes when resetting. However, if the simulation is paused when the reset occurs, ensure you trigger a single frame update or restart the runner so the canvas updates immediately to reflect the new state:

// If the runner is stopped, manually trigger an engine and renderer update
Matter.Engine.update(engine);
Matter.Render.world(render);