Is Matter.js Compatible With Node.js?

Matter.js is fully compatible with Node.js environments, allowing developers to execute robust 2D physics simulations directly on the server. This guide covers how Matter.js functions outside of the browser, how to manage headless physics engines without standard DOM APIs, and how to implement server-side physics for applications like multiplayer games and backend simulation tasks.

Running Matter.js Headless

The core architecture of Matter.js cleanly separates the physics computation from rendering and input handling. Modules such as Matter.Engine, Matter.Bodies, Matter.Composite, and Matter.Detector rely solely on pure JavaScript mathematical operations. Because they do not depend on browser-specific APIs like window, document, or the HTML5 Canvas, they run natively inside Node.js without polyfills.

The only components that require a browser environment are:

When working in Node.js, you simply omit Matter.Render and manage the physics state headlessly.

How to Install and Set Up Matter.js in Node.js

Install the library using npm:

npm install matter-js

In your Node.js script, import the required modules:

const Matter = require('matter-js');

const { Engine, Bodies, Composite } = Matter;

// Create an engine instance
const engine = Engine.create();

// Create physics bodies
const box = Bodies.rectangle(400, 200, 80, 80);
const ground = Bodies.rectangle(400, 610, 810, 60, { isStatic: true });

// Add bodies to the world
Composite.add(engine.world, [box, ground]);

Driving the Simulation Loop

In a browser, Matter.Runner or requestAnimationFrame typically drives the engine updates. In Node.js, you can manually step the engine forward using a fixed timestep with setInterval or high-resolution timers like process.hrtime():

const fps = 60;
const delta = 1000 / fps;

setInterval(() => {
  // Step the physics simulation forward by delta milliseconds
  Engine.update(engine, delta);

  // Read body states
  console.log(`Box Position: X=${box.position.x.toFixed(2)}, Y=${box.position.y.toFixed(2)}`);
}, delta);

Common Server-Side Use Cases