Main Modules in the Matter.js Library

Matter.js is a widely used 2D rigid body physics engine built for JavaScript and the modern web. This article outlines the essential modules that make up the Matter.js architecture, explaining how each component contributes to simulating realistic motion, handling collisions, managing constraints, and rendering visual output in browser-based applications.

1. Matter.Engine

The Engine module is the brain of the physics simulation. It manages the state of the simulation world, processes collision detection, calculates body interactions, and advances the simulation step-by-step over time. Every Matter.js project requires an engine instance to coordinate the physics environment.

2. Matter.Runner

The Runner module provides an execution loop that automatically steps the Engine forward in synchronization with the browser's frame rate using requestAnimationFrame. While optional—developers can manually trigger engine ticks—it simplifies implementation by ensuring smooth, frame-rate-independent physics updates.

3. Matter.World and Matter.Composite

• Matter.Composite: The fundamental container structure in Matter.js. It holds collections of bodies, constraints, and other nested composites.
• Matter.World: A specialized root composite associated directly with an Engine instance. Everything that exists in a simulation—including objects and boundaries—must be added to the simulation's root world.

4. Matter.Bodies

The Bodies module is a factory for creating standard geometric rigid bodies. It includes preconfigured methods to generate shapes such as:

• Bodies.rectangle: Generates rectangular or square bodies, often used for walls and platforms.
• Bodies.circle: Creates circular bodies with defined radii.
• Bodies.polygon: Creates regular n-sided polygons.
• Bodies.trapezoid: Produces trapezoid shapes.
• Bodies.fromVertices: Generates complex, concave, or convex bodies based on a set of vector coordinates.

5. Matter.Body

While Bodies creates shapes, the Body module contains utility methods to manipulate individual rigid bodies during runtime. It provides functions to apply forces, apply torque, update velocities, alter physical properties (such as friction, restitution, density, and mass), and toggle properties like isStatic or isSensor.

6. Matter.Constraint

The Constraint module manages joints and connections. Constraints can link two bodies together or pin a single body to a fixed point in the world. They simulate elastic or rigid physical links such as ropes, springs, pivots, and suspension systems, defined by properties such as length and stiffness.

7. Matter.Render

The Render module is a built-in, HTML5 Canvas-based visualizer. Primarily designed for debugging, testing, and rapid prototyping, it draws bodies, constraints, and collision wireframes directly onto the screen. For production-ready games, developers often bypass Matter.Render in favor of dedicated graphics libraries like PixiJS, Three.js, or custom WebGL engines.

8. Matter.Mouse and Matter.MouseConstraint

• Matter.Mouse: Normalizes mouse and touch inputs across different screen resolutions and pixel ratios.
• Matter.MouseConstraint: Couples user pointer input directly to the physics simulation, allowing users to click, drag, flick, and interact with dynamic bodies on the canvas.

9. Matter.Collision and Matter.Detector

The Collision and Detector modules handle collision testing. They provide low-level methods to test whether specific bodies overlap, compute collision pairs, determine penetration depths, and resolve contact manifolds without necessarily requiring a full simulation step.