Tiled 自定义导出格式完整指南:基于 JavaScript、Python 与 C++ 插件扩展地图与图块集格式

原创2026-09-21 12:52:471,915 阅读
文章标签:游戏开发桌面应用开发工具图形学

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 等插件得以长期维护的途径。

如何选择:决策建议

  1. 绝大多数场景:使用 JavaScript 脚本格式。API 完整、全平台可用、热重载迭代快,且支持控制台与命令行两种调试/执行方式;
  2. 仅当历史项目已存在 Python 脚本:可考虑 Python 插件,但务必先确认目标平台的 Python 版本与插件可用性(macOS/snap 不可用、Linux 需精确匹配 Python 3.10、Windows 需 3.8 或 3.12),并到 Preferences 中手动启用;
  3. 需要深度集成或性能敏感:选择 C++ 插件,但需接受与 Tiled 捆绑编译的约束,并以 src/plugins 下的十余个插件为模板。

相关资源索引

登录后查看全文
tiled