Show Collision Axes in Matter.js Render

Visualizing collision mechanics in Matter.js is essential for debugging physics simulations and understanding how the Separating Axis Theorem (SAT) resolves overlaps. This guide demonstrates how to display body axes and collision separation vectors by configuring the debug visualization flags in the built-in Matter.Render module, either during initialization or dynamically at runtime.

Enabling Axes via Render Options

Matter.js provides built-in debug options through the Render.create method. To visualize the orientation axes of bodies and the axes generated during collision separation, set showAxes and showSeparations to true in the render configuration.

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

const engine = Engine.create();

// Create the renderer with collision debug options enabled
const render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: true,      // Recommended for debug clarity
        showAxes: true,        // Renders the local projection axes of bodies
        showSeparations: true, // Renders the separating axes active during collisions
        showCollisions: true   // Renders collision points and contact normals
    }
});

Render.run(render);
Runner.run(Runner.create(), engine);

Relevant Debug Properties Explained

• showAxes: When set to true, this property draws the internal local axes for each body. In 2D rigid-body simulations using SAT, these axes represent the normal vectors of each body's faces, which are the exact axes tested for overlap during collision detection.
• showSeparations: Setting this to true draws the minimum translation vectors and separating axes determined by the collision solver when two bodies intersect.
• showCollisions: Highlights the exact contact points and collision indicators where axes intersect.

Toggling Axes at Runtime

If the renderer is already initialized, you can toggle the visualization of collision axes dynamically by mutating the options object on your existing render instance:

// Enable collision axes during an active simulation
render.options.showAxes = true;
render.options.showSeparations = true;
render.options.showCollisions = true;

// Disable wireframe mode if you want to see body fills alongside debug lines
render.options.wireframes = false;

When wireframes is set to false, the renderer continues to draw the axis lines over the filled body polygons, providing clear visual feedback on how collisions align with object surfaces.