Display Collision Normals in Matter.js

This guide explains how to visually display collision contact normals in a Matter.js simulation using the built-in showCollisions renderer option. Enabling this flag allows developers to inspect contact points and collision normal vectors directly on the canvas, providing vital visual feedback for debugging physics behaviors, penetrations, and impulse responses.

Enabling showCollisions in Matter.Render

The Matter.Render module includes a built-in debugging suite. Collision contact normals can be visualized by setting the showCollisions property to true within the renderer's options configuration object.

When active, Matter.js draws small indicators at the exact contact positions where two rigid bodies intersect, along with lines indicating the collision normal—the direction perpendicular to the contact surface along which separation forces and impulses are applied.

Configuration Example

You can enable this setting when initializing the renderer using Render.create:

const { Engine, Render, Runner, Bodies, Composite } = Matter;

// 1. Create engine and world
const engine = Engine.create();
const world = engine.world;

// 2. Create the renderer with showCollisions enabled
const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: false, // Optional: set false to see body fills alongside debug lines
        showCollisions: true // Visualizes contact points and contact normals
    }
});

// 3. Add bodies to test collisions
const boxA = Bodies.rectangle(400, 200, 80, 80);
const ground = Bodies.rectangle(400, 500, 810, 60, { isStatic: true });

Composite.add(world, [boxA, ground]);

// 4. Start the simulation
Render.run(render);
Runner.run(Runner.create(), engine);

Toggling showCollisions Dynamically

If your simulation is already running, you can toggle the display of collision normals on the fly without re-instantiating the renderer. Access the options object of your active render instance:

// Enable collision normals
render.options.showCollisions = true;

// Disable collision normals
render.options.showCollisions = false;

Interpreting the Visual Output

Once showCollisions is active: