name: physics-matter

description: "Use this skill when using Matter.js physics in Phaser 4. Covers rigid bodies, constraints, composite bodies, sensors, collision filtering, world configuration, and advanced physics shapes. Triggers on: Matter, matter physics, constraint, joint, rigid body, sensor."

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