Getting Started With Matter.js: Introduction

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 including IE8+. 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 Bower or NPM with the help of the following commands:

bower install matter-js
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="path/to/matter.min.js"></script>

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.

var Engine = Matter.Engine,
    Render = Matter.Render,
    World = Matter.World,
    Bodies = Matter.Bodies;
    
var engine = Engine.create();

var render = Render.create({
                element: document.body,
                engine: engine,
                options: {
                    width: 800,
                    height: 400,
                    wireframes: false
                }
             });
             
var boxA = Bodies.rectangle(400, 200, 80, 80);
var ballA = Bodies.circle(380, 100, 40, 10);
var ballB = Bodies.circle(460, 10, 40, 10);
var ground = Bodies.rectangle(400, 380, 810, 60, { isStatic: true });

World.add(engine.world, [boxA, ballA, ballB, ground]);

Engine.run(engine);
Render.run(render);

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 Matter.World module is used to create and manipulate the world in which the engine runs. It is similar to the Matter.Composite module, but it lets you tweak a few additional properties like gravity and bounds. The last module in our code, called Matter.Bodies, allows you to create rigid body objects. Another similar module called Matter.Body allows you to manipulate individual bodies.

The next line uses the create([settings]) method of the Matter.Engine module to create a new engine. 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. 

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 wireframe key to true or false respectively.

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.World module. After adding the necessary bodies to our world, we just need to run the engine 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.


• 
  World: This module provides you with methods and properties to create and manipulate whole worlds at once. The World is actually a Composite body with additional properties like gravity and bounds.


• 
  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 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 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 few common modules. The rest of the series will focus on teaching you about these common modules in more detail.