Appendix B: About Tile GIDs Document

Previous: Appendix A: Types & Functions - Next:

Throughout this document, you’ll find mentions of GID. GID is an abbreviation for “Global (unique) IDentifier”. It’s a way to uniquely identify a tile in the map across all tilesets. In other words: it’s a tile’s global index.

In TilemapKit, GIDs are represented by the type TKTileGID and simply referred to as tile in variables and functions.

Local GIDs

Each tile in a tileset is assigned a local GID, which starts at 0 - this is the topmost, leftmost tile in the tileset. The tile to the right of it has the local GID 1, and the counting continues from left to right, top to bottom.

In a 64x64 orthogonal tileset image with a tile size of 16x16 and both spacing and margin set to 0 you will have 4 rows and 4 columns of tiles, a total of 16 tiles. The tiles' local GIDs would range from 0 to 15, with local GID 15 referring to the bottom-most, right-most tile in the tileset.

Global GIDs

Now comes the fact that each map may have multiple tilesets. Assuming you’d have a total of 3 tilesets, all containing 4x4 (=16) tiles, how would you identify them uniquely?

By having a continuous count across all tilesets - that is the (global) GID. Global GIDs start counting at 1 - because GID 0 refers to an empty tile (TKTileGIDEmpty).

Therefore, for your three tilesets, you have the following relation between local and global GIDs:

  • Tileset #1:
    • Local GIDs: 0-15
    • Global GIDs: 1-16
  • Tileset #2:
    • Local GIDs: 0-15
    • Global GIDs: 17-32
  • Tileset #3:
    • Local GIDs: 0-15
    • Global GIDs: 33-48

Each tileset has [TKTileset firstTile] (1, 17, 33) and [TKTileset lastTile] (16, 32, 48) properties which record the first and last global GID of the tiles in the corresponding tileset.

Caution You should not rely on a specific tileset having a specific range of global GIDs, or on a specific tile to have a specific GID all the time. Tile GIDs can change at any time when a tileset is added or removed, or when a tileset's image changes its size or margin/spacing properties.

Global GIDs may contain Bits!

Global GIDs may have bits (TKTileFlags) encoded in them, which record whether a tile is flipped horizontally, vertically or diagonally.

TilemapKit API methods account for bit flags and remove them if necessary before further processing. But the fact that tile GIDs may contain bits may still take you by surprise. For instance, this check is prone to fail:

if (aTileGID == otherTileGID) { .. }

Assuming both tile GIDs represent the same tile in the tileset, but either one of them is flipped on the tile layer, then this comparison will evaluate to false. It’s easy to “mask out” (remove) the flags though:

if ((aTileGID & TKTileFlagMask) == (otherTileGID & TKTileFlagMask)) { .. }

Now the comparison ignores the tiles' flags and will work as intended, flipped tiles or not.

You can also ensure you’re using a tile without flags by using [TKTileLayer tileAt:] and related methods, which return a tile GID without any flags. If you do want the flags, use [TKTileLayer tileWithFlagsAt:] and related methods. And to get just the flags, use [TKTileLayer tileFlagsAt:] or by removing the non-flag bits: TKTileGID flags = (tileWithFlags & TKTileFlagAll).

On the other hand, if you don’t flip any tiles in Tiled you’ll be on the safe side as you can ignore the flags.

Converting between Local and Global GIDs

If you don’t want to do the math yourself, use the [TKTileset convertToLocalTile:] and [TKTileset convertToTile:] methods to convert between local and global GIDs. This will also correctly handle global GIDs with flags (see next section).

It’s important to note that many TilemapKit API functions require local GIDs rather than global GIDs. So watch the wording of methods and properties, ie a method with a forLocalTile: parameter expects a local tile GID, not a global one.

And vice versa: a GID parameter without the word “local” expects a global GID.

Previous: Appendix A: Types & Functions - Next: