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 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() , setSleepThreshold(n) , setSleepEvents(start, end) Collision setCollisionCategory(cat) , setCollisionGroup(group) , setCollidesWith(cats) , setOnCollide(cb) , setOnCollideEnd(cb) , setOnCollideActive(cb) , setOnCollideWith(body, cb) SetBody setRectangle(w, h, opts) , setCircle(r, opts) , setPolygon(r, sides, opts) , setTrapezoid(w, h, slope, opts) , setBody(config, opts) , setExistingBody(body) Transform Position sync between Matter body and Game Object Common Patterns Setup and World Configuration Creating Matter Sprites and Images 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) friction (0 1), frictionAir (air resistance), frictionStatic (stickiness when still) slop (overlap tolerance), chamfer ( { radius: 5 } for rounded corners) collisionFilter: { category: 0x0001, mask: 0xFFFFFFFF, group: 0 } onCollideCallback , onCollideEndCallback , onCollideActiveCallback shape (for Game Objects): { type: 'circle', radius: 24 } or PhysicsEditor data Velocity, Forces, and Thrust Constraints (Joints and Springs) Composites (Stacks, Chains, Soft Bodies) Compound Bodies Combine multiple shapes into a single body. The first part is the parent. Parts share position, angle, and velocity. Constraints must target the parent body, not parts. Sleep System Bodies at rest can sleep to skip simulation. Requires enableSleeping: true in config. Sensors Sensors detect collisions but do not physically react. Useful for trigger zones, pickups, detection areas. Collision Categories and Filtering Matter uses bitmasks: category (which group this body belongs to, power of 2), mask (which categories it collides with), and group (shortcut: same positive = always collide, same negative = never collide, 0 = use category/mask). Collision Callbacks Tilemap Integration Friction Types Matter.js has three independent friction values: Complex Shapes from Vertices Pointer Constraint (Mouse/Touch Dragging) Queries (Raycasting and Hit Testing) Debug Rendering Events All events are emitted on this.matter.world (which extends EventEmitter ): Event Callback Signature When 'collisionstart' (event, bodyA, bodyB) Two bodies first start colliding 'collisionactive' (event, bodyA, bodyB) Two bodies are still colliding 'collisionend' (event, bodyA, bodyB) Two bodies stop colliding 'beforeupdate' (event) Before engine update step 'afterupdate' (event) After engine update step 'beforeadd' (event) Before a body/constraint is added 'afteradd' (event) After a body/constraint is added 'beforeremove' (event) Before a body/constraint is removed 'afterremove' (event) After a body/constraint is removed 'dragstart' (body, part, constraint) Pointer starts dragging body 'drag' (body, constraint) Pointer is dragging body 'dragend' (body, constraint) Pointer stops dragging body 'sleepstart' (event, body) Body goes to sleep (requires setSleepEvents ) 'sleepend' (event, body) Body wakes up (requires setSleepEvents ) 'pause' none World paused 'resume' none World resumed Collision events include event.pairs an array of collision pair objects with bodyA , bodyB , collision depth, and normal. API Quick Reference this.matter.add (Factory) Game Objects: sprite(x, y, key, frame?, opts?) , image(x, y, key, frame?, opts?) , gameObject(go, opts?) , tileBody(tile, opts?) Body shapes: rectangle(x, y, w, h, opts?) , circle(x, y, r, opts?) , polygon(x, y, sides, r, opts?) , trapezoid(x, y, w, h, slope, opts?) , fromVertices(x, y, verts, opts?) , fromPhysicsEditor(x, y, config, opts?) , fromSVG(x, y, xml, scale?, opts?) , fromJSON(x, y, config, opts?) Constraints: constraint(a, b, len?, stiff?, opts?) (aliases: joint , spring ), worldConstraint(body, len?, stiff?, opts?) , mouseSpring(opts?) (alias: pointerConstraint ) Composites: stack(x, y, cols, rows, colGap, rowGap, cb) , imageStack(key, frame, x, y, cols, rows) , pyramid(...) , chain(composite, xA, yA, xB, yB, opts?) , mesh(composite, cols, rows, cross, opts?) , softBody(...) , car(x, y, w, h, wheelSize) , newtonsCradle(x, y, num, size, len) this.matter (MatterPhysics) batch and utility pause() , resume() , set60Hz() , set30Hz() , step(delta?) , setVelocity(bodies, x, y) , setAngularVelocity(bodies, v) , applyForce(bodies, force) , applyForceFromAngle(bodies, speed, angle?) , containsPoint(body, x, y) , intersectPoint(x, y) , intersectRect(x, y, w, h, outside?) , intersectRay(x1, y1, x2, y2, width?) , intersectBody(body) , overlap(target, bodies?, cb?) , setCollisionCategory(bodies, value) , setCollisionGroup(bodies, value) , setCollidesWith(bodies, cats) , alignBody(body, x, y, align) this.matter.world (World) setBounds(x?, y?, w?, h?, thickness?, l?, r?, t?, b?) , setGravity(x?, y?, scale?) , disableGravity() , add(object) , remove(object, deep?) , removeConstraint(constraint) , convertTilemapLayer(layer, opts?) , convertTiles(tiles, opts?) , nextCategory() , nextGroup(isNonColliding?) , getAllBodies() , has(body) , pause() , resume() Direct Matter.js module references on this.matter body (Matter.Body), bodies (Matter.Bodies), composite (Matter.Composite), composites (Matter.Composites), constraint (Matter.Constraint), detector , query , pair , pairs , resolver , axes , bounds , svg , vector , vertices Gotchas Force values are tiny. Use 0.01 0.1 for forces, 1 15 for velocity. Not pixel based. setBody / setRectangle /etc. resets all properties mass, friction, collision filters, callbacks are wiped. Re apply after changing shape. Constraints must target parent body , not compound body parts . 32 collision categories max. Each nextCategory() uses one bit. collisionFilter.group overrides category/mask. Same positive = always collide; same negative = never collide; zero/different = use category/mask. Sensors still need matching collision filters to fire events. Matter position is center of mass , not top left (unlike Arcade Physics). Sleep events require opt in: sprite.setSleepEvents(true, true) . Tilemap conversion requires collision set first via setCollisionByProperty etc. Restitution uses Math.max(bodyA.restitution, bodyB.restitution) the bouncier value wins. body.ignorePointer = true prevents pointer constraint from dragging that body. Source File Map Path Purpose src/physics/matter js/MatterPhysics.js Scene plugin ( this.matter ), exposes all Matter modules src/physics/matter js/World.js World management, engine, bounds, debug, events proxy src/physics/matter js/Factory.js this.matter.add all creation methods src/physics/matter js/MatterSprite.js Physics sprite (Sprite + Matter components) src/physics/matter js/MatterImage.js Physics image (Image + Matter components) src/physics/matter js/MatterGameObject.js Injects Matter components into any Game Object src/physics/matter js/MatterTileBody.js Wraps a Tile with a Matter body src/physics/matter js/PointerConstraint.js Click and drag body constraint src/physics/matter js/BodyBounds.js Body alignment by visual bounds

physics-matter