Tiled 自定义导出格式完整指南:基于 JavaScript、Python 与 C++ 插件扩展地图与图块集格式
Tiled 自定义导出格式完整指南:基于 JavaScript、Python 与 C++ 插件扩展地图与图块集格式
导读
Tiled 内置的 TMX/JSON 等格式并不能覆盖所有游戏引擎与工具的资产管线需求。本指南围绕官方手册 export-custom.rst 展开,系统讲解 Tiled 提供的三条自定义格式扩展路径:JavaScript 脚本格式(自 Tiled 1.3 起推荐)、Python 插件(部分平台可用)与 C++ 原生插件(Tiled 自带全部导出格式的实现方式)。阅读本文后,你将能够为自己的项目注册专属的地图/图块集格式,让它出现在文件对话框与命令行导出流程中,并理解每种方案的适用场景、限制与底层实现机制。
三种扩展路径总览
| 方案 | 语言 | 推荐度 | 平台限制 | 官方文档 | 底层实现 |
|---|---|---|---|---|---|
| JavaScript 脚本格式 | JavaScript | 推荐(官方首选) | 全平台开箱即用 | scripting.rst | tiled.registerMapFormat / tiled.registerTilesetFormat |
| Python 插件 | Python 3 | 不推荐(官方明确警告) | macOS 与 snap 版不可用,Python 版本匹配严格 | python.rst | ~/.tiled 目录脚本 + tiled.Plugin 类 |
| C++ 插件 | C++ | 面向深度集成 | 需与 Tiled 同平台、同编译器、同 Qt 版本编译 | libtiled 源码中的 Doxygen 注释 | 继承 Tiled::MapFormat / Tiled::TilesetFormat |
自 Tiled 1.3 起(见 export-custom.rst 开头的版本标记),Tiled 官方明确推荐通过 JavaScript 扩展自定义格式,原因在于 JavaScript API 文档完善、全平台开箱即用,且能覆盖比"格式读写"更广的编辑器扩展能力(自定义工具、动作、菜单等)。
方案一:JavaScript 注册自定义格式(推荐)
1.1 核心 API 与格式对象结构
JavaScript 扩展通过两个全局函数注册格式:
tiled.registerMapFormat(shortName, mapFormatObject):注册地图格式;tiled.registerTilesetFormat(shortName, tilesetFormatObject):注册图块集格式。
在 docs/scripting-doc/index.d.ts 中定义了 ScriptedMapFormat 接口,格式对象需包含以下成员:
| 成员 | 类型 | 必填 | 说明 |
|---|---|---|---|
name |
string |
是 | 文件对话框中显示的名称,如 "Custom map format" |
extension |
string |
是 | 格式使用的文件扩展名(不带点号) |
read(fileName) |
函数 | 可选 | 从文件读取地图,返回 TileMap 对象;可使用 TextFile 或 BinaryFile 读取 |
write(map, fileName) |
函数 | 可选 | 将地图写入文件;返回非空字符串时作为错误信息显示 |
outputFiles(map, fileName) |
函数 | 可选 | 导出时返回将要写入的文件列表 |
校验逻辑位于 src/tiled/scriptedfileformat.cpp 的 validateFileFormatObject:name 与 extension 必须是字符串,且 read/write 至少实现其一,否则注册会被拒绝并抛出错误。
1.2 完整可运行的示例:导出简易 JSON 地图
以下是官方 API 定义中直接给出的示例(摘自 docs/scripting-doc/index.d.ts),它将地图导出为包含尺寸与逐行图块 ID 的 JSON:
var customMapFormat = {
name: "Custom map format",
extension: "custom",
write: function(map, fileName) {
var m = {
width: map.width,
height: map.height,
layers: []
};
for (var i = 0; i < map.layerCount; ++i) {
var layer = map.layerAt(i);
if (layer.isTileLayer) {
var rows = [];
for (y = 0; y < layer.height; ++y) {
var row = [];
for (x = 0; x < layer.width; ++x)
row.push(layer.cellAt(x, y).tileId);
rows.push(row);
}
m.layers.push(rows);
}
}
var file = new TextFile(fileName, TextFile.WriteOnly);
file.write(JSON.stringify(m));
file.commit();
},
}
tiled.registerMapFormat("custom", customMapFormat)
关键 API 补充说明:
layer.cellAt(x, y)返回cell对象(定义见 docs/scripting-doc/index.d.ts),其中tileId为局部图块 ID,空单元格为-1;flags、flippedHorizontally、flippedVertically、flippedAntiDiagonally等属性用于表达翻转/旋转状态;shortName不仅用于内部标识,还可直接在命令行配合--export-map指定格式(见下文 1.4 节),当文件扩展名有歧义或需要指定不同扩展名时尤为有用;- 同名单注册会替换已有格式(见 src/tiled/scriptmodule.cpp 的
registerMapFormat/registerTilesetFormat实现)。
1.3 格式对象的能力推导与底层桥接
从 src/tiled/scriptedfileformat.cpp 可以看到,Tiled 通过检查对象属性是否为可调用函数来推导格式能力:
- 存在可调用的
read属性 → 具备FileFormat::Read能力; - 存在可调用的
write属性 → 具备FileFormat::Write能力。
nameFilter() 则由 name 与 extension 拼接为 "%1 (*.%2)" 形式(如 "Custom map format (*.custom)"),这正是文件对话框中显示的过滤器;supportsFile() 则做扩展名大小写不敏感的结尾匹配(src/tiled/scriptedfileformat.cpp)。
写入时,write(map, fileName) 收到的 map 是包装后的 EditableMap 对象;从脚本返回的字符串会被当作错误信息,返回 undefined 或空字符串表示成功(src/tiled/scriptedfileformat.cpp)。读取时,脚本返回的 EditableMap/EditableTileset 会被克隆后再交给 Tiled 的文档系统,以避免脚本后续修改破坏撤销/重做机制(src/tiled/scriptedfileformat.cpp 与 #L226-L247 的注释说明了这一点)。
1.4 脚本的加载、控制台与命令行执行
脚本需要放置在扩展目录中,Tiled 启动时会自动执行(详见 scripting.rst):
- 系统级扩展目录:Windows
C:/Users/<USER>/AppData/Local/Tiled/extensions/、macOS~/Library/Preferences/Tiled/extensions/、Linux~/.config/tiled/extensions/,也可在 Preferences 对话框的 Plugins 页直接打开; - 项目级扩展目录:默认为
.tiled-project文件所在目录下的extensions,可在 Project Properties 中修改。注意自 Tiled 1.7 起,打开非新建项目时需手动允许启用脚本扩展; - 目录内的脚本(或子目录中的脚本)会在启动时全部执行;扩展目录中新增/删除/修改文件会自动重载脚本引擎,无需重启 Tiled;
- 使用
.mjs扩展名可将脚本作为 JavaScript 模块加载(自 Tiled 1.8),支持import/export拆分代码且不污染全局作用域。
除扩展目录外,脚本还可通过以下方式运行:
- Console 视图:View > Views and Toolbars > Console 中可直接输入/粘贴脚本表达式求值,上下方向键可浏览历史;
- 命令行:
tiled --evaluate script.js(或-e),可多次传入执行多个脚本;命令行模式下 UI 不会实例化,但加载/保存地图、图块集(tiled.mapFormats、tiled.tilesetFormats)等不依赖界面的操作均可用;脚本文件后的额外参数会以tiled.scriptArguments暴露给脚本(scripting.rst)。
注册完成后,新格式会出现在 File > Export(导出地图)与图块集保存对话框中,并可通过 --export-map <文件> <格式shortName> 之类的命令行流程直接使用。
方案二:Python 插件(受平台限制,不推荐)
2.1 使用前提与重要警告
官方文档 python.rst 对 Python 方案给出了非常明确的警告:
- 平台限制:macOS 官方发行版与 Ubuntu snap 版不支持 Python 插件;Linux AppImage 构建基于 Ubuntu 22.04 的 Python 3.10,需安装完全一致的版本(Ubuntu 为
libpython3.10,Fedora 为python3.10-libs);Windows 10+ 构建需要 Python 3.12,Windows 7-8 构建需要 Python 3.8,且安装时需勾选 "Add python.exe to PATH"; - 默认禁用:自 Tiled 1.2.4 起 Python 插件默认关闭(取决于系统 Python 版本,加载可能导致崩溃,见 python.rst 引用的 issue #2091),使用前需在 Preferences 中手动启用;
- 由于上述种种苛刻条件,官方明确"不推荐使用",凡能用 JavaScript 实现的场景应优先选择 JavaScript。
2.2 脚本放置与热加载
- 脚本需放在
~/.tiled目录;Windows 下可在cmd.exe中执行mkdir .tiled创建(Linux 下隐藏文件夹可用Ctrl+H切换显示); - Tiled 会监听该目录变化,新增/修改脚本无需重启即可生效(但目录必须在 Tiled 启动时已存在)。
2.3 官方示例:导出 CSV 风格图块矩阵
文档给出了一个完整示例(python.rst):假设希望把地图导出为每行图块 ID 以逗号分隔、最后一行以分号结尾的文本格式,将以下 example.py 放入脚本目录即可:
from tiled import *
class Example(Plugin):
@classmethod
def nameFilter(cls):
return "Example files (*.example)"
@classmethod
def shortName(cls):
return "example"
@classmethod
def write(cls, tileMap, fileName):
with open(fileName, 'w') as fileHandle:
for i in range(tileMap.layerCount()):
if isTileLayerAt(tileMap, i):
tileLayer = tileLayerAt(tileMap, i)
for y in range(tileLayer.height()):
tiles = []
for x in range(tileLayer.width()):
if tileLayer.cellAt(x, y).tile() != None:
tiles.append(str(tileLayer.cellAt(x, y).tile().id()))
else:
tiles.append(str(-1))
line = ','.join(tiles)
if y == tileLayer.height() - 1:
line += ';'
else:
line += ','
print(line, file=fileHandle)
return True
保存后,在 File > Export 的类型下拉框中就会出现 "Example files" 选项。官方同时提醒:该示例不支持组图层(Group Layer)。绑定的辅助函数 isTileLayerAt / tileLayerAt(以及 isObjectGroupAt / objectGroupAt 等)用于在遍历 layerCount() 时安全地按类型获取图层。
2.4 图块集插件与调试
- 编写图块集插件时,将类继承自
tiled.TilesetPlugin而非tiled.Plugin(自 Tiled 1.11 起)。仓库 src/plugins/python/scripts/tileset.py 提供了一个精简示例:通过tileset.tileCount()与tileset.tileAt(idx)遍历并写出每个图块的 id、type 与宽高; - 脚本解析或运行期间的任何错误都会打印到 Console(View > Views and Toolbars > Console);
- 从源码结构看,Python 绑定由 tiledbinding.py 通过 pybindgen 生成:C++ 侧
PythonScript类在 Python 侧表现为tiled.Plugin,PythonTilesetScript表现为tiled.TilesetPlugin(tiledbinding.py),并实现了LoggingInterface用于向 Tiled 输出日志(INFO/WARNING/ERROR); - 仓库中还自带多个真实示例脚本:fotf.py(Fury of the Furries 关卡加载器,实现了
read与supportsFile)、mappy.py、pk2.py、zst.py 等,均可作为参考。
方案三:C++ 原生插件(Tiled 自带格式的实现方式)
3.1 API 概况
Tiled 随发行版自带的所有导出格式(csv、defold、gmx、json、json1、lua、tbin、tscn、yy、rpd、rpmap、flare、droidcraft、replicaisland、tengine 等)均为 C++ 插件,完整清单见 src/plugins/plugins.qbs。C++ 插件 API 没有独立文档,仅以 libtiled 源码中的 Doxygen 风格注释形式存在,但仓库提供了十几个可直接参考的实现范例。
核心抽象类为 Tiled::FileFormat(src/libtiled/fileformat.h),其关键成员:
| 成员 | 类型 | 说明 |
|---|---|---|
Capabilities capabilities() |
虚函数 | 返回 Read/Write/ReadWrite 能力位 |
nameFilter() |
纯虚函数 | 文件对话框过滤器字符串 |
shortName() |
纯虚函数 | 格式短名,用于命令行指定格式 |
supportsFile(fileName) |
纯虚函数 | 通常做文件扩展名检查 |
errorString() |
纯虚函数 | 读写出错时反馈给用户的错误信息 |
WriteMinimized |
Option 枚举 | 写入选项(最小化输出,如压缩 JSON) |
地图格式继承 MapFormat、图块集格式继承 TilesetFormat;插件通过 PluginManager 注册对象(如 src/tiled/scriptedfileformat.cpp 中 ScriptedMapFormat 构造时调用 PluginManager::addObject(this) 的机制一致)。文件对话框可用 FormatHelper<Format> 模板按能力位聚合所有已注册格式的过滤器(src/libtiled/fileformat.h),命令行则可通过 findFileFormat(shortName, capabilities) 按短名查找目标格式。
3.2 参考示例:tbin 插件结构
以 src/plugins/tbin 为例,一个完整插件包含:
plugin.json:插件元数据(名称、版本、依赖等);tbin.qbs:qbs 构建描述,声明对 libtiled 的依赖;tbinmapformat.h/.cpp:TbinMapFormat地图格式实现;tidemapformat.h/.cpp:TideMapFormat(同插件中的另一个格式);tbinplugin.h/.cpp:插件入口类,负责把格式对象注册进 PluginManager;- 头文件子目录
tbin/:Layer、Tile、TileSheet、PropertyValue 等格式自身的运行时数据结构。
其他格式(如 src/plugins/defold、src/plugins/json、src/plugins/lua)结构类似,均遵循"格式类 + 插件入口类 + qbs + plugin.json"的约定。
3.3 二进制兼容性要求(务必注意)
官方文档特别强调(export-custom.rst):出于二进制兼容性考虑,C++ 插件必须用与目标 Tiled 完全相同的平台、编译器以及相同版本的 Qt 和 Tiled 编译。实践中最简单的做法是随 Tiled 一起编译插件——Tiled 自带的所有插件正是如此。如果你编写了可能对他人有用的 C++ 插件,官方建议通过 Pull Request 将其随 Tiled 一同发布,这正是仓库中 csv、defold、tbin 等插件得以长期维护的途径。
如何选择:决策建议
- 绝大多数场景:使用 JavaScript 脚本格式。API 完整、全平台可用、热重载迭代快,且支持控制台与命令行两种调试/执行方式;
- 仅当历史项目已存在 Python 脚本:可考虑 Python 插件,但务必先确认目标平台的 Python 版本与插件可用性(macOS/snap 不可用、Linux 需精确匹配 Python 3.10、Windows 需 3.8 或 3.12),并到 Preferences 中手动启用;
- 需要深度集成或性能敏感:选择 C++ 插件,但需接受与 Tiled 捆绑编译的约束,并以 src/plugins 下的十余个插件为模板。
相关资源索引
- 官方手册原文:docs/manual/export-custom.rst
- JavaScript 脚本系统:docs/manual/scripting.rst
- Python 脚本说明:docs/manual/python.rst
- 脚本 API 类型定义(含
ScriptedMapFormat、registerMapFormat等完整签名与示例):docs/scripting-doc/index.d.ts - 脚本格式桥接实现:src/tiled/scriptedfileformat.cpp、src/tiled/scriptmodule.cpp
- 格式基类与工具:src/libtiled/fileformat.h
- Python 插件实现与示例脚本:src/plugins/python
- C++ 插件范例:src/plugins/tbin、src/plugins/defold、src/plugins/json、src/plugins/lua