Physics Matter

Matter.js Physics

Setting up and using Matter.js physics in Phaser 4 -- full-body physics with rigid bodies, compound bodies, constraints, composites, sensors, collision filtering, pointer dragging, tilemap integration, and debug rendering.

Key source paths: src/physics/matter-js/MatterPhysics.js, src/physics/matter-js/World.js, src/physics/matter-js/Factory.js, src/physics/matter-js/MatterSprite.js, src/physics/matter-js/MatterImage.js, src/physics/matter-js/MatterGameObject.js, src/physics/matter-js/PointerConstraint.js, src/physics/matter-js/MatterTileBody.js, src/physics/matter-js/components/, src/physics/matter-js/events/, src/physics/matter-js/typedefs/ Related skills: ../game-setup-and-config/SKILL.md, ../sprites-and-images/SKILL.md, ../physics-arcade/SKILL.md, ../tilemaps/SKILL.md

Quick Start

class GameScene extends Phaser.Scene {
    create() {
        // Matter sprite (dynamic, has animation support)
        this.player = this.matter.add.sprite(400, 200, 'player');
        this.player.setBounce(0.5);
        this.player.setFriction(0.05);

        // Matter image (dynamic, no animation)
        const box = this.matter.add.image(300, 100, 'crate');

        // Static body from raw shape
        this.matter.add.rectangle(400, 580, 800, 40, { isStatic: true });

        // Enable pointer dragging on all bodies
        this.matter.add.mouseSpring();

        this.cursors = this.input.keyboard.createCursorKeys();
    }

    update() {
        if (this.cursors.left.isDown) {
            this.player.setVelocityX(-5);
        } else if (this.cursors.right.isDown) {
            this.player.setVelocityX(5);
        }
        if (this.cursors.up.isDown && this.player.body.velocity.y > -0.1) {
            this.player.setVelocityY(-10);
        }
    }
}

// Enable Matter physics in game config
const config = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    physics: {
        default: 'matter',
        matter: {
            gravity: { y: 1 },
            enableSleeping: true,
            debug: true,
            setBounds: true    // walls around canvas edges
        }
    },
    scene: GameScene
};

const game = new Phaser.Game(config);

Core Concepts

Scene Plugin (this.matter)

The MatterPhysics class is the scene-level plugin. Key properties:

• `this.matter.add` -- Factory for creating bodies, constraints, Game Objects (auto-added to world).
• `this.matter.world` -- World instance managing the engine, bounds, debug rendering. Extends EventEmitter.
• `this.matter.body` / `bodies` / `composite` / `composites` / `constraint` -- Direct references to Matter.js modules for low-level use.
• `this.matter.bodyBounds` -- Helper for aligning bodies by visual bounds.

World (this.matter.world)

• `engine` -- The MatterJS.Engine instance.
• `localWorld` -- The MatterJS.World composite containing all bodies and constraints.
• `enabled` -- Boolean; false pauses simulation. `autoUpdate` -- true = engine updates each game step.
• `walls` -- { left, right, top, bottom } boundary wall bodies (or null).

World Config (MatterWorldConfig)

Passed under physics.matter in game or scene config:

Matter Game Objects

Phaser provides two physics-aware Game Object classes and a function to add physics to any Game Object:

• `Phaser.Physics.Matter.Sprite` -- Extends Sprite with all Matter components. Created via this.matter.add.sprite(x, y, key, frame, options). Supports animations.
• `Phaser.Physics.Matter.Image` -- Extends Image with all Matter components. Created via this.matter.add.image(x, y, key, frame, options). No animation support, lighter weight.
• `MatterGameObject(world, gameObject, options)` -- Injects all Matter components into any existing Game Object. Created via this.matter.add.gameObject(mySprite, options).

Both MatterSprite and MatterImage default to a rectangle body matching the texture size. Pass options.shape to override.

Matter Components (Mixins)

All Matter Game Objects have these component methods mixed in:

Common Patterns

Setup and World Configuration

// Runtime gravity and bounds
this.matter.world.setGravity(0, 2);          // x, y, scale (default 0.001)
this.matter.world.disableGravity();
this.matter.world.setBounds(0, 0, 1600, 1200, 64, true, true, true, true);

this.matter.set60Hz();                        // fixed timestep
this.matter.world.autoUpdate = false;         // then manual: this.matter.step(16.666);
this.matter.pause();                          // pause/resume
this.matter.resume();

Creating Matter Sprites and Images

const player = this.matter.add.sprite(200, 300, 'hero');  // default rect body matching texture

// Custom body shapes via options.shape
const ball = this.matter.add.image(400, 100, 'ball', null, { shape: { type: 'circle', radius: 24 } });
const hex = this.matter.add.sprite(300, 100, 'hex', null, { shape: { type: 'polygon', sides: 6, radius: 32 } });
const ship = this.matter.add.sprite(400, 200, 'ship', null, {
    shape: { type: 'fromVerts', verts: '0 0 40 0 40 40 20 60 0 40' }
});

// PhysicsEditor shape data
const shapes = this.cache.json.get('shapes');
const enemy = this.matter.add.sprite(500, 200, 'enemy', null, { shape: shapes.enemy });

// Add Matter physics to an existing Game Object
const existingSprite = this.add.sprite(100, 100, 'box');
this.matter.add.gameObject(existingSprite, { restitution: 0.8 });
// existingSprite now has setVelocity, setBounce, etc.

Body Configuration Options (MatterBodyConfig)

Pass as the options parameter to any factory method or as the options for a Matter Game Object:

• label, isStatic, isSensor, angle (radians), timeScale, ignoreGravity, ignorePointer
• density (0.001 default, auto-calculates mass), mass, restitution (bounce 0-1)