Matter.js is a 2D rigid body physics engine written in JavaScript. This library can help you easily simulate 2D physics in the browser. It offers a lot of features like the ability to create rigid bodies and assign physical properties like mass, area or density to them. You can also simulate different kinds of collisions and forces like gravity and friction.

Matter.js supports all major browsers. Additionally, it is suitable for use on mobile devices as it can detect touch and has responsiveness. All these features make it worth investing your time to learn how to use the engine as you will then be able to create physics-based 2D games or simulations easily. In this tutorial, I will cover the basics of this library, including its installation and usage, and I'll provide a working example.

Installation

You can install Matter.js by using package managers like NPM with the help of the following commands:

npm install matter-js

You can also get a link to the library from a CDN and directly include it in your projects like this:

<script src="https://cdnjs.cloudflare.com/ajax/libs/matter-js/0.18.0/matter.min.js"></script>

Matter.js frequently releases updates which might require you to make slight modifications to your code to make it work. The examples in this tutorial are based on version 0.18.0.

A Basic Example

The best way to learn about Matter.js is to see some actual code and understand how it works. In this section, we will create a few bodies and go through the required code line by line.

const Engine = Matter.Engine,
    Render = Matter.Render,
    Runner = Matter.Runner,
    Bodies = Matter.Bodies,
    Composite = Matter.Composite;

const iEngine = Engine.create();
const iRunner = Runner.create();

const iRender = Render.create({
  element: document.body,
  engine: iEngine,
  options: {
    width: 800,
    height: 400,
    wireframes: false,
    background: "white"
  }
});

const boxA = Bodies.rectangle(400, 200, 80, 80);
const ballA = Bodies.circle(380, 100, 40, 10);
const ballB = Bodies.circle(460, 10, 40, 10);
const ground = Bodies.rectangle(400, 380, 810, 60, { isStatic: true });

Composite.add(iEngine.world, [boxA, ballA, ballB, ground]);

Render.run(iRender);

Runner.run(iRunner, iEngine);

We begin by creating aliases for all the Matter.js modules that we might need in our project.

The Matter.Engine module contains methods for creating and manipulating engines. Engines are required in a project to update the simulation of the world.

The Matter.Render module is a basic HTML5 canvas-based renderer. This module is required to visualize different engines. The computations done by the engine for different bodies in a simulation are shown visually to users with the help of this module. For example, the engine module might compute where an object is supposed to be, and the render module will draw it there.

The Matter.Runner module gives you access to a game loop in order to continuously update the engine and your world.

The Matter.Bodies module allows you to create rigid body objects. A similar module called Matter.Body allows you to manipulate individual bodies.

The last module we load is the Matter.Composite module, which allows you to create a collection of bodies, constraints, or other composite objects. A composite can consist of a single body or the whole simulation.

The next line uses the create([settings]) method of the Matter.Engine module to create a new engine. Similarly, we also create a new runner and a new renderer. The settings parameter in the above method is actually an object with key-value pairs to override the default values of a few properties related to the engine. We have kept everything at the default values for our example.

For example, you can control the global scaling factor of time for all the bodies in the world. Setting a value less than 1 will result in the world interacting in slow motion. Similarly, a value greater than 1 will make the world fast-paced. You will learn more about the Matter.Engine module in the next tutorial of the series.

After that, we use the create([settings]) method of the Matter.Render module to create a new renderer. Just like the Engine module, the settings parameter in the above method is an object used to specify different options for the parameter. You can use the element key to specify the element where the library should insert the canvas. Similarly, you can also use the canvas key to specify the canvas element where the Matter.js world should be rendered.

There is an engine key that you can use to specify the engine that should be used to render the world. There is also an options key that actually accepts an object as its value. You can use this key to set values for different parameters like the width or height of the canvas. You can also turn the wireframes on or off by setting the value of the wireframe key to true or false respectively. We have also made the canvas for our world white in color by setting the value of the background to white.

The next few lines create different bodies that will interact in our world. The bodies are created with the help of the Matter.Bodies module in Matter.js. In this example, we have just created two circles and a rectangle using the circle() and rectangle() method. Other methods are available as well to create different polygons.

Once we have created the bodies, we need to add them to a world of our choice using the add() method from the Matter.Composite module. After adding the necessary bodies to our world, we just need to run the runner and the renderer using the run() method from the respective modules. That is basically all the code you need to create and render a world in Matter.js.

The code at the beginning of this section creates the following result.

Common Matter.js Modules

There are more than 20 different modules in Matter.js. All these modules provide different methods and properties that are useful for creating different kinds of simulations and allow you to interact with them. Some of these modules handle collisions, while others handle rendering and simulation.

The example in the previous section used four different modules to handle the rendering, simulation, and creation of bodies. In this section, you will learn about the roles of some common modules available in Matter.js.

• Engine: You need engines to update the simulations of your Matter.js world. The Engine module provides different methods and properties that allow you to control the behavior of different engines.
• Render: A renderer is required for you to create actual bodies in your simulation that your users can see. You can use it to develop basic games with its support for sprites, etc.
• Runner: Bodies in any world that you simulate will interact with each other continuously. The runner module handles these continuous updates of the engine and the world.
• Bodies: The Bodies module contains different methods to help you create rigid bodies with common shapes like a circle, rectangle, or trapezium.
• Body: This module provides you with different methods and properties to create and manipulate the rigid bodies that you have created using the functions from the Bodies module. This module allows you to scale, rotate, or translate individual bodies. It also has functions to let you specify the velocity, density, or inertia of different bodies. Because of so many functions, the third tutorial in this series only discusses the methods and properties available in the Body module.
• Composites: Just like the Bodies module, this module contains different methods that you can use to create composite bodies with common configurations. For example, you can create a stack or pyramid of rectangular boxes using just a single method with the help of the Composites module.
• Composite: The Composite module has methods and properties that allow you to create and manipulate composite bodies. You can read more about the Composite and Composites modules in the fourth tutorial of the series.
• Constraint: This module allows you to create and manipulate constraints. You can use a constraint to make sure that two bodies or a fixed world-space point and a body maintain a fixed distance. It is similar to connecting two bodies through a steel rod. You can modify the stiffness of these constraints so that the rod starts acting more like springs. Matter.js uses constraints when creating a Newton's cradle or a chain composite.
• MouseConstraint: This module provides you with methods and properties that let you create and manipulate mouse constraints. This is helpful when you want different bodies in the world to interact with the user.

Final Thoughts

This tutorial was meant to introduce you to the Matter.js library. Keeping that in mind, I have provided a quick overview of the features and installation of the library. The basic example involving two circles and a box shows how easy it is to create simple simulations using the library.

Since Matter.js has a lot of modules each of which adds its own unique methods to the engine, I have written a brief summary of a few common modules. The rest of the series will focus on teaching you about these common modules in more detail.

This post has been updated with contributions from Monty Shokeen. Monty is a full-stack developer who also loves to write tutorials and to learn about new JavaScript libraries.