Tiled TMX 地图格式完全指南:从 XML 结构到 GID 底层原理

原创2026-09-22 12:59:272,232 阅读
文章标签:游戏开发桌面应用开发工具图形学

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)或当前版本不再支持。

阅读规范与兼容性准则

在逐元素展开之前,先明确三条贯穿全文的读写规则:

  1. 兼容性优先:解析 TMX 文件时,建议忽略未知元素与未知属性(或至少给出警告)。Tiled 官方在文档中明确建议这样做,因为它允许在不破坏向后兼容的前提下持续增加新特性,也让基于 TMX 的第三方工具和自定义变体可以继续工作。这一点在源码中得到印证——MapReaderPrivate::readUnknownElement() 会安全跳过未知节点(见 src/libtiled/mapreader.cpp)。
  2. 可选的判定:文档中所有可选属性要么被显式标记为 optional,要么带有默认值。带有默认值的属性,缺省时即采用默认值。
  3. 弃用标记:格式中的历史遗留元素(如 <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

三种存储方式:

  1. 无 encoding/compression:瓦片以独立的 XML <tile> 元素逐个存储——文档明确标注此方式已弃用,且是效率最低的存储方式,应尽量避免;
  2. CSV:逗号分隔值格式,最容易解析;
  3. 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 对此有专门论述。要点如下:

  1. "全局"是相对的:GID 只在单个地图内全局。同一瓦片在不同地图中可能具有不同 GID(取决于图块集组成与顺序);
  2. 32 位 GID 的高四位是翻转标志,读取时必须先提取并清除这些标志:
位 正交/等距地图 六边形地图
Bit 32 (0x80000000) 水平翻转 水平翻转
Bit 31 (0x40000000) 垂直翻转 垂直翻转
Bit 30 (0x20000000) 反对角线翻转(实现瓦片旋转) 顺时针旋转 60 度
Bit 29 (0x10000000) 可忽略 顺时针旋转 120 度

即使解析非六边形地图,也务必清除 Bit 29——Tiled 即使改变地图朝向也会保留并输出该标志,不清除可能得到无效瓦片 ID。渲染正交/等距瓦片时运算顺序很重要:先做对角线翻转,再做水平与垂直翻转;对角线翻转交换瓦片的左下与右上角,可理解为 x/y 轴交换。六边形瓦片则顺序无关。

  1. 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 Map Format 文档本身采用 Creative Commons Attribution-ShareAlike 3.0 许可发布;仓库中另有 XML Schema 版本 map.xsd 可供程序化校验参考。

登录后查看全文
tiled