matter-js

Matter.js is a JavaScript 2D rigid body physics engine for the web

brm.io/matter-js

Demos ・ Gallery ・ Features ・ Plugins ・ Install ・ Usage ・ Examples ・ Docs ・ Wiki ・ References ・ License

Demos

Mixed Shapes Solid Shapes Concave SVG Paths Concave Terrain Concave Bodies Compound Bodies Newton's Cradle Wrecking Ball Slingshot Game Rounded Corners Views Time Scaling Body Manipulation Composite Manipulation

Raycasting Sprites Pyramid Car Catapult Reverse Gravity Bridge Avalanche Basic Soft Bodies Cloth Events Collision Filtering Chains Ball Pool

Stack Circle Stack Compound Stack Restitution Friction Air Friction Static Friction Sleeping Beach Balls Stress 1 Stress 2 Sensors

Gallery

See how others are using matter.js physics

• Patrick Heng by Patrick Heng
• USELESS by Nice and Serious
• Secret 7 by Goodness
• New Company by New Company
• Game of The Year by Google
• Pablo The Flamingo by Nathan Gordon
• Les métamorphoses de Mr. Kalia by Lab212
• Phaser by Photon Storm
• Sorry I Have No Filter by Jessica Walsh
• Fuse by Fuse
• Glyphfinder by überdosis
• Isolation by sabato studio
• more...

Features

• Rigid bodies
• Compound bodies
• Composite bodies
• Concave and convex hulls
• Physical properties (mass, area, density etc.)
• Restitution (elastic and inelastic collisions)
• Collisions (broad-phase, mid-phase and narrow-phase)
• Stable stacking and resting
• Conservation of momentum
• Friction and resistance
• Events
• Constraints
• Gravity
• Sleeping and static bodies
• Plugins
• Rounded corners (chamfering)
• Views (translate, zoom)
• Collision queries (raycasting, region tests)
• Time scaling (slow-mo, speed-up)
• Canvas renderer (supports vectors and textures)
• MatterTools for creating, testing and debugging worlds
• World state serialisation (requires resurrect.js)
• Cross-browser and Node.js support (Chrome, Firefox, Safari, IE8+)
• Mobile-compatible (touch, responsive)
• An original JavaScript physics implementation (not a port)

Install

You can install using package managers npm and Yarn using:

npm install matter-js

Alternatively you can download a stable release or try the latest experimental alpha build (master) and include the script in your web page:

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

Performance with other tools (e.g. Webpack, Vue etc.)

Bundlers and frameworks may reduce real-time performance when using their default configs, especially in development modes.

When using Webpack, the default sourcemap config can have a large impact, for a solution see issue.

When using Vue.js, watchers can have a large impact, for a solution see issue.

Usage

Visit the Getting started wiki page for a minimal usage example which should work in both browsers and Node.js.
Also see the Running and Rendering wiki pages, which show how to use your own game and rendering loops.

Tutorials

See the list of tutorials.

Examples

See the examples directory which contains the source for all demos.
There are even more examples on codepen.

Plugins

The engine can be extended through plugins, see these resources:

• Using plugins
• Creating plugins
• List of plugins
• matter-plugin-boilerplate

Documentation

See the API Documentation and the wiki

Building and Contributing

To build you must first install node.js, then run

npm install

This will install the required build dependencies, then run

npm run dev

to spawn a development server. For information on contributing see CONTRIBUTING.md.

Changelog

To see what's new or changed in the latest version, see the changelog.

References

See the wiki page on References.

License

Matter.js is licensed under The MIT License (MIT)
Copyright (c) 2014 Liam Brummitt

This license is also supplied with the release and source code.
As stated in the license, absolutely no warranty is provided.

Changelog

0.20.0 (2024-06-23)

• added event passive options to Matter.Mouse, closes #930, closes #976 (e888f3c), closes #930 #976
• added arrow key navigation of examples in development demo (45cad77)
• added body removal to Example.remove (1209e88)
• added Constraint.currentLength, closes #1184 (812f8af), closes #1184
• added doc and warning for Bodies.trapezioid slope parameter range, closes #1075 (7ea5bc1), closes #1075
• added docs for body.chamfer property, closes #1059 (5ed985d), closes #1059
• added engine beforeSolve event, closes #1173 (8dd0e99), closes #1173
• added event.timestamp and event.delta to collision events, closes #368 (2af54d5), closes #368
• added Example.renderResize (b88c82f)
• added Example.stress4 (0f0ac93)
• added Example.substep (205aaa5)
• added high delta warning to Matter.Engine (72e6e89)
• added local pairs functions in Pairs.update (e9da32c)
• added new Matter.Runner with default fixed timestep (3e61951)
• added pixel ratio scaling to render debug stats (7ec38a1)
• added render.options.wireframeStrokeStyle, closes #406 (401553d), closes #406
• added Render.setSize, closes #955, closes #595 (fc05839), closes #955 #595
• added repeats and updates options to test tools (6142991)
• added updates per frame to Matter.Render debug (a5b5767)
• changed Composte.removeComposite and Composte.removeBody to reset body.sleepCounter (6d10c3d)
• changed Pair.id format to use shorter ids (5b6f30b)
• fixed collision events for sleeping pairs, closes #1077 (51f49ce), closes #1077
• fixed missing mouse.sourceEvents.mousewheel, closes #1146 (272049a), closes #1146
• fixed Body.setStatic when applied multiple times, closes #641 (9655785), closes #641
• fixed compare tool layer order in demo testbed (a3e801a) (0cc4d96)
• fixed Runner.stop docs re. runner.enabled, closes #586, closes #1054 (2ecc563), closes #586 #1054
• improved Example.substep comments (8046341)
• improved Matter.Runner (b8a1563) (7206600)
• improved Matter.Runner docs (283cd96) (dc693e7) (6e302a8)
• improved test comparison report (962fba5) (2cc1c1c)
• improved body.parts docs (013698b) (411af06), closes #600 (c1f9584), closes #600
• optimised Collision._findSupports (653a110)
• optimised Collision.collides (6f8a54b)
• optimised contacts and supports memory and gc use (97d502e)
• optimised pairs and collisions memory and gc use (f9208df)
• optimised Resolver.solvePosition (89963f7)
• optimised Resolver.solveVelocity (182ba90)
• preserve pair.contacts order (e891d37)
• reduced canvas hit testing in demo when using matter-tools (da99acb)
• removed redundant runner.isFixed from examples (aba0e9e)
• removed Collision._projectToAxis (4c56e5b)
• removed pair.confirmedActive (72bc203)
• renamed Composites function xx and yy params, closes #1095 (6bda7e8), closes #1095
• updated development demo render options (0b131a4)
• updated benchmark tests (e668c02)