1TMX Map Format 2============== 3 4**Version 1.5** 5 6TMX and TSX are `Tiled <http://www.mapeditor.org>`__'s own formats for storing 7tile maps and tilesets, based on XML. TMX provides a flexible way to describe a 8tile based map. It can describe maps with any tile size, any amount of 9layers, any number of tile sets and it allows custom properties to be 10set on most elements. Beside tile layers, it can also contain groups of 11objects that can be placed freely. 12 13Note that there are many :doc:`libraries and frameworks <support-for-tmx-maps>` 14available that can work with TMX maps and TSX tilesets. 15 16In this document we'll go through each element found in these file formats. 17The elements are mentioned in the headers and the list of attributes of 18the elements are listed right below, followed by a short explanation. 19Attributes or elements that are deprecated or unsupported by the current 20version of Tiled are formatted in italics. All optional attributes are 21either marked as optional, or have a default value to imply that they are 22optional. 23 24Have a look at the :doc:`changelog <tmx-changelog>` when you're interested 25in what changed between Tiled versions. 26 27.. note:: 28 29 A DTD-file (Document Type Definition) is served at 30 http://mapeditor.org/dtd/1.0/map.dtd. This file is not up-to-date but might 31 be useful for XML-namespacing anyway. 32 33.. note:: 34 35 For compatibility reasons, it is recommended to ignore unknown elements and 36 attributes (or raise a warning). This makes it easier to add features 37 without breaking backwards compatibility, and allows custom variants and 38 additions to work with existing tools. 39 40.. _tmx-map: 41 42<map> 43----- 44 45- **version:** The TMX format version. Was "1.0" so far, and will be 46 incremented to match minor Tiled releases. 47- **tiledversion:** The Tiled version used to save the file (since Tiled 48 1.0.1). May be a date (for snapshot builds). (optional) 49- **orientation:** Map orientation. Tiled supports "orthogonal", 50 "isometric", "staggered" and "hexagonal" (since 0.11). 51- **renderorder:** The order in which tiles on tile layers are rendered. 52 Valid values are ``right-down`` (the default), ``right-up``, 53 ``left-down`` and ``left-up``. In all cases, the map is drawn 54 row-by-row. (only supported for orthogonal maps at the moment) 55- **compressionlevel:** The compression level to use for tile layer data 56 (defaults to -1, which means to use the algorithm default). 57- **width:** The map width in tiles. 58- **height:** The map height in tiles. 59- **tilewidth:** The width of a tile. 60- **tileheight:** The height of a tile. 61- **hexsidelength:** Only for hexagonal maps. Determines the width or 62 height (depending on the staggered axis) of the tile's edge, in 63 pixels. 64- **staggeraxis:** For staggered and hexagonal maps, determines which axis 65 ("x" or "y") is staggered. (since 0.11) 66- **staggerindex:** For staggered and hexagonal maps, determines whether 67 the "even" or "odd" indexes along the staggered axis are shifted. 68 (since 0.11) 69- **backgroundcolor:** The background color of the map. (optional, may 70 include alpha value since 0.15 in the form ``#AARRGGBB``. Defaults to 71 fully transparent.) 72- **nextlayerid:** Stores the next available ID for new layers. This 73 number is stored to prevent reuse of the same ID after layers have 74 been removed. (since 1.2) (defaults to the highest layer id in the file 75 + 1) 76- **nextobjectid:** Stores the next available ID for new objects. This 77 number is stored to prevent reuse of the same ID after objects have 78 been removed. (since 0.11) (defaults to the highest object id in the file 79 + 1) 80- **infinite:** Whether this map is infinite. An infinite map has no fixed 81 size and can grow in all directions. Its layer data is stored in chunks. 82 (``0`` for false, ``1`` for true, defaults to 0) 83 84The ``tilewidth`` and ``tileheight`` properties determine the general 85grid size of the map. The individual tiles may have different sizes. 86Larger tiles will extend at the top and right (anchored to the bottom 87left). 88 89A map contains three different kinds of layers. Tile layers were once 90the only type, and are simply called ``layer``, object layers have the 91``objectgroup`` tag and image layers use the ``imagelayer`` tag. The 92order in which these layers appear is the order in which the layers are 93rendered by Tiled. 94 95The ``staggered`` orientation refers to an isometric map using staggered 96axes. 97 98Can contain at most one: :ref:`tmx-properties` 99 100Can contain any number: :ref:`tmx-tileset`, :ref:`tmx-layer`, 101:ref:`tmx-objectgroup`, :ref:`tmx-imagelayer`, :ref:`tmx-group` (since 1.0), 102:ref:`tmx-editorsettings` (since 1.3) 103 104.. _tmx-editorsettings: 105 106<editorsettings> 107---------------- 108 109This element contains various editor-specific settings, which are generally 110not relevant when reading a map. 111 112Can contain: :ref:`tmx-chunksize`, :ref:`tmx-export` 113 114.. _tmx-chunksize: 115 116<chunksize> 117~~~~~~~~~~~ 118 119- **width:** The width of chunks used for infinite maps (default to 16). 120- **height:** The width of chunks used for infinite maps (default to 16). 121 122.. _tmx-export: 123 124<export> 125~~~~~~~~ 126 127- **target:** The last file this map was exported to. 128- **format:** The short name of the last format this map was exported as. 129 130.. _tmx-tileset: 131 132<tileset> 133--------- 134 135- **firstgid:** The first global tile ID of this tileset (this global ID 136 maps to the first tile in this tileset). 137- **source:** If this tileset is stored in an external TSX (Tile Set XML) 138 file, this attribute refers to that file. That TSX file has the same 139 structure as the ``<tileset>`` element described here. (There is the 140 firstgid attribute missing and this source attribute is also not 141 there. These two attributes are kept in the TMX map, since they are 142 map specific.) 143- **name:** The name of this tileset. 144- **tilewidth:** The (maximum) width of the tiles in this tileset. 145- **tileheight:** The (maximum) height of the tiles in this tileset. 146- **spacing:** The spacing in pixels between the tiles in this tileset 147 (applies to the tileset image, defaults to 0) 148- **margin:** The margin around the tiles in this tileset (applies to the 149 tileset image, defaults to 0) 150- **tilecount:** The number of tiles in this tileset (since 0.13) 151- **columns:** The number of tile columns in the tileset. For image 152 collection tilesets it is editable and is used when displaying the 153 tileset. (since 0.15) 154- **objectalignment:** Controls the alignment for tile objects. 155 Valid values are ``unspecified``, ``topleft``, ``top``, ``topright``, 156 ``left``, ``center``, ``right``, ``bottomleft``, ``bottom`` and 157 ``bottomright``. The default value is ``unspecified``, for compatibility 158 reasons. When unspecified, tile objects use ``bottomleft`` in orthogonal mode 159 and ``bottom`` in isometric mode. (since 1.4) 160 161If there are multiple ``<tileset>`` elements, they are in ascending 162order of their ``firstgid`` attribute. The first tileset always has a 163``firstgid`` value of 1. Since Tiled 0.15, image collection tilesets do 164not necessarily number their tiles consecutively since gaps can occur 165when removing tiles. 166 167Image collection tilesets have no ``<image>`` tag. Instead, each tile has 168an ``<image>`` tag. 169 170Can contain at most one: :ref:`tmx-image`, :ref:`tmx-tileoffset`, 171:ref:`tmx-grid` (since 1.0), :ref:`tmx-properties`, :ref:`tmx-terraintypes`, 172:ref:`tmx-wangsets` (since 1.1), :ref:`tmx-tileset-transformations` (since 1.5) 173 174Can contain any number: :ref:`tmx-tileset-tile` 175 176.. _tmx-tileoffset: 177 178<tileoffset> 179~~~~~~~~~~~~ 180 181- **x:** Horizontal offset in pixels. (defaults to 0) 182- **y:** Vertical offset in pixels (positive is down, defaults to 0) 183 184This element is used to specify an offset in pixels, to be applied when 185drawing a tile from the related tileset. When not present, no offset is 186applied. 187 188.. _tmx-grid: 189 190<grid> 191~~~~~~ 192 193- **orientation:** Orientation of the grid for the tiles in this 194 tileset (``orthogonal`` or ``isometric``, defaults to ``orthogonal``) 195- **width:** Width of a grid cell 196- **height:** Height of a grid cell 197 198This element is only used in case of isometric orientation, and 199determines how tile overlays for terrain and collision information are 200rendered. 201 202.. _tmx-image: 203 204<image> 205~~~~~~~ 206 207- **format:** Used for embedded images, in combination with a ``data`` 208 child element. Valid values are file extensions like ``png``, 209 ``gif``, ``jpg``, ``bmp``, etc. 210- *id:* Used by some versions of Tiled Java. Deprecated and unsupported. 211- **source:** The reference to the tileset image file (Tiled supports most 212 common image formats). Only used if the image is not embedded. 213- **trans:** Defines a specific color that is treated as transparent 214 (example value: "#FF00FF" for magenta). Including the "#" is optional 215 and Tiled leaves it out for compatibility reasons. (optional) 216- **width:** The image width in pixels (optional, used for tile index 217 correction when the image changes) 218- **height:** The image height in pixels (optional) 219 220Note that it is not currently possible to use Tiled to create maps with 221embedded image data, even though the TMX format supports this. It is 222possible to create such maps using ``libtiled`` (Qt/C++) or 223`tmxlib <https://pypi.python.org/pypi/tmxlib>`__ (Python). 224 225Can contain at most one: :ref:`tmx-data` 226 227.. _tmx-terraintypes: 228 229<terraintypes> 230~~~~~~~~~~~~~~ 231 232This element defines an array of terrain types, which can be referenced 233from the ``terrain`` attribute of the ``tile`` element. 234 235Can contain any number: :ref:`tmx-terrain` 236 237.. _tmx-terrain: 238 239<terrain> 240^^^^^^^^^ 241 242- **name:** The name of the terrain type. 243- **tile:** The local tile-id of the tile that represents the terrain 244 visually. 245 246Can contain at most one: :ref:`tmx-properties` 247 248.. _tmx-tileset-transformations: 249 250<transformations> 251~~~~~~~~~~~~~~~~~ 252 253This element is used to describe which transformations can be applied to the 254tiles (e.g. to extend a Wang set by transforming existing tiles). 255 256- **hflip:** Whether the tiles in this set can be flipped horizontally (default 0) 257- **vflip:** Whether the tiles in this set can be flipped vertically (default 0) 258- **rotate:** Whether the tiles in this set can be rotated in 90 degree increments (default 0) 259- **preferuntransformed:** Whether untransformed tiles remain preferred, otherwise 260 transformed tiles are used to produce more variations (default 0) 261 262.. _tmx-tileset-tile: 263 264<tile> 265~~~~~~ 266 267- **id:** The local tile ID within its tileset. 268- **type:** The type of the tile. Refers to an object type and is used 269 by tile objects. (optional) (since 1.0) 270- **terrain:** Defines the terrain type of each corner of the tile, 271 given as comma-separated indexes in the terrain types array in the 272 order top-left, top-right, bottom-left, bottom-right. Leaving out a 273 value means that corner has no terrain. (optional) 274- **probability:** A percentage indicating the probability that this 275 tile is chosen when it competes with others while editing with the 276 terrain tool. (defaults to 0) 277 278Can contain at most one: :ref:`tmx-properties`, :ref:`tmx-image` (since 2790.9), :ref:`tmx-objectgroup`, :ref:`tmx-animation` 280 281.. _tmx-animation: 282 283<animation> 284^^^^^^^^^^^ 285 286Contains a list of animation frames. 287 288Each tile can have exactly one animation associated with it. In the 289future, there could be support for multiple named animations on a tile. 290 291Can contain any number: :ref:`tmx-frame` 292 293.. _tmx-frame: 294 295<frame> 296''''''' 297 298- **tileid:** The local ID of a tile within the parent 299 :ref:`tmx-tileset`. 300- **duration:** How long (in milliseconds) this frame should be displayed 301 before advancing to the next frame. 302 303.. _tmx-wangsets: 304 305<wangsets> 306~~~~~~~~~~ 307 308Contains the list of Wang sets defined for this tileset. 309 310Can contain any number: :ref:`tmx-wangset` 311 312.. _tmx-wangset: 313 314<wangset> 315^^^^^^^^^ 316 317Defines a list of corner colors and a list of edge colors, and any 318number of Wang tiles using these colors. 319 320- **name:** The name of the Wang set. 321- **tile:** The tile ID of the tile representing this Wang set. 322 323Can contain at most one: :ref:`tmx-properties` 324 325Can contain up to 255: :ref:`tmx-wangcolor` (since Tiled 1.5) 326 327Can contain any number: :ref:`tmx-wangtile` 328 329.. _tmx-wangcolor: 330 331<wangcolor> 332''''''''''' 333 334A color that can be used to define the corner and/or edge of a Wang tile. 335 336- **name:** The name of this color. 337- **color:** The color in ``#RRGGBB`` format (example: ``#c17d11``). 338- **tile:** The tile ID of the tile representing this color. 339- **probability:** The relative probability that this color is chosen 340 over others in case of multiple options. (defaults to 0) 341 342Can contain at most one: :ref:`tmx-properties` 343 344.. _tmx-wangtile: 345 346<wangtile> 347'''''''''' 348 349Defines a Wang tile, by referring to a tile in the tileset and 350associating it with a certain Wang ID. 351 352- **tileid:** The tile ID. 353- **wangid:** "The Wang ID, given by a comma-separated list of indexes 354 (starting from 1, because 0 means _unset_) referring to the Wang colors in 355 the Wang set in the following order: top, top right, right, bottom right, 356 bottom, bottom left, left, top left (since Tiled 1.5). Before Tiled 1.5, the 357 Wang ID was saved as a 32-bit unsigned integer stored in the format 358 ``0xCECECECE`` (where each C is a corner color and each E is an edge color, 359 in reverse order)." 360- *hflip:* Whether the tile is flipped horizontally (removed in Tiled 1.5). 361- *vflip:* Whether the tile is flipped vertically (removed in Tiled 1.5). 362- *dflip:* Whether the tile is flipped on its diagonal (removed in Tiled 1.5). 363 364.. _tmx-layer: 365 366<layer> 367------- 368 369All :ref:`tmx-tileset` tags shall occur before the first :ref:`tmx-layer` tag 370so that parsers may rely on having the tilesets before needing to resolve 371tiles. 372 373- **id:** Unique ID of the layer. Each layer that added to a map gets 374 a unique id. Even if a layer is deleted, no layer ever gets the same 375 ID. Can not be changed in Tiled. (since Tiled 1.2) 376- **name:** The name of the layer. (defaults to "") 377- *x:* The x coordinate of the layer in tiles. Defaults to 0 and can not be changed in Tiled. 378- *y:* The y coordinate of the layer in tiles. Defaults to 0 and can not be changed in Tiled. 379- **width:** The width of the layer in tiles. Always the same as the map width for fixed-size maps. 380- **height:** The height of the layer in tiles. Always the same as the map height for fixed-size maps. 381- **opacity:** The opacity of the layer as a value from 0 to 1. Defaults to 1. 382- **visible:** Whether the layer is shown (1) or hidden (0). Defaults to 1. 383- **tintcolor:** A :ref:`tint color <tint-color>` that is multiplied with any tiles drawn by this layer in ``#AARRGGBB`` or ``#RRGGBB`` format (optional). 384- **offsetx:** Horizontal offset for this layer in pixels. Defaults to 0. 385 (since 0.14) 386- **offsety:** Vertical offset for this layer in pixels. Defaults to 0. 387 (since 0.14) 388- **parallaxx:** Horizontal :ref:`parallax factor <parallax-factor>` for this layer. Defaults to 1. (since 1.5) 389- **parallaxy:** Vertical :ref:`parallax factor <parallax-factor>` for this layer. Defaults to 1. (since 1.5) 390 391Can contain at most one: :ref:`tmx-properties`, :ref:`tmx-data` 392 393.. _tmx-data: 394 395<data> 396~~~~~~ 397 398- **encoding:** The encoding used to encode the tile layer data. When used, 399 it can be "base64" and "csv" at the moment. (optional) 400- **compression:** The compression used to compress the tile layer data. 401 Tiled supports "gzip", "zlib" and (as a compile-time option since Tiled 1.3) 402 "zstd". 403 404When no encoding or compression is given, the tiles are stored as 405individual XML ``tile`` elements. Next to that, the easiest format to 406parse is the "csv" (comma separated values) format. 407 408The base64-encoded and optionally compressed layer data is somewhat more 409complicated to parse. First you need to base64-decode it, then you may 410need to decompress it. Now you have an array of bytes, which should be 411interpreted as an array of unsigned 32-bit integers using little-endian 412byte ordering. 413 414Whatever format you choose for your layer data, you will always end up 415with so called "global tile IDs" (gids). They are global, since they may 416refer to a tile from any of the tilesets used by the map. In order to 417find out from which tileset the tile is you need to find the tileset 418with the highest ``firstgid`` that is still lower or equal than the gid. 419The tilesets are always stored with increasing ``firstgid``\ s. 420 421Can contain any number: :ref:`tmx-tilelayer-tile`, :ref:`tmx-chunk` 422 423.. _tmx-tile-flipping: 424 425Tile flipping 426^^^^^^^^^^^^^ 427 428The highest three bits of the gid store the flipped states. Bit 32 is 429used for storing whether the tile is horizontally flipped, bit 31 is 430used for the vertically flipped tiles and bit 30 indicates whether the 431tile is flipped (anti) diagonally, enabling tile rotation. These bits 432have to be read and cleared before you can find out which tileset a tile 433belongs to. 434 435When rendering a tile, the order of operation matters. The diagonal flip 436(x/y axis swap) is done first, followed by the horizontal and vertical 437flips. 438 439The following C++ pseudo-code should make it all clear: 440 441.. code:: cpp 442 443 // Bits on the far end of the 32-bit global tile ID are used for tile flags 444 const unsigned FLIPPED_HORIZONTALLY_FLAG = 0x80000000; 445 const unsigned FLIPPED_VERTICALLY_FLAG = 0x40000000; 446 const unsigned FLIPPED_DIAGONALLY_FLAG = 0x20000000; 447 448 ... 449 450 // Extract the contents of the <data> element 451 string tile_data = ... 452 453 unsigned char *data = decompress(base64_decode(tile_data)); 454 unsigned tile_index = 0; 455 456 // Here you should check that the data has the right size 457 // (map_width * map_height * 4) 458 459 for (int y = 0; y < map_height; ++y) { 460 for (int x = 0; x < map_width; ++x) { 461 unsigned global_tile_id = data[tile_index] | 462 data[tile_index + 1] << 8 | 463 data[tile_index + 2] << 16 | 464 data[tile_index + 3] << 24; 465 tile_index += 4; 466 467 // Read out the flags 468 bool flipped_horizontally = (global_tile_id & FLIPPED_HORIZONTALLY_FLAG); 469 bool flipped_vertically = (global_tile_id & FLIPPED_VERTICALLY_FLAG); 470 bool flipped_diagonally = (global_tile_id & FLIPPED_DIAGONALLY_FLAG); 471 472 // Clear the flags 473 global_tile_id &= ~(FLIPPED_HORIZONTALLY_FLAG | 474 FLIPPED_VERTICALLY_FLAG | 475 FLIPPED_DIAGONALLY_FLAG); 476 477 // Resolve the tile 478 for (int i = tileset_count - 1; i >= 0; --i) { 479 Tileset *tileset = tilesets[i]; 480 481 if (tileset->first_gid() <= global_tile_id) { 482 tiles[y][x] = tileset->tileAt(global_tile_id - tileset->first_gid()); 483 break; 484 } 485 } 486 } 487 } 488 489(Since the above code was put together on this wiki page and can't be 490directly tested, please make sure to report any errors you encounter 491when basing your parsing code on it, thanks.) 492 493.. _tmx-chunk: 494 495<chunk> 496~~~~~~~ 497 498- **x:** The x coordinate of the chunk in tiles. 499- **y:** The y coordinate of the chunk in tiles. 500- **width:** The width of the chunk in tiles. 501- **height:** The height of the chunk in tiles. 502 503This is currently added only for infinite maps. The contents of a chunk 504element is same as that of the ``data`` element, except it stores the 505data of the area specified in the attributes. 506 507Can contain any number: :ref:`tmx-tilelayer-tile` 508 509.. _tmx-tilelayer-tile: 510 511<tile> 512~~~~~~ 513 514- **gid:** The global tile ID (default: 0). 515 516Not to be confused with the ``tile`` element inside a ``tileset``, this 517element defines the value of a single tile on a tile layer. This is 518however the most inefficient way of storing the tile layer data, and 519should generally be avoided. 520 521.. _tmx-objectgroup: 522 523<objectgroup> 524------------- 525 526- **id:** Unique ID of the layer. Each layer that added to a map gets 527 a unique id. Even if a layer is deleted, no layer ever gets the same 528 ID. Can not be changed in Tiled. (since Tiled 1.2) 529- **name:** The name of the object group. (defaults to "") 530- **color:** The color used to display the objects in this group. (defaults 531 to gray ("#a0a0a4")) 532- *x:* The x coordinate of the object group in tiles. Defaults to 0 and 533 can no longer be changed in Tiled. 534- *y:* The y coordinate of the object group in tiles. Defaults to 0 and 535 can no longer be changed in Tiled. 536- *width:* The width of the object group in tiles. Meaningless. 537- *height:* The height of the object group in tiles. Meaningless. 538- **opacity:** The opacity of the layer as a value from 0 to 1. (defaults to 539 1) 540- **visible:** Whether the layer is shown (1) or hidden (0). (defaults to 1) 541- **tintcolor:** A color that is multiplied with any tile objects drawn by this layer, in ``#AARRGGBB`` or ``#RRGGBB`` format (optional). 542- **offsetx:** Horizontal offset for this object group in pixels. (defaults 543 to 0) (since 0.14) 544- **offsety:** Vertical offset for this object group in pixels. (defaults 545 to 0) (since 0.14) 546- **draworder:** Whether the objects are drawn according to the order of 547 appearance ("index") or sorted by their y-coordinate ("topdown"). 548 (defaults to "topdown") 549 550The object group is in fact a map layer, and is hence called "object 551layer" in Tiled. 552 553Can contain at most one: :ref:`tmx-properties` 554 555Can contain any number: :ref:`tmx-object` 556 557.. _tmx-object: 558 559<object> 560~~~~~~~~ 561 562- **id:** Unique ID of the object. Each object that is placed on a map gets 563 a unique id. Even if an object was deleted, no object gets the same 564 ID. Can not be changed in Tiled. (since Tiled 0.11) 565- **name:** The name of the object. An arbitrary string. (defaults to "") 566- **type:** The type of the object. An arbitrary string. (defaults to "") 567- **x:** The x coordinate of the object in pixels. (defaults to 0) 568- **y:** The y coordinate of the object in pixels. (defaults to 0) 569- **width:** The width of the object in pixels. (defaults to 0) 570- **height:** The height of the object in pixels. (defaults to 0) 571- **rotation:** The rotation of the object in degrees clockwise around (x, y). 572 (defaults to 0) 573- **gid:** A reference to a tile. (optional) 574- **visible:** Whether the object is shown (1) or hidden (0). (defaults to 575 1) 576- **template:** A reference to a :ref:`template file <tmx-template-files>`. (optional) 577 578While tile layers are very suitable for anything repetitive aligned to 579the tile grid, sometimes you want to annotate your map with other 580information, not necessarily aligned to the grid. Hence the objects have 581their coordinates and size in pixels, but you can still easily align 582that to the grid when you want to. 583 584You generally use objects to add custom information to your tile map, 585such as spawn points, warps, exits, etc. 586 587When the object has a ``gid`` set, then it is represented by the image 588of the tile with that global ID. The image alignment currently depends 589on the map orientation. In orthogonal orientation it's aligned to the 590bottom-left while in isometric it's aligned to the bottom-center. The 591image will rotate around the bottom-left or bottom-center, respectively. 592 593When the object has a ``template`` set, it will borrow all the 594properties from the specified template, properties saved with the object 595will have higher priority, i.e. they will override the template 596properties. 597 598Can contain at most one: :ref:`tmx-properties`, :ref:`tmx-ellipse` (since 5990.9), :ref:`tmx-point` (since 1.1), :ref:`tmx-polygon`, :ref:`tmx-polyline`, 600:ref:`tmx-text` (since 1.0) 601 602.. _tmx-ellipse: 603 604<ellipse> 605~~~~~~~~~ 606 607Used to mark an object as an ellipse. The existing ``x``, ``y``, 608``width`` and ``height`` attributes are used to determine the size of 609the ellipse. 610 611.. _tmx-point: 612 613<point> 614~~~~~~~~~ 615 616Used to mark an object as a point. The existing ``x`` and ``y`` attributes 617are used to determine the position of the point. 618 619.. _tmx-polygon: 620 621<polygon> 622~~~~~~~~~ 623 624- **points:** A list of x,y coordinates in pixels. 625 626Each ``polygon`` object is made up of a space-delimited list of x,y 627coordinates. The origin for these coordinates is the location of the 628parent ``object``. By default, the first point is created as 0,0 629denoting that the point will originate exactly where the ``object`` is 630placed. 631 632.. _tmx-polyline: 633 634<polyline> 635~~~~~~~~~~ 636 637- **points:** A list of x,y coordinates in pixels. 638 639A ``polyline`` follows the same placement definition as a ``polygon`` 640object. 641 642.. _tmx-text: 643 644<text> 645~~~~~~ 646 647- **fontfamily:** The font family used (defaults to "sans-serif") 648- **pixelsize:** The size of the font in pixels (not using points, 649 because other sizes in the TMX format are also using pixels) 650 (defaults to 16) 651- **wrap:** Whether word wrapping is enabled (1) or disabled (0). 652 (defaults to 0) 653- **color:** Color of the text in ``#AARRGGBB`` or ``#RRGGBB`` format 654 (defaults to #000000) 655- **bold:** Whether the font is bold (1) or not (0). (defaults to 0) 656- **italic:** Whether the font is italic (1) or not (0). (defaults to 0) 657- **underline:** Whether a line should be drawn below the text (1) or 658 not (0). (defaults to 0) 659- **strikeout:** Whether a line should be drawn through the text (1) or 660 not (0). (defaults to 0) 661- **kerning:** Whether kerning should be used while rendering the text 662 (1) or not (0). (defaults to 1) 663- **halign:** Horizontal alignment of the text within the object 664 (``left``, ``center``, ``right`` or ``justify``, defaults to ``left``) 665 (since Tiled 1.2.1) 666- **valign:** Vertical alignment of the text within the object (``top`` 667 , ``center`` or ``bottom``, defaults to ``top``) 668 669Used to mark an object as a text object. Contains the actual text as 670character data. 671 672For alignment purposes, the bottom of the text is the descender height of 673the font, and the top of the text is the ascender height of the font. For 674example, ``bottom`` alignment of the word "cat" will leave some space below 675the text, even though it is unused for this word with most fonts. Similarly, 676``top`` alignment of the word "cat" will leave some space above the "t" with 677most fonts, because this space is used for diacritics. 678 679If the text is larger than the object's bounds, it is clipped to the bounds 680of the object. 681 682.. _tmx-imagelayer: 683 684<imagelayer> 685------------ 686 687- **id:** Unique ID of the layer. Each layer that added to a map gets 688 a unique id. Even if a layer is deleted, no layer ever gets the same 689 ID. Can not be changed in Tiled. (since Tiled 1.2) 690- **name:** The name of the image layer. (defaults to "") 691- **offsetx:** Horizontal offset of the image layer in pixels. (defaults to 692 0) (since 0.15) 693- **offsety:** Vertical offset of the image layer in pixels. (defaults to 694 0) (since 0.15) 695- *x:* The x position of the image layer in pixels. (defaults to 0, deprecated 696 since 0.15) 697- *y:* The y position of the image layer in pixels. (defaults to 0, deprecated 698 since 0.15) 699- **opacity:** The opacity of the layer as a value from 0 to 1. (defaults to 700 1) 701- **visible:** Whether the layer is shown (1) or hidden (0). (defaults to 1) 702- **tintcolor:** A color that is multiplied with the image drawn by this layer in ``#AARRGGBB`` or ``#RRGGBB`` format (optional). 703 704A layer consisting of a single image. 705 706Can contain at most one: :ref:`tmx-properties`, :ref:`tmx-image` 707 708.. _tmx-group: 709 710<group> 711------- 712 713- **id:** Unique ID of the layer. Each layer that added to a map gets 714 a unique id. Even if a layer is deleted, no layer ever gets the same 715 ID. Can not be changed in Tiled. (since Tiled 1.2) 716- **name:** The name of the group layer. (defaults to "") 717- **offsetx:** Horizontal offset of the group layer in pixels. (defaults to 718 0) 719- **offsety:** Vertical offset of the group layer in pixels. (defaults to 720 0) 721- **opacity:** The opacity of the layer as a value from 0 to 1. (defaults to 722 1) 723- **visible:** Whether the layer is shown (1) or hidden (0). (defaults to 1) 724- **tintcolor:** A color that is multiplied with any graphics drawn by any child layers, in ``#AARRGGBB`` or ``#RRGGBB`` format (optional). 725 726A group layer, used to organize the layers of the map in a hierarchy. 727Its attributes ``offsetx``, ``offsety``, ``opacity``, ``visible`` and 728``tintcolor`` recursively affect child layers. 729 730Can contain at most one: :ref:`tmx-properties` 731 732Can contain any number: :ref:`tmx-layer`, 733:ref:`tmx-objectgroup`, :ref:`tmx-imagelayer`, :ref:`tmx-group` 734 735.. _tmx-properties: 736 737<properties> 738------------ 739 740Wraps any number of custom properties. Can be used as a child of the 741``map``, ``tileset``, ``tile`` (when part of a ``tileset``), 742``terrain``, ``wangset``, ``wangcolor``, ``layer``, ``objectgroup``, 743``object``, ``imagelayer`` and ``group`` elements. 744 745Can contain any number: :ref:`tmx-property` 746 747.. _tmx-property: 748 749<property> 750~~~~~~~~~~ 751 752- **name:** The name of the property. 753- **type:** The type of the property. Can be ``string`` (default), ``int``, 754 ``float``, ``bool``, ``color``, ``file`` or ``object`` (since 0.16, with 755 ``color`` and ``file`` added in 0.17, and ``object`` added in 1.4). 756- **value:** The value of the property. (default string is "", default 757 number is 0, default boolean is "false", default color is #00000000, default 758 file is "." (the current file's parent directory)) 759 760Boolean properties have a value of either "true" or "false". 761 762Color properties are stored in the format ``#AARRGGBB``. 763 764File properties are stored as paths relative from the location of the 765map file. 766 767Object properties can reference any object on the same map and are stored as an 768integer (the ID of the referenced object, or 0 when no object is referenced). 769When used on objects in the Tile Collision Editor, they can only refer to 770other objects on the same tile. 771 772When a string property contains newlines, the current version of Tiled 773will write out the value as characters contained inside the ``property`` 774element rather than as the ``value`` attribute. It is possible that a 775future version of the TMX format will switch to always saving property 776values inside the element rather than as an attribute. 777 778.. _tmx-template-files: 779 780Template Files 781-------------- 782 783Templates are saved in their own file, and are referenced by 784:ref:`objects <tmx-object>` that are template instances. 785 786.. _tmx-template: 787 788<template> 789~~~~~~~~~~ 790 791The template root element contains the saved :ref:`map object <tmx-object>` 792and a :ref:`tileset <tmx-tileset>` element that points to an external 793tileset, if the object is a tile object. 794 795Example of a template file: 796 797 .. code:: xml 798 799 <?xml version="1.0" encoding="UTF-8"?> 800 <template> 801 <tileset firstgid="1" source="desert.tsx"/> 802 <object name="cactus" gid="31" width="81" height="101"/> 803 </template> 804 805Can contain at most one: :ref:`tmx-tileset`, :ref:`tmx-object` 806 807-------------- 808 809.. figure:: CC-BY-SA.png 810 :alt: Creative Commons License 811 812 Creative Commons License 813 814The **TMX Map Format** by https://www.mapeditor.org is licensed under a 815`Creative Commons Attribution-ShareAlike 3.0 Unported 816License <http://creativecommons.org/licenses/by-sa/3.0/>`__. 817
