Phaser Matter Physics — Advanced Physics Simulation

DodaTech Updated 2026-06-28 3 min read

In this tutorial, you will learn about Phaser Matter Physics. We cover key concepts, practical examples, and best practices to help you master this topic.

Phaser Matter physics provides advanced 2D physics with complex body shapes, constraints, joints, sensors, and stacked object simulation.

What You'll Learn

By the end of this guide, you will create Matter bodies with custom shapes, use constraints for joints and springs, implement sensors for trigger zones, build stacked objects with friction, and create ragdoll physics.

Custom Body Shape

var body = Phaser.Physics.Matter.Matter.Bodies.polygon(200, 100, 6, 30);
var hexagon = this.matter.add.image(200, 100, 'hex', null, { shape: { type: 'fromVerts' } });

Constraints

var bodyA = this.matter.add.image(300, 100, 'box');
var bodyB = this.matter.add.image(400, 100, 'box');

this.matter.add.constraint(bodyA, bodyB, {
    length: 100,
    stiffness: 0.9,
    damping: 0.1
});

Ragdoll

// Create bodies for torso, head, arms, legs
// Connect them with constraints
var torso = this.matter.add.rectangle(300, 200, 40, 60);
var head = this.matter.add.circle(300, 150, 20);

this.matter.add.constraint(torso, head, {
    pointA: { x: 0, y: -30 },
    pointB: { x: 0, y: 20 },
    length: 5,
    stiffness: 1
});

Sensors

var sensor = this.matter.add.rectangle(200, 300, 80, 80, {
    isSensor: true,
    isStatic: true
});

this.matter.world.on('collisionstart', function(event) {
    event.pairs.forEach(function(pair) {
        if (pair.bodyA === sensor || pair.bodyB === sensor) {
            console.log('Sensor triggered');
        }
    });
});

Common Mistakes

1. Performance With Many Bodies

Matter handles hundreds of bodies. Beyond 500, use sleeping and compound bodies.

2. Body Not Visible

this.matter.add.image creates both physics body and sprite. this.matter.add.rectangle is invisible.

3. Constraint Stiffness Too Low

Low stiffness causes stretchy connections. Use 0.8-1.0 for rigid joints.

4. Sensor Not Detecting

Sensors only detect via collision events. They do not push objects.

5. World Bounds Not Set

Without world bounds, bodies fall forever. Set this.matter.world.setBounds(0, 0, 800, 600).

Practice Questions

Q1: How do you create a Matter body with image? A: Use this.matter.add.image(x, y, texture, null, options).

Q2: How do you create a constraint between two bodies? A: Use this.matter.add.constraint(bodyA, bodyB, config).

Q3: What is a sensor? A: A body with isSensor: true that detects overlaps without physical collision.

Q4: How do you make a body static? A: Set isStatic: true in the body options.

Q5: How do you handle collision events? A: Listen to 'collisionstart' and 'collisionend' events on matter.world.

Challenge: Build a tower of blocks that the player can shoot with a cannon. Use Matter physics for realistic stacking and falling. Add a score for blocks destroyed.

FAQ

Can I use both Arcade and Matter physics?

No. Choose one physics system per project.

How do I create a compound body?

Use Phaser.Physics.Matter.Matter.Body.create with parts array.

How do I set friction?

In body options: friction: 0.1, frictionAir: 0.01, frictionStatic: 0.5.

Can I use Matter with tilemaps?

Yes. Create static bodies from tilemap tiles.

How do I debug Matter bodies?

Set this.matter.world.drawDebug = true to see body outlines.

Try It Yourself

Create a stack of blocks with Matter physics.

<!DOCTYPE html>
<html>
<head>
    <title>Phaser Matter Physics</title>
    <script src="https://cdn.jsdelivr.net/npm/phaser@3/dist/phaser.min.js"></script>
</head>
<body style="font-family:sans-serif;padding:20px;">
<h2>Matter Physics Demo</h2>
<button onclick="addBlock()">Add Block</button>
<script>
var config = {
    type: Phaser.AUTO,
    width: 600,
    height: 400,
    backgroundColor: '#1a1a2e',
    physics: {
        default: 'matter',
        matter: {
            gravity: { y: 0.8 },
            debug: false
        }
    },
    scene: {
        create: function() {
            // Ground
            var ground = this.matter.add.rectangle(300, 380, 600, 40, { isStatic: true });
            ground.setDisplaySize(600, 40);
            ground.setFillStyle(0x333333);

            // Walls
            this.matter.add.rectangle(10, 200, 20, 400, { isStatic: true });
            this.matter.add.rectangle(590, 200, 20, 400, { isStatic: true });

            // Initial blocks
            for (var i = 0; i < 5; i++) {
                this.createBlock(200 + i * 40, 340, 0x4ecdc4);
            }

            window.matterScene = this;
        }
    }
};

var game = new Phaser.Game(config);

function addBlock() {
    var scene = window.matterScene;
    if (!scene) return;
    var x = 200 + Math.random() * 200;
    var y = 50;
    scene.createBlock(x, y, 0xff6b35);
}

// Add createBlock method to scene prototype
config.scene.createBlock = function(x, y, color) {
    var block = this.matter.add.rectangle(x, y, 40, 40, {
        restitution: 0.2,
        friction: 0.5
    });
    block.setDisplaySize(40, 40);
    block.setFillStyle(color);
};
</script>
</body>
</html>

What's Next

Implement responsive scaling.

Scaling — Responsive game scaling. Project — Complete Phaser project.

← Previous Phaser Arcade Physics — Simple 2D Physics Engine Next → Phaser Scaling — Responsive Game Layouts

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Phaser