docs/reference/tmx-map-format.rst
Version 1.8
TMX and TSX are Tiled <http://www.mapeditor.org>__'s own formats for storing
tile maps and tilesets, based on XML. TMX provides a flexible way to describe a
tile based map. It can describe maps with any tile size, any amount of
layers, any number of tile sets and it allows custom properties to be
set on most elements. Beside tile layers, it can also contain groups of
objects that can be placed freely.
Note that there are many :doc:libraries and frameworks <support-for-tmx-maps>
available that can work with TMX maps and TSX tilesets.
In this document we'll go through each element found in these file formats. The elements are mentioned in the headers and the list of attributes of the elements are listed right below, followed by a short explanation. Attributes or elements that are deprecated or unsupported by the current version of Tiled are formatted in italics. All optional attributes are either marked as optional, or have a default value to imply that they are optional.
Have a look at the :doc:changelog <tmx-changelog> when you're interested
in what changed between Tiled versions.
.. note::
A DTD-file (Document Type Definition) is served at
http://mapeditor.org/dtd/1.0/map.dtd. This file is not up-to-date but might
be useful for XML-namespacing anyway.
.. note::
For compatibility reasons, it is recommended to ignore unknown elements and
attributes (or raise a warning). This makes it easier to add features
without breaking backwards compatibility, and allows custom variants and
additions to work with existing tools.
.. _tmx-map:
<map> -----right-down (the default), right-up,
left-down and left-up. In all cases, the map is drawn
row-by-row. (only supported for orthogonal maps at the moment)#AARRGGBB. Defaults to
fully transparent.)0 for false, 1 for true, defaults to 0)The tilewidth and tileheight properties determine the general
grid size of the map. The individual tiles may have different sizes.
Larger tiles will extend at the top and right (anchored to the bottom
left).
A map contains three different kinds of layers. Tile layers were once
the only type, and are simply called layer, object layers have the
objectgroup tag and image layers use the imagelayer tag. The
order in which these layers appear is the order in which the layers are
rendered by Tiled.
The staggered orientation refers to an isometric map using staggered
axes. The oblique orientation uses a skewed grid of parallelogram-shaped
tiles.
The tilesets used by the map should always be listed before the layers.
Can contain at most one: :ref:tmx-properties,
:ref:tmx-editorsettings (since 1.3)
Can contain any number: :ref:tmx-tileset, :ref:tmx-layer,
:ref:tmx-objectgroup, :ref:tmx-imagelayer, :ref:tmx-group (since 1.0)
.. _tmx-editorsettings:
<editorsettings> ----------------This element contains various editor-specific settings, which are generally not relevant when reading a map.
Can contain at most one: :ref:tmx-chunksize, :ref:tmx-export
.. _tmx-chunksize:
<chunksize> ~~~~~~~~~~~.. _tmx-export:
<export> ~~~~~~~~.. _tmx-tileset:
<tileset> ---------tmx-tileset element described here. (There is the
firstgid attribute missing and this source attribute is also not
there. These two attributes are kept in the TMX map, since they are
map specific.)unspecified, topleft, top, topright,
left, center, right, bottomleft, bottom and
bottomright. The default value is unspecified, for compatibility
reasons. When unspecified, tile objects use bottomleft in orthogonal mode
and bottom in isometric mode. (since 1.4)tile (the default) and grid. When
set to grid, the tile is drawn at the tile grid size of the map. (since 1.9)stretch (the default) and preserve-aspect-fit. Only
relevant when the tiles are not rendered at their native size, so this
applies to resized tile objects or in combination with tilerendersize set
to grid. (since 1.9)A tileset can be either based on a single image, which is cut into tiles
based on the given parameters, or a collection of images, in which case each
tile defines its own image. In the first case there is a single child
:ref:tmx-image element. In the latter case, each child
:ref:tmx-tileset-tile element contains an :ref:tmx-image element.
If there are multiple :ref:tmx-tileset elements, they are in ascending
order of their firstgid attribute. The first tileset always has a
firstgid value of 1. Since Tiled 0.15, image collection tilesets do
not necessarily number their tiles consecutively since gaps can occur
when removing tiles.
Can contain at most one: :ref:tmx-image, :ref:tmx-tileoffset,
:ref:tmx-grid (since 1.0), :ref:tmx-properties, :ref:tmx-terraintypes,
:ref:tmx-wangsets (since 1.1), :ref:tmx-tileset-transformations (since 1.5)
Can contain any number: :ref:tmx-tileset-tile
.. _tmx-tileoffset:
<tileoffset> ~~~~~~~~~~~~This element is used to specify an offset in pixels, to be applied when drawing a tile from the related tileset. When not present, no offset is applied.
.. _tmx-grid:
<grid> ~~~~~~orthogonal or isometric, defaults to orthogonal)This element is only used in case of isometric orientation, and determines how tile overlays for terrain and collision information are rendered.
.. _tmx-image:
<image> ~~~~~~~tmx-data
child element. Valid values are file extensions like png,
gif, jpg, bmp, etc.Tiled maps or tilesets with embedded image data can currently only be created
using the :doc:JavaScript API </manual/scripting>, or in custom tools
based on libtiled (Qt/C++) or tmxlib <https://pypi.python.org/pypi/tmxlib>__ (Python).
Can contain at most one: :ref:tmx-data
.. _tmx-terraintypes:
<terraintypes> ~~~~~~~~~~~~~~Deprecated: This element has been deprecated since Tiled 1.5, in favour of
the :ref:tmx-wangsets element, which is more flexible. Tilesets containing
terrain types are automatically saved with a Wang set instead.
This element defines an array of terrain types, which can be referenced
from the terrain attribute of the :ref:tmx-tileset-tile element.
Can contain any number: :ref:tmx-terrain
.. _tmx-terrain:
<terrain> ^^^^^^^^^Deprecated: This element has been deprecated since Tiled 1.5, in favour of
the :ref:tmx-wangcolor element.
Can contain at most one: :ref:tmx-properties
.. _tmx-tileset-transformations:
<transformations> ~~~~~~~~~~~~~~~~~This element is used to describe which transformations can be applied to the tiles (e.g. to extend a Wang set by transforming existing tiles).
.. _tmx-tileset-tile:
<tile> ~~~~~~class in 1.9)tmx-wangtile)Can contain at most one: :ref:tmx-properties, :ref:tmx-image (since
0.9), :ref:tmx-objectgroup, :ref:tmx-animation
.. _tmx-animation:
<animation> ^^^^^^^^^^^Contains a list of animation frames.
Each tile can have exactly one animation associated with it. In the future, there could be support for multiple named animations on a tile.
Can contain any number: :ref:tmx-frame
.. _tmx-frame:
<frame> '''''''tmx-tileset... _tmx-wangsets:
<wangsets> ~~~~~~~~~~Contains the list of Wang sets defined for this tileset.
Can contain any number: :ref:tmx-wangset
.. _tmx-wangset:
<wangset> ^^^^^^^^^Defines a list of colors and any number of Wang tiles using these colors.
Can contain at most one: :ref:tmx-properties
Can contain up to 254: :ref:tmx-wangcolor (255 since Tiled 1.5, 254 since Tiled 1.10.2)
Can contain any number: :ref:tmx-wangtile
.. _tmx-wangcolor:
<wangcolor> '''''''''''A color that can be used to define the corner and/or edge of a Wang tile.
#RRGGBB format (example: #c17d11).Can contain at most one: :ref:tmx-properties
.. _tmx-wangtile:
<wangtile> ''''''''''Defines a Wang tile, by referring to a tile in the tileset and associating it with a certain Wang ID.
0xCECECECE (where each C is a corner color and each E is an edge
color, in reverse order)... _tmx-layer:
<layer> -------All :ref:tmx-tileset tags shall occur before the first :ref:tmx-layer tag
so that parsers may rely on having the tilesets before needing to resolve
tiles.
tint color <tint-color> that is multiplied with any tiles drawn by this layer in #AARRGGBB or #RRGGBB format (optional).parallax factor <parallax-factor> for this layer. Defaults to 1. (since 1.5)parallax factor <parallax-factor> for this layer. Defaults to 1. (since 1.5)normal, add, multiply, screen, overlay, darken, lighten,
color-dodge, color-burn, hard-light, soft-light,
difference and exclusion (since 1.12, defaults to normal).Can contain at most one: :ref:tmx-properties, :ref:tmx-data
.. _tmx-data:
<data> ~~~~~~This element is usually used as a child of a :ref:tmx-layer element, and
contains the actual tile layer data. It can also occur as a child of
an :ref:tmx-image element, where it can store embedded image data.
When no encoding or compression is given, the tiles are stored as individual
XML :ref:tmx-tilelayer-tile elements, but this option is deprecated. Next to
that, the easiest format to parse is the "csv" (comma separated values) format.
The base64-encoded and optionally compressed layer data is somewhat more complicated to parse. First you need to base64-decode it, then you may need to decompress it. Now you have an array of bytes, which should be interpreted as an array of unsigned 32-bit integers using little-endian byte ordering.
Whatever format you choose for your layer data, you will always end up with so
called ":doc:global-tile-ids" (gids). They are called "global", since they
may refer to a tile from any of the tilesets used by the map. The IDs also
contain :ref:flipping flags <gid-tile-flipping>. The tilesets are always
stored with increasing firstgid\ s.
Can contain any number: :ref:tmx-tilelayer-tile, :ref:tmx-chunk
.. _tmx-chunk:
<chunk> ~~~~~~~This is currently added only for infinite maps. The contents of a chunk
element is same as that of the :ref:tmx-data element, except it stores the
data of the area specified in the attributes.
Can contain any number: :ref:tmx-tilelayer-tile
.. _tmx-tilelayer-tile:
<tile> ~~~~~~Not to be confused with the :ref:tmx-tileset-tile element inside a
:ref:tmx-tileset, this element defines the value of a single tile on a tile
layer. This is however the most inefficient way of storing the tile layer data,
and should generally be avoided.
.. _tmx-objectgroup:
<objectgroup> -------------#AARRGGBB or #RRGGBB format (optional).parallax factor <parallax-factor> for this object group. Defaults to 1. (since 1.5)parallax factor <parallax-factor> for this object group. Defaults to 1. (since 1.5)The object group is in fact a map layer, and is hence called "object layer" in Tiled.
Can contain at most one: :ref:tmx-properties
Can contain any number: :ref:tmx-object
.. _tmx-object:
<object> ~~~~~~~~class in 1.9)template file <tmx-template-files>. (optional)While tile layers are very suitable for anything repetitive aligned to the tile grid, sometimes you want to annotate your map with other information, not necessarily aligned to the grid. Hence the objects have their coordinates and size in pixels, but you can still easily align that to the grid when you want to.
You generally use objects to add custom information to your tile map, such as spawn points, warps, exits, etc.
When the object has a gid set, then it is represented by the image
of the tile with that global ID. The image alignment currently depends
on the map orientation. In orthogonal orientation it's aligned to the
bottom-left while in isometric it's aligned to the bottom-center. The
image will rotate around the bottom-left or bottom-center, respectively.
When the object has a template set, it will borrow all the
properties from the specified template, properties saved with the object
will have higher priority, i.e. they will override the template
properties.
Can contain at most one: :ref:tmx-properties, :ref:tmx-ellipse (since 0.9),
:ref:tmx-capsule (since 1.12), :ref:tmx-point (since 1.1),
:ref:tmx-polygon, :ref:tmx-polyline, :ref:tmx-text (since 1.0)
.. _tmx-ellipse:
<ellipse> ~~~~~~~~~Used to mark an object as an ellipse. The existing x, y,
width and height attributes are used to determine the size of
the ellipse.
.. _tmx-capsule:
<capsule> ~~~~~~~~~Used to mark an object as a capsule. The existing x, y,
width and height attributes are used to determine the size of
the capsule.
.. _tmx-point:
<point> ~~~~~~~~~Used to mark an object as a point. The existing x and y attributes
are used to determine the position of the point.
.. _tmx-polygon:
<polygon> ~~~~~~~~~Each polygon object is made up of a space-delimited list of x,y
coordinates. The origin for these coordinates is the location of the
parent object. By default, the first point is created as 0,0
denoting that the point will originate exactly where the object is
placed.
.. _tmx-polyline:
<polyline> ~~~~~~~~~~A polyline follows the same placement definition as a polygon
object.
.. _tmx-text:
<text> ~~~~~~#AARRGGBB or #RRGGBB format
(defaults to #000000)left, center, right or justify, defaults to left)
(since Tiled 1.2.1)top
, center or bottom, defaults to top)Used to mark an object as a text object. Contains the actual text as character data.
For alignment purposes, the bottom of the text is the descender height of
the font, and the top of the text is the ascender height of the font. For
example, bottom alignment of the word "cat" will leave some space below
the text, even though it is unused for this word with most fonts. Similarly,
top alignment of the word "cat" will leave some space above the "t" with
most fonts, because this space is used for diacritics.
If the text is larger than the object's bounds, it is clipped to the bounds of the object.
.. _tmx-imagelayer:
<imagelayer> ------------parallax factor <parallax-factor> for this layer. Defaults to 1. (since 1.5)parallax factor <parallax-factor> for this layer. Defaults to 1. (since 1.5)#AARRGGBB or #RRGGBB format (optional).A layer consisting of a single image.
Can contain at most one: :ref:tmx-properties, :ref:tmx-image
.. _tmx-group:
<group> -------parallax factor <parallax-factor> for this group. Defaults to 1. (since 1.5)parallax factor <parallax-factor> for this group. Defaults to 1. (since 1.5)#AARRGGBB or #RRGGBB format (optional).A group layer, used to organize the layers of the map in a hierarchy.
Its attributes offsetx, offsety, opacity, visible and
tintcolor recursively affect child layers.
Can contain at most one: :ref:tmx-properties
Can contain any number: :ref:tmx-layer,
:ref:tmx-objectgroup, :ref:tmx-imagelayer, :ref:tmx-group
.. _tmx-properties:
<properties> ------------Wraps any number of custom properties. Can be used as a child of the
map, tileset, tile (when part of a tileset),
terrain, wangset, wangcolor, layer, objectgroup,
object, imagelayer, group and property elements.
Can contain any number: :ref:tmx-property
.. _tmx-property:
<property> ~~~~~~~~~~string (default), int,
float, bool, color, file, object or class (since
0.16, with color and file added in 0.17, object added in 1.4 and
class added in 1.8).custom property type <custom-property-types>, when applicable
(since 1.8).Boolean properties have a value of either "true" or "false".
Color properties are stored in the format #AARRGGBB.
File properties are stored as paths relative from the location of the map file.
Object properties can reference any object on the same map and are stored as an integer (the ID of the referenced object, or 0 when no object is referenced). When used on objects in the Tile Collision Editor, they can only refer to other objects on the same tile.
Class properties will have their member values stored in a nested
:ref:tmx-properties element. Only the actually set members are saved. When no
members have been set the properties element is left out entirely.
When a string property contains newlines, the current version of Tiled
will write out the value as characters contained inside the property
element rather than as the value attribute. It is possible that a
future version of the TMX format will switch to always saving property
values inside the element rather than as an attribute.
Can contain at most one: :ref:tmx-properties (since 1.8)
.. _tmx-template-files:
Templates are saved in their own file, and are referenced by
:ref:objects <tmx-object> that are template instances.
.. _tmx-template:
<template> ~~~~~~~~~~The template root element contains the saved :ref:map object <tmx-object>
and a :ref:tileset <tmx-tileset> element that points to an external
tileset, if the object is a tile object.
Example of a template file:
.. code:: xml
<?xml version="1.0" encoding="UTF-8"?>
<template>
<tileset firstgid="1" source="desert.tsx"/>
<object name="cactus" gid="31" width="81" height="101"/>
</template>
Any tileset reference should always come before the object. Embedded tilesets are not supported.
Can contain at most one: :ref:tmx-tileset
Should contain exactly one: :ref:tmx-object
.. figure:: CC-BY-SA.png :alt: Creative Commons License
Creative Commons License
The TMX Map Format by https://www.mapeditor.org is licensed under a
Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>__.