TMX地图格式规范逐行详解:开发者必看的Tiled文件标准完整指南
TMX地图格式规范逐行详解:开发者必看的Tiled文件标准完整指南
如果你要用 Tiled 地图编辑器制作游戏关卡,却不知道保存下来的 .tmx 文件里到底写了什么,这篇文章就是为你准备的。Tiled 是一款强大的开源关卡编辑器,它用自己的 TMX(Tile Map XML)和 TSX(Tile Set XML)格式存储地图与图块集,格式规范文档就放在仓库的 tmx-map-format.rst 中。下面我们将逐元素拆解这份规范:从 <map> 根节点的核心属性,到 <data> 的编码方式、GID 翻转标志、自定义属性,帮你快速读懂并写出符合标准的 Tiled 地图文件。
一、TMX/TSX 是什么:一图看懂两种文件格式
TMX 格式基于 XML,官方规范明确了几点设计原则(见 tmx-map-format.rst):
- 版本化:
version属性跟随 TMX 格式版本(当前为 1.8),tiledversion记录保存文件的 Tiled 版本; - 向后兼容优先:解析器遇到未知元素或属性时,建议忽略或仅发出警告,而不是直接报错;
- TMX 存地图,TSX 存图块集:外部图块集文件(.tsx)与 TMX 中的
<tileset>结构相同,但缺少firstgid属性。
你可以直接把仓库里的 forest.tmx 和 forest.tsx 当作最规范的示例文件来对照学习。
二、<map> 根元素:逐行读懂一张地图的“身份证”
所有 TMX 文件都以 <map> 开头。以示例文件 forest.tmx 第一行为例:
<map version="1.8" tiledversion="1.8.4" orientation="orthogonal"
renderorder="right-down" width="40" height="16"
tilewidth="16" tileheight="16" infinite="0"
nextlayerid="11" nextobjectid="42">
核心属性速查表:
| 属性 | 含义 | 说明 |
|---|---|---|
orientation |
地图朝向 | orthogonal(正交)、isometric(等距)、staggered(交错)、hexagonal(六边形)、oblique(斜向,1.12 起) |
renderorder |
渲染顺序 | 默认 right-down,还有 right-up 等 4 种 |
width / height |
地图尺寸 | 以图块为单位 |
tilewidth / tileheight |
图块尺寸 | 定义网格大小,单位是像素 |
infinite |
是否无限地图 | 无限地图无固定大小,数据按 chunk 分块存储 |
nextlayerid / nextobjectid |
ID 计数器 | 防止删除后 ID 被重复使用 |
💡 官方文档特别提醒:图块集必须排在所有层之前,解析器才能先建立图块集再解析层数据。
无限地图(infinite="1")的数据不按整张地图存储,而是拆分成 <chunk x="0" y="0" width="16" height="16"> 分块,每个 chunk 内部结构与 <data> 一致,这是无限地图(如 Roguelike 大地图)能在 TMX 中落地的关键设计。
三、<tileset> 元素与 TSX 文件:图块集的标准写法
<tileset> 有两种形态:
- 引用外部 TSX:如 forest.tmx 中的
<tileset firstgid="1" source="forest.tsx"/>,firstgid是该图块集第一个图块的全局 ID; - 内嵌图块集:直接包含
<image>和<tile>子元素。
关键字段:
firstgid:起始全局 ID,第一个图块集恒为 1,多个图块集按 firstgid 升序排列;spacing/margin:图块图之间的间距和外边距(像素);tilecount/columns:图块数量与列数。
外部 TSX 文件 forest.tsx 展示了一个“图像集合”式图块集:每个 <tile id="..."> 各自引用同一张 squirrel.png 上的一个子区域(x/y/width/height)。它还包含一个 <animation> 子元素:
<tile id="13" x="116" y="824" width="25" height="25">
<image width="1024" height="1024" source="squirrel.png"/>
<animation>
<frame tileid="10" duration="150"/>
<frame tileid="11" duration="150"/>
</animation>
</tile>
每个 <frame> 指定帧图块的本地 ID 和停留毫秒数——这就是 Tiled 中“图块动画”的底层存储方式,编辑器对应界面如下:
此外,图块集还可携带 <wangsets>(地形/王格集,1.5 起取代了旧的 <terraintypes>)来支持自动地形绘制:
四、<layer> 与 <data>:瓦片层数据到底怎么编码
瓦片层是地图的骨架。<layer> 常用属性包括 name、opacity(0~1 透明度)、visible(1/0 显示开关)、offsetx/offsety(像素偏移)、tintcolor(图层染色,格式 #AARRGGBB)等。
其下的 <data> 元素有三种存储方式(见 tmx-map-format.rst):
| 编码 | 属性 | 特点 |
|---|---|---|
| CSV | encoding="csv" |
逗号分隔的数字,最容易解析,适合新手 |
| Base64 | encoding="base64" |
先 Base64 解码,再按 little-endian 的无符号 32 位整数数组读取 |
| 压缩 | compression="zlib|gzip|zstd" |
可与 base64 叠加,zstd 是 1.3 起的编译期选项 |
例如 desert.tmx 使用的是 encoding="base64" compression="zlib"。CSV 格式则直观得多,forest.tmx 中的 platforms 层每行 40 个数字,0 表示空格,1 表示图块集里 firstgid+0 的图块:
<layer id="1" name="platforms" width="40" height="16">
<data encoding="csv">
0,0,0,0,0,0,0,0,1,1,1,1,0,0,...
</data>
</layer>
五、<objectgroup> 与 <object>:对象层是地图的“外挂信息”
瓦片层适合对齐网格的重复内容,而对象层(<objectgroup>)用像素坐标自由标注任意信息——出生点、传送门、碰撞盒、寻路标记……
<object> 的核心属性:x/y/width/height(像素)、rotation(顺时针角度)、gid(引用图块渲染)、type(对象类名)、name。子元素则决定形状:
<ellipse/>椭圆、<point/>点、<polygon points="..."/>多边形、<polyline points="..."/>折线、<capsule/>胶囊(1.12 起)、<text>文本对象;- 支持
template="xxx.tx"属性引用外部模板文件,实例对象会继承模板属性。
下面的截图里,对象的 Type(COORDDINATE)、Custom Properties(path=79)正是分别对应 <object> 的 type 属性和 <properties> 子元素:
对象组的 draworder 属性还控制绘制顺序:topdown(按 y 坐标排序,默认)或 index(按文件出现顺序),方便实现“站在树后面”这类遮挡效果。
六、<properties> 自定义属性:给地图加任意元数据
<properties> 几乎可以挂在任何元素上(map、tileset、tile、layer、object、group……),内部是一组 <property>:
<property name="music" type="file" value="tracks/cave.ogg"/>
<property name="enemyDensity" type="float" value="0.8"/>
type 支持 string(默认)、int、float、bool、color、file、object,以及 1.8 起新增的 class 和 1.12 起的 list。自 1.8 起还支持用户自定义属性类型(propertytype 属性),可在“属性类型编辑器”中定义枚举或类:
完整字段说明见 tmx-map-format.rst 的 <properties> 与 <property> 章节。
七、进阶知识:GID 全局图块 ID 与翻转标志
这是解析 TMX 时最容易踩坑的地方,单独看 global-tile-ids.rst 这篇官方文档:
- 32 位 GID 的最高 4 位是翻转标志:bit32 水平翻转、bit31 垂直翻转、bit30 对角翻转(可实现旋转),读图前必须先清除标志位;
- GID 0 永远表示空格;第一个图块集的
firstgid恒为 1; - 反查算法:找到
firstgid≤ GID 的最大图块集,GID - firstgid即图块集内本地 ID。
例如三个图块集 firstgid 分别为 1、65、115 时,GID 72 属于第二个图块集,本地 ID 为 7(72−65)。官方文档中附有完整的 C++ 伪代码示例(global-tile-ids.rst),可作为解析器参考实现。
八、版本演进与兼容性:规范文件去哪找
TMX 格式随 Tiled 持续演进,完整变更记录见 tmx-changelog.rst。几个开发中必须知道的变更点:
| 版本 | 关键变化 |
|---|---|
| 1.12 | 新增图层混合模式 mode、胶囊对象、oblique 朝向、list 属性类型 |
| 1.10 | tile/object 的 class 属性改回 type,保持与 1.8 的兼容 |
| 1.9 | 新增 class 属性、图块子矩形、tilerendersize/fillmode |
| 1.1 | 无限地图(infinite + <chunk>)、对象 id、Wang 地形集、点对象 |
| 1.0 | <group> 分组层(图层层级化)、文本对象、图块 type |
| 0.16 | 属性引入 type 属性(string/int/float/bool) |
⚠️ 实用建议:解析器对未知字段保持宽容,这是官方明确推荐的兼容策略。
配套参考资料清单:
- 格式规范:tmx-map-format.rst
- 全局图块 ID 指南:global-tile-ids.rst
- 格式变更记录:tmx-changelog.rst
- XML Schema / DTD:map.xsd、map.dtd
- 支持的第三方解析库与引擎列表:support-for-tmx-maps.rst
- Tiled 自有的格式读写核心源码(C++/Qt):src/libtiled/tmxmapformat.cpp
小结:一张图掌握 TMX 的骨架
<map>
├─ <tileset> (必须位于所有层之前,firstgid 递增)
├─ <layer>/<data> 瓦片层:csv / base64 / 压缩
├─ <objectgroup><object> 对象层:像素坐标 + 形状 + 模板
├─ <imagelayer> 单图层背景
├─ <group> 分组层,递归包含以上所有类型
└─ <properties> 自定义元数据,几乎无处不在
只要记住这张结构图 + GID 翻转标志这两个要点,你就能读懂任何 Tiled 导出的 TMX 文件,甚至手写或程序生成符合规范的地图——这正是 TMX 作为跨引擎通用地图交换格式的价值所在。






