Tiled TMX 地图格式完全指南:从 XML 结构到 GID 底层原理
Tiled TMX 地图格式完全指南:从 XML 结构到 GID 底层原理
TMX(Tile Map XML)是 Tiled 编辑器自身的原生地图格式,基于 XML,用于存储瓦片地图与图块集(TSX)。它以任意瓦片尺寸、任意图层数量、任意图块集组合以及丰富的自定义属性著称。本篇指南以 Tiled 官方《TMX Map Format》参考文档为核心,结合本仓库 src/libtiled 的读写器源码与 examples 下的真实地图文件,逐元素拆解 TMX 格式规范,帮助你掌握从手动阅读/校验 .tmx 文件到自行实现解析器的完整能力。
本文涉及的格式为 Version 1.8(对应 map version="1.8"),文档中凡以斜体标注的属性均表示已弃用(deprecated)或当前版本不再支持。
阅读规范与兼容性准则
在逐元素展开之前,先明确三条贯穿全文的读写规则:
- 兼容性优先:解析 TMX 文件时,建议忽略未知元素与未知属性(或至少给出警告)。Tiled 官方在文档中明确建议这样做,因为它允许在不破坏向后兼容的前提下持续增加新特性,也让基于 TMX 的第三方工具和自定义变体可以继续工作。这一点在源码中得到印证——
MapReaderPrivate::readUnknownElement()会安全跳过未知节点(见 src/libtiled/mapreader.cpp)。 - 可选的判定:文档中所有可选属性要么被显式标记为
optional,要么带有默认值。带有默认值的属性,缺省时即采用默认值。 - 弃用标记:格式中的历史遗留元素(如
<terraintypes>、<terrain>、图层的x/y坐标属性)均以斜体标注,新版文件不再写出这些内容,解析器遇到时应宽容处理。
<map> 是 TMX 文件的根元素,直接子元素中至多包含一个 <properties> 和一个 <editorsettings>(Tiled 1.3 起),可以包含任意数量的 <tileset>、<layer>、<objectgroup>、<imagelayer> 和 <group>(Tiled 1.0 起)。
根元素属性一览
| 属性 | 说明 | 默认值/约束 |
|---|---|---|
version |
TMX 格式版本,目前为 "1.0",未来会随 Tiled 小版本递增 | 必填 |
tiledversion |
保存该文件所用的 Tiled 版本(1.0.1 起),快照版可能是日期 | 可选 |
class |
地图的类名(1.9 起) | "" |
orientation |
地图朝向:orthogonal、isometric、oblique、staggered、hexagonal(0.11 起) |
必填 |
renderorder |
瓦片图层渲染顺序:right-down(默认)、right-up、left-down、left-up,逐行绘制 |
仅正交地图支持 |
compressionlevel |
瓦片图层数据的压缩级别,-1 表示使用算法默认值 | -1 |
width / height |
地图宽/高(瓦片数) | 必填 |
tilewidth / tileheight |
单个瓦片的宽/高(像素) | 必填 |
skewx / skewy |
oblique 地图中每行/每列的像素偏移 | 可选 |
hexsidelength |
仅六边形地图:瓦片边缘的像素长度(取决于 staggeraxis) | 可选 |
staggeraxis |
staggered/hexagonal 地图的错位轴:x 或 y(0.11 起) |
可选 |
staggerindex |
错位轴上的偏移索引是 even 还是 odd(0.11 起) |
可选 |
parallaxoriginx / parallaxoriginy |
视差原点坐标(像素,1.8 起) | 0 |
backgroundcolor |
地图背景色;0.15 起支持 #AARRGGBB 含 alpha |
默认全透明 |
nextlayerid |
下一个可用图层 ID(1.2 起),防止图层删除后 ID 复用 | 文件中最大图层 ID + 1 |
nextobjectid |
下一个可用对象 ID(0.11 起),防止对象删除后 ID 复用 | 文件中最大对象 ID + 1 |
infinite |
是否为无限地图(0/1),无限地图无固定尺寸,图层数据按 chunk 存储 |
0 |
tilewidth 与 tileheight 决定地图的通用网格尺寸,但单个瓦片可以有不同的实际尺寸——更大的瓦片会向上和向右延伸(锚定在左下角)。
在源码层面,mapreader.cpp 完整印证了这些属性的解析:orientation 通过 orientationFromString() 转换(无法识别的朝向会直接报 "Unsupported map orientation" 错误),skewx/skewy 通过 toInt(&ok) 判断后写入 Map::Parameters,parallaxoriginx/y 则按 qreal 解析,backgroundcolor 仅在 QColor::isValidColor() 通过时才采用。对应的枚举定义位于 map.h。
三种图层类型
地图内包含三种不同类型的图层:
- 瓦片图层
<layer>:最初唯一存在的图层类型; - 对象图层
<objectgroup>:放置自由对象; - 图像图层
<imagelayer>:单张图片组成的图层。
这些图层在文件中出现的顺序,就是 Tiled 渲染它们的顺序。另外需要注意,地图用到的所有 <tileset> 必须出现在图层之前,这样解析器在解析瓦片之前就能拿到图块集信息。
一个真实的
以仓库自带的 examples/orthogonal-outside.tmx 为例:
<?xml version="1.0" encoding="UTF-8"?>
<map version="1.8" tiledversion="1.8.5" orientation="orthogonal" renderorder="right-down"
width="45" height="31" tilewidth="16" tileheight="16" infinite="0"
nextlayerid="4" nextobjectid="38">
<properties>
<property name="enemyTint" type="color" value="#ffa33636"/>
</properties>
<tileset firstgid="1" name="outdoor" tilewidth="16" tileheight="16" tilecount="288" columns="24">
<image source="buch-outdoor.png" width="384" height="192"/>
...
</tileset>
<layer id="1" name="Ground" width="45" height="31">
<data encoding="base64" compression="zlib">
eJyNWE1vvVUU3Y0KQeXL4kBL7QAiEkcopQOIkjgysXagYeLIpE0HGucEtY5U6giw1Bj8AdiWxhZ+ANLS4nv+AJKW1+TVH9DklWfSR+LeeWt51j3eWxmsnPvuPR9rr7P3vvu8hpkd7DFb8dYb24Pf89bFtOOio8/xquNreZ/jdccxx0nH53j+SN7F81nHOfz+BGs1vP0C706i/1kZ+6asMWRdrvMY+4q3bzmedTwj/FfAO/i2HVcc10s4f+t4QzidcEw6vnd8lz0HfrAu3wOO8xj3seO44AT6cY0GONPWTx1jjp8cvzjO4Fsbfan/luP3XXgrJ+4XtWnjeQX9VzBmErgsdud8lXdwCb94G5w3HE+g+R5ZcwDPDx114U3dY569wkW5UZ8J8I6+AfalPbT7MvhS03nMMV3CNzT+A5zHMt70obvezjrWwfue47HwynUhH3JivwG01E1Be0cs8eW3mOd9x2lwXHVsOx7AP8bgI/PCZ5+PmwHvHceSaK76UZO2cGyg1X2mT/eKrtOwUX2Le/RcicbB4zfHyz6239sPs3VijtB6E33XRPPr0CbXmpwaAvrEPPyBvsDvOn4IbQ+4jkHnDaxfE52POl6zFIe0n1oH12Vw37Hq2HzH8W5o6DgE9FrRn+l7uk8rVvSZi6LvDdF4GaBPU2edS32kDjub1vWrMt6Mq8gJkc/OwQbypq9T54jrKcfVkrl+Fq5ctwn9/hTOZefIgPC+7VhEW9tFb+bwyL2Rw3le5DHGeVuY6xrma0DPJtpYL+Ip/JT+TM7uT9/k649jji3MEWMO+5gF2Py4hLOel8y/A1bMKdRbeW8K99BkzlIOmMVe37GuL2u+y/PYCNbbAkfGwCo0vyX9cq0nwbcsXnP/e97xAjADzutoQ6def3+kJ2lMnCmZL/wl/C7y87bsTXDuOB5Bt//jpbgiflBlQwe6am4bE40Dw6J1PscW9inmiJhlvvzVcaAn7fnT8JyC/ZG77u/SX3Nx8CPnQNRxl6xY05XZPYN5HoBv+F+VL49kccF9on9GG757q2J84KXMD0bBrw/+EHt7yro5umqOh7IW1330FHtNvkvQdg72co8GKtajnn2ib+QJ1p7T2XMgzlDPI//mv+C8Db5NWVO/MeangB/Bt4Y9CnuXs7FVIEfWofy9d5cxPF8mRKtNaDQLvxiy5O/xvgMteQ5si7Y1PLdkf8owjvW+hIan7L85gnXJRLd/wQ+ZD+jPjOU1K9ao1JLfeWatgfdtvGcNsBtnzjcu+/+VdWMubNA6i3lNx9MWahl7qvUHa1RqS79pWjord9C/hedFjLsKaByQ72KJLax1437GmqZX+OV2Mz+FP9y0dI52wKuFd3y/CH3Zh1qz1f7x7n62X/USHm3ggqU7pdYyeZ57EedTxI3W1XXw25T1a+DFs4vn/Bz4d7BHm5bOOe4XvzdLeBBRO0YdwzszeYevjFvymYg1xiv1qFvKtx1o17QUi1EXMHYOgfsR8G9Z8hXWiZyrjvFVnFl/kfOxjDdrmeAZeeuapTOce8x6gHquAVEv6jnL51VozH6shdbAn3VnrBvxdtCS7/LdeUv/NUQNxntlG7ypK/dxHWuw/tbzlTVIrMlaKu4Zeu4egm30I+a/WbTL+KaaHoeWh8GX+sZ/I1HnDlixFr9nqY5dtFQztjK+vMurbsH7hqU7J/X+GxyXMGcNWJI9oy9csOJ/PKEr/0cJe96Dvjdl/3g/2ZZ1uH9/Wbe2GnR8AC7Rb8dSPOV2jaIfc7ae6ew7akX/nQRP+kC8j/OO98vgvA95Yj/q2v2SK7Sm5fx5rC2gT/R/YsXacRT7EeMXLMVdcNa4rYrByMd6B676j44+3QFn1U7jTLkzz6nGw/I93m9Yyot5HcdzhPkrELkrYjD8mnGZc2a9pnUO+Q5mPEO/fivG21Grtktty+8eqjM58b873tk+s25c6t0+cNdS/cAYv1Oxfhn6pB20oh+dzvoOZ/b+A6OnAUo=
</data>
</layer>
...
</map>
注意其中两个细节:nextlayerid="4"(当前最大图层 id 为 3)与 nextobjectid="38",这正是防止 ID 复用的机制;<property name="enemyTint" type="color" value="#ffa33636"/> 展示了 #AARRGGBB 格式的颜色属性。
编辑器设置
<editorsettings> 用于保存编辑器相关的设置,读取地图时一般无需关注。它至多包含一个 <chunksize> 与一个 <export>。
<chunksize>:无限地图使用的 chunk 尺寸,width与height均默认 16。源码 readMapEditorSettings() 会读取这两个属性并写入 map;<export>:记录最近一次导出目标,target为导出的目标文件,format为导出格式的短名称。
图块集
<tileset> 定义了地图使用的图块集,其属性如下:
| 属性 | 说明 | 默认值/约束 |
|---|---|---|
firstgid |
该图块集的第一个全局瓦片 ID,即本图块集第 0 号瓦片对应的 GID | 必填 |
source |
若图块集存放在外部 TSX 文件中,这里指向该文件 | 可选 |
name |
图块集名称 | 必填 |
class |
图块集的类名(1.9 起) | "" |
tilewidth / tileheight |
瓦片宽/高;图像集合型图块集中存储最大瓦片尺寸 | 至少为 1 |
spacing |
图块集图片中瓦片之间的像素间距(仅对单图图块集有效) | 0 |
margin |
图块集图片边缘的留白像素(仅对单图图块集有效) | 0 |
tilecount |
图块集中的瓦片数量(0.13 起)。图像集合型图块集删除瓦片后,可能出现高于 tilecount 的瓦片 ID | 可选 |
columns |
图块集的列数;图像集合型图块集可编辑,用于展示 | 可选 |
objectalignment |
瓦片对象的对齐方式:unspecified、topleft、top、topright、left、center、right、bottomleft、bottom、bottomright(1.4 起)。unspecified 时,正交地图用 bottomleft,等距地图用 bottom |
unspecified |
tilerendersize |
在瓦片图层上渲染本图块集瓦片的尺寸:tile(默认)或 grid。设为 grid 时按地图网格尺寸绘制(1.9 起) |
tile |
fillmode |
渲染缩放时的填充模式:stretch(默认)或 preserve-aspect-fit;仅在瓦片非原生尺寸渲染时生效,如缩放后的瓦片对象或 tilerendersize="grid" 组合(1.9 起) |
stretch |
图块集有两种形态:
- 单图图块集:基于一张大图,按
tilewidth/tileheight、spacing、margin参数切割成瓦片,只含一个<image>子元素; - 图像集合图块集:每个瓦片(
<tile>)各自定义一个<image>。
当存在多个 <tileset> 时,它们按照 firstgid 升序排列,第一个图块集的 firstgid 恒为 1。Tiled 0.15 起,图像集合图块集的瓦片 ID 允许不连续(删除瓦片产生空隙)。
<tileset> 至多包含一个 <image>、<tileoffset>、<grid>(1.0 起)、<properties>、<terraintypes>、<wangsets>(1.1 起)、<transformations>(1.5 起),可包含任意数量的 <tile>。
瓦片偏移
x:水平偏移像素(默认 0);y:垂直偏移像素(正方向为下,默认 0)。
用于绘制该图块集瓦片时的像素偏移,缺省即不偏移。
网格
orientation:网格朝向:orthogonal或isometric(默认orthogonal);width/height:网格单元格宽高。
该元素仅在等距朝向时使用,决定地形与碰撞信息叠加层(tile overlays)的渲染方式。
图片
| 属性 | 说明 |
|---|---|
format |
用于内嵌图片(配合子元素 <data>),取值如 png、gif、jpg、bmp 等 |
id |
已弃用且不受支持(Tiled Java 某些版本使用) |
source |
图片文件引用,Tiled 支持大多数常见图片格式;仅在图片非内嵌时使用 |
trans |
指定被当作透明的颜色(如 #FF00FF 表示洋红)。# 可选,Tiled 出于兼容性通常省略 |
width / height |
图片像素尺寸(可选,用于图片变化时的瓦片索引校正) |
Tiled 地图或图块集中内嵌图片数据,目前只能通过 JavaScript API 或基于 libtiled(Qt/C++)的自定义工具创建。
变换能力(Tiled 1.5 起)
描述该图块集中的瓦片允许被应用哪些变换(例如通过变换已有瓦片来扩展 Wang 集):
hflip:可否水平翻转(默认 0);vflip:可否垂直翻转(默认 0);rotate:可否按 90 度增量旋转(默认 0);preferuntransformed:是否优先保留未变换瓦片,否则使用变换瓦片产生更多变体(默认 0)。
(图块集内的瓦片定义)
id:图块集内的本地瓦片 ID;type:瓦片的类(1.0 起,默认"",1.9 中曾以class保存);terrain:已弃用(1.5 起),以逗号分隔的 4 个地形类型索引(顺序为左上、右上、左下、右下),缺省值表示该角无地形;probability:使用地形工具编辑时该瓦片被选中的概率百分比(默认 1);x/y:瓦片子矩形的位置(默认 0);width/height:瓦片子矩形的尺寸(默认图片尺寸)。
至多包含一个 <properties>、<image>(0.9 起)、<objectgroup>、<animation>。
与 动画
每个瓦片至多关联一个动画。<animation> 包含任意数量的 <frame>:
frame.tileid:父图块集中的本地瓦片 ID;frame.duration:该帧显示时长(毫秒)。
与 (已弃用)
<terraintypes> 自 Tiled 1.5 起被弃用,由更灵活的 <wangsets> 取代;包含地形类型的图块集在保存时会被自动转换为 Wang 集。<terrain> 定义单个地形类型:name 为名称,tile 为视觉上代表该地形的本地瓦片 ID。
/ / /
Wang 集是 Tiled 1.1 引入、用于自动拼接地形/边缘的系统:
<wangsets>是 Wang 集的列表容器;<wangset>属性:name(名称)、class(类,1.9 起,默认"")、tile(代表该 Wang 集的瓦片 ID)。至多一个<properties>,至多 254 个<wangcolor>(Tiled 1.5 起为 255,1.10.2 起回退为 254),任意数量<wangtile>;<wangcolor>属性:name、class(1.9 起)、color(#RRGGBB格式,如#c17d11)、tile(代表该颜色的瓦片 ID)、probability(多个候选时该颜色被选中的相对概率,默认 1);<wangtile>属性:tileid(瓦片 ID)、wangid(Wang ID)、hflip/vflip/dflip(已在 1.5 移除)。
wangid 自 Tiled 1.5 起为逗号分隔的 8 个索引(0-254),顺序为:上、右上、右、右下、下、左下、左、左上;索引 0 表示 unset(未设置),索引 1 指向第一个 Wang 颜色。1.5 之前,Wang ID 以 32 位无符号整数保存,格式为 0xCECECECE(每个 C 是角颜色、每个 E 是边颜色,逆序存储)。
仓库示例 examples/orthogonal-outside.tmx 中有一段完整的 corner 类型 Wang 集("Terrains",含 Grass/Dirt/Dark Dirt/Water 四种颜色,以及从 tileid="0" wangid="0,1,0,2,0,1,0,1" 开始的数百个 Wang 瓦片映射),是理解 wangid 各索引含义的最佳真实样本。
瓦片图层
所有 <tileset> 标签必须出现在第一个 <layer> 之前,这样解析器解析瓦片时已具备全部图块集信息。
| 属性 | 说明 | 默认值 |
|---|---|---|
id |
图层唯一 ID(1.2 起),至少为 1。每个添加到地图的图层都会获得唯一 ID,图层删除后 ID 不再复用,且不能在 Tiled 中修改 | 0 |
name |
图层名称 | "" |
class |
图层类名(1.9 起) | "" |
x / y |
图层的瓦片坐标,默认 0,无法在 Tiled 中修改 | 0 |
width / height |
图层的瓦片宽高;固定尺寸地图中始终等于地图宽高 | — |
opacity |
图层不透明度,0 到 1 | 1 |
visible |
是否显示(1/0) | 1 |
tintcolor |
与图层绘制内容相乘的着色颜色,#AARRGGBB 或 #RRGGBB 格式 |
可选 |
offsetx / offsety |
图层像素偏移(0.14 起) | 0 |
parallaxx / parallaxy |
图层视差系数(1.5 起) | 1 |
mode |
图层混合模式:normal、add、multiply、screen、overlay、darken、lighten、color-dodge、color-burn、hard-light、soft-light、difference、exclusion(1.12 起) |
normal |
至多包含一个 <properties> 与一个 <data>。
图层数据
<data> 通常作为 <layer> 的子元素,存储实际的瓦片数据;它也可以作为 <image> 的子元素存储内嵌图片数据。
| 属性 | 说明 |
|---|---|
encoding |
数据编码方式:base64,瓦片图层数据还可为 csv |
compression |
数据压缩方式:gzip、zlib,以及(Tiled 1.3 起作为编译期选项的)zstd |
三种存储方式:
- 无 encoding/compression:瓦片以独立的 XML
<tile>元素逐个存储——文档明确标注此方式已弃用,且是效率最低的存储方式,应尽量避免; - CSV:逗号分隔值格式,最容易解析;
- Base64(可压缩):解析相对复杂——先 base64 解码,再视情况解压,得到的字节数组需按小端字节序解释为无符号 32 位整数数组。
无论哪种格式,最终得到的都是所谓 Global Tile IDs(GID)。它们称为"全局"是因为可能引用地图中任意图块集的瓦片,同时 GID 中还包含翻转标志位(详见下文 GID 与翻转标志)。图块集总是按 firstgid 递增存储。
源码 readTileLayerData() 精确实现了这一分支逻辑:无 encoding → Map::XML;csv → Map::CSV;base64 无压缩 → Map::Base64;配合 gzip/zlib/zstd → Map::Base64Gzip / Map::Base64Zlib / Map::Base64Zstandard。对应的枚举定义在 map.h,而 Tiled 默认以 Base64Zlib 写出(见 mapwriter.cpp)。写入端逻辑在 mapwriter.cpp:Base64* 系列一律写 encoding="base64",CSV 写 encoding="csv"。
无限地图数据块
<chunk> 目前仅用于无限地图:
x/y:chunk 的瓦片坐标;width/height:chunk 的瓦片宽高。
chunk 的内容与 <data> 相同,只是只包含其属性指定区域的瓦片数据。源码中 readTileLayerRect() 递归处理 chunk——遇到 <chunk> 子元素时读取其坐标与尺寸,再递归调用自身读取该区块(QRect(x, y, width, height))。
(图层瓦片)
gid:全局瓦片 ID(默认 0,表示空格子)。
不要与图块集内的 <tile> 混淆:图层中的 <tile> 定义的是瓦片图层上单个格子的值,是效率最低的存储方式,应避免使用。
对象图层
对象图层本质上是地图的一层(因此在 Tiled 中被称为 "object layer"),用于放置不严格对齐网格的对象。属性包括:id、name、class(1.9 起)、color(显示对象颜色)、x/y(已无法修改)、width/height(无意义)、opacity、visible、tintcolor、offsetx/offsety、parallaxx/parallaxy、draworder(index 按出现顺序绘制,topdown 按 y 坐标排序,默认 topdown)。至多一个 <properties>,任意数量 <object>。
| 属性 | 说明 | 默认值 |
|---|---|---|
id |
对象唯一 ID(0.11 起),至少为 1,删除后不复用,不可修改 | 0 |
name |
对象名称 | "" |
type |
对象的类(任意字符串,1.9 曾保存为 class) |
"" |
x / y |
对象像素坐标 | 0 |
width / height |
对象像素尺寸 | 0 |
rotation |
围绕 (x, y) 顺时针旋转的度数 | 0 |
opacity |
不透明度 0~1 | 1 |
gid |
对瓦片的引用(可选) | — |
visible |
是否显示 | 1 |
template |
对模板文件的引用(可选) | — |
对象通常用于为地图添加自定义信息,如出生点、传送点、出口等。其坐标和尺寸以像素为单位,但需要时仍可轻松对齐到网格。
关于 gid 的渲染:当对象设置了 gid 时,它由该全局 ID 瓦片的图像表示。图像的对齐取决于地图朝向——正交朝向对齐到左下,等距朝向对齐到底部中央;旋转也分别绕这两个锚点进行。
关于 template:设置了 template 的对象会借用模板的所有属性,但对象自身保存的属性优先级更高,即覆盖模板属性。
<object> 至多包含一个 <properties>、<ellipse>(0.9 起)、<capsule>(1.12 起)、<point>(1.1 起)、<polygon>、<polyline>、<text>(1.0 起)。
在 examples/orthogonal-outside.tmx 的对象图层中可以看到各类对象的实际写法:带 type="Location" 与自定义属性的区域对象、带 <ellipse/> 的触发器、带 <polygon>/<polyline> 的碰撞/路径、带 gid 的瓦片对象(如 gid="2147483930" ——注意这个值的高位正是翻转标志位)、以及 <point/> 标记的出生点。
/ / / / /
<ellipse>:将对象标记为椭圆,复用x、y、width、height决定尺寸;<capsule>:将对象标记为胶囊体,同样复用四个属性(1.12 起);<point>:将对象标记为点,复用x、y;<polygon>:points为空格分隔的 x,y 坐标列表(像素),原点为父object的位置,默认第一个点为 0,0;<polyline>:与 polygon 相同的定位规则;<text>:将对象标记为文本对象,实际文本作为字符数据存放。
<text> 的全部属性:fontfamily(默认 sans-serif)、pixelsize(像素字号,默认 16,不用点是因为 TMX 其他尺寸均用像素)、wrap(自动换行,默认 0)、color(#AARRGGBB 或 #RRGGBB,默认 #000000)、bold、italic、underline、strikeout(默认 0)、kerning(字距调整,默认 1)、halign(left/center/right/justify,默认 left,1.2.1 起)、valign(top/center/bottom,默认 top)。
关于对齐的细节:文本底部是字体的下行线高度(descender),顶部是上行线高度(ascender)。例如对单词 "cat" 做 bottom 对齐,多数字体下底部会留出未使用的空隙;top 对齐时顶部也会为变音符号留出空间。若文本超过对象边界,则裁剪到对象边界内。
图像图层
单张图片组成的图层。属性:id、name、class(1.9 起)、offsetx/offsety(0.15 起,像素偏移)、parallaxx/parallaxy(1.5 起)、x/y(0.15 起弃用)、opacity、visible、tintcolor、repeatx/repeaty(1.8 起,图片是否沿轴重复)。至多包含一个 <properties> 与一个 <image>。
组图层
用于以层级结构组织地图图层。其 offsetx、offsety、opacity、visible、tintcolor 属性会递归影响所有子图层。至多一个 <properties>,任意数量的 <layer>、<objectgroup>、<imagelayer>、<group>(可嵌套)。属性同样包括 id、name、class(1.9 起)。
自定义属性系统
<properties> 包装任意数量的自定义属性,可作为 map、tileset、tile(图块集内)、terrain、wangset、wangcolor、layer、objectgroup、object、imagelayer、group 和 property 的子元素。
属性
| 属性 | 说明 |
|---|---|
name |
属性名 |
type |
属性类型:string(默认)、int、float、bool、color、file、object、class、list(0.16 起,color/file 于 0.17 加入,object 于 1.4 加入,class 于 1.8 加入,list 于 1.12 加入) |
propertytype |
自定义属性类型的名称(1.8 起) |
value |
属性值。默认:字符串 ""、数字 0、布尔 "false"、颜色 #00000000、文件 "."(当前文件的父目录) |
各类型值的存储约定:
- 布尔:
"true"或"false"; - 颜色:
#AARRGGBB格式; - 文件:相对于地图文件位置的路径;
- 对象:引用同一地图上的对象,存储为整数(被引用对象的 ID,未引用时为 0)。在 Tile Collision Editor 中用于对象时,只能引用同一瓦片上的其他对象;
- 类(class):成员值存放在嵌套的
<properties>元素中,只保存实际设置的成员;未设置任何成员时整个properties元素省略; - 列表(list):每个值存放在嵌套的
<item>元素中,自身没有value属性。
多行字符串的特别约定:当字符串属性包含换行时,当前版本 Tiled 会把值写成 property 元素内的字符数据,而不是 value 属性。未来版本的 TMX 格式可能会完全改为把属性值写在元素内部。
<property> 至多包含一个 <properties>(1.8 起),可包含任意数量 <item>(1.12 起)。
- 列表项
<item> 存储 list 类型属性的一个值(1.12 起)。除没有 name 属性外,结构同 <property>:class 项的成员放在嵌套 <properties> 中,list 项包含自己的 item 元素,多行字符串写成 item 元素内的字符数据。属性:type(同 property.type,默认 string)、propertytype、value。
文档给出的嵌套列表示例:
<property name="list property" type="list">
<item type="int" value="10"/>
<item value="text"/>
<item type="list">
<item type="bool" value="true"/>
</item>
</property>
模板文件(Template Files)
模板保存在独立文件中,被作为模板实例的对象引用。根元素为 <template>,包含保存的 <object> 和(若对象是瓦片对象)一个指向外部图块集的 <tileset> 元素。任何图块集引用必须出现在对象之前,且不支持内嵌图块集。
文档给出的模板文件示例:
<?xml version="1.0" encoding="UTF-8"?>
<template>
<tileset firstgid="1" source="desert.tsx"/>
<object name="cactus" gid="31" width="81" height="101"/>
</template>
<template> 至多一个 <tileset>,恰好一个 <object>。仓库中 examples/objecttypes.xml 及 docs/manual/using-templates.rst 可继续参考模板的实际使用。
GID 与翻转标志
GID(Global Tile ID)是理解 TMX 瓦片数据的核心概念,仓库文档 docs/reference/global-tile-ids.rst 对此有专门论述。要点如下:
- "全局"是相对的:GID 只在单个地图内全局。同一瓦片在不同地图中可能具有不同 GID(取决于图块集组成与顺序);
- 32 位 GID 的高四位是翻转标志,读取时必须先提取并清除这些标志:
| 位 | 正交/等距地图 | 六边形地图 |
|---|---|---|
Bit 32 (0x80000000) |
水平翻转 | 水平翻转 |
Bit 31 (0x40000000) |
垂直翻转 | 垂直翻转 |
Bit 30 (0x20000000) |
反对角线翻转(实现瓦片旋转) | 顺时针旋转 60 度 |
Bit 29 (0x10000000) |
可忽略 | 顺时针旋转 120 度 |
即使解析非六边形地图,也务必清除 Bit 29——Tiled 即使改变地图朝向也会保留并输出该标志,不清除可能得到无效瓦片 ID。渲染正交/等距瓦片时运算顺序很重要:先做对角线翻转,再做水平与垂直翻转;对角线翻转交换瓦片的左下与右上角,可理解为 x/y 轴交换。六边形瓦片则顺序无关。
- GID 到本地瓦片 ID 的映射:每个图块集有自己的本地 ID(通常从 0 开始)。图块集在 map 中分配
firstgid,即本地 ID 0 的瓦片对应的 GID。解析算法:找到firstgid小于等于该 GID 的最大图块集,然后用 GID 减去该firstgid得到本地瓦片 ID。第一个图块集的firstgid恒为 1;图层中 GID 为 0 表示该格为空。
文档中的三段图块集示例:
<tileset firstgid="1" source="TilesetA.tsx"/>
<tileset firstgid="65" source="TilesetB.tsx"/>
<tileset firstgid="115" source="TilesetC.tsx"/>
此时 GID 1-64 属于 TilesetA,65-114 属于 TilesetB,115 以上属于 TilesetC。GID 72 属于 TilesetB(65 ≤ 72 < 115),本地 ID 为 7(72 - 65)。
源码中的 GID 实现
src/libtiled/gidmapper.cpp 定义了与文档完全一致的标志常量:
const unsigned FlippedHorizontallyFlag = 0x80000000;
const unsigned FlippedVerticallyFlag = 0x40000000;
const unsigned FlippedAntiDiagonallyFlag = 0x20000000;
const unsigned RotatedHexagonal120Flag = 0x10000000;
GidMapper::gidToCell()(gidmapper.cpp)展示了权威的解析流程:先读取四个标志位写入 Cell,再清除标志,然后通过 mFirstGidToTileset.upperBound(gid) 定位"firstgid 小于等于 GID 的最大图块集"(QMap 的 upperBound 找到第一个大于 gid 的键,再回退一位),最后 tileId = gid - firstgid 得到本地瓦片 ID。cellToGid() 则执行反向映射(空 Cell 返回 0)。GidMapper 的构造函数从图块集列表生成映射时,firstGid 从 1 开始,每次累加该图块集的 nextTileId()(gidmapper.cpp),与文档描述的分配规则一致。
gidToCell 还处理了三种错误情况:空 GID(返回空 Cell,ok=true)、有瓦片但无图块集(ok=false)、GID 落在第一个图块集之前(无效 GID,ok=false)。对应 decodeLayerData 的 NoError、TileButNoTilesets、InvalidTile 错误码(见 gidmapper.h)。
解析伪代码(来自官方文档)
文档还提供了一份 C++ 伪代码,完整演示 base64+压缩数据的解码与 GID 解析流程(注意其中包含对数据长度 map_width * map_height * 4 的检查建议):
// 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;
const unsigned ROTATED_HEXAGONAL_120_FLAG = 0x10000000;
// Extract the contents of the <data> element
string tile_data = ...;
// If the data is encoded and compressed, decode and decompress:
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) {
// Read the GID in little-endian byte order:
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);
bool rotated_hex120 = (global_tile_id & ROTATED_HEXAGONAL_120_FLAG);
// Clear all four flags
global_tile_id &= ~(FLIPPED_HORIZONTALLY_FLAG |
FLIPPED_VERTICALLY_FLAG |
FLIPPED_DIAGONALLY_FLAG |
ROTATED_HEXAGONAL_120_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->get_tile(global_tile_id - tileset->first_gid());
break;
}
}
}
}
伪代码中从后往前遍历图块集、寻找 first_gid() <= gid 的实现方式,与 GidMapper 使用 QMap upperBound 的算法在逻辑上等价。
读写器源码速览:一次完整的 TMX 存取链路
结合上述源码,一次完整的 TMX 保存/加载流程如下:
- 写入:MapWriterPrivate::writeMap() 写出
<map>根元素及orientation、renderorder、尺寸等属性;compressionlevel >= 0时才写出compressionlevel属性;writeTileset() 写出firstgid等图块集属性;图层数据则依据mLayerDataFormat决定编码与压缩属性(默认Base64Zlib,见 mapwriter.cpp),内嵌图片数据则 base64 编码后写入(mapwriter.cpp); - 读取:MapReaderPrivate::readMap() 逐属性解析根元素,按
editorsettings、图层、properties、tileset分派解析;readTileLayerData() 判定编码/压缩组合;readTileLayerRect() 递归处理chunk与tile;decodeBinaryLayerData() 通过GidMapper::decodeLayerData完成 base64 解码、解压与 GID→Cell 转换,并区分CorruptLayerData、TileButNoTilesets、InvalidTile三种错误。读取完成后还会对瓦片对象做向后兼容的尺寸修正(width/height为 0 时用瓦片实际尺寸填充,见 mapreader.cpp)。
这两个类分别通过 mapreader.h 与 mapwriter.h 暴露 readMap() / writeMap() / writeTileset() 接口,是 libtiled 库(BSD 许可)对外提供 TMX 能力的核心入口,也是许多第三方工具复用的对象。
参考与延伸阅读
- TMX 格式变更历史:docs/reference/tmx-changelog.rst
- GID 与翻转标志的专门文档:docs/reference/global-tile-ids.rst
- JSON 地图格式(同一数据模型的另一种序列化):docs/reference/json-map-format.rst
- 支持 TMX 的第三方库与框架列表:docs/reference/support-for-tmx-maps.rst
- 可交互参考的真实地图:examples/orthogonal-outside.tmx、examples/desert.tmx、examples/hexagonal-mini.tmx、examples/isometric_grass_and_water.tmx、examples/isometric_staggered_grass_and_water.tmx
- 运行时渲染实现参考:src/libtiled/orthogonalrenderer.cpp、src/libtiled/hexagonalrenderer.cpp
- 格式的 DTD 定义文件:map.dtd(注意:文档提示该 DTD 未保持最新,但仍可用于 XML 命名空间)
附注:TMX Map Format 文档本身采用 Creative Commons Attribution-ShareAlike 3.0 许可发布;仓库中另有 XML Schema 版本 map.xsd 可供程序化校验参考。