Unlock Realistic Game Physics with Matter.js: A Complete Guide

What Is a Physics Engine and What Can It Do?

A physics engine is a program that uses variables such as mass, velocity, friction, and air resistance to simulate a near‑real physical system, giving rigid bodies realistic effects like gravity, rotation, and collisions. It makes objects behave more like they would in the real world, e.g., determining how high a character can jump or how a bullet arcs.

Real‑time vs High‑Precision Engines

Real‑time engines prioritize speed and simplify calculations for games, while high‑precision engines require more processing power and are used in scientific research or animation movies where accuracy is critical.

Physics Engines in Games

Older games like CS 1.5 used a low‑fidelity engine that produced fixed death animations, causing characters to clip through doors. Modern titles such as CS:GO, built on the Source Engine, calculate death poses with physics, allowing more realistic interactions.

Introducing Matter.js

Matter.js is a lightweight (≈84 KB minified) JavaScript 2D rigid‑body physics library for the web, first released on 28 Feb 2014. Compared with the older Box2D, Matter.js offers similar performance and features while being easier to integrate.

Installing Matter.js

Include the script directly in an HTML page:

<script src="matter.js" type="text/javascript"></script>

Or install via package managers:

$ bower install matter-js

$ npm install matter-js

Key Features of Matter.js

Rigid bodies, composites, and compound bodies

Concave and convex shapes

Collision detection (coarse, intermediate, fine)

Stable stacking and sleeping

Friction, air friction, static friction

Constraints and joints

Gravity and world properties

Vector operations

Canvas renderer with textures

Cross‑browser support (Chrome, Firefox, Safari, IE8+)

Touch support for mobile

Native JavaScript implementation

Fundamental Concepts

Engine and World

Matter.Engine

creates and updates the simulation. Matter.World holds bodies, constraints, and composites, and defines gravity and bounds.

Render

var engine = Engine.create();
var render = Render.create({
    element: document.body,
    engine: engine,
    options: options
});
Engine.run(engine);
Render.run(render);

The renderer draws bodies on a canvas; wireframe mode is useful for debugging.

Body

Rigid bodies are created with Matter.Bodies.rectangle, .circle, .polygon, .trapezoid, etc., and added to the world.

var rect = Bodies.rectangle(200,100,50,50);
var circle = Bodies.circle(300,100,25);
World.add(engine.world, [rect, circle]);

Composite

Composites group bodies and constraints. Matter.js provides helpers such as Composites.chain, .newtonsCradle, .softBody, .car, .stack, and others.

Constraint

Constraints connect two bodies, acting like springs or rods.

World.add(engine.world, Constraint.create({
    bodyA: rect,
    bodyB: circle,
    stiffness: 0.6
}));

MouseConstraint

Enables interactive dragging of bodies with mouse or touch.

var mouseConstraint = MouseConstraint.create({
    element: render.canvas
});
World.add(engine.world, mouseConstraint);

Vector

Matter.Vector

offers operations for creating and manipulating vectors, essential for applying forces and setting velocities.

Events

Use Matter.Events.on, .off, and .trigger to bind, remove, or fire custom events.

Important Properties

Applying Force

Body.applyForce(body, body.position, {x: fx, y: fy});

Gravity

engine.world.gravity.y = -1; // reverse gravity
engine.world.gravity.y = 0;  // no gravity

Sleeping

var engine = Engine.create({enableSleeping:true});
Event.on(body, "sleepStart", function(){
    World.remove(engine.world, body);
});

Friction

// friction
Bodies.rectangle(300,70,40,40,{friction:0.01});
// air friction
Bodies.rectangle(300,70,40,40,{frictionAir:0.05});
// static friction
Bodies.rectangle(300,70,40,40,{frictionStatic:1});

Time Scale

engine.timing.timeScale = 0.1; // slow motion

Debugging with Matter.Render

Render options let you toggle wireframes, show sleeping bodies, velocities, collisions, bounds, and more.

var render = Render.create({
    element: document.body,
    engine: engine,
    options: {
        width:800,
        height:600,
        wireframes:true,
        showSleeping:true,
        // other debug flags default to false
    }
});

MatterTools

The suite includes MatterTools.Demo for running examples, MatterTools.Gui for tweaking engine parameters, and MatterTools.Inspector for inspecting the world.

References

Matter.js – a 2D rigid body JavaScript physics engine; liabru/matter-tools; Physics engine – Wikipedia; Matter.js Demo.