tmx格式

TMX Map Format

• Page History

The TMX (Tile Map XML) map format used by Tiled is 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.

TMX地圖格式是Tiled編輯器採用的一種靈活的基於瓦片的地圖描述格式。用它來描述的地圖有以下特點：任意數量的圖塊，任意數量的層（layer），任意數量的圖塊集（tile sets）還有附加於這些元素（elements）之上的用戶自定義屬性。除了地圖的多分層控制之外，它也提供了可以自由放置的對象組（Objects Group）。

In this document we'll go through each element found in this map format. 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 that are deprecated or unsupported by the current version of Tiled are formatted in italics.

在這篇文檔中我們將全面的瞭解TMX格式的所有元素。每個元素都將以標題的形式列出，然後是該元素支持的屬性及該屬性的一段簡要說明，當前版本的Tiled 編輯器所不支持的屬性將以斜體的形式出現在屬性列表中。

<map>

• version: The TMX format version, generally 1.0.

　　TMX格式版本號，一般爲1.0

• orientation: Map orientation. Tiled supports "orthogonal" and "isometric" at the moment.

　　地圖朝向，目前支持“正交”和“45度等距”兩種方式。

• width: The map width in tiles.

　　地圖的寬度（tile個數isometric則是斜邊的tile個數）

• height: The map height in tiles.

　　地圖的高度（tile個數）

• tilewidth: The width of a tile.

　　單Tile的寬度

• tileheight: The height of a tile.

　　單Tile的高度

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).

tilewidth與tileheight兩個屬性決定了地圖網格的大小，個別tiles允許有不同的大小，所有的Tile將靠掛在左下角，超出的部分將在頂部和右側延伸。

Can contain: properties, tileset, layer, objectgroup

可以包含下列元素：屬性，圖塊集，層，對象組

<tileset>

• firstgid: The first global tile ID of this tileset (this global ID maps to the first tile in this tileset).

　　此圖塊集的第一個圖塊在全局圖塊集中的位置。

• source: If this tileset is stored in an external TSX (Tile Set XML) file, this attribute refers to that file. That TSX file has the same structure as the attribute as described here. (There is the firstgid attribute missing and thissource attribute is also not there. These two attributes are kept in the TMX map, since they are map specific.)

　　圖像來源：如果此圖塊集來自於一個外部圖塊定義文件，此屬性的值爲該圖塊定義文件路徑。TSX文件同樣擁有相同的屬性結構。在TSX文件中沒有firstgid與source屬性，如果這個圖塊集定義文件中的圖塊在地圖中被使用，這兩個屬性將在TMX文件之中被設置。

• name: The name of this tileset.

　　圖塊集的名稱

• tilewidth: The (maximum) width of the tiles in this tileset.

　　圖塊的寬度

• tileheight: The (maximum) height of the tiles in this tileset.

　　圖塊的高度

• spacing: The spacing in pixels between the tiles in this tileset (applies to the tileset image).

　　圖塊的間距，在原圖上採樣圖塊時，圖塊與圖塊之間的間隔

• margin: The margin around the tiles in this tileset (applies to the tileset image).

　　圖塊的邊距，在原圖上採樣圖塊時，圖像左側與上方採樣的剔除邊界大小

Can contain: properties (since 0.8.0), image, tile

可以包含下列元素：屬性（自Tiled0.8.0版本）,圖像，圖塊

<image>

• format: To be used when embedding images. Deprecated and unsupported in Tiled Qt.

　　嵌入圖片時所使用的格式，TiledQT版本當前不支持此屬性。

• id: Used by some versions of Tiled Java. Deprecated and unsupported by Tiled Qt.

　　在Tiled Java的某些版本中被使用，TiledQT版本當前不支持此屬性。

• source: The reference to the tileset image file (Tiled supports most common image formats).

　　圖塊集對應圖像文件的路徑。（Tiled支持大多數常見圖像格式：bmp,gif,jpeg,jpg,pbm,pgm,png,ppm,tif,tiff,xbm,xpm）

• trans: Defines a specific color that is treated as transparent (example value: "FF00FF" for magenta).

　　定義一種用於表示半透的顏色，將原圖像中所有相同顏色值的alpha值改爲0

• width: The image width in pixels (optional, used for tile index correction when the image changes)

　　圖像的寬度

• height: The image height in pixels (optional)

　　圖像的高度

As of the current version of Tiled Qt, each tileset has a single image associated with it, which is cut into smaller tiles based on the attributes defined on the tileset element. Later versions may add support for adding multiple images to a single tileset, as is possible in Tiled Java.

當前版本的Tiled QT版本，每個圖片集與一張圖像對應，按照圖片集的屬性將該圖像切割爲多個較小的圖塊。QT後續開發計劃將在一個圖片集中支持多個圖像，如同JAVA版本的Tiled提供的功能。

<tile>

• id: The local tile ID within its tileset.

　　圖塊集內部的圖塊編號

Can contain: properties, image

可以包含下列元素：屬性,圖像

<layer>

• name: The name of the layer.

　　圖層的名稱

• x: The x coordinate of the layer in tiles. Defaults to 0 and can no longer be changed in Tiled Qt.

　　該層的X座標（單位爲圖塊）。默認爲0，該值在QT版本的Tiled編輯器中不允許修改。

• y: The y coordinate of the layer in tiles. Defaults to 0 and can no longer be changed in Tiled Qt.

　　該層的Y座標（單位爲圖塊）。默認爲0，該值在QT版本的Tiled編輯器中不允許修改。

• width: The width of the layer in tiles. Traditionally required, but as of Tiled Qt always the same as the map width.

　　該層的寬度（單位爲圖塊）。歷史版本要求存在，該值在QT版本的Tiled編輯器中與地圖的寬度相同。

• height: The height of the layer in tiles. Traditionally required, but as of Tiled Qt always the same as the map height.

　　該層的高度（單位爲圖塊）。歷史版本要求存在，該值在QT版本的Tiled編輯器中與地圖的高度相同。

• opacity: The opacity of the layer as a value from 0 to 1. Defaults to 1.

　　不透明度，範圍0~1,0爲全透，1爲不透。

• visible: Whether the layer is shown (1) or hidden (0). Defaults to 1.

　　是否可見，1可見，0不可見，默認值爲1。

Can contain: properties, data

可以包含下列元素：屬性,數據塊

<data>

• encoding: The encoding used to encode the tile layer data. When used, it can be "base64" and "csv" at the moment.

　　圖層數據的編碼方式，當前提供兩種“base64”和“csv”

　　Base64是一種通用的方法，其原理很簡單，就是把三個Byte的數據用4個Byte表示。在這四個Byte中，實際用到的都只有前面6bit，這樣就不存在只能傳輸7bit的字符的問題了。Base64的縮寫一般是“B”。

　　CSV逗號分隔值文件（COMMA Separated value）,是一種用來存儲數據的純文本文件格式。

• compression: The compression used to compress the tile layer data. Tiled Qt supports "gzip" and "zlib".

　　圖層數據的壓縮方式，QT版本的Tiled編輯器支持gzip或者zlib方式的數據壓縮。

When no encoding or compression is given, the tiles are stored as individual XML tile elements. Next to that, the easiest format to parse is the "csv" (comma separated values) format.

如果數據爲本進行編碼轉換和壓縮的情況下，圖塊數據將被作爲XML的子元素來存儲，這是最容易解析的數據格式。

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.

採用base64編碼格式的數據和壓縮過後的數據解析起來較爲複雜。首先你必須對數據進行解碼，然後你可能需要加壓縮數據。你的數據存儲於一個字節數組，你不得不將它排序爲一個little-endian字節序的無符號整形數組。

Whatever format you choose for your layer data, you will always end up with so called "global tile IDs" (gids). They are global, since they may refer to a tile from any of the tilesets used by the map. In order to find out from which tileset the tile is you need to find the tileset with the highest firstgid that is still lower or equal than the gid. The tilesets are always stored with increasing firstgids.

無論採用哪種格式存儲你的圖層數據，你都必須以所謂的gids作爲結尾。它們是全局的，自從圖塊集的任意圖塊被用於設計當前地圖。爲了能夠找到圖塊所在的圖塊集，你需要找到小於圖塊gid的最大的圖塊集的firstgid。所有圖塊集的firstgids都是按順序排列的。

When you use the tile flipping feature added in Tiled Qt 0.7.0, the highest two bits of the gid store the flipped state. Bit 32 is used for storing whether the tile is horizontally flipped and bit 31 is used for the vertically flipped tiles. And since Tiled Qt 0.8.0, bit 30 means whether the tile is flipped (anti) diagonally, enabling tile rotation. These bits have to be read and cleared before you can find out which tileset a tile belongs to.

當你使用QT版本的Tiled編輯0.7.0提供的圖塊翻轉特性時，gid的高兩位存儲的是當前圖塊的翻轉狀態。第32位用來存儲這個圖塊是否被水平翻轉，第31位用來存儲這個圖塊是否被垂直翻轉。

The following C++ pseudo-code should make it all clear:

// Bits on the far end of the 32-bit global tile ID are used for tile flags
const unsigned FLIPPED_HORIZONTALLY_FLAG = 0x80000000;
const unsigned FLIPPED_VERTICALLY_FLAG   = 0x40000000;
const unsigned FLIPPED_DIAGONALLY_FLAG   = 0x20000000;

...

// Extract the contents of the <data> element
string tile_data = ...

unsigned char *data = decompress(base64_decode(tile_data));
unsigned tile_index = 0;

// Here you should check that the data has the right size
// (map_width * map_height * 4)

for (int y = 0; y < map_height; ++y) {
  for (int x = 0; x < map_width; ++x) {
    unsigned global_tile_id = data[tile_index] |
                              data[tile_index + 1] << 8 |
                              data[tile_index + 2] << 16 |
                              data[tile_index + 3] << 24;
    tile_index += 4;

    // Read out the flags
    bool flipped_horizontally = (global_tile_id & FLIPPED_HORIZONTALLY_FLAG);
    bool flipped_vertically = (global_tile_id & FLIPPED_VERTICALLY_FLAG);
    bool flipped_diagonally = (global_tile_id & FLIPPED_DIAGONALLY_FLAG);

    // Clear the flags
    global_tile_id &= ~(FLIPPED_HORIZONTALLY_FLAG |
                        FLIPPED_VERTICALLY_FLAG |
                        FLIPPED_DIAGONALLY_FLAG);

    // Resolve the tile
    for (int i = tileset_count - 1; i >= 0; --i) {
      Tileset *tileset = tilesets[i];

      if (tileset->first_gid() <= global_tile_id) {
        tiles[y][x] = tileset->tileAt(global_tile_id - tileset->first_gid());
        break;
      }
    }
  }
}

(Since the above code was put together on this wiki page and can't be directly tested, please make sure to report any errors you encounter when basing your parsing code on it, thanks.)

由於以上代碼防止與wiki頁面，併爲沒有直接測試，所以如果您的解析過程基於上面的代碼出現問題的話，請將BUG提出來。

Can contain: tile

可以包含下列元素：圖塊

<tile>

• gid: The global tile ID.

　　圖塊的全局ID

Not to be confused with the tile element inside a 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.

不用因爲圖塊存在於圖塊集中而感到困惑，這個元素定義了可用於圖層的一個基本圖塊。這是最有效率的層數據存儲方式，通常應該避免。

<objectgroup>

• name: The name of the object group.

　　對象組的名稱。

• color: The color used to display the objects in this group.

　　當前對象組的顏色。

• x: The x coordinate of the object group in tiles. Defaults to 0 and can no longer be changed in Tiled Qt.

　　對象組的X座標。默認爲0，TiledQT版本此屬性無法修改。

• y: The y coordinate of the object group in tiles. Defaults to 0 and can no longer be changed in Tiled Qt.

　　對象組的Y座標。默認爲0，TiledQT版本此屬性無法修改。

• width: The width of the object group in tiles. Meaningless.

　　對象組的寬度，當前無意義。

• height: The height of the object group in tiles. Meaningless.

　　對象組的高度，當前無意義。

• opacity: The opacity of the layer as a value from 0 to 1. Defaults to 1.

　　對象組的圖透明度0~1，默認爲1不透。

• visible: Whether the layer is shown (1) or hidden (0). Defaults to 1.

　　對象組的可見性 1顯示 0隱藏，默認爲1。

The object group is in fact a map layer, and is hence called "object layer" in Tiled Qt.

對象組事實上就是一個圖層，因此在TiledQt版本中我們也稱之爲對象層。

Can contain: properties, object

可以包含下列元素：屬性，對象

<object>

• name: The name of the object. An arbitrary string.

　　對象名稱。字符串表示

• type: The type of the object. An arbitrary string.

　　對象類型。字符串表示

• x: The x coordinate of the object in pixels.

　　對象的X座標，單位像素

• y: The y coordinate of the object in pixels.

　　對象的Y座標，單位像素

• width: The width of the object in pixels.

　　對象的寬度，單位像素

• height: The height of the object in pixels.

　　對象的高度，單位像素

• gid: An reference to a tile (optional).

　　圖塊的索引（可選）

• visible: Whether the object is shown (1) or hidden (0). Defaults to 1.

　　可見性，1顯示0隱藏，默認爲1

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. Currently that means width and height are ignored for such objects. 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.

如果某個對象的gid屬性被設置，對象將用該ID對應的圖塊來表示，也就是說該對象的寬度和高度信息是被忽略的。圖片的對齊方式取決於當前地圖的朝向。在正交地圖中，於左下角對齊，在等距地圖中於底部中心對齊。

Can contain: properties, polygon, polyline, image

可以包含下列元素：屬性，多邊形，多段線段，圖片

<polygon>

• points: A list of x,y coordinates in pixels.

　　一系列X,Z座標點（單位像素）

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.

　　多邊形對象由一系列空格符分隔的座標點組成。這些座標點的原點是父對象的位置。默認情況下，第一個點的座標爲0,0 指示對象的存放位置。

<polyline>

• points: A list of x,y coordinates in pixels.

　　一系列X,Z座標點（單位像素）

A polyline follows the same placement definition as a polygon object.

　　規則如同多邊形。

<properties>

Can contain: property

可以包含下列元素：屬性

Wraps any number of custom properties. Can be used as a child of the map, tile (when part of a tileset), layer, objectgroup and object elements.

可以包含任意數量的自定義屬性。可以用來作爲地圖，圖塊，層，對象組，對象的子元素。

<property>

• name: The name of the property.

　　屬性名

• value: The value of the property.

　　屬性值

When the property spans contains newlines, the current versions of Tiled Java and Tiled Qt will write out the value as characters contained inside the property element rather than as the value attribute. However, it is at the moment not really possible to edit properties consisting of multiple lines with Tiled.

如果屬性值中包含換行符，當前JAVA和QT版本的Tiled編輯器的處理方法是將其包含在property元素中而非value值，當前Tiled編輯器並沒有真正意義上支持多行屬性值。

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.

也許在將在的版本中屬性值將直接存儲於元素中而非作爲一個attribute存儲。