Inspect Internal Edges in Matter.js Polygons

This article explains how to visualize and inspect the internal edges of decomposed polygons using the built-in Matter.js renderer. When working with complex, concave shapes in Matter.js, the physics engine decomposes them into multiple convex parts. By configuring specific flags within the Render module options, developers can display these internal boundaries to debug decomposition artifacts, verify collision geometry, and optimize physics bodies.

Understanding Polygon Decomposition in Matter.js

Matter.js relies on convex polygons for its rigid body collision calculations. When you supply vertices that form a concave polygon—typically using Bodies.fromVertices—the engine uses a decomposition library (such as poly-decomp) to break the concave path into a collection of convex sub-bodies joined into a single compound body.

By default, the standard renderer hides the seam lines between these sub-parts to keep the final shape visually unified. However, visualizing these seams is essential when troubleshooting simulation instability, incorrect center of mass calculations, or improper vertex winding.

Enabling Internal Edge Visualization

The Matter.js renderer includes a dedicated configuration property named showInternalEdges inside its rendering options. Enabling this property forces the canvas to draw the internal dividing lines between sub-parts of a decomposed body.

Configuration via Render Initialization

You can enable internal edge inspection directly when instantiating the renderer by setting showInternalEdges: true within the options object of Render.create:

const render = Matter.Render.create({
    element: document.body,
    engine: engine,
    options: {
        width: 800,
        height: 600,
        wireframes: true,
        showInternalEdges: true
    }
});

Matter.Render.run(render);

Key Render Options to Consider

Toggling Internal Edges at Runtime

If the simulation is already running, you do not need to recreate the renderer to inspect internal edges. You can toggle the property dynamically directly on the active renderer instance:

// Enable internal edges
render.options.showInternalEdges = true;

// Disable internal edges
render.options.showInternalEdges = false;

When modified at runtime, the changes take effect immediately on the next render frame.

Practical Debugging Tips