phaser-arcade-physics

Phaser 4 Arcade Physics

Add movement and collision to a Phaser game with the lightweight Arcade Physics engine (AABB rectangles and circles only). Targets Phaser 4.2 for new projects; inspect the installed major before editing an existing project.

When to use

• Use for top-down or platformer movement, velocity/acceleration/gravity, bouncing, world bounds, and collision/overlap resolution between sprites, groups, and tiles.
• Use when the scene enables physics: { default: 'arcade' } and code calls this.physics.add.*, body.setVelocity, or this.physics.add.collider.

When not to use: the Game config, scene structure, asset loading, or cameras → use phaser-core. Hinges, springs, complex polygons, or stacking rigid bodies → use Matter physics (a different engine; Arcade and Matter bodies do not interact). For engine-agnostic feel tuning see physics-tuning.

Core workflow

1. Enable the world. Set physics: { default: 'arcade', arcade: { gravity: {...}, debug: true } } in the game or scene config. Turn debug on while building to see body outlines and velocity vectors.
2. Give a sprite a body. Create it with this.physics.add.sprite(...) (dynamic) or this.physics.add.staticImage(...) (static), or attach to an existing object with this.physics.add.existing(obj).
3. Drive it through the body, not by setting x/y. Use setVelocity, setAcceleration, gravity, setBounce, and setCollideWorldBounds. The engine integrates position from velocity each step (already frame-rate independent).
4. Resolve interactions. this.physics.add.collider(a, b) separates bodies; this.physics.add.overlap(a, b, cb) detects without separating (pickups, triggers). Pass a callback to react.
5. Group many objects. Use this.physics.add.group() (dynamic) or staticGroup() (platforms) so one collider call handles all members.
6. Check ground contact with body.onFloor() / body.blocked.down before jumping. Run with debug: true and confirm bodies, contacts, and bounds.

Patterns

1. Enable Arcade Physics (game config)

const config = {
  type: Phaser.AUTO,
  width: 800, height: 600,
  physics: {

2. Top-down movement (velocity from input)

3. Platformer jump (gravity + ground check)

4. Colliders vs overlaps (separate vs detect)

5. A group of moving objects

Pitfalls

• Sprite ignores physics → it was added with this.add.sprite instead of this.physics.add.sprite (or this.physics.add.existing(obj)), so it has no body.
• Setting sprite.x directly fights the engine → move dynamic bodies with setVelocity/setAcceleration. Direct position writes can tunnel through colliders.
• Diagonal movement is faster → independent X and Y velocities add up; normalise the velocity vector and rescale to the intended speed.
• Platforms get pushed by the player → use a staticGroup, or set body.setImmovable(true) on a dynamic platform.
• onFloor() is always false → the body needs something to collide with; add the collider against the ground/platforms before checking, and ensure gravity is on.
• Moved a static body but collisions are stale → static bodies don't auto-sync; call body.updateFromGameObject() (or refreshBody() on the game object).
• Collider added every frame → register collider/overlap once in create, not in update.

References

• For body anatomy and tuning (drag, bounce, max velocity, custom setSize/ setCircle/setOffset hitboxes, collision categories/masks, and worldbounds events), read references/bodies-and-collision.md.

Related skills

• phaser-core — game config, scenes, loader, cameras (the prerequisite setup).
• physics-tuning — engine-agnostic feel (fixed timestep, tunneling, jitter).
• platformer / tower-defense — genres that compose this skill.
• level-design — laying out tile/platform geometry these bodies collide with.