Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Tilemaps and Cameras

Tile Collision and Interactions

Make tilemap layers solid in Phaser Arcade Physics. Use setCollision, collision by property, tile callbacks for hazards and pickups, and debug drawing.

A tilemap that you can only look at is a picture. To turn it into a level, characters must stop at walls, stand on floors and react to hazards. Phaser's Arcade Physics knows how to treat a whole tilemap layer as a collision surface: you mark which tiles are solid, then add one collider between the player and the layer. There is no need to create a physics body for every wall.

This lesson covers the three steps (choose solid tiles, add a collider, debug it), the several ways to choose tiles, and tile callbacks, which run your code when something touches a particular tile such as spikes or a coin. The runnable examples use rectangles for the player and a tileset drawn in code, so they work on this page without any image files.

Step 1: mark tiles as colliding

Collision is a flag on each tile. By default no tile collides. You switch the flag on through the layer, and the usual ways are:

JavaScript
layer.setCollision(3);                       // one tile index
layer.setCollision([3, 4, 7]);               // a list of indexes
layer.setCollisionBetween(10, 20);           // an inclusive range of indexes
layer.setCollisionByExclusion([-1, 0]);      // every tile except these
layer.setCollisionByProperty({ solid: true });// tiles with a custom property

setCollisionByProperty is the preferred choice for maps made in Tiled: the designer ticks solid on the tiles, and your code never needs to know their index numbers. Remember that these methods work on tile indexes (the picture in the tileset), not on positions.

If you only want one specific cell to collide, call layer.getTileAt(x, y).setCollision(true), or pass false to turn it off. You can even choose which sides collide: tile.setCollision(left, right, up, down). A tile with only the up side set is a one-way platform, because a player can jump through it from below but lands on it from above.

Step 2: add a collider

Arcade Physics needs a body on the thing that moves. For a quick prototype, a rectangle works well: create it, then call this.physics.add.existing(rect) to give it a body. Then connect the body and the layer:

JavaScript
this.physics.add.collider(player, layer);

That single line makes the player stop at every solid tile. The collider keeps working when you change tiles at run time (for example when a door tile is removed), because it reads the current state of the layer each frame.

Example: a top-down maze

Top-down maze with walls

The scripted push at the start shows the collider working: the red square slides left, hits the wall tile and stops with its left edge exactly on the wall (center x of 43 = 32 + half its width). After that, the arrow keys are yours. Click the canvas so the keyboard works.

renderDebug draws colliding tiles in orange, tiles with face edges as lines, and everything else in a tile color. It is the quickest way to see why a character gets stuck, because you see exactly which tiles Phaser considers solid. Draw it once while developing, and remove the call (or the graphics) before release.

Platformer physics on tiles

The same collider works with gravity. Add gravity: { y: 900 } to the arcade config, give the player a body and set collideWorldBounds if you want an invisible frame around the world. Check body.blocked.down or body.onFloor() to know when the player stands on a tile and may jump:

JavaScript
if (cursors.up.isDown && body.onFloor()) {
  body.setVelocityY(-420);
}

Tile bodies have no velocity or mass, so the player never pushes them. Everything is solved as "dynamic body versus static tile".

Tile callbacks: spikes and coins

Sometimes you do not want a tile to stop the player, you want to run code when the player touches it. Phaser has two tools:

  • layer.setTileIndexCallback(indexes, callback, context) runs callback(sprite, tile) whenever a body touches a tile with that index.
  • layer.setTileLocationCallback(tx, ty, w, h, callback, context) does the same for a rectangle of cells.

The callback only fires through a collider or overlap between the body and the layer. For tiles that should not block, use this.physics.add.overlap(player, layer) and keep those tiles out of the collision list. Returning false from a callback attached to a collider lets the object pass through that one tile.

Platformer with spikes and coins

Notes on the example:

  1. Stone (index 0) is solid. Spikes (1) and coins (2) are not in the collision list, so the player moves through them, but the overlap fires their callbacks.
  2. collectCoin removes the tile with removeTileAt, so the coin cannot be collected twice. Always change the map, or you collect the same coin every frame.
  3. body.reset(x, y) moves a body and clears its velocity, which is better than assigning x and y directly.
  4. Empty cells are -1. Tile index 0 is a real tile (stone), which is easy to forget.

When a callback must change the tile you are standing on, mutate the layer after the physics step. Phaser tolerates removeTileAt inside a tile callback, but moving many bodies there can cause glitches. If you see odd behaviour, store a flag and apply the change in update().

Performance and edge cases

Phaser only tests the tiles near a body, so a huge layer costs almost nothing per frame. Problems come from elsewhere:

  • Tunneling. A body that moves more than one tile per frame can skip through a thin wall. Keep maximum speeds below one tile per frame (at 60 fps and 32 px tiles, under about 1900 px/s), or use bigger tile colliders.
  • Seams between tiles. Floating point positions can make a character catch on the joint between two flat tiles. Round the camera (roundPixels: true) and keep body sizes slightly smaller than tile multiples.
  • Collision with several layers. Add a collider for every layer that should block. Decoration layers get no collider.
  • Slopes. Arcade Physics only knows rectangles. For slopes use the Matter physics engine or a plugin.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which line makes every tile that has a custom property solid: true in Tiled collide?

    setCollisionByProperty takes an object of property names and values and flags every matching tile. setCollision expects indexes.
  2. 2. After marking tiles as colliding, what else is needed for a sprite to stop at them?

    Collision flags describe the tiles; this.physics.add.collider(sprite, layer) tells Arcade Physics to test them against the sprite's body.
  3. 3. How do you run code when the player touches spikes without blocking the player?

    Tile callbacks fire through colliders or overlaps. Without collision flags the player passes through, and the overlap triggers the callback.
  4. 4. What does a tile with collision enabled only on its up side behave like?

    A body can pass upward through it but lands on top of it, which is how one-way platforms work.
  5. 5. Why is the layer.renderDebug() method useful?

    Debug drawing outlines colliding tiles and their faces. Use it during development, then remove it.

Summary

  • Tile collision is a flag per tile, set by setCollision, setCollisionBetween, setCollisionByExclusion or setCollisionByProperty.
  • A physics.add.collider(body, layer) call makes the flagged tiles solid; the whole layer needs only one collider.
  • body.blocked and body.onFloor() tell you which side touches a tile, which drives jumping.
  • Tile callbacks (setTileIndexCallback) with an overlap trigger hazards and pickups; remove or change the tile to avoid repeating the event.
  • renderDebug shows collision tiles; watch out for fast bodies, seams and slopes.

Next: Camera Basics