Matter.js

The matter-js engine is extensible via a plugin system. You can use existing plugins, create your own, or follow a boilerplate to get started.

• Using plugins: Documentation
• Creating plugins: Documentation
• Plugin list: View available plugins
• Boilerplate: matter-plugin-boilerplate

For minimal usage examples that work in both browsers and Node.js, refer to the Getting started wiki page.

If you are building a custom game or rendering engine, consult the following wiki pages for guidance on integration:

• Running: How to use your own game loops.
• Rendering: How to use your own rendering loops.

You can install matter-js using npm or Yarn, or by including the script directly in your HTML.

Using npm

npm install matter-js

Using Yarn

yarn add matter-js

Using a script tag

Download a stable release and include it in your web page:

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

You can control which bodies collide using the collisionFilter object. It uses two main methods:

1. Group-based filtering: If two bodies have the same non-zero collisionFilter.group value, they will always collide if the value is positive, and never collide if the value is negative.
2. Category and Mask filtering: If groups are different or zero, the engine uses bitwise logic. A body A collides with body B only if (categoryA & maskB) !== 0 AND (categoryB & maskA) !== 0.

category should be a power of two (e.g., 0x0001, 0x0002) representing one of 32 possible categories. mask is a bitmask of all categories the body is allowed to collide with.

The Matter.Runner uses a timeBuffer to accumulate elapsed time between browser frames. It then attempts to run as many Engine.update calls as necessary to catch up to the elapsed time, using the fixed delta specified in the runner configuration.

To prevent the simulation from consuming too much CPU and blocking the browser UI, the runner respects two performance budgets:

1. maxFrameTime: Limits the total execution time of the runner's tick.
2. maxUpdates: Limits the total number of engine updates per frame.

If these budgets are exceeded, the runner will defer remaining updates to the next frame by storing the remaining time in the timeBuffer.

To be considered a valid plugin by the Matter.js Plugin system, an object must implement the following properties:

• name: A unique string identifier for the plugin.
• version: A semver-compatible version string (e.g., '1.0.0').
• install: A function that is called when the plugin is installed on a module. This function receives the target module as its argument.

Additionally, you can optionally specify a for property to restrict the plugin to specific modules or versions. The format for for is 'module-name' or 'module-name@version'. If for is not specified, the plugin is assumed to be applicable to any module.

const myPlugin = {
    name: 'my-plugin',
    version: '1.0.0',
    install: function(module) {
        // Extend the module here
        console.log('Installing my-plugin on', module.name);
    }
};

Matter.Vector is a utility module for creating and manipulating 2D vectors. A vector in Matter.js is a plain JavaScript object with the shape { x: number, y: number }. This module provides essential methods for physics-related calculations such as addition, subtraction, rotation, and magnitude.

Most methods allow for an optional output parameter. If provided, the result is written into that object instead of creating a new one, which helps reduce garbage collection overhead in high-frequency physics loops.

// Example of creating and adding vectors
const v1 = Matter.Vector.create(10, 20);
const v2 = Matter.Vector.create(5, 5);

// Returns a new vector { x: 15, y: 25 }
const result = Matter.Vector.add(v1, v2);

// Using an output object to avoid allocation
const output = { x: 0, y: 0 };
Matter.Vector.add(v1, v2, output);

The Matter.Runner module provides an optional utility for running a Matter.Engine inside a browser environment. It synchronizes engine updates with the browser's frame rate, favoring a smooth user experience over perfect timekeeping.

To use it, create a runner instance with Runner.create(options) and then start it with Runner.run(runner, engine). To stop the loop entirely, use Runner.stop(runner). To temporarily pause updates without stopping the loop, toggle the runner.enabled property.

var runner = Matter.Runner.create();
var engine = Matter.Engine.create();

Matter.Runner.run(runner, engine);

When integrating matter-js with certain bundlers or frameworks, default configurations may impact real-time physics performance:

• Webpack: The default sourcemap configuration can significantly impact performance. Refer to this issue for solutions.
• Vue.js: Vue's watchers can have a large impact on performance. Refer to this issue comment for a solution.

To rotate a vector around a pivot point rather than the origin (0, 0), use Matter.Vector.rotateAbout. This is useful for orbital mechanics or rotating objects around their center of mass.

Matter.Vector.rotateAbout(vector, angle, point, [output])

• vector: The vector to rotate.
• angle: The rotation angle in radians.
• point: The pivot point { x, y }.
• output (optional): An existing vector object to store the result.

const center = { x: 100, y: 100 };
const pos = { x: 110, y: 100 };
const angle = Math.PI; // 180 degrees

// Rotates 'pos' around 'center'
const newPos = Matter.Vector.rotateAbout(pos, angle, center);
// newPos will be { x: 90, y: 100 }