Tilesets

A tileset is an image plus the metadata that turns it into a grid of paintable tiles. Drop a PNG into the editor, set tile width and height, and you have a tileset.

First GID

Every tileset on a map gets a firstGid: the global tile ID that the tileset's first cell maps to. The first tileset usually starts at 1 (0 is reserved for empty). The next tileset starts at previousFirstGid + previousTileCount. When a tile layer stores the value 137, the renderer finds the tileset whose firstGid range contains 137, subtracts that firstGid, and looks up the local tile.

Embedded vs external

An embedded tileset lives inside the map file. An external tileset lives in its own .tsx or .tsj file, and the map references it by path. External tilesets are useful when you share the same atlas across many maps: edit it once, every map sees the change.

Per-tile data

You can attach extra data to individual tiles in the tileset:

• Custom properties for names, flags, anything your engine needs to read.
• Animation frames: a list of (tileId, duration) pairs that the renderer cycles through.
• Collision shapes: rectangles, ellipses, or polygons attached to the tile.
• Wang IDs for the terrain solver.
• Type / class: a free string used by some exporters and by AutoMap rules.

Margin and spacing

Margin is the gap (in pixels) between the edge of the image and the first tile. Spacing is the gap between adjacent tiles. Set both to 0 for tightly packed atlases. Use them when your atlas was authored with gutters to prevent bleeding.