physics-matter

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha d14f4c86f869 · 31 Oct 2026Report an issue or request a re-scan

• Publisherphaserjs GitHub organizationOwner of the repository this skill is read from
• Source folderphaserjs/phaser/skills/physics-matterThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictd14f4c86f869A new audit runs when the source changes
• Repository statusNot archivedLast push 71 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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…

---
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

```js
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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/phaserjs/phaser
git -C phaser checkout d14f4c86f869

Works in

1. 2026-10-31
   ✓SAFE B 89 / 100

   first audit · source d14f4c86f869

Questions about physics-matter

• github.com/phaserjs/phaser/tree/master/skills/physics-matter — the audited source at commit d14f4c86f869 and every finding aboveObserved · 31 Oct 2026

Spotted something wrong? Report a correction · Methodology