Tiled Tip Sheet

Last updated:

This is a collection of various tips to help you better utilize Tiled. It is not intended for first-time users. Rather, this document collects the advice and answers I often find myself giving on the Tiled Discord and forum, so that it is easier to find and refer to. This is not intended as a replacement for the Tiled documentation, but as a companion to it, and will link to it where appropriate.

In addition, I've noticed that many tutorials focus too much step-by-step processes and that users do not develop an understanding of how Tiled's tools work and are unable to effectively use Tiled in any scenarios that don't closely match what they saw in those tutorials. I hope that my focus on how to approach various tasks in Tiled will help you be a better-rounded Tiled user.

Note

Sometimes it is helpful to use words both in their everyday meanings and in their Tiled-specific meanings. I will capitalize terms when referring to Tiled tools and features, and use all lower-case when using words in their everyday meaning. For example, "Tileset" means a tileset as used in Tiled, such as a TSX file, while "tileset" refers to the broader concept or to tileset images.

Missing Panels 

If you close a panel or can't find some panel you need, the first place to look is the View menu. At the top is the Views and Toolbars submenu, from which you can enable and disable most panels.

The Tile Stamps panel is closed by default. This is a very useful panel which is barely mentioned in the official Tiled documentation. You can read more about it here.

Map Orientation 

In Tiled, only maps have orientations - orthogonal, isometric, hexagonal. Tilesets do not have any meaningful concept of orientation, except as a hint to help Tiled render Terrain labels correctly.

A tile is always a rectangular image, no matter the type and style of Tileset. This means that even if you're using an isometric or hexagonal tileset, you can't use a tileset image where the tiles are arranged on an isometric or hexagonal grid, because Tiled will not be able to cut out the individual tiles from that.

The map's orientation determines where these rectangles are drawn, creating the appearance of other orientations. This is how most game engines render non-orthographic tiles, too.

The fact that tiles are fundamentally rectangles regardless of map orientation has implications for Tile Objects: they're always orthographic rectangles, even on non-orthographic maps! This is particularly disorienting on isometric maps, where normal rectangular objects conform to the isometric grid, but Tile Objects do not. If you need to have Objects with world-space coordinates on isometric maps, it is probably better to avoid using Tile Objects and get by with regular Objects. You can set the tile or other graphical information using Custom Properties instead.

Hexagonal considerations 

For the most part, using hexagonal tiles in Tiled is just like using orthogonal and isometric tiles. However, there are some limitations and bugs that affect hexagonal maps:

Misaligned Tiles 

Many isometric and hexagonal tilesets feature tiles that have some depth to them. If you set your map's tile size to be the same as the tileset's tile size with such tiles, they will not align correctly. This is because the actual functional surface of these tiles is smaller than the space the tiles take up in the image.

Isometric map with grass-topped ground tiles. The tiles are misaligned, and the sides are visible where they should not be
Incorrectly aligned isometric tiles due to an incorrectly set map tile size.
The same map and ground tiles, but with the tops aligning neatly, forming a continuous ground surface
The same tiles with the map tile size set correctly.

To fix this, the map's Tile Height needs to be set to a smaller value in Map > Map Properties. The tile height in the Map should be the height of the flat surface of the tile, not including its depth, since the depth should not contribute to tiling a continuous flat area with the tiles. As you can probably guess, you should be using the most basic flat tile in your tileset to determine the Tile Height, do not use tiles that slope or have details that obscure the tile's top surface.

For isometric maps, you can measure the height of the surface of the tile in an image editor, or reduce the Tile Height of the Map in Tiled until the tiling looks correct. For pixel art tiles that don't have anything sticking out their sides, the correct height is almost always 1/2 the width, so that's a good value to start with.

For hexagonal maps, you will also need to set the Tile Side Length correctly to get proper tiling. The most reliable way is to measure in an image editor. If you want to just adjust the sizes in Tiled instead of measuring, start by reducing the Tile Height until the bottom of the tile grid aligns with the bottom edge of the surface of the tile. After that, adjust the Tile Side Length until the tile grid matches the surface of the tile and the tiles tile correctly.

Hint

You can use the Up and Down arrow keys on your keyboard to quickly change the value of the properties instead of typing values in. Click the value to edit it, and then you can use the arrow keys. You can also use the small arrows that show up on the field using your mouse.

If your tiles' surface doesn't span the entire width of the tile, you'll also need to adjust the map's Tile Width. This can happen with tilesets that include details that go off the tile.

Warning

If your tileset has tiles placed haphazardly, that is, placed such that the top surfaces aren't always in the same place within the tile, you will not be able to get them to align. The only remedy is to adjust the tileset image(s) in an image editor so that the tiles are aligned consistently.

Tile Stamps Panel 

A hidden gem in Tiled is the Tile Stamps panel. It lets you save arrangements of tiles for later reuse, and allows you to paint with random Stamps. This panel is hidden by default, you'll need to enable it in View > Views and Toolbars > Tile Stamps.

Note

In Tiled, "(Tile) Stamp" doesn't only refer to Stamps saved in the Tile Stamps panel. Any time you use the Stamp Brush, which is the basic drawing tool in Tiled, your brush is a Tile Stamp. Any time you pick one or more tiles from a Tileset to draw with, that's a Tile Stamp. The only things different about the Stamps in the Tile Stamps panel is that they're saved for later use, and that random variations can be selected.

Variations 

A very useful feature of this panel is the ability to create Variations of Tile Stamps. For example, you can make a tree Stamp and save a bunch of other trees as Variations of that Stamp. Then, when you use that tree Stamp, Tiled will pick a random tree to place. To use this feature, you first need to create a base Stamp. Select the tile or tile arrangement you want to make a stamp out of, and click the Add New Stamp button. Then, one by one, select your variants and click the Add Variation button.

Warning

Tiled currently has no way to change whether a given Stamp is a base Stamp or a Variation, so be careful when creating stamps. If you accidentally make a base Stamp when you want a Variation or vice versa, you'll need to delete and re-add it.

After you've created your Stamp with Variations, any time you paint with the base Stamp, a random Stamp will be selected from among the base Stamp and its Variations. If you click the arrow to the left of the Stamp in the Tile Stamps panel, you can expand or collapse the Tile Stamp. When expanded, you can view and edit the Variations. One of the properties you can edit is the Probability, which lets you control how often a particular stamp shows up relative to the others. Probability is only meaningful for Variations. The probability listed for the base Stamp is just the sum of the probabilities of the variations and isn't used for anything.

If you select a Variation to draw with instead of the base Stamp, only that Variation will be used. This means you can also use Variations as a way to group Stamps together, rather than just for randomness.

When using Variations, you'll usually want the Stamp Brush's random mode to be off, so that the entire Stamp is drawn, rather than a random tile from it.

Random Mode 

The Tile Stamps panel can be used to improve the usefulness of the Stamp Brush's Random mode. In Random mode, a single random tile from your current brush (Stamp) is drawn. You can save commonly-needed tile selections as Stamps, saving you the trouble of selecting them from your tileset or map every time. One thing you can do with stamps that you can't do by selecting tiles directly from your tileset is add flipped tiles. Using a stamp that contains various flips and rotations of your tiles allows you to randomize between those flips and rotations when you draw using Random Mode.
Two columns of two ladder tiles each. The right column is a horizontal mirroring of the left.
This Tile Stamp contains two ladder tiles and their horizontal flips. Using this Stamp with Random Mode will draw a random and randomly-flipped ladder tile.
Of course, when you just need a one-off bunch of random tiles like this, you can draw them on a map and copy+paste them from there to use with Random Mode. You only need to use the Tile Stamps panel when you want to save that bunch of tiles to use later.

RPG Maker Tilesets 

Some of the stock tilesets you'll find online, both free and paid, will be designed for RPG Maker autotiling. Such tilesets are stored in a compressed format, designed to be broken up into smaller sub-tiles and reassembled into full-size tiles at runtime. Tiled cannot use such tilesets directly effectively.

A 2x3 arrangement of grass and dirt tiles in RPG Maker autotile format
Tilesets with tiles arranged in patterns like this are usually designed for RPG Maker autotiling and cannot easily be used directly in Tiled.

In theory, you could use such tilesets in Tiled by loading them in with half the tile size they're intended for, but this will make it troublesome to get correct tiling, and they won't play very nicely with Terrains. There are two ways to use such tilesets in Tiled.

One option is to expand the tilesets by rebuilding the full tileset out of the sub-parts. These are some tools available to automate this:

The advantage of this method is you get an easy-to-use tileset image that Tiled can work with directly, and which you can load into engines other than RPG Maker with no issues. The disadvantage is that you get a much larger tileset, and if you are using RPG Maker, that's wasteful.

The other option is to use a two-tiered tileset taking advantage of Tiled's metatile feature. Load the RPG Maker tileset image as a Tileset with half the tile size (e.g. 16x16 instead of 32x32) so that the tiles in Tiled are the sub-tiles that RPG Maker would actually use at runtime, and then make a map where you expand it into full tiles yourself (this could be scripted, to avoid the tedious work). Then, make a new Tileset and use the map as the tileset "image", with the tile size set to the intended tile size (e.g. 32x32). Tiled will treat the map as a tileset image, and you'll be able to use the arranged tiles as regular tiles in Tiled, while still using the original source RPG Maker tileset image. The advantages of this method is it doesn't require expanding the tileset, so you can use the tileset image as downloaded, and you can use tiles from several tileset images within a single tileset-map, making it easy to merge these tilesets into one (for e.g. use with Terrains) without merging the original images. If you find you made a mistake in expanding the tiles or missed some tile, you can edit the tileset-map right within Tiled. The disadvantage is that metatiles like this are not supported by all Tiled map importers.

Terrains 

Terrains are simple to use once you set them up, but if you don't understand how the feature works, you may have difficulty correctly labelling your tiles if the tileset is complex or arranged in an unusual way. There's really just one thing to understand about Terrains, everything else flows from it: the labels tell Tiled how the tiles are intended to connect rather than what's on them, if the labels on the adjacent sides of two tiles match, they're allowed to placed next to each other, otherwise they are not. This is different from how some other level editors approach this task, but has the benefit of being very flexible.

Two water-and-grass tiles next to each other, shown without labels above and with labels below. The edges where they meet are entirely water. The matching edges are circled in pink.
The adjacent labels on these tiles match, so the Terrain tools will place them together.
Similar to the previous figure, but the right tile is different, with both grass and water along its edge, no longer a sensible match for the left tile. The mismatched edges are circled in pink.
The adjacent labels on these tiles do not match, so the Terrain tools will never place them together like this.

This concept of matching labels is applied in all four directions, the Terrain tools will try to find an arrangement of tiles such that all the labels on adjacent sides match perfectly. It is from these small relationships that larger coherent terrain shapes are built up.

Before you can label your tileset with Terrains, you need to understand how the tiles should be used, how they should connect to each other. If you've just downloaded a new tileset, take the time to play around with it by manually placing tiles before you start labelling it with Terrains. Understanding how your tileset works will make labelling it much easier. Consider not only which arrangements of tiles you're likely to use, but also how you may split your map across layers. For example, many RPG-style tilesets have plateaus where the top and sides of the plateau has transparency, which means plateaus should be drawn on a layer above the base terrain, and those Terrains should therefore transition to empty rather than to the ground Terrains.

Note

In the interest of performance, Tiled does not do an exhaustive search for a valid arrangement of tiles. So, Tiled will sometimes make mistakes and leave you with an invalid arrangement if you're using incomplete Terrains. Because of this, it's best to make your Terrains as simple and complete as possible. It's often better to handle the complex transitions with Automapping that runs after you paint with Terrains than to try to do everything with Terrains.

Warning

Not every tileset is well-suited to being used with Terrains. Some tilesets have complex, multi-tile transitions that can't be easily represented with Terrains, some rely on sharp boundaries and only have a small number of transitions, some rely on each tile being used in several contexts. Such tilesets are better used with Automapping than Terrains.

Some tilesets can be used with Terrains, but have only a small subset of transitions that they support, which will lead to broken results if you try to draw unsupported situations with them. It's important to know your tileset's limitations.

And lastly, some tilesets are so irregular that neither Automapping nor Terrains are a good fit, their tiles are best placed manually.

Identifying Terrains 

To avoid accidentally mislabelling some tiles, look through your tileset and figure out which tiles are part of which terrains, before you start labelling. Sometimes things that look different may actually be part of the same terrain. For example, a tileset may look like it has water, sand, and grass terrains, but the sand may just be decoration at all water-grass edges, so you wouldn't actually need a separate sand terrain, just water and grass. As a starting point, look for those tiles are filled with some terrain (e.g. all-water, all-grass tiles), and see if there are tiles that could serve as transitions between those tiles and other filled tiles.

Some Tilesets have multiple independent sets of terrain in them, that is, groups of terrains that connect with other terrains in their group, but not with terrains in other groups. For example, a tileset may have some interior wall and floor tiles that can be used as Terrains, but which have no way to connect to the exterior Terrains. I recommend having these as separate Terrain Sets, so that you don't have to look through the entire list of Terrains every time you want to find the one you want.

Terrain Set types 

When you create a new Terrain Set, you will need to choose a Terrain Set type. If you don't know what type of terrain you have, try to build the smallest shapes of each terrain that you can with the tiles, not counting 1x1 single-tile "islands". If it's a filled 2x2 shape connected at the corners, it's a Corner-based terrain. If it's a 2x1 or 1x2 line, it's an Edge-based terrain. If you can make both, it's a Mixed terrain.

Four-tile shape using a corner terrain set
Filled four-tile shapes like this are only possible with Corner (and Mixed) Terrains.
Horizontal and vertical two-tile shapes using an edge terrain set
Two-tile shapes like this are only possible with Edge (and Mixed) Terrains.

Because most tilesets are incomplete, you may find yourself unable to make these shapes in every combination of terrains, but only some of them. In particular, with Mixed tilesets, it's very common that you can make the two-tile shapes with one terrain, but not with the terrain around it. The island tileset above, for example, can make two-tile islands but not two-tile lakes. If you suspect you may be dealing with an incomplete Mixed tileset (i.e. you can make four-tile corner-linked shapes, but have way more tiles than would be needed for a corner-based terrain), try making the two-tile shapes in both configurations - terrain A inside and terrain B outside, and vice versa. If at least one of them works, you've definitely got a Mixed Terrain Set.

Note

It's common for a single tileset to contain multiple sets of terrains with different types. For example, top-down tilesets usually have Corner-based ground terrain, but may include Edge-based details like roads and fences. For this reason, you should check the type for all the different terrains you want to use.

The types and labels for each Terrain Set are independent, so you can set up the labels in each Terrain Set in whatever way is most useful for that set, the label for a particular tile can be different in each Terrain Set.

Labelling Terrains 

Once you've created your Terrain Set, you can start labelling. Place each terrain colour at each corner and/or edge (depending on your terrain type) where that terrain occurs. The Terrain documentation has more information on the UI for labelling and using Terrains.

Hint

If you're working with an isometric tileset, you can set the Orientation in the Tileset Properties to "Isometric" and set the grid size to match your tiles' visuals, so that the Terrain labels more closely match the art.

My usual advice for labelling Terrains is to put each label colour on those corners/edges of each tile where that terrain or material is present. For many tilesets, especially top-down ones, the labels will match the art well.

Side-by-side comparison of several tiles and their Terrain labels. The blue water labels neatly overlay the water parts of the tiles, while the green ground labels neatly overlay the grassy parts of the tiles
Part of a Mixed Terrain Set, with the art and the labels side by side.
Hint

Choose your Terrains' colours so that they resemble or evoke the terrain they represent, such as blue for water and green for grass, like in the example above. This can make labelling less confusing. You can customize the colour for your Terrains by right-clicking the Terrain name in the list of Terrains and choosing "Pick Custom Color".

Avoid using colours that exactly match the tile art, choose more saturated colours instead, so that they stand out from the art.

However, it can be harder to see where each terrain goes if the art on the tiles has different proportions from the Terrain labels in Tiled.

Part of a sidescroller tileset where the entire tile is covered by the ground, without Terrain labels
These sidescroller ground terrain tiles should transition to empty space, but the entirety of each tile is covered in ground.
The same sidescroller tiles, overlaid with red Terrain labels. The labels only cover part of the tile
The ground in the tile art reaches the tile edges, but the labels do not.

The key thing to keep in mind is that when you label Terrains, what you're doing is telling Tiled how the tiles should connect to one another. It doesn't matter what the labels look like, what's important is that the edges/corners of tiles that can be placed together have matching labels. In the above example, the outermost parts of the tiles that transition to empty space are left empty (unlabelled), and the rest is filled with the ground Terrain.

When labelling Terrains, take care to stay focused on the individual tiles and how they may connect with other tiles. Do not fall into the trap of looking at the overall shapes your labels make across neighbouring tiles. While there are some common arrangements of tiles in tilesets, such as the 3x3 block of corner-based terrains, tiles can be arranged in any way and you can't rely on their arrangement. Pay attention to the tiles instead.

Hint

Some tilesets include 1x1 "island" tiles of some of their terrains. You can see two such tiles in the example above, the two unlabelled tiles. The top right one is ground on all sides and empty in the middle, the bottom left one is empty on all sides and ground in the middle. Since Tiled has no way to mark the middles of tiles with Terrains, these tiles are functionally identical to the all-ground and empty tile, respectively. Such tiles should be placed by hand.

However, it is a good idea to label them where possible, so that if you do place them manually and then edit the surrounding tiles with the Terrain tools, the tools will know how to connect other tiles to them. In order to prevent those tiles from showing up automatically as random variants of the regular tiles with those same labels, set their Probability to 0 in the Tile Properties.

Incomplete Terrains 

Most tilesets out there are incomplete. Even those featuring just one set of corner-based terrains, something that normally only requires 15 or 16 tiles, are usually missing tiles. Tiled can handle incomplete Terrains to some degree, and most common types of incomplete tilesets will work well. However, in some cases, Tiled will have no idea what to do, and will either not let you draw at all, or will draw an explosion of garbage. If you find yourself facing these two results too frequently, consider expanding your tileset, those missing tiles may actually be important for your maps.

For Corner Terrain Sets, it's very common to leave out the two tiles where opposite corners match. This means that you can't draw very tight, snaking shapes with those tiles, and should instead draw your shapes spaced out. If you run into issues using Corner Terrains, check if you're missing these two tiles, adding them can help.

Two tiles. The left tile is mostly grass and has water in the top right and bottom left. The right tile is similar, but has water in the top left and bottom right.
Tiles similar to these, with matching opposite corners, are often missing from Corner-based tilesets.

Edge Terrain Sets for things like fences often only include those tiles where only one or two of the edges are the "fence" and the rest are the surrounding terrain. This means that the "fences" can't branch, as that would require tiles where three of the edges are "fence". If only tiles where two of the four edges are "fence" are included, the fence can only make closed loops, it has no way to terminate to make an opening.

A complete Mixed Terrain Set with two Terrains would require 256 tiles. Unsurprisingly, it's very rare to find such a tileset, as that's a lot of art to produce, and most of those tiles aren't that useful. Instead, it's far more common to use the 47-tile "Blob" subset. This style of tileset allows for a large variety of terrain with only a fraction of the tiles.

One very common mistake involving deliberately incomplete tilesets is to try to draw on an empty layer with a Terrain that has no way to transition to empty tiles. Tiled will not let you draw anything at all since there's nothing it can draw, making the Terrain Brush appear to not work. The solution is to fill your layer with the base tile for one of the Terrains before you start drawing with the Terrain Brush, so that there's something valid for your desired Terrain to transition to.

Tilesets not designed with Terrains/automapping in mind often require incomplete Terrains to properly label, and the incomplete terrains often give Tiled trouble, sometimes to the point of barely being useable. Automapping can be a better option in these cases. If you are an artist designing tileset, I highly recommend getting to know the Terrain tools in Tiled and making your tilesets work with them. Basic two-colour Terrains in Tiled will also work well with Unity and Godot's autotiling tools.

Transitional Terrains 

Not every tileset fits nicely with Tiled's concept of Terrains. You can't always just add labels that tell Tiled, "here's Terrain A, here's Terrain B", but that doesn't mean you can't make those tiles work with Terrains. Sometimes you just have to get creative.

A not uncommon scenario is when two sets of tiles have corresponding edges, but no actual transition tiles.

Small room made out of tiles in a dark void. The bricks are lighter around the perimeter of the room
These sidescroller tiles do not include any transition tiles between the wooden back wall and the brick side walls, but the two should clearly be connected: the side walls have light edges, and the back wall has shading where it meets the side walls.

If you label the edges of one of these as being the other terrain, then it won't connect to the correct Tiles of the other terrain. Instead, you need to tell Tiled that the edges of one link up with the edges of another. And the mechanism Terrains have to do that is... another Terrain.

3x3 sets of tiles of bricks and wooden back wall, without labels
Some brick side wall and back wall tiles from the tileset used for the room above.
The same tiles, overlaid with Terrain labels: purple for the inside part of the brick walls, blue for the back wall, and orange for the light outer part of the brick walls and shaded parts of the back wall
Labels for those tiles. The orange Terrain is the transitional Terrain that tells Tiled that the shadows on the back wall should connect to the light edges of the brick side walls.

Can't Paint with a Terrain 

If you make a terrain but Tiled won't place any tiles when you try to use the Terrain Brush, the most likely culprit is that your terrain has no way to transition to whatever is already on the layer. This commonly occurs when painting on an empty layer with a terrain that has no transitions to empty. Try filling the layer with a solid tile from the terrain set you want to use, and then painting with that.

Parsing Tiled Layer Data 

If you're parsing Tiled files yourself rather than using an existing library or exporting in an engine-specific format, you may run into some of these issues when trying to read the Tile Layer data. Fortunately, they all have relatively simple solutions.

Garbled-looking Data 

Tiled supports several data formats for the list of tiles that make up each Tile Layer. It's quite likely that you'll find layer data that looks something like this:

eJztzwENwCAQBEEQVKQhDWnVUBPNPYEZA5ttDQAAAAAAgD+Ny/oz3Kvur3Cvuu/37P4b7lX3Rw8Hi/tPNrddHyDlA1RLB+E=

This can be rather intimidating since it doesn't look like the list of tile IDs you might be expecting, but don't worry. The map contains information to help you parse this data, and Tiled has options for formats that you might find easier to understand.

The Tile Layer Format can be changed in Tiled in the Map Properties, this determines how the layer data is stored in the map files. As of Tiled 1.7, the following options are available:

As mentioned above, if you're just getting started, try changing your map's Tile Layer Format to CSV, as it's probably the easiest format to work with when you're just trying to get the basics working, as you can just look at the data and know roughly what it corresponds to, unlike the Base64-encoded formats. When you're ready to parse the other formats (except XML, which isn't worth bothering with), come back here.

Parsing the Base64-encoded formats 

If you look at the data field in the layer, it should have encoding and (optionally) compression properties. The examples here will use the TMX format, but this is all pretty similar with JSON format and any other export formats that respect the Tile Layer Format property in your maps. If the encoding is "csv", then you're dealing with a CSV string, which should be fairly easy to figure out. If the encoding is "base64", then read on.

The Base64 formats are should all be dealt with roughly the same way:

  1. Decode base64. The result will be a bunch of binary data, typically an array of bytes, though different languages and frameworks have slightly different ways to deal with this.
  2. If a compression is set, decompress. The compression options are "zlib", "gzip", and "zstd", and you'll need to run the appropriate decompression algorithm based on the value of the property. If the compression property isn't set, then skip this set, because the data wasn't compressed. Again, the exact way to do this will depend on the language and libraries you're using, but zlib and gzip libraries are widely available. Generally, they'll take a byte array or a string as an input, and output a new, decompressed byte array or string.
  3. Reinterpret the bytes as 32-bit unsigned integers. The base64 decoder and the decompression libraries operate at the byte level and don't care what the bytes mean, but what you need out of the data is 32-bit unsigned integers. The data is always in little-endian byte order, regardless of the endianness of the system it was written on. Most architectures these days are little-endian, so it's sufficient to just copy the binary data into an array of unsigned 32-bit integers or to reinterpret the existing data in memory (e.g. via casting). If you're compiling for a big-endian system, you'll want to rearrange the bytes (swap bytes 0 and 3 and bytes 1 and 2 of every set of 4 bytes) before doing that.

This might sound complicated, but once you have the decompression libraries you need, the actual code should be fairly simple. Here's some C++ that's very similar to what I do in my engine, using zlibcomplete for decompressing zlib and gzip:

//get the layer data from the file:
std::string data = dataNode->value();

//Prepare a container for the layer data:
unsigned int* tileGIDs = new unsigned int[mapWidth*mapHeight];

if(std::strcmp(encoding, "base64") == 0) {
	data = base64_decode(data);

	if(std::strcmp(compression, "zlib") == 0) {
		zlibcomplete::ZLibDecompressor decompressor;
		data = decompressor.decompress(data);
	} else if(std::strcmp(compression, "gzip") == 0) {
		zlibcomplete::GZipDecompressor decompressor;
		data = decompressor.decompress(data);
	} else if(std::strcmp(compression, "zstd") == 0) {
		//unsupported compression
		//report an error, clean up, abort loading
	}
	//Copy the bytes into the unsigned int array:
	memcpy(tileGIDs, data.data(), data.size());
} else if(std::strcmp(encoding, "csv") == 0) {
	//parse the data string as CSV, into the tileGIDs array:
	parseCSV(data, tileGIDs);
}

Very Large Tile IDs 

If you encounter tile IDs in the data that are much larger than the maximum tile ID you expect, these are probably flipped/rotated tiles. Tiled uses the most significant four bits (bits 29-32) for flip and rotation flags. Before you can get at the tile ID, you should read these flags and store their state so that you can apply these transformations to the tile when you render, and then you need to clear the flags, so that only the tile ID remains. The Tiled docs have a parsing example, but it's out of date. The current full list of flags:

To remove all the flags after reading them, you can perform a bitwise AND on the tile ID and the bitwise negation of the combination of all the flags. Here's a C++ example:

tileID = tileID & ~(0x80000000 | 0x40000000 | 0x20000000 | 0x10000000);
Note

The documentation has recently been updated and now includes more information about all four flags. You can view it here. This section of the tip sheet will be trimmed down when this updated documentation makes it to the stable branch, as it is largely redundant.

Tile IDs slightly off 

If you're rendering your tiles successfully but getting the wrong tile from what you expect, you're probably neglecting the firstgid of your tileset. A Tiled map can have tiles from multiple tilesets, and there needs to be some way to tell which Tileset a tile is from. Just using the tile ID directly wouldn't work, since each tileset has its own, independent tile IDs, typically starting from 0. Instead of using these conflicting IDs, every tile in a map uses a global ID, or a gid for short, so that every tile can have a unique identifier even if there are multiple tilesets in the map.

Tiled maps have a list of Tilesets used in them, and each of these tileset entries in the list has a firstgid property. The same tileset may have different firstgids in different maps, so make sure you read the tileset list for every map, don't make assumptions.

<tileset firstgid="1" source="TilesetA.tsx"/>
<tileset firstgid="2049" source="TilesetB.tsx"/>
Example tileset list from a TMX map. Each tileset has a firstgid property.

To determine which tileset a tile belongs to, find the largest firstgid that is smaller than or equal to the tile's gid. If the tile ID is smaller than all of the firstgids (typically this means it's 0), that means it's an empty tile. After you've determined which tileset the tile belongs to, you can get its tileset-local ID by subtracting the firstgid from the tile's gid. In the example above, tile 476 would belong to TilesetA and have local ID 475, while tile 2156 would belong to TilesetB and have local ID 117.

Note

Maps that have only one tileset have a firstgid of 1 for that tileset. If your parser only supports single-tileset maps, you can generally assume that tileset will always have firstgid 1.

Although firstgids are usually assigned based on the previous tileset's tile count, this is not a guarantee and should not be relied upon. Tilesets' sizes may change after the map is saved, and Tiled could easily start basing the firstgid on the tiles that are actually used within the map instead. When dealing with multiple tilesets, always read the firstgid from the map instead of guessing at it.

Credits 

Some examples on this page use art from the following asset packs: