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
- 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.
- 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).
- 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).
- 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.
- Group many objects. Use
this.physics.add.group() (dynamic) or
staticGroup() (platforms) so one collider call handles all members.
- 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: {
default: 'arcade',
arcade: {
gravity: { x: 0, y: 600 }, // top-down? use { x: 0, y: 0 }
debug: false // true to draw bodies + velocity while building
}
},
scene: [PlayScene]
};
new Phaser.Game(config);
2. Top-down movement (velocity from input)
create() {
this.player = this.physics.add.sprite(400, 300, 'player');
this.player.setCollideWorldBounds(true);
this.cursors = this.input.keyboard.createCursorKeys();
}
update() {
const speed = 220;
const body = this.player.body;
body.setVelocity(0); // reset each frame
if (this.cursors.left.isDown) body.setVelocityX(-speed);
if (this.cursors.right.isDown) body.setVelocityX(speed);
if (this.cursors.up.isDown) body.setVelocityY(-speed);
if (this.cursors.down.isDown) body.setVelocityY(speed);
body.velocity.normalize().scale(speed); // keep diagonals same speed
}
3. Platformer jump (gravity + ground check)
create() {
this.player = this.physics.add.sprite(100, 450, 'player');
this.player.setCollideWorldBounds(true);
// Static platforms: one body each, never moved by collisions.
this.platforms = this.physics.add.staticGroup();
this.platforms.create(400, 568, 'ground');
this.physics.add.collider(this.player, this.platforms);
this.cursors = this.input.keyboard.createCursorKeys();
}
update() {
const // or this.player.body.onFloor()
if (this.cursors.left.isDown) this.player.setVelocityX(-160);
else if (this.cursors.right.isDown) this.player.setVelocityX(160);
else this.player.setVelocityX(0);
if (this.cursors.up.isDown && onGround) this.player.setVelocityY(-450);
}
4. Colliders vs overlaps (separate vs detect)
// Push apart and react: player vs enemies.
this.physics.add.collider(this.player, this.enemies, (player, enemy) => {
this.handleHit(player, enemy);
});
// Detect without pushing: collect coins. The 4th arg is an optional
// process callback returning a boolean to filter pairs before the main callback.
this.physics.add.overlap(this.player, this.coins, (player, coin) => {
coin.disableBody(true, true); // deactivate + hide
this.registry.inc('score', 10);
});
5. A group of moving objects
this.bullets = this.physics.add.group({
defaultKey: 'bullet',
maxSize: 30 // pool size; reuse instead of allocating
});
fire(x, y) {
const bullet = this.bullets.get(x, y); // reuses an inactive bullet if available
if (!bullet) return; // pool is full: every bullet is active
bullet.enableBody(true, x, y, true, true);
bullet.setVelocityY(-500);
}
update() {
// Return off-screen bullets to the pool, or firing stops after 30 shots.
this.bullets.getChildren().forEach((bullet) => {
if (bullet.active && bullet.y < -32) bullet.disableBody(true, true);
});
}
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.
Standing on an ordinary dynamic body does not count as blocked; make platforms
static, immovable, or non-pushable (platform.setPushable(false)).
- 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.
- Fast bullets pass through thin walls → Arcade has no swept collision; a body
that moves farther than a wall's thickness in one physics step skips it. Thicken
the wall's body, cap speed with
setMaxVelocity, or raise the step rate
(arcade: { fps: 120 }, default 60) at extra CPU cost.
- Bodies pass through each other after adding collision categories → a pair only
collides when each side's mask includes the other's category, and untouched bodies
keep mask
1. Widen the other side's mask too, and set groups and their members
separately (see the reference).
- Drag does nothing while a key is held → Arcade applies drag only on an axis
with zero acceleration; set the acceleration to 0 when input stops.
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.
1---2name: phaser-arcade-physics3description: >4 Use Phaser 4 Arcade Physics: enable the world, give sprites bodies, set5 velocity/acceleration/gravity, and resolve collisions with colliders, overlaps,6 groups, and world bounds. Use when a Phaser game needs movement or collisions —7 when the user mentions Arcade Physics, this.physics, setVelocity, collider,8 overlap, gravity, onFloor, or a platformer/top-down controller. For game config,9 scenes, and the loader use phaser-core.10metadata:11 source: https://skillmd.com/skills/junmystery/phaser-arcade-physics12---1314# Phaser 4 Arcade Physics1516Add movement and collision to a Phaser game with the lightweight **Arcade17Physics** engine (AABB rectangles and circles only). Targets **Phaser 4.2** for18new projects; inspect the installed major before editing an existing project.1920## When to use2122- Use for top-down or platformer movement, velocity/acceleration/gravity, bouncing,23 world bounds, and collision/overlap resolution between sprites, groups, and tiles.24- Use when the scene enables `physics: { default: 'arcade' }` and code calls25 `this.physics.add.*`, `body.setVelocity`, or `this.physics.add.collider`.2627**When *not* to use:** the `Game` config, scene structure, asset loading, or28cameras → use `phaser-core`. Hinges, springs, complex polygons, or stacking29rigid bodies → use Matter physics (a different engine; Arcade and Matter bodies30do not interact). For engine-agnostic feel tuning see `physics-tuning`.3132## Core workflow33341. **Enable the world.** Set `physics: { default: 'arcade', arcade: { gravity:35 {...}, debug: true } }` in the game or scene config. Turn `debug` on while36 building to see body outlines and velocity vectors.372. **Give a sprite a body.** Create it with `this.physics.add.sprite(...)` (dynamic)38 or `this.physics.add.staticImage(...)` (static), or attach to an existing object39 with `this.physics.add.existing(obj)`.403. **Drive it through the body, not by setting `x`/`y`.** Use `setVelocity`,41 `setAcceleration`, gravity, `setBounce`, and `setCollideWorldBounds`. The engine42 integrates position from velocity each step (already frame-rate independent).434. **Resolve interactions.** `this.physics.add.collider(a, b)` separates bodies;44 `this.physics.add.overlap(a, b, cb)` detects without separating (pickups,45 triggers). Pass a callback to react.465. **Group many objects.** Use `this.physics.add.group()` (dynamic) or47 `staticGroup()` (platforms) so one collider call handles all members.486. **Check ground contact** with `body.onFloor()` / `body.blocked.down` before49 jumping. Run with `debug: true` and confirm bodies, contacts, and bounds.5051## Patterns5253### 1. Enable Arcade Physics (game config)5455```js56const config = {57 type: Phaser.AUTO,58 width: 800, height: 600,59 physics: {60 default: 'arcade',61 arcade: {62 gravity: { x: 0, y: 600 }, // top-down? use { x: 0, y: 0 }63 debug: false // true to draw bodies + velocity while building64 }65 },66 scene: [PlayScene]67};68new Phaser.Game(config);69```7071### 2. Top-down movement (velocity from input)7273```js74create() {75 this.player = this.physics.add.sprite(400, 300, 'player');76 this.player.setCollideWorldBounds(true);77 this.cursors = this.input.keyboard.createCursorKeys();78}7980update() {81 const speed = 220;82 const body = this.player.body;83 body.setVelocity(0); // reset each frame84 if (this.cursors.left.isDown) body.setVelocityX(-speed);85 if (this.cursors.right.isDown) body.setVelocityX(speed);86 if (this.cursors.up.isDown) body.setVelocityY(-speed);87 if (this.cursors.down.isDown) body.setVelocityY(speed);88 body.velocity.normalize().scale(speed); // keep diagonals same speed89}90```9192### 3. Platformer jump (gravity + ground check)9394```js95create() {96 this.player = this.physics.add.sprite(100, 450, 'player');97 this.player.setCollideWorldBounds(true);9899 // Static platforms: one body each, never moved by collisions.100 this.platforms = this.physics.add.staticGroup();101 this.platforms.create(400, 568, 'ground');102 this.physics.add.collider(this.player, this.platforms);103104 this.cursors = this.input.keyboard.createCursorKeys();105}106107update() {108 const onGround = this.player.body.blocked.down; // or this.player.body.onFloor()109 if (this.cursors.left.isDown) this.player.setVelocityX(-160);110 else if (this.cursors.right.isDown) this.player.setVelocityX(160);111 else this.player.setVelocityX(0);112113 if (this.cursors.up.isDown && onGround) this.player.setVelocityY(-450);114}115```116117### 4. Colliders vs overlaps (separate vs detect)118119```js120// Push apart and react: player vs enemies.121this.physics.add.collider(this.player, this.enemies, (player, enemy) => {122 this.handleHit(player, enemy);123});124125// Detect without pushing: collect coins. The 4th arg is an optional126// process callback returning a boolean to filter pairs before the main callback.127this.physics.add.overlap(this.player, this.coins, (player, coin) => {128 coin.disableBody(true, true); // deactivate + hide129 this.registry.inc('score', 10);130});131```132133### 5. A group of moving objects134135```js136this.bullets = this.physics.add.group({137 defaultKey: 'bullet',138 maxSize: 30 // pool size; reuse instead of allocating139});140141fire(x, y) {142 const bullet = this.bullets.get(x, y); // reuses an inactive bullet if available143 if (!bullet) return; // pool is full: every bullet is active144 bullet.enableBody(true, x, y, true, true);145 bullet.setVelocityY(-500);146}147148update() {149 // Return off-screen bullets to the pool, or firing stops after 30 shots.150 this.bullets.getChildren().forEach((bullet) => {151 if (bullet.active && bullet.y < -32) bullet.disableBody(true, true);152 });153}154```155156## Pitfalls157158- **Sprite ignores physics** → it was added with `this.add.sprite` instead of159 `this.physics.add.sprite` (or `this.physics.add.existing(obj)`), so it has no body.160- **Setting `sprite.x` directly fights the engine** → move dynamic bodies with161 `setVelocity`/`setAcceleration`. Direct position writes can tunnel through colliders.162- **Diagonal movement is faster** → independent X and Y velocities add up; normalise163 the velocity vector and rescale to the intended speed.164- **Platforms get pushed by the player** → use a `staticGroup`, or set165 `body.setImmovable(true)` on a dynamic platform.166- **`onFloor()` is always false** → the body needs something to collide with; add the167 `collider` against the ground/platforms before checking, and ensure gravity is on.168 Standing on an ordinary dynamic body does not count as blocked; make platforms169 static, immovable, or non-pushable (`platform.setPushable(false)`).170- **Moved a static body but collisions are stale** → static bodies don't auto-sync;171 call `body.updateFromGameObject()` (or `refreshBody()` on the game object).172- **Collider added every frame** → register `collider`/`overlap` once in `create`,173 not in `update`.174- **Fast bullets pass through thin walls** → Arcade has no swept collision; a body175 that moves farther than a wall's thickness in one physics step skips it. Thicken176 the wall's body, cap speed with `setMaxVelocity`, or raise the step rate177 (`arcade: { fps: 120 }`, default 60) at extra CPU cost.178- **Bodies pass through each other after adding collision categories** → a pair only179 collides when each side's mask includes the other's category, and untouched bodies180 keep mask `1`. Widen the other side's mask too, and set groups and their members181 separately (see the reference).182- **Drag does nothing while a key is held** → Arcade applies drag only on an axis183 with zero acceleration; set the acceleration to 0 when input stops.184185## References186187- For body anatomy and tuning (drag, bounce, max velocity, custom `setSize`/188 `setCircle`/`setOffset` hitboxes, collision categories/masks, and `worldbounds`189 events), read `references/bodies-and-collision.md`.190191## Related skills192193- `phaser-core` — game config, scenes, loader, cameras (the prerequisite setup).194- `physics-tuning` — engine-agnostic feel (fixed timestep, tunneling, jitter).195- `platformer` / `tower-defense` — genres that compose this skill.196- `level-design` — laying out tile/platform geometry these bodies collide with.