Tiled TMX 文件格式演进史从 Tiled 0.8 到 1.12 的 Changelog 深度解读【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiledTMXTile Map XML是 Tiled 编辑器自有的瓦片地图格式也是整个 Tiled 生态的数据交换基石。本文以仓库内的 tmx-changelog.rst 为骨架完整梳理该格式从 Tiled 0.8 到 1.12 的每一次版本变更并对照 TMX Map Format 参考文档 与 libtiled 源码逐一解释每个新属性、新元素背后的设计动机与实际含义。读完本文你将能够判断一个.tmx文件由哪个版本的 Tiled 写出、各版本引入了哪些必须解析的新特性以及在自行编写 TMX 解析器或生成器时如何保持向后兼容。为什么需要一份 TMX ChangelogTMX 与 TSXTileset XML是基于 XML 的、Tiled 自有的地图与图块集存储格式其完整元素与属性清单记录在 docs/reference/tmx-map-format.rst 中。这份格式规范并非一成不变随着 Tiled 功能不断扩展斜投影、胶囊碰撞体、列表属性、Zstd 压缩、无限地图……文件格式也在持续演进。changelog 的价值在于面向解析器开发者明确哪些属性是后来加的从而知道哪些字段可能缺失、需要给默认值面向游戏引擎与工具链了解格式升级对旧文件的影响判断是否需要迁移逻辑面向深度用户理解编辑器里某个新选项最终落地为文件中的哪个 XML 属性。仓库中的 map.dtd 与 map.xsd 可用于 XML 命名空间与结构校验不过正如 tmx-map-format 文档所述该 DTD 并不总是与最新格式同步官方推荐的兼容策略是解析时忽略未知元素与未知属性或仅给出警告这样新特性可以平滑加入而不破坏旧工具。一、Tiled 1.12混合模式、斜投影与胶囊对象图层的混合模式blend modelayer元素新增了mode属性用于指定图层渲染时的混合模式。参考 tmx-map-format.rst 中layer一节的完整取值表取值含义normal默认值普通混合add加色混合常用于发光、火焰特效multiply正片叠底screen滤色overlay/darken/lighten叠加、变暗、变亮color-dodge/color-burn颜色减淡 / 颜色加深hard-light/soft-light强光 / 柔光difference/exclusion差值 / 排除在读取端mapreader.cpp中通过blendModeFromString将字符串转换为内部枚举并写入Layer::setBlendMode见 src/libtiled/mapreader.cpp 中读取mode属性的逻辑写入端则由mapwriter.cpp负责序列化。斜投影oblique方向与 skew 属性orientation属性新增了oblique取值同时map元素新增skewx、skewy两个属性分别表示每行/每列在像素上的斜切偏移量。这与正交、等距isometric、交错staggered、六边形hexagonal并列构成 Tiled 支持的第五种地图方向。从源码看这一能力由独立的渲染器 src/libtiled/obliquerenderer.cpp 实现其transform()方法根据map()-skewX() / tileHeight与map()-skewY() / tileWidth构造 QTransform 的 shear 变换得到平行四边形网格staggered是使用交错轴的等距地图而oblique使用斜切的平行四边形瓦片。mapreader.cpp在读取map属性时同步解析skewx、skewy因此两者必须配套使用。胶囊对象capsule对象形状新增了胶囊体capsule类型其 XML 表示与矩形/椭圆对象类似——沿用x、y、width、height四个属性确定大小通过一个空的子元素capsule/标记形状object name... x... y... capsule/ /object在 src/libtiled/mapobject.h 中可以看到MapObject::Shape枚举新增了Capsule值渲染端obliquerenderer.cpp 的shape()与drawMapObject()将其绘制为圆角矩形圆角半径取宽高中的较小值的一半。这与 Tiled 0.9 引入椭圆ellipse/的设计一脉相承。对象透明度object元素新增opacity属性取值 0 到 1默认 1用于单独控制每个对象的绘制透明度此前只有图层级 opacity。列表属性list propertyproperty元素的type属性新增list取值。列表属性的每个元素存储在一个嵌套的item元素中property namelist property typelist item typeint value10/ item valuetext/ item typelist item typebool valuetrue/ /item /property根据 tmx-map-format.rst 中item一节的说明item与property结构类似但没有name属性class类型的 item 在嵌套properties中保存成员list类型的 item 可以继续嵌套自己的item多行字符串则写入元素内部而非value属性。列表属性支持嵌套因此可以表达相当复杂的自定义数据结构。二、Tiled 1.10 与 1.9class / type 属性的一次往返这两个版本最值得关注的是类名属性的反复重命名理解它有助于解析历史文件Tiled 1.9将tiletileset 内的 tile和object上的type属性改名为class同时为map、tileset、layer、imagelayer、objectgroup、group、wangset、wangcolor统一新增class属性默认。Tiled 1.10出于与 Tiled 1.8 及更早版本兼容的考虑又把tile和object上的class改回type。其他元素则保留class因为并非所有元素都能无歧义地改名为type。因此tmx-map-format文档中tile的type注释为 was saved asclassin 1.9object的type同样如此。做解析器时建议对这两个属性同时接受type与class两种写法。1.9 的其他新增tile新增x、y、width、height四个属性记录用于表示该 tile 的图像子矩形默认使用整张图像即 collection tileset 中每个 tile 可以从同一张图的不同区域裁切。tileset新增tilerendersizetile或grid默认tile与fillmodestretch或preserve-aspect-fit默认stretch。前者决定瓦片按自身尺寸还是按地图网格尺寸渲染后者在瓦片非原生尺寸渲染时如缩放后的 tile 对象、或tilerendersizegrid决定如何适配。三、Tiled 1.8自定义属性类型与视差原点自定义属性类型custom property typesproperty元素新增propertytype属性引用用户定义的自定义属性类型名称属性值若为class类型则在property内嵌套一个properties元素保存成员值仅保存被实际设置的成员一个成员都没设置时整个properties元素会被省略。相关概念详见 docs/manual/custom-properties.rst。map新增parallaxoriginx、parallaxoriginy像素默认 0作为图层视差的原点坐标。imagelayer新增repeatx、repeaty控制图像层沿 X/Y 轴平铺重复。四、Tiled 1.7Tile ID 的保存顺序tileset 内的tile元素不再保证按 ID 递增保存而是按 Tiled 中可调整的显示顺序保存。这意味着解析器不能依赖第 N 个tile就是 ID 为 N 的 tile必须始终读取每个tile的id属性。五、Tiled 1.5Wang 集全面取代地形类型这是 TMX 格式中影响较大的一次重构涉及四件事Wang 颜色统一wangset中不再区分角颜色corner与边颜色edge统一由单个wangcolor元素定义可含name、class、color#RRGGBB、tile、probability及自定义属性。wangid 改为逗号分隔wangtile的wangid从 32 位十六进制整数改为逗号分隔的索引列表顺序为 top, top-right, right, bottom-right, bottom, bottom-left, left, top-left原因是为了支持更多颜色——Wang 集支持的颜色数从 15 提升到 255。源码侧src/libtiled/wangset.cpp 中的WangId::fromString/toString即按逗号分隔解析/序列化 8 个索引并校验索引不超过WangId::MAX_COLOR_COUNT而fromUint/toUint则保留旧的 4-bit-per-index 32 位格式用于兼容。另外tmx-map-format文档注明一个 wangset 可含最多 254 个 wangcolor1.5 起为 2551.10.2 起为 254。变换声明瓦片集合的合法变换水平翻转、垂直翻转、90° 旋转改由transformations元素声明hflip、vflip、rotate、preferuntransformedwangtile上此前对vflip、hflip、dflip的部分支持被移除。元素替换wangsets/wangset取代了已弃用的terraintypes元素Tiled 1.5 起包含地形类型的 tileset 保存时会被自动转换为 Wang 集。旧版terraintypes/terrain仍可在 tmx-map-format.rst 中查阅到完整说明但已标记为 Deprecated。此外1.5 还为layer、objectgroup、imagelayer、group四个元素统一新增parallaxx、parallaxy视差因子默认 1。六、Tiled 1.4对象对齐与着色tileset新增objectalignment控制 tile 对象使用哪种对齐方式。合法值包括unspecified、topleft、top、topright、left、center、right、bottomleft、bottom、bottomright默认unspecified兼容性考虑未指定时正交地图使用bottomleft、等距地图使用bottom。layer、objectgroup、imagelayer、group新增tintcolor#AARRGGBB或#RRGGBB用于实现图层变暗、着色等图形效果。property的type新增object取值通过对象 ID 引用同一地图上的某个对象整数存储0 表示未引用在 Tile Collision Editor 中只能引用同一 tile 上的对象。七、Tiled 1.3编辑器设置与 Zstd 压缩新增editorsettings元素存放与地图加载无关的编辑器专属设置其下可包含chunksize无限地图的 chunk 宽高默认 16×16与export上次导出目标与格式。瓦片层数据支持 Zstandard 压缩data compressionzstd自 1.3 起作为编译期选项。map新增compressionlevel记录压缩级别默认 -1 表示使用算法默认级别。因此文件中的压缩效果同时受压缩算法与压缩级别两个属性控制。八、Tiled 1.2 / 1.1ID 机制、无限地图与模板1.2.1 与 1.2图层 ID 与文本对齐1.2.1 修复文本对象的水平对齐现在可以保存为justify此前 UI 中存在该选项但未正确写入文件。1.2 新增layer、objectgroup、imagelayer、group的id属性地图内唯一、删除后不复用、在 Tiled 中不可修改以及map的nextlayerid下一个可用图层 ID防止图层删除后 ID 被复用。1.1无限地图、模板与地形map新增infinite属性0/1指示地图是否无界无限地图的瓦片层数据以 chunk 形式存储。对应地新增chunk元素携带x、y、width、height内容与data相同但只覆盖其指定区域。实现层面src/libtiled/tilelayer.cpp 用QHashQPoint, Chunk组织瓦片数据并以CHUNK_MASK做坐标掩码定位 chunk。新增模板Templates支持模板是外部文件.tx模板实例对象通过template属性引用例如object id3 templatediamond.tx x200 y100/模板文件结构详见 tmx-map-format.rst 的 Template Files 一节template根元素包含一个tileset引用与一个object实例对象会继承模板属性但自身保存的属性优先级更高。使用说明见 docs/manual/using-templates.rst。Tileset 支持地形Terrain集保存在新的wangsets元素中当时仍是角/边颜色分离的早期形式1.5 才统一。用法见 docs/manual/terrain.rst。object新增point/子元素标记点对象无尺寸、无旋转。九、Tiled 1.0组图层、文本对象与类型化 tile新增group组图层可包含其他图层为子元素图层从此形成层级结构组图层的offsetx、offsety、opacity、visible、tintcolor会递归作用于子图层。新增文本对象通过object的子元素text标识包含fontfamily默认 sans-serif、pixelsize默认 16注意用像素而非磅值、wrap、color#AARRGGBB/#RRGGBB、bold、italic、underline、strikeout、kerning默认 1、halignleft/center/right/justify1.2.1 起支持 justify、valigntop/center/bottom等属性。tileset 内tile新增type属性默认1.9 曾保存为class支持类型化 tiletyped tiles该类型会被 tile 对象继承。十、Tiled 0.100.18属性系统、翻转与碰撞体成型这一阶段奠定了如今 TMX 格式的大部分基础能力0.10tile 对象支持水平/垂直翻转复用与普通瓦片相同的 gid 高位标志位机制详见 global-tile-ids.rst 中关于翻转标志位的说明对象可自由旋转rotation属性以度为单位、顺时针为正map新增renderorderright-down默认、right-up、left-down、left-up仅正交地图支持objectgroup新增drawordertopdown默认按 y 坐标排序index按文件出现顺序配合 Raise/Lower 操作手动控制绘制顺序tile可含objectgroup子元素定义碰撞形状对应 Tile Collision Editortile可含单个循环动画animation每帧由frame元素定义本地 tile ID 与毫秒时长tile id[n] animation frame tileid0 duration100/ frame tileid1 duration100/ frame tileid2 duration100/ /animation /tile0.9对象可见性标志visible0|1默认 1tileset 内加入地形信息terraintypes/terrain对游戏本身通常无关紧要初步支持 staggered 等距投影新增基本图像层imagelayer含image source.../新增椭圆对象ellipse/子元素map新增backgroundcolor#RRGGBB支持单 tile 独立/内嵌图片当时无 GUI 支持。0.8tileset 支持自定义属性properties子元素tileset 支持tileoffset绘制偏移如 examples/perspective_walls.tmx 中perspective_walls即使用tileoffset实现立体墙效果全局 tile ID 引入第三个最高位作为 anti-diagonal flip反对角线翻转交换 x/y 轴支持 90° 整数倍的瓦片旋转。0.11orientation支持hexagonal新增staggerindexeven/odd、staggeraxisx/y、hexsidelength对象与图层分别引入id/nextobjectid机制。所有坐标与大小的像素语义可参见 examples/hexagonal-mini.tmx 等示例文件。0.12tile 对象开始使用width/height存储图像渲染尺寸默认值为 tile 图像自身尺寸。0.13tileset新增tilecount帮助解析器预分配内存。0.14layer、objectgroup新增可选offsetx/offsety像素偏移默认 0。0.15imagelayer改用offsetx/offsety取代x/y与其他图层类型保持一致图像集合 tileset 中的 tile ID 不再保证连续删除 tile 不会改变其他 tile 的 ID纯 XML 与 Gzip 压缩的瓦片层数据格式被弃用仅保留 CSV、base64、Zlib后续 1.3 才加入 Zstdtileset新增columns图像集合 tileset 中可编辑用于显示map的backgroundcolor在 alpha 非 255 时以#AARRGGBB保存此前 alpha 被静默丢弃。0.16property新增type属性支持string默认、int、float、bool。0.17type新增color、file支持多行字符串属性换行时值写入元素内部而非value属性。0.18无文件格式变更。十一、给解析器与生成器的兼容性清单综合 changelog 与格式规范编写 TMX 工具时建议遵循以下要点忽略未知元素与属性或仅给出警告——这是 Tiled 官方推荐的兼容策略也是新特性不断加入仍不破坏旧工具的原因。注意双重命名tile与object的类名属性在 1.9 为class其余版本为type最好两者都接受。tile ID 不连续、不递增1.7 起按显示顺序保存1.15 起集合 tileset 的 ID 可能有空洞永远读取id属性不要按出现顺序推导。firstgid决定 gid 归属瓦片层数据中的 gid 是全局 ID高位含翻转标志H/V/anti-diagonal flip须结合各 tileset 的firstgid解析详见 global-tile-ids.rst。属性类型是演进最频繁的区域property.type从 0.16 的 4 种逐步扩展到color、file、object、class、list并伴随propertytype、嵌套properties、item等结构解析时应按类型分支处理。压缩与编码data支持csv、base64压缩算法有gzip、zlib、zstd1.3配合map.compressionlevelbase64 数据按小端序 32 位无符号整数解释。旧格式元素仍可能出现在存量文件中如terraintypes、纯 XML tile 数据、imagelayer的x/y建议至少做到可读不报错。对每个元素、属性的完整权威定义含默认值与取值范围始终以 docs/reference/tmx-map-format.rst 为准而本文梳理的这份 changelog则是理解某段 TMX 数据为什么长这样的最直接线索。【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiled创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考