Tiled Tip Sheet

Foreground and Background Layers 

You can sort your tree tiles into two layers: a foreground layer that contains the tiles that are always on top of the player, and a background layer that contains the tiles that are always behind the player.

Pros:

• No special handling required in the engine: simply draw the player and other dynamic entities between the foreground and background layers.
• Good runtime performance because there is no dynamic z-sorting, and all tile layer optimizations apply. Many kinds of entities can be included on the same background and foreground layers, so your overall layer count can stay low, too.
• Widely supported by engines, since it uses regular tile layers where each tile fits in its cell.

Cons:

• You have to manage your trees across two or more layers.
  • This can be partially mitigated by saving stamps of your trees where the tiles are already on the correct layers. When you use such stamps, Tiled will automatically put the tiles on the correct layers.
  • You can also set up Automapping rules to add the tree crowns on the foreground layer when you draw trunks on the background layer, and erase tree crowns from the foreground when the corresponding trunks are removed.
• Any part of the tree is either always behind or always in front of the player. If a dynamic sprite is tall enough to reach the tree's crown when standing in front of it, they will still be overlapped by it. This limitation makes this approach best-suited for games with smaller sprites.
• There is still a risk of "collision" and overwriting tiles if you want multiple trees to be very close to each other, tree foreground portions can only overlap only the background portion of other trees. You can use additional background and foreground layers to allow backgrounds to overlap other backgrounds and foregrounds to overlap other foregrounds, but that will further complicate layer management, and using too many layers can impact rendering performance.

One Tile per Tree 

You create a tileset where each tree is a single tile, so it's impossible for a part of the tree to be overwritten by something else, and so that the tree can be z-sorted as a single entity. In Tiled, you can use such oversized tiles on a Tile Layer, in which case they'll stick out of their cells, or you can place them as Tile Objects on an Object Layer. In either case, in-engine, you'll need to z-sort the trees at runtime to know what order to render them and the other entities in.

Pros:

• Easy to edit and manage, since each tree is a single tile. If you use Tile Layers, you can even easily randomize which tree you place.
• If you use an Object Layer with Tile Objects without "Snap to Grid", you can position the trees freely, they don't have to follow the tile grid if you don't want them to.
• Dynamic z-sorting allows any part of the tree to be a background or a foreground based on where exactly the player is relative to it.

Cons:

• You may need to put your trees and other similar props in a separate tileset so that each tree can be a single tile. In some cases you may be able to use the same tileset image as your main tileset as the source, just with a different tile size, but in most cases, you will need to make an entirely separate image or collection of images to serve as the source(s) for this tileset.
  • If/when Tiled gets support for Tile Atlases (see issue #2863) so that you can define a tile out of any rectangle in your image, this issue will be mitigated somewhat. However, tightly packed tilesets may not leave the space around the narrower parts of the trees empty, and for those, a separate tileset would still be required.
• Z-sorting has a performance cost, and the more entities you sort, the more noticeable it becomes.
  • Trees are likely to be static rather than dynamic objects, which means they never change z-order relative to each other. Some engines have optimizations for sorting static entities, so their impact may be small.
• If you use a Tile Layer, you'll need some way to tell the engine to include its tiles in z-sorting rather than treating them as a single flat layer. Objects are usually assumed to be z-sortable dynamic entities, but then you might still need some way to tell the engine that they're z-sortable static entities if you want to optimize the z-sorting.
• When each tree is a single tile, it can get confusing to know where exactly each tree is located, which can complicate things like collision detection and selections. In the illustration above, the tree is aligned to the bottom left corner of its cell, which means the actual location of the tree is actually in an empty part of the tile. Tilesets have a Drawing Offset property you can tweak to make it so that the base of the tree is centered on the cell, but a single offset may not work for every tile in the tileset.
  • This issue will be mitigated if per-tile drawing offsets are implemented in Tiled (see issue #871).

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. The following options are available:

• XML (deprecated): Each tile is stored as an XML element. This format is offered only for backwards compatibility, and should not be used as it makes for needlessly large files and is slow to parse.
• Base64 (uncompressed): The data is a list of tile IDs as unsigned 32-bit integers, base64 encoded. This format has some niche uses, but usually one of the compressed formats is better.
• Base64 (gzip compressed): The data is a list of tile IDs as unsigned 32-bit integers, compressed with gzip, and then base64 encoded. This or the other compressed formats should be used whenever possible, as they make the data much smaller. gzip and zlip libraries are also commonly available either as part of engines or as plugins/scripts.
• Base64 (zlib compressed): As above, but compressed with zlib.
• Base64 (Zstandard compressed): As above, but compressed with Zstandard. While this is a good compression format, it's not as widely supported as zlib and gzip, so I don't recommend using it unless you're sure it's supported in your engine.
• CSV: The data is a list of tile IDs as CSV. This is the easiest format for a human to read, but it makes for larger files than the compressed formats. If you're just getting started and just want to get some tiles drawn in your game, this is a good place to start, but I don't recommend using CSV in production since it makes for large files, and can be slow to parse if you don't optimize.
Hint

In TMJ (Tiled Map JSON) maps, the "CSV" format actually outputs a native JSON array rather than a CSV string. This means rather than parsing the JSON yourself, you may be able to use your JSON library's built in array parsing.

//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 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 more information on these flags and parsing them, including a code example.

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.

The Tiled documentation has a section on dealing with firstgids.

Drawing tiles from a Tileset 

Tiled supports two kinds of Tilesets: Image Collections, and Based on Tileset Image.

Image Collections

In Image Collections, every tile is its own separate image, so to render a given tile, you'd look up its image and render it. As of Tiled 1.9, these Image Collection tiles have x, y, width, and height properties which determine where exactly in the image the tiles are, so you should draw the subrectangle of each tile's image that's defined by these properties.

Based on Tileset Image

Tilesets that are Based on Tileset Image are all subrectangles of the Tileset's source image, but their locations are not explicitly defined anywhere. Instead, they can be simply calculated from the tile ID like this:

x = tileID % columnCount; //in tiles
x = x * (tileWidth + spacing) + margin; //now in pixels
y = floor(tileID / columnCount); //in tiles
y = y * (tileHeight + spacing) + margin //now in pixels

At the end of this, x and y contain the pixel coordinate of the top left pixel of your tile. To get the other three corners, add tileWidth to x and tileHeight to y as needed.

The column count is the width of the Tileset in tiles. It's included as a columns field on the Tileset in most versions of Tiled, and can be calculated for very old tilesets, which don't have it, from the image width, tile width, margin, and spacing:

columnCount = floor( (imageWidth - margin + spacing) / (tileWidth + spacing) );

Rendering Maps 

While it is outside the scope of this document to describe 2D video game rendering, this section will cover where each grid cell is positioned for the different map orientations in Tiled, as this is not always trivial, and few engines natively support non-orthogonal orientations, and even those that support orthogonal orientations don't always support drawing the tiles in all the ways Tiled does.

In general, you should render layers from bottom to top, i.e. in the order that the layers appear in the Tiled map file, and each layer is largely independent. Each layer in Tiled can have its own offsetx and offsety, this means the layer should be drawn that many pixels right and down from its default location; in most engines you can simply subtract the offset from the layer's origin. If that's not an option, you'll need to add the offset to the layer's render position every time you draw it.

Tiled supports four map orientations: orthogonal, isometric, isometric (staggered), and hexagonal. The actual tile textures are always rectangles, and the rendered layer can be thought of as a screenspace rectangle, so all these orientations change is where each cell is. The cell is the slot where a tile can be, the cells the spaces between the grid lines that you can see in Tiled. Cells and tiles aren't the same thing. A cell may be empty, which means no tile should be drawn there, and more importantly, tiles may stick out of their cells, may not fill the entirety of the cell, and may be offset from their cells - sometimes all at the same time. The rest of this section will discuss cell positions, but to figure out where to draw the tile relative to the cell, you'll need to do some additional work, in this order:

1. Calculate the tile's render size and scale. By default, this is the same as the tile size, so both the x and y scale factors are 1.0, but tilerendersize on the Tileset may be set to grid, which means the tiles should be scaled to fit the grid size. In that case, the exact scaling depends on the fillmode. If it's stretch (default), then divide the cell width by the tile width to obtain the x scale factor, and the cell height by the tile height to obtain the y scale factor. If it's preserve-aspect-fit, then do the same, but then use the smaller value of the two for scaling both the width and height of the tile. The tile's render size is its base size multiplied by the calculated scale factor. Since tiles can differ in size and shape, this calculation has to be done for each tile, though you can cache the results since within a map, each cell is the same size.
Hint

In all Maps, the cells are the map's tileWidth in width and the map's tileHeight in height. The different orientations only change where each cell is, not the cells' size.

2. To match Tiled, tiles should be drawn with bottom left alignment, that is, the bottom left corner of the tile's bounding box should be in the bottom left corner of the cell's bounding box. If the tile is drawn larger than the cell, that means it'll stick out at the top and left side, and if the tile is drawn smaller than the cell, it'll leave space above and to the right. Since most rendering happens relative the top left, that means you'll need to subtract the tile's render height from the bottom left corner position, this'll give you the location of the top left corner of the tile for that cell. This has to be done for each tile independently, as tiles may have differing sizes.

   If the fillmode is preserve-aspect-fit, the tile should be centered within its bounding box. Add half the difference between the cell size and tile's scaled size to the render position. For simplicity, you can apply this to stretch Tilesets too - the difference will just always be 0, 0 and not change the render position.

3. Tilesets have a tileoffset property, this should be scaled by the render scale and then added to the tile's render position.

This process is the same regardless of map orientation, so in the orientation-specific sections below, I will focus on calculating the bottom left origin for each tile. From this, you can calculate the position at which to render the tile following the process above.

In the orientation-specific sections below, x and y are always the cell's coordinates, i.e. in map-space, and are assumed to be integers. gridWidth and gridHeight are the map's tile size, which may be different from the size of the tiles. These pseudocode examples are based on the code Tiled internally uses to translate map-space coordinates to screenspace coordinates.

left = x * gridWidth;
right = left + gridWidth;
top = y * gridHeight;
bottom = top + gridHeight;

originX = mapHeight * gridWidth / 2;
xPixel = (x - y) * gridWidth / 2 + originX;
yPixel = (x + y) * gridHeight / 2;
//xPixel and yPixel are at the upper corner of the cell,
//i.e. the middle of the top edge of the bounding box.
left = xPixel - gridWidth / 2;
right = xPixel + gridWidth / 2;
top = yPixel;
bottom = yPixel + gridHeight;

for(sum = 0; sum < mapWidth + mapHeight - 2; ++sum) {
	for(x = 0; x < sum && x < mapWidth; ++x) {
		y = sum - x;
		if(y < mapHeight)
			//render the tile at x, y
	}
}

//Some useful functions and values:
bool shouldStaggerX(int x) {
	if(staggerX) {
		if(x % 2 == 0) //x is even
			return staggerEven;
		else
			return !staggerEven;
	}
	return false;
}
bool shouldStaggerY(int y) {
	if(!staggerX) { if staggerY
		if(y % 2 == 0) //y is even
			return staggerEven;
		else
			return !staggerEven;
	}
	return false;
}

columnWidth = gridWidth / 2;
rowHeight = gridHeight / 2;
if(staggerX)
	columnWidth += sidelength / 2;
else //staggerY
	rowHeight += sideLength / 2;

//Finally, the actual cell calculations:
if(staggerX) {
	xPixel = x * columnWidth;
	yPixel = y * (gridHeight + sideLength);
	if( shouldStaggerX(x) )
		yPixel += rowHeight;
} else { //staggerY
	xPixel = x * (gridWidth + sideLength);
	if( shouldStaggerY(y) )
		xPixel += columnWidth;
	yPixel = y * rowHeight;
}
left = xPixel;
right = xPixel + gridWidth;
top = yPixel;
bottom = yPixel + gridHeight;

bool shouldStaggerX(int x) {
	return staggerX && (x & 1) ^ staggerEven;
}
bool shouldStaggerY(int y) {
	return !staggerX && (y & 1) ^ staggerEven;;
}

if(!staggerX) {
	for(y = 0; y < mapHeight; ++y) {
		for(x = 0; x < mapWidth; ++x) {
			//render the tile at x, y
		}
	}
}

else {
	for(y = 0; y < mapHeight; ++y) {
		startX = 0;
		if(staggerEven)
			startX = 1;
		for(x = startX; x < mapWidth; x += 2) {
			//render the tile at x, y
		}
		
		if(startX == 0)
			startX = 1;
		else
			startX = 0;
		for(x = startX; x < mapWidth; x += 2) {
			//render the tile at x, y
		}
	}
}

CLI 

Scripts are typically run via the Tiled Editor GUI, but they can also be run via the CLI: --export-map and --export-tileset can use scripted Map and Tileset formats, and you can execute arbitrary scripts with --evaluate <scriptFile> [args]. The latter allows you to pass additional parameters to the script as well, which you can access in the script via tiled.scriptArguments.

When running scripts via CLI, none of the GUI features are available. This includes most of the functionality in the Tiled GUI section below, methods like tiled.trigger() and tiled.open(), and, perhaps surprisingly, TileMap.automap(), as Automapping is part of the Tiled Editor GUI and not part of the core Tiled library.

If you want to write scripts that work both via CLI and GUI, you should avoid relying on the GUI-specific features and tiled.scriptArguments. If your script needs the current document, the way to do this will vary: if the user is running the GUI, then tiled.activeAsset will work, and if that's null, you can check tiled.scriptArguments for a path, which you can then read.

GUI 

When running scripts in the Tiled GUI, they can access many parts of the GUI, so your scripts can respond to the user's current brush, chosen tileset, current document tab, etc. These parts of the API are not available to scripts running via the CLI.

You can get the current active document via tiled.activeAsset, and the list of all open documents via tiled.openAssets.

Tiled's GUI consists of two major parts, each with their own selection of panels: the Map Editor, which is shown when the active document is a Map, and the Tileset Editor, which is shown when the active document is a Tileset. Understanding this split is important if you want to write scripts that interact with the GUI. For example, the Terrain chosen in the Map Editor's Terrain Sets panel is used for painting on Maps and has nothing to do with the Terrain chosen in the Tileset Editor's Terrain Sets panel, which is used for assigning Terrains to Tiles.

Scripting Caveats 

There are a number of quirks to the scripting API - some due to bugs, some due to the API functions originally being written for purposes other than scripting, some due to Qt/Tiled limitations. This is not an exhaustive list.

• When editing Tile Layers with setTile(), the apply() function currently takes the user's selection into account, so any modifications you make that are outside the user's selection will not be applied. You can get around this by clearing the selection, e.g. map.selectedArea = Qt.rect(0,0,0,0). You should do this any time that you're a document the user may have previously interacted with, unless you specifically want to only modify tiles within their selection (in which case, you can make your script perform better by only doing the work within the selection in the first place). This is issue #3482.

  • If you clear the user's selection to avoid this issue, consider saving it to a variable first, and then restoring it.

• Although it is a property, Tileset.tiles creates JavaScript-side Tile objects every time you access it, making it rather slow. Instead of accessing it repeatedly, save it to a local variable, and then do work with that variable, as much as you can.

• Resizing a layer via resize(), whether directly or via resizing the map it's in, causes the layer to be replaced with a clone, invalidating any existing references you may have to that layer. This means that you should avoid resizing any layers that aren't part of a map (or you won't be able to recover them!), and if you need to compile a list of layer references for a map, you will want to do it after any resizing. This is tracked as issue #3480. You can resize by changing a layer's or map's width and height properties without issue.

• There is currently no way to open a Tiled document "silently" - without displaying it to the user. This becomes an issue when you need to open Tilesets to add to a TileMap in a custom map format, for example. It's possible to read the contents of a Map or Tileset file with the appropriate format's read() method, but this creates a copy disconnected from the original file, and using a Tileset loaded this way in a Map would create an embedded Tileset. There might eventually be something like tiled.load() that will open a document without displaying it to the user.

  tiled.open() is the correct way to go in this case, at least for now. You can tiled.close() the document after you're done with it, though you'll want to avoid closing any documents that were already opened by the user. You can achieve this by first checking tiled.openAssets for the document you want, and only doing open() and close() if you don't find it there.

• All Tiled scripts share the same global context. Any persistent variables you declare in one script, can be accessed in any code that runs later, even from other scripts. You should avoid creating more global variables than you need, and you should be careful to name them specifically enough that they're not likely to collide with the variables of another script.

• This isn't a quirk, but rather a natural consequence of having JavaScript-side proxy objects for objects on the C++ side: you can assign any property on the JS objects, but only properties that are valid for the C++ objects will make it to the C++ side for use and display in Tiled. You can, however, take advantage of this to conveniently store temporary data about Tiled objects. For example, if you register an Action in Tiled, you can store its configuration on the Action object in JS, without interfering with the action's functionality, without filling up the global space with a bunch of variables.

Reading and Writing Files 

Sharing Your Scripts 

If a script you've written might be useful to other people, please consider sharing it! The tiled-extensions repo accepts pull requests - you don't need to set up a git repo for your scripts to submit them, you can submit files via the GitHub website. Before you submit your script, consider it's usability - you know your script well, but other people will not. Some things to consider:

• If you write any temporary files, delete them after you're done. If you're storing user preferences in files to save them across executions, consider if you really need this - maybe make it opt-in somewhere near the top of your script. Minimise how often you read/write these settings, e.g only write when settings change, and read only when the script first runs, and save them in-memory afterwards. When #2903 is implemented, you'll be able to save your preferences as part of the user's project instead of your own files.

• If your script has a potentially long execution time, or if it is an action modifies files or documents without the possibility of Undo, consider adding a confirmation pop-up (at least when not running via CLI). Accidental executions can and do happen, especially if your script is an action added to a menu or toolbar.

• Try to leave the GUI as you found it, except for the changes your user expects the script to make. For example, if you're opening some documents that the user didn't ask for (e.g. tilesets for a new map), close them, and if you need to change the user's selection, you may want to restore it after you're done.

• Make icons for scripted tools. This can just be a small PNG file, you don't have to make a full vector icon if you don't want to. Icons usually take up less space than the tool name.

• If your script adds an action that doesn't need to be used frequently, consider not adding it to any menus, to avoid cluttering them. As long as the action is named appropriately, users can find it via Search Actions.

• Add explanatory tooltips to your Dialog widgets.

• Since English is the default language of Tiled and most Tiled users have some knowledge of it, try to write your user-facing texts in English, unless your extension is meant for users of another language. If you want to take it a step further, English comments and English function and variable names can make it easier for more people to troubleshoot your script.

• Add a comment at the top of the script that explains what your script does, where to find any actions it adds, and who wrote it (e.g. GitHub username). This way people browsing their script files will know what the file is, and where to go if they need help with it. If your script consists of multiple files, each file should mention which extension it's a part of, and ideally list all the files, so that users can remove them all easily once they no longer need them.