phaser-arcade-physics
Use Phaser 4 Arcade Physics: enable the world, give sprites bodies, set velocity/acceleration/gravity, and resolve collisions with colliders, overlaps, groups, and world bounds. Use when a Phaser game needs movement or collisions — when the user mentions Arcade Physics, this.phys
Install
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills/tree/main/skills/web-engines/phaser-arcade-physics
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gamedev-skills-awesome-gamedev-agent-skills@llmmart
git clone https://github.com/gamedev-skills/awesome-gamedev-agent-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gamedev-skills/awesome-gamedev-agent-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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 callsthis.physics.add.*,body.setVelocity, orthis.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. Turndebugon while building to see body outlines and velocity vectors. - Give a sprite a body. Create it with
this.physics.add.sprite(...)(dynamic) orthis.physics.add.staticImage(...)(static), or attach to an existing object withthis.physics.add.existing(obj). - Drive it through the body, not by setting
x/y. UsesetVelocity,setAcceleration, gravity,setBounce, andsetCollideWorldBounds. 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) orstaticGroup()(platforms) so one collider call handles all members. - Check ground contact with
body.onFloor()/body.blocked.downbefore jumping. Run withdebug: trueand 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 onGround = this.player.body.blocked.down; // 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.spriteinstead ofthis.physics.add.sprite(orthis.physics.add.existing(obj)), so it has no body. - Setting
sprite.xdirectly fights the engine → move dynamic bodies withsetVelocity/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 setbody.setImmovable(true)on a dynamic platform. onFloor()is always false → the body needs something to collide with; add thecollideragainst 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()(orrefreshBody()on the game object). - Collider added every frame → register
collider/overlaponce increate, not inupdate. - 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/setOffsethitboxes, collision categories/masks, andworldboundsevents), readreferences/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.
Files (awesome-gamedev-agent-skills)
-
references
-
bodies-and-collision.md 6.2 KB
Loading…
-
-
SKILL.md 8 KB
--- name: phaser-arcade-physics description: > Use Phaser 4 Arcade Physics: enable the world, give sprites bodies, set velocity/acceleration/gravity, and resolve collisions with colliders, overlaps, groups, and world bounds. Use when a Phaser game needs movement or collisions — when the user mentions Arcade Physics, this.physics, setVelocity, collider, overlap, gravity, onFloor, or a platformer/top-down controller. For game config, scenes, and the loader use phaser-core. --- # 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) ```js 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) ```js 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) ```js 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 onGround = this.player.body.blocked.down; // 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) ```js // 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 ```js 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.