TMX地图格式规范逐行详解:开发者必看的Tiled文件标准完整指南

原创2026-09-21 21:07:312,143 阅读
文章标签:游戏开发桌面应用开发工具图形学

TMX地图格式规范逐行详解:开发者必看的Tiled文件标准完整指南

如果你要用 Tiled 地图编辑器制作游戏关卡,却不知道保存下来的 .tmx 文件里到底写了什么,这篇文章就是为你准备的。Tiled 是一款强大的开源关卡编辑器,它用自己的 TMX(Tile Map XML)和 TSX(Tile Set XML)格式存储地图与图块集,格式规范文档就放在仓库的 tmx-map-format.rst 中。下面我们将逐元素拆解这份规范:从 <map> 根节点的核心属性,到 <data> 的编码方式、GID 翻转标志、自定义属性,帮你快速读懂并写出符合标准的 Tiled 地图文件。

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 被重复使用

💡 官方文档特别提醒:图块集必须排在所有层之前,解析器才能先建立图块集再解析层数据。

无限地图在Tiled中的编辑效果,数据按chunk分块存储

无限地图(infinite="1")的数据不按整张地图存储,而是拆分成 <chunk x="0" y="0" width="16" height="16"> 分块,每个 chunk 内部结构与 <data> 一致,这是无限地图(如 Roguelike 大地图)能在 TMX 中落地的关键设计。

三、<tileset> 元素与 TSX 文件:图块集的标准写法

<tileset> 有两种形态:

  1. 引用外部 TSX:如 forest.tmx 中的 <tileset firstgid="1" source="forest.tsx"/>,firstgid 是该图块集第一个图块的全局 ID;
  2. 内嵌图块集:直接包含 <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 中“图块动画”的底层存储方式,编辑器对应界面如下:

Tiled图块动画编辑器,设置每帧持续时间,对应TSX中的animation元素

此外,图块集还可携带 <wangsets>(地形/王格集,1.5 起取代了旧的 <terraintypes>)来支持自动地形绘制:

Tiled地形集功能,对应TSX中wangsets元素的编辑界面

四、<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>

Tiled图层属性面板,展示Tint Color、透明度等对应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> 子元素:

Tiled对象属性面板,展示对象的Type与自定义属性,对应TMX的object和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 属性),可在“属性类型编辑器”中定义枚举或类:

Tiled属性类型编辑器,对应TMX格式1.8新增的自定义属性类型

完整字段说明见 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>
 ├─ <tileset>  (必须位于所有层之前,firstgid 递增)
 ├─ <layer>/<data>        瓦片层:csv / base64 / 压缩
 ├─ <objectgroup><object> 对象层:像素坐标 + 形状 + 模板
 ├─ <imagelayer>          单图层背景
 ├─ <group>                分组层,递归包含以上所有类型
 └─ <properties>          自定义元数据,几乎无处不在

只要记住这张结构图 + GID 翻转标志这两个要点,你就能读懂任何 Tiled 导出的 TMX 文件,甚至手写或程序生成符合规范的地图——这正是 TMX 作为跨引擎通用地图交换格式的价值所在。

登录后查看全文
tiled