Use this skill when using Arcade Physics in Phaser 4. Covers enabling physics, velocity, acceleration, gravity, collisions, overlap, world bounds, physics groups, static bodies, and collision categories. Triggers on: physics, arcade, velocity, gravity, collide, overlap, bounce, physics body.

Arcade Physics Setting up and using Arcade Physics in Phaser 4 enabling physics in GameConfig, creating physics enabled sprites/images/groups, velocity, acceleration, gravity, collisions (collide/overlap), world bounds, body properties, and collision categories. Key source paths: src/physics/arcade/ArcadePhysics.js , src/physics/arcade/World.js , src/physics/arcade/Body.js , src/physics/arcade/StaticBody.js , src/physics/arcade/Factory.js , src/physics/arcade/components/ , src/physics/arcade/events/ Related skills: ../game setup and config/SKILL.md, ../sprites and images/SKILL.md, ../tilemaps/SKILL.md, ../groups and containers/SKILL.md Quick Start Core Concepts World ( this.physics.world ) The Phaser.Physics.Arcade.World manages all bodies in the simulation. Accessed via this.physics.world in a Scene. gravity Vector2 applied to all dynamic bodies each step. Set via config or this.physics.world.gravity.y = 300 . bounds Rectangle defining the world boundary. Defaults to game canvas size. bodies Set of all dynamic Body instances. staticBodies Set of all StaticBody instances. colliders ProcessQueue of registered Collider objects (from this.physics.add.collider / this.physics.add.overlap ). fps Physics steps per second (default 60). Read only; change via world.setFPS(120) . fixedStep true (default) uses fixed timestep; false syncs to render fps. timeScale Scaling factor: 1.0 = normal, 2.0 = half speed, 0.5 = double speed. isPaused When true, no bodies update and no colliders run. Toggle via world.pause() / world.resume() . useTree true (default) uses RTree spatial index for dynamic bodies. Disable for 5000+ bodies. drawDebug Enables debug rendering when true . Set via config debug: true . Bodies ( Body ) A dynamic body is created automatically when you use this.physics.add.sprite() or this.physics.add.image() . Access it via gameObject.body . Key properties (all on Body ): velocity Vector2 , pixels/sec acceleration Vector2 , pixels/sec^2 drag Vector2 , deceleration (applied only when acceleration is zero) gravity Vector2 , per body gravity added to world gravity bounce Vector2 , rebound factor relative to 1 friction Vector2 , default (1, 0) velocity imparted by immovable body to riding body maxVelocity Vector2 , default (10000, 10000) maxSpeed scalar cap, default 1 (none) mass default 1 , affects collision momentum exchange immovable false ; if true , never moved by collisions pushable true ; if false , reflects velocity to colliding body moves true ; if false , position/rotation not updated by physics enable true ; false removes from simulation useDamping false ; when true , drag is a multiplier (0 1) instead of linear collideWorldBounds false ; onWorldBounds/onCollide/onOverlap false , set true to emit events Shape: isCircle (set via setCircle ), width/height , offset ( Vector2 ), center (read only midpoint). Collision state (read only, reset each step): touching / blocked / wasTouching { none, up, down, left, right } . embedded both overlapping with zero velocity. Angular: angularVelocity (deg/sec), angularAcceleration , angularDrag , maxAngular (default 1000), allowRotation (default true). Static Bodies ( StaticBody ) A static body never moves and is not affected by gravity or velocity. It uses an optimized RTree for fast spatial lookups. Created via this.physics.add.staticSprite() , this.physics.add.staticImage() , or this.physics.add.staticGroup() . After changing the parent Game Object's position or scale, call body.reset() or gameObject.refreshBody() to sync. Has collisionCategory and collisionMask like dynamic bodies. Does not have velocity, acceleration, drag, or gravity properties. Common Patterns Enabling Physics on Existing Game Objects Creating Physics Sprites and Images Velocity and Gravity Collide and Overlap Two approaches: persistent Colliders (checked every frame automatically) or one shot checks (called in update() ). Groups PhysicsGroup config keys (applied as defaults to new members): collideWorldBounds , bounceX/Y , accelerationX/Y , dragX/Y , gravityX/Y , frictionX/Y , velocityX/Y , angularVelocity , angularAcceleration , angularDrag , maxVelocityX/Y , maxSpeed , mass , immovable , allowDrag , allowGravity , allowRotation , useDamping , enable . World Bounds Body Properties Collision Categories Collision categories let you filter which bodies can collide with each other using bitmask values. Maximum 32 categories. Default: all bodies have category 0x0001 and collisionMask 1 . Everything still collides with everything because (1 & 1) !== 0 . PhysicsGroup defaults to mask 2147483647 (all bits). Call resetCollisionCategory() to set the mask to all bits after changing categories. Configuration Reference ArcadeWorldConfig passed via physics.arcade in GameConfig or SceneConfig: Property Default Description fps 60 Physics steps per second fixedStep true Use fixed timestep vs render sync timeScale 1 Simulation speed multiplier gravity { x: 0, y: 0 } World gravity in px/sec x , y 0 World bounds origin width , height game size World bounds dimensions checkCollision all true { up, down, left, right } edge collision overlapBias 4 Overlap threshold for separation tileBias 16 Tile overlap threshold forceX false Separate horizontally first isPaused false Start simulation paused debug false Enable debug rendering debugShowBody / debugShowStaticBody / debugShowVelocity true Debug display toggles debugBodyColor / debugStaticBodyColor / debugVelocityColor 0xff00ff / 0x0000ff / 0x00ff00 Debug colors maxEntries 16 RTree items per node useTree true Use RTree for dynamic bodies customUpdate false If true, call world.update() yourself Scene level config overrides game level config (merged). Events All events are emitted on this.physics.world : Event String Condition Callback Args COLLIDE 'collide' Two bodies collide and at least one has onCollide = true (gameObject1, gameObject2, body1, body2) OVERLAP 'overlap' Two bodies overlap and at least one has onOverlap = true (gameObject1, gameObject2, body1, body2) WORLD BOUNDS 'worldbounds' Body hits world edge and has onWorldBounds = true (body, up, down, left, right) TILE COLLIDE 'tilecollide' Body collides with a tile (gameObject, tile, body) TILE OVERLAP 'tileoverlap' Body overlaps a tile (gameObject, tile, body) WORLD STEP 'worldstep' After each physics step (delta) PAUSE 'pause' World paused none RESUME 'resume' World resumed none Events require opt in per body: set body.onCollide , body.onOverlap , or body.onWorldBounds to true . API Quick Reference Scene Plugin ( this.physics ) Method Description this.physics.add.sprite(x, y, key, frame) Create sprite with dynamic body this.physics.add.image(x, y, key, frame) Create image with dynamic body this.physics.add.staticSprite(x, y, key, frame) Sprite with static body this.physics.add.staticImage(x, y, key, frame) Image with static body this.physics.add.group(config) Dynamic physics group this.physics.add.staticGroup(config) Static physics group this.physics.add.existing(go, isStatic?) Add body to existing Game Object this.physics.add.body(x, y, w?, h?) Standalone dynamic Body (no GO) this.physics.add.staticBody(x, y, w?, h?) Standalone static Body (no GO) this.physics.add.collider(a, b, cb?, proc?, ctx?) Persistent collider this.physics.add.overlap(a, b, cb?, proc?, ctx?) Persistent overlap this.physics.collide(a, b, cb?, proc?, ctx?) One shot collision check this.physics.overlap(a, b, cb?, proc?, ctx?) One shot overlap check this.physics.nextCategory() Next collision category bitmask this.physics.pause() / resume() Pause/resume simulation this.physics.accelerateTo(go, x, y, spd?, maxX?, maxY?) Accelerate toward point this.physics.moveTo(go, x, y, spd?, maxTime?) Move toward point at speed this.physics.velocityFromAngle(angle, speed?, vec2?) Angle (deg) to velocity this.physics.velocityFromRotation(rot, speed?, vec2?) Rotation (rad) to velocity this.physics.closest(source, targets?) Find nearest body this.physics.furthest(source, targets?) Find farthest body this.physics.overlapRect(x, y, w, h, dyn?, static?) Query bodies in rectangle this.physics.overlapCirc(x, y, r, dyn?, static?) Query bodies in circle Also: accelerateToObject , moveToObject , collideTiles , overlapTiles , enableUpdate , disableUpdate . World ( this.physics.world ) Method Description setBounds(x, y, w, h, left?, right?, up?, down?) Set boundary + edge checks setBoundsCollision(left?, right?, up?, down?) Set which edges collide setFPS(framerate) Change physics step rate enable(object, bodyType?) Enable physics on object/group/array disable(object) Disable physics on object/group/array add(body) / remove(body) Add/remove Body from simulation addCollider / addOverlap Create Collider (same args as factory) removeCollider(collider) Remove Collider pause() / resume() Pause/resume simulation createDebugGraphic() Create debug rendering graphic Body Methods Method Description setVelocity(x, y) / setVelocityX / setVelocityY Set velocity setAcceleration(x, y) / setAccelerationX / Y Set acceleration setMaxVelocity(x, y) / setMaxSpeed(speed) Velocity caps setBounce(x, y) / setDrag(x, y) Bounce and drag setDamping(bool) Enable damping mode setFriction(x, y) / setGravity(x, y) Friction and per body gravity setMass(val) / setImmovable(bool) / setPushable(bool) Mass and collision behavior setSize(w, h, center?) / setOffset(x, y) Resize/offset body setCircle(radius, offX?, offY?) Switch to circular body setCollideWorldBounds(val, bX?, bY?) World bounds collision setBoundsRectangle(rect) Custom bounds rectangle setAllowGravity / setAllowDrag / setAllowRotation Toggle physics features setEnable(val) Enable/disable body setCollisionCategory / setCollidesWith / addCollidesWith / removeCollidesWith Category filtering resetCollisionCategory() Reset to default (all) reset(x, y) / stop() Reset position or zero velocity Gotchas 1. debug: true in production Debug rendering is expensive. Always disable for release builds. 2. Static body transform changes After changing position, scale, or origin of a static body's Game Object, you must call body.reset() or gameObject.refreshBody() . Static bodies do not auto sync. 3. collide vs overlap collide performs separation (pushes bodies apart). overlap only detects intersection without moving anything. Use overlap for triggers like pickups. 4. Persistent Collider vs one shot this.physics.add.collider() creates a Collider checked every frame automatically. this.physics.collide() is a one shot check that must be called each frame in update() . Prefer persistent Colliders. 5. Events require opt in World events ( 'collide' , 'overlap' , 'worldbounds' ) only fire if the relevant body property (

physics-arcade