Physics matters

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