Matter.js — 2D Physics Engine for the Web

Introduction

Matter.js is a 2D rigid body physics engine for JavaScript. It handles collision detection, forces, constraints, and compound bodies, making it straightforward to add realistic physics to browser-based games, interactive demos, and data visualizations without writing simulation math from scratch.

What Matter.js Does

• Simulates rigid body dynamics including gravity, friction, restitution, and air resistance
• Provides broad-phase and narrow-phase collision detection with SAT (Separating Axis Theorem)
• Supports constraints such as springs, ropes, and pin joints between bodies
• Handles compound bodies and concave shapes through convex decomposition
• Includes a built-in Canvas renderer for quick prototyping and debugging

Architecture Overview

The engine runs a fixed-timestep simulation loop that updates body positions, detects collisions, and resolves contacts each frame. Bodies are organized in a Composite tree structure. The Detector module uses a grid-based broad phase to cull impossible collisions, then an SAT narrow phase for precise contact points. A Resolver applies impulses iteratively to satisfy constraints and prevent penetration. The Render module is optional and decoupled from the physics core.

Self-Hosting & Configuration

• Install via npm with npm install matter-js or include the CDN script tag
• Create an Engine, add Bodies and Constraints to its World composite
• Configure gravity direction and scale via engine.gravity.x and engine.gravity.y
• Use Matter.Runner for automatic frame stepping or call Engine.update() manually for custom loops
• Swap the built-in renderer for any canvas or WebGL library by reading body positions each frame

Key Features

• Zero dependencies and under 90 KB minified for a complete physics simulation
• Deterministic simulation with fixed timestep for reproducible results
• Event system for collision start, active, and end callbacks on any body pair
• Mouse and touch constraint for interactive dragging of physics bodies
• Sleeping bodies optimization that skips computation for stationary objects

Comparison with Similar Tools

• Box2D (via Emscripten) — industry-standard C++ engine ported to JS; heavier but more feature-complete for complex joints
• Planck.js — JavaScript rewrite of Box2D with a similar API; stricter physics but larger learning curve
• p2.js — another JS physics engine with AABB tree broadphase; less actively maintained than Matter.js
• Rapier (WASM) — Rust-based high-performance engine compiled to WASM; faster but requires WASM support and a different workflow

FAQ

Q: Can Matter.js handle 3D physics? A: No. It is strictly a 2D engine. For 3D physics in JavaScript, consider Cannon.js, Ammo.js, or Rapier.

Q: How many bodies can it simulate at 60 FPS? A: Performance depends on the device, but a few hundred active bodies typically run smoothly in modern browsers. Enable sleeping for inactive bodies to improve performance.

Q: Does Matter.js work with Pixi.js or Three.js? A: Yes. Use Matter.js for physics and read body positions and angles each frame to update your rendering library of choice.

Q: Is Matter.js suitable for production games? A: It is used in many browser games and interactive sites. For performance-critical titles with thousands of bodies, a WASM-based engine may be more appropriate.

Sources

• https://github.com/liabru/matter-js
• https://brm.io/matter-js/