physics-arcade

# 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 ```js class GameScene extends Phaser.Scene { create() { // Physics sprite (dynamic body, affected by gravity) this.player = this.physics.add.sprite(100, 300, 'player'); this.player.setCollideWorldBounds(true); this.player.setBounce(0.2); // Static group (immovable platforms) this.platforms = this.physics.add.staticGroup(); this.platforms.create(400, 568, 'ground').setScale(2).refreshBody(); // Register a persistent collider (checked every frame automatically) this.physics.add.collider(this.player, this.platforms); this.cursors = this.input.keyboard.createCursorKeys(); } update() { if (this.cursors.left.isDown) { this.player.setVelocityX(-160); } else if (this.cursors.right.isDown) { this.player.setVelocityX(160); } else { this.player.setVelocityX(0); } } } // Enable Arcade Physics in game config const config = { type: Phaser.AUTO, width: 800, height: 600, physics: { default: 'arcade', arcade: { gravity: { y: 300 }, debug: false } }, scene: GameScene }; const game = new Phaser.Game(config); ``` ## 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 ```js // Add a physics body to any existing Game Object this.physics.add.existing(mySprite); // dynamic body this.physics.add.existing(mySprite, true); // static body // Or enable via the world directly this.physics.world.enable(mySprite); // dynamic this.physics.world.enable(mySprite, Phaser.Physics.Arcade.STATIC_BODY); ``` ### Creating Physics Sprites and Images ```js // Via the physics factory (this.physics.add) const player = this.physics.add.sprite(100, 200, 'player'); // dynamic body const coin = this.physics.add.image(300, 100, 'coin'); // dynamic body const wall = this.physics.add.staticImage(400, 300, 'wall'); // static body const platform = this.physics.add.staticSprite(400, 500, 'plat'); // static body // Standalone bodies (no Game Object) const sensor = this.physics.add.body(200, 200, 32, 32); // dynamic Body const zone = this.physics.add.staticBody(100, 100, 64, 64); // static Body ``` ### Velocity and Gravity ```js // Direct velocity player.setVelocity(200, -300); // x=200 px/s, y=-300 px/s (upward) player.setVelocityX(200); player.body.velocity.set(200, -300); // equivalent via Vector2 // Acceleration + max velocity player.setAcceleration(100, 0); player.setMaxVelocity(300, 600); // Per-body gravity (added to world gravity) player.body.gravity.y = 200; player.body.allowGravity = false; // exempt from world gravity // Drag (applied only when acceleration is zero) player.setDrag(300); // linear deceleration player.body.useDamping = true; player.setDrag(0.05); // damping mode: keeps 5% velocity/sec // Bounce player.setBounce(0.5); // both axes player.setBounceY(1); // full vertical bounce ``` ### Collide and Overlap Two approaches: **persistent Colliders** (checked every frame automatically) or **one-shot checks** (called in `update()`). ```js // --- Persistent Colliders (preferred) --- // Created via this.physics.add.collider / this.physics.add.overlap // Automatically checked every physics step const collider = this.physics.add.collider(player, platforms); const overlap = this.physics.add.overlap(player, coins, collectCoin, null, this); function collectCoin (player, coin) { coin.disableBody(true, true); // disable physics and hide } // Collider management collider.active = false; // temporarily disable collider.destroy(); // remove permanently // With processCallback (must return boolean to allow collision) this.physics.add.collider(player, enemies, onHit, canCollide, this); function canCollide (player, enemy) { return !player.getData('invincible'); } // --- One-shot checks (in update) --- // Called manually each frame; no Collider object created this.physics.collide(player, platforms); this.physics.overlap(player, coins, collectCoin, null, this); // Self-collision within a single group this.physics.add.collider(enemies, enemies); ``` ### Groups ```js // Dynamic physics group -- members get dynamic bodies automatically const bullets = this.physics.add.group({ classType: Phaser.Physics.Arcade.Sprite, // default: ArcadeSprite maxSize: 20, collideWorldBounds: true, bounceX: 1, bounceY: 1, velocityX: 200, velocityY: 0, allowGravity: false, immovable: false }); // Static physics group -- members get static bodies const platforms = this.physics.add.staticGroup(); platforms.create(400, 568, 'ground'); platforms.create(600, 400, 'ground'); // After modifying a static group member's transform, refresh: platforms.create(400, 568, 'ground').setScale(2).refreshBody(); // Group velocity helpers bullets.setVelocity(200, 0); // all members bullets.setVelocityX(200); bullets.setVelocityY(0, 10); // with step increment per member ``` 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 ```js // Set bounds size and which edges collide (left, right, up, down) this.physics.world.setBounds(0, 0, 1600, 1200, true, true, false, true); this.physics.world.setBoundsCollision(true, true, false, true); // edges only // Per-body world bounds player.setCollideWorldBounds(true); player.body.setBoundsRectangle(new Phaser.Geom.Rectangle(100, 100, 600, 400)); player.body.worldBounce = new Phaser.Math.Vector2(0.5, 0.5); // Detect world bounds hit via event (requires opt-in) player.body.onWorldBounds = true; this.physics.world.on('worldbounds', (body, up, down, left, right) => { console.log('Hit edge:', { up, down, left, right }); }); ``` ### Body Properties ```js // Size and shape player.body.setSize(24, 32, true); // width, height, re-center on GO player.body.setOffset(4, 0); // offset from GO position player.body.setCircle(16); // circular body, radius 16 player.body.setCircle(16, 4, 4); // circular with offset // Collision behavior player.body.setImmovable(true); // not moved by collisions player.body.setPushable(false); // reflects velocity to collider player.body.slideFactor.set(0, 0); // Sokoban-style: stops after push player.body.setMass(2); // affects momentum exchange // Enable / disable player.disableBody(true, true); // disable body + hide Game Object player.enableBody(true, x, y, true, true); // re-enable at position + show // Per-direction collision check player.body.checkCollision.up = false; // don't collide from above player.body.syncBounds = true; // auto-sync size to texture ``` ### Collision Categories Collision categories let you filter which bodies can collide with each other using bitmask values. Maximum 32 categories. ```js // Get unique category values from the physics plugin const CAT_PLAYER = this.physics.nextCategory(); // 0x0002 const CAT_ENEMY = this.physics.nextCategory(); // 0x0004