Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Tilemaps and Cameras

Maps from the Tiled Editor

Design levels in Tiled and load them into Phaser. Learn the Tiled JSON format, tile properties, multiple layers and object layers for spawn points.

Typing a map as an array of numbers works for a tiny demo, but nobody designs a real level that way. The standard tool for 2D levels is Tiled, a free map editor: you paint tiles with a brush, add layers, mark special places such as the player spawn or a door, and export a JSON file. Phaser reads that file directly, which means a level designer can change a level without touching the game code.

This lesson explains the Tiled workflow, what the exported file looks like, and how Phaser turns it into layers, tile properties and objects. The sandbox on this site cannot load external files, so the runnable examples place the map JSON inside the page and register it with Phaser's cache. In a real project you would load the very same JSON from a file, and the rest of the code stays unchanged.

The workflow in Tiled

Tiled itself is a desktop program, so this part is a checklist rather than code you can run here:

  1. New map: choose orthogonal orientation, the tile size that matches your art (for example 32 by 32), and a map size in tiles.
  2. New tileset: pick your tileset image, set the tile size, and tick Embed in map. An embedded tileset keeps everything in one file, which avoids "missing tileset" problems in the browser.
  3. Tile layers: paint ground, walls and decoration on separate layers. Give every layer a clear name such as ground or walls, because your code will look them up by name.
  4. Object layers: add an object layer called objects. Place rectangles or points for the player start, enemies, coins and doors, and give each a name or type.
  5. Properties: select tiles in the tileset editor and add custom properties such as a boolean solid or a number damage. Select objects and add properties like target = "level2".
  6. Export as JSON (File, Export As). Keep the tile layer format on the default (a plain array of numbers) or CSV. Phaser cannot read compressed layer data.
flowchart LR
  A["Tiled editor<br/>paint layers + objects"] --> B["level.json<br/>(+ tileset.png)"]
  B --> C["Phaser preload<br/>load.tilemapTiledJSON"]
  C --> D["make.tilemap + createLayer"]

A designer works in Tiled. The game only needs the exported JSON and the tileset image.

What the JSON contains

An exported map has a predictable shape. Here is a shortened version, with the interesting fields only:

JSON
{
  "width": 15, "height": 9,
  "tilewidth": 32, "tileheight": 32,
  "orientation": "orthogonal",
  "layers": [
    { "type": "tilelayer", "name": "ground", "width": 15, "height": 9, "data": [1, 1, 2, "..."] },
    { "type": "objectgroup", "name": "objects",
      "objects": [ { "id": 1, "name": "spawn", "x": 64, "y": 96, "width": 0, "height": 0 } ] }
  ],
  "tilesets": [
    { "firstgid": 1, "name": "tiles", "tilewidth": 32, "tileheight": 32,
      "columns": 4, "tilecount": 4, "image": "tiles.png", "imagewidth": 128, "imageheight": 32 }
  ]
}

Two details matter. First, tile numbers in the file are GIDs (global tile ids), where 0 means empty and the first tile of the first tileset is 1. Phaser subtracts firstgid for you, so in your code the first picture of the tileset has tile.index === 0. Second, an object's x and y are in pixels, not tiles.

Loading the map

In a normal project the loading code lives in preload() and refers to files:

JavaScript
preload() {
  this.load.image('tiles', 'assets/tiles.png');
  this.load.tilemapTiledJSON('level1', 'assets/level1.json');
}
create() {
  const map = this.make.tilemap({ key: 'level1' });
  const tileset = map.addTilesetImage('tiles', 'tiles');
  const ground = map.createLayer('ground', tileset, 0, 0);
}

addTilesetImage takes two names: the tileset name as written inside Tiled and the texture key you gave load.image. They are often the same, and when they differ, a wrong first argument is the number one cause of the error "Cannot read properties of undefined" when creating layers. Check the name field in the tilesets array of your JSON.

In the examples below there is no file to load, so we put the JSON object into the tilemap cache by hand, and call make.tilemap({ key }) just as before.

Layers, properties and objects in action

Load a Tiled JSON map

What happened:

  • map.layers lists the data of every tile layer, so you can discover names at run time.
  • The water tile (index 0) carries the solid property from the tileset's tiles entry. Phaser converts Tiled's list of { name, value } records into a plain object, so you read tile.properties.solid.
  • findObject('objects', callback) returns the first object that matches, and filterObjects returns all of them. The layer name is the one you typed in Tiled.
  • Press D (after clicking the canvas) to hide the decoration layer. Layers are game objects with setVisible, setAlpha, setDepth and setPosition.

Using objects to place things

Object layers hold everything that is not a tile: spawn points, enemies, triggers and exits. Phaser gives you two ways to use them.

Read the data yourself (as above), then create whatever you like. This works for any game object and any component.

Let Phaser create sprites with createFromObjects. It turns every matching object into a sprite or image, copying position, size, rotation and custom properties:

JavaScript
const coins = map.createFromObjects('objects', {
  name: 'coin',
  key: 'coin-texture'
});

Tiled lets you give an object a tile image (a "tile object"). When your objects have a gid, createFromObjects can use the tile's picture as the texture. For plain rectangles and points you must pass key as shown. One more trap: a tile object's y is its bottom edge in Tiled, so Phaser sets its origin to the bottom left for you; a rectangle's y is its top edge.

Handling tile properties

Custom properties are how a designer talks to your code without changing it. A few useful patterns:

  • A solid boolean on tiles, which you turn into collisions with setCollisionByProperty({ solid: true }) (the next lesson shows this).
  • A damage number on spikes, read in an overlap callback.
  • A terrain string such as "ice" or "mud", used to change the player's speed.
Read tile properties on click

The speed multiplier idea scales to real games: on every frame you look up getTileAtWorldXY(player.x, player.y) and multiply the walking speed by tile.properties.speed. No if (terrain === 'water') chains are needed in the code.

Common problems

  • "Invalid Tilemap Layer ID". The layer name in createLayer('ground', ...) must match the name in Tiled exactly, including capitals.
  • Tileset name mismatch. The first argument of addTilesetImage is the tileset name inside Tiled, not the file name.
  • Blank screen. The texture key given to addTilesetImage (second argument) must match the load.image key. A 404 on the PNG also gives an empty map.
  • Blurry or striped tiles. Tilesets with margins or spacing between tiles need the same values in Tiled, and a sub-pixel camera position can show seams. Using pixelArt: true or roundPixels: true helps, and extruding tiles (padding each tile's edge pixels) fixes seams for good.
  • Infinite maps. Phaser cannot load Tiled's "infinite" map option. Turn it off in the map properties.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In an exported Tiled layer, which value marks an empty cell?

    Tiled stores GIDs, where 0 means empty and the first tile of a tileset with firstgid 1 is 1. Phaser converts this so that the first tile has index 0 in your code.
  2. 2. What are the two arguments of map.addTilesetImage('a', 'b') in a Tiled-based project?

    The first is the tileset name stored in the JSON, the second is the texture key from load.image. A mismatch in either gives an empty or failing layer.
  3. 3. How do you read a custom boolean property named solid on a tile?

    Phaser converts Tiled's property records into a plain object on tile.properties.
  4. 4. Why does a designer put spawn points and coins on an object layer instead of a tile layer?

    Objects describe things and their data. Your code reads them and creates sprites, enemies or triggers.

Summary

  • Tiled lets designers paint layers and place objects, then export JSON that Phaser loads with load.tilemapTiledJSON and make.tilemap({ key }).
  • Tile layers hold GIDs (0 is empty); Phaser converts them so the first tile has index 0.
  • addTilesetImage(tilesetNameInTiled, textureKey) links the picture; names must match exactly.
  • Custom tile properties arrive as tile.properties, and object layers are read with findObject, filterObjects or createFromObjects.
  • Embed tilesets, avoid infinite maps and compressed layer data, and name layers clearly.

Next: Tile Collision and Interactions