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

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

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

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

// 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()).

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