/physics-matter

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:

| Property | Default | Purpose | |---|---|---| | `gravity` | `{ x: 0, y: 1 }` | Gravity vector. Set `false` to disable | | `setBounds` | `false` | `true` or `{ x, y, width, height, thickness, left, right, top, bottom }` | | `enableSleeping` | `false` | Allow bodies to sleep when at rest | | `positionIterations` | `6` | Position solving accuracy | | `velocityIterations` | `4` | Velocity solving accuracy | | `constraintIterations` | `2` | Constraint stability | | `timing.timeScale` | `1` | `0` freezes, `0.5` slow-motion | | `autoUpdate` | `true` | Auto-step each game frame | | `debug` | `false` | `true` or `MatterDebugConfig` object | | `runner` | `{}` | Use `runner.fps` for fixed timestep |

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:

| Component | Key Methods | |---|---| | **Velocity** | `setVelocity(x, y)`, `setVelocityX(x)`, `setVelocityY(y)`, `getVelocity()`, `setAngularVelocity(v)`, `getAngularVelocity()`, `setAngularSpeed(s)`, `getAngularSpeed()` | | **Force** | `applyForce(vec2)`, `applyForceFrom(position, force)`, `thrust(speed)`, `thrustLeft(speed)`, `thrustRight(speed)`, `thrustBack(speed)` | | **Bounce** | `setBounce(value)` -- restitution, 0 to 1 | | **Friction** | `setFriction(value, air?, fstatic?)`, `setFrictionAir(value)`, `setFrictionStatic(value)` | | **Mass** | `setMass(value)`, `setDensity(value)`, `centerOfMass` (getter) | | **Gravity** | `setIgnoreGravity(bool)` | | **Sensor** | `setSensor(bool)`, `isSensor()` | | **Static** | `setStatic(bool)`, `isStatic()` | | **Sleep** | `setToSleep()`, `setAwake()`, `setSlee