Where do the Tile ID/Global IDs come from?

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?

This question is duplicated here:

The answers to the two questions are:

They would be 0 to 24 (local tile IDs), left to right, top to bottom.

Each tileset has a firstgid (first global ID) property which tells you the global ID of its first tile (the one with local tile ID 0). This allows you to map the global IDs back to the right tileset, and then calculate the local tile ID by subtracting the firstgid from the global tile ID.

I realize the documentation could use some improvements in this area. I’ll get to that eventually.

Just wondering why not have a globally unique ID (a 6 character hash could do) across all TMX/TSX files?

What would you do with it? The “first global id” mechanism allows tiles from multiple tilesets to be referred to, using a single number range. So if you have three tilesets with 10 tiles, those tiles are identified by numbers (global IDs) 1 to 30, with the tilesets having “first global IDs” of 1, 11 and 21.

A unique global ID for a tileset consisting of a hash would not solve this issue. The only alternatives to the global ID range I know about are:

  • Storing two numbers for each tile instance, so it can refer to a tileset ID and a tile ID separately. This would simplify lookup, but it would either cost more memory or have stricter limits depending on how the 32 bits are divided among “tileset ID” and “tile ID” and the flipping flags (currently 4 bits).

  • Interleaving tile references with tileset references, so that each change of tileset requires a tileset reference, after which all tile references are taken to be from that tileset.

In any case I think neither of these systems are so much of an improvement over the current system that it is worth changing it.

Introducing globally unique IDs for resources in itself is an interesting feature, since it could simplify lookups compared to using file references. This is probably something to do as part of introducing support for projects. Though for human readability (and backwards compatibility) I think we need to keep the file references as well.