Where do the Tile IDs come from in Tiled?

I've used Tiled to build JSON tilemap files for Phaser games in the past. I would now like to build my JSON map files on the fly with PHP.

Here's an example object:

{
    "height": 50,
    "layers": [{
        "data": [5884, 5885, 5886, 5887, 5888, 5885],
        "height": 50,
        "name": "background",
        "opacity": 1,
        "type": "tilelayer",
        "visible": true,
        "width": 50,
        "x": 0,
        "y": 0
    }],
    "orientation": "orthogonal",
    "properties": {},
    "tileheight": 16,
    "tilesets": [{
        "firstgid": 1,
        "image": "tiles.png",
        "imageheight": 1684,
        "imagewidth": 2738,
        "margin": 1,
        "name": "tiles",
        "properties": {},
        "spacing": 1,
        "tileheight": 16,
        "tilewidth": 16
    }],
    "tilewidth": 16,
    "version": 1,
    "width": 50
}

The properties are pretty self-explanatory and are documented on Github, which references the TMX Map format docs on the Tiled website, but neither explain how the tile id's for the layer's data property are generated.

Two questions:

1) How are the Tile Ids generated for the "data" array? For example, If I have a 5x5 tile sheet, would they just be 1 thru 25 left to right, top to bottom?

2) The data array uses global ids, which are unique across all the tile sheets. How are these generated? For example, if I have 3 5x5 tile sheets, would they be 1-75? But in what order?

Solution

Based upon testing, I'm going to answer your questions in reverse order, based upon Tiled 0.16.1's behavior.

You may also want to add individual images initially, and use the XML output (*.tmx) as it's a little easier, in my opinion, than the JSON output to see the data format. I'm providing one below:

<?xml version="1.0" encoding="UTF-8"?>
<map version="1.0" orientation="orthogonal" renderorder="right-down" width="10" height="10" tilewidth="64" tileheight="64" nextobjectid="1">
 <tileset firstgid="1" name="second" tilewidth="64" tileheight="64" tilecount="3" columns="0">
  <tile id="0">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/forest.png"/>
  </tile>
  <tile id="1">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/forest-dirt-corner-ne.png"/>
  </tile>
  <tile id="2">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/forest-dirt-corner-nw.png"/>
  </tile>
 </tileset>
 <tileset firstgid="4" name="third" tilewidth="64" tileheight="64" tilecount="1" columns="0">
  <tile id="0">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/grass.png"/>
  </tile>
 </tileset>
 <tileset firstgid="5" name="first" tilewidth="64" tileheight="64" tilecount="2" columns="0">
  <tile id="0">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/dirt.png"/>
  </tile>
  <tile id="1">
   <image width="64" height="64" source="../../../OneDrive/Projects/Tiles/dirt-forest-corner-ne.png"/>
  </tile>
 </tileset>
 <layer name="Tile Layer 1" width="10" height="10">
  <data encoding="csv">
1,2,3,0,0,0,0,0,0,0,
4,0,0,0,0,0,0,0,0,0,
5,6,0,0,0,0,0,0,0,0,
1,2,3,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0,
0,0,0,0,0,0,0,0,0,0
</data>
 </layer>
</map>

2. How are ids generated?

First it's important to understand that there are one or more tileset elements that have a firstgid attribute. Per the documentation:

firstgid: The first global tile ID of this tileset (this global ID maps to the first tile in this tileset).

Additionally:

The first tileset always has a firstgid value of 1.

A little further we get an explanation of tile and id:

id: The local tile ID within its tileset.

So in the example above you'll see that tileset firstgid="1" has within it three tile elements, with ids ranging from 0 to 2. Doing the math you see that these are tiles with the unique ids of 1, 2, and 3.

The next tileset has a firstgid of 4, since the tiles with ids 1, 2, and 3 have already come before. The first tile within has an id of 0, and since 4 + 0 = 4, we know what our 4th tile is.

If tilesets are moved around in the Tiled interface than the ids are also updated accordingly. So the first tile in the first tileset will always have the id of 1.

For example, if I have 3 5x5 tile sheets, would they be 1-75? But in what order?

So yes, and it would be based upon the order of the tile sets that the tile sheets were added to.

1. How are ids generated for the data array?

The ids are based upon the generated ids, which ties into your second question, answered above. '0' signifies that no tile is in place, while '1' would be the first tile (top left) in the first tileset.

So:

For example, If I have a 5x5 tile sheet, would they just be 1 thru 25 left to right, top to bottom?

Yes.