Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 36 ยท Input and Physics

Phaser Collisions, Overlaps and Physics Groups

Detect and respond to hits in Phaser Arcade Physics: colliders versus overlaps, callbacks, physics groups, static groups, process callbacks, one-way platforms and pickups.

Games are about things touching things: a player hits a wall, a bullet hits an enemy, a hero grabs a coin. In Arcade Physics there are exactly two ways to test contact, and knowing which to use removes most of the confusion: the collider and the overlap.

Collider versus overlap

  • A collider makes bodies solid. They cannot pass through each other; the engine separates them and, if the bodies can move, pushes or bounces them. Use it for walls, floors, platforms, crates and solid enemies.
  • An overlap only detects that two bodies intersect. Nothing is pushed. Use it for pickups, damage zones, triggers, checkpoints and bullets that disappear on contact.
JavaScript
this.physics.add.collider(player, walls);                         // solid
this.physics.add.overlap(player, coins, collectCoin, null, this); // detect only

The signature is the same for both: (objectA, objectB, callback, processCallback, callbackContext). Each argument can be a single object or a group, so one line connects a player to a hundred walls.

Callbacks

When contact happens, Phaser calls your callback with the two objects that touched. Their order matches the order you passed them to add.collider or add.overlap, with one rule: if A is a single object and B a group, you always get (A, memberOfB).

JavaScript
collectCoin(player, coin) {
  coin.disableBody(true, true);        // switch the body off and hide the coin
  this.score += 10;
  this.scoreText.setText('Score: ' + this.score);
}

disableBody(disableGameObject, hideGameObject) is the clean way to remove a pickup, and the object can be reused later with enableBody(true, x, y, true, true). Calling coin.destroy() also works, but does not allow pooling.

The optional process callback runs before separation and returns true or false to allow or cancel the collision. It decides whether the contact counts, which is how you build one-way platforms or invincibility frames:

JavaScript
this.physics.add.collider(player, platforms, null, (player, platform) => {
  return player.body.velocity.y > 0;   // only collide when falling: jump up through it
}, this);

Groups of bodies

You already know groups from Containers, Groups and Particles. For physics there are two kinds:

JavaScript
const walls = this.physics.add.staticGroup();       // never move; cheap
walls.create(240, 320, 'wall').setScale(10, 1).refreshBody();

const enemies = this.physics.add.group({             // dynamic bodies
  key: 'enemy', repeat: 4, setXY: { x: 60, y: 40, stepX: 70 },
  bounceX: 1, collideWorldBounds: true, velocityX: 80
});

The important detail for static groups: after changing a member's scale or position, call refreshBody() so the body updates to match. (Dynamic bodies follow automatically.) Collisions between two static groups are never tested, because neither can move.

A group can be given to collider and overlap as either argument, and a group can also collide with itself: this.physics.add.collider(enemies, enemies) makes the members bump each other.

What a collider does to speed and position

When two dynamic bodies collide, the engine separates them and exchanges momentum based on mass, bounce and friction. Two useful flags:

  • body.setImmovable(true): the body cannot be pushed; it behaves like a wall but can still move on its own (a moving platform).
  • body.pushable = false (Arcade): the other body bounces but this one keeps its velocity.

For a moving platform that carries the player, use an immovable body plus body.friction, or move the player with the platform's velocity.

You can also disable parts of collision per body: Setting checkCollision.down, left and right to false on a platform leaves only its top face solid, so a player can jump up through it and land on top. That is the simplest one-way platform.

A top-down mini-game

The scene below combines everything: a static wall group with colliders, coins gathered with overlaps, a patrolling enemy that bounces off walls, and an "ouch" process callback with invincibility frames. Use the arrow keys or WASD (click the game first).

Coins, walls and a patrolling enemy

Study how each of the three rules is expressed:

  1. collider(player, walls): solid. The player cannot cross the border or the inner walls; the enemy bounces off them because its bounce is 1.
  2. overlap(player, coins, collect): the player walks through coins, and the callback removes each one.
  3. overlap(player, enemy, hurt, process): the process callback returns false while invincible is true, so the player flashes for a moment instead of losing all lives in one touch.

Notice also setCircle(12) on the player: a round body slides around corners smoothly instead of catching on them.

Bullets and enemies

The classic shooter pattern uses two physics groups and one overlap. This version deletes both objects when they touch. Bullets and enemies are pooled: bullets by get and killAndHide, enemies by the same trick, which avoids creating objects constantly.

JavaScript
this.physics.add.overlap(this.bullets, this.enemies, (bullet, enemy) => {
  this.bullets.killAndHide(bullet);
  bullet.body.enable = false;
  enemy.hp -= 1;
  if (enemy.hp <= 0) this.enemies.killAndHide(enemy), (enemy.body.enable = false);
});

The callback receives the objects in the order of the groups you passed. With group.killAndHide, remember to disable the body too, or the invisible object keeps colliding.

Collision events from the world and from bodies

  • this.physics.world.on('collide', (a, b, up, down, left, right) => ...) fires for every collision of bodies that have body.onCollide = true.
  • body.onOverlap = true plus the world 'overlap' event does the same for overlaps.
  • body.onWorldBounds = true plus 'worldbounds' reports edge hits.

These world events avoid wiring a callback per collider and are handy for sound effects.

Debugging contacts

Turn on debug: true. A body outline turns blue while it is touching and shows its velocity as a line. Static bodies are drawn in a different color. If a collider does nothing, work through this checklist:

  1. Do both objects have bodies (.body is not undefined)?
  2. Did you create the collider after creating both objects?
  3. Is one of them a static body that moved without refreshBody()?
  4. Are two static bodies colliding? That is never tested.
  5. Does a process callback return false?
  6. Is body.enable or checkCollision switched off?

Common mistakes

  • Using a collider for pickups. The player bounces off coins. Use an overlap.
  • Static body not updated after setScale or setPosition. Call refreshBody().
  • Killing an object but leaving its body enabled. Disable the body or use disableBody(true, true).
  • Creating a collider every frame in update. Colliders are created once in create.
  • Callback arguments in the wrong order. They follow the order you passed to collider/overlap.
  • Tunneling. A fast, small bullet can skip a thin enemy between steps; make hit boxes a little bigger.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which method should you use so a player can walk through a coin and pick it up?

    An overlap detects contact without making the bodies solid, which is what pickups need.
  2. 2. What does a process callback do?

    Returning false from the process callback cancels that contact, which is how one-way platforms and invincibility work.
  3. 3. You scaled a static wall with setScale. What must you call so its body matches?

    Static bodies do not follow their game object automatically; refreshBody updates the body to the new size and position.
  4. 4. Two static bodies are touching. What does Arcade Physics do?

    Neither body can move, so the engine skips the test.
  5. 5. Which line makes a platform solid only from above?

    Turning off the down, left and right collision faces of the platform leaves only its top face solid, giving a one-way platform.

Summary

  • Use collider for solid contact (walls, floors, crates) and overlap for detection (coins, triggers, bullets).
  • Both accept single objects or groups and an optional callback and process callback; the callback receives the two objects in order.
  • Use static groups (with refreshBody()) for scenery and dynamic groups for enemies and bullets; disable bodies of removed pooled objects.
  • Process callbacks and checkCollision flags build one-way platforms and invincibility frames.
  • debug: true and the checklist above solve nearly every "why is nothing colliding" problem.

Next: Platformer Movement and Jumping