Matter.js showPositions: Visualizing Body Origins

Visualizing body origin reference points is essential for debugging object alignment, rotational centers, and collision behavior in 2D physics simulations. Matter.js includes a built-in canvas renderer with several debugging flags designed specifically for this purpose. This article explains how to configure and enable the showPositions render option to visually display body origins across your simulation.

Understanding showPositions in Matter.js

By default, the Matter.js Render module draws rigid body shapes defined by their vertices. However, every rigid body possesses a central position vector (body.position) that acts as the origin for translations, rotations, and force applications.

When the showPositions flag is enabled in the renderer options, Matter.js draws a visual marker—typically a small colored circle or dot—at the exact coordinates of each body's reference origin. This makes it immediately clear whether an object's center of mass or designated origin aligns properly with its geometry.

Enabling showPositions During Render Creation

The most straightforward way to visualize body origins is by setting showPositions: true in the configuration object passed to Matter.Render.create().

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

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

// Initialize the renderer with showPositions enabled
const render = Render.create({
  element: document.body,
  engine: engine,
  options: {
    width: 800,
    height: 600,
    wireframes: true,
    showPositions: true
  }
});

// Run renderer and engine
Render.run(render);
Runner.run(Runner.create(), engine);

While showPositions can operate with colored shapes, it is best utilized when wireframes is set to true, as solid fills can sometimes obscure origin points and other visual debugging cues.

Toggling showPositions at Runtime

You can dynamically enable or disable origin point rendering on an existing Render instance without re-instantiating the renderer. This is useful for building debug menus or toggling visual states with keyboard shortcuts.

// Enable position markers
render.options.showPositions = true;

// Disable position markers
render.options.showPositions = false;

When changing render options on an active simulation, the canvas automatically reflects the changes on the next render frame.

To gain a more complete picture of how a body's origin relates to its orientation and boundaries, showPositions can be combined with other Matter.js render options:

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

Using these debugging flags together ensures that custom compound bodies, offset vertices, and rotational constraints behave as expected throughout the physics lifecycle.