# Matter.js — 2D Physics Engine for the Web

> A lightweight, fast 2D rigid body physics engine written in JavaScript for browsers and Node.js, powering games, simulations, and interactive experiences.

## Install

Save as a script file and run:

# Matter.js — 2D Physics Engine for the Web

## Quick Use
```html
<script src="https://cdn.jsdelivr.net/npm/matter-js/build/matter.min.js"></script>
<script>
  const engine = Matter.Engine.create();
  const render = Matter.Render.create({ element: document.body, engine });
  const box = Matter.Bodies.rectangle(400, 200, 80, 80);
  const ground = Matter.Bodies.rectangle(400, 580, 810, 60, { isStatic: true });
  Matter.Composite.add(engine.world, [box, ground]);
  Matter.Render.run(render);
  Matter.Runner.run(Matter.Runner.create(), engine);
</script>
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-2103df05
Author: Script Depot