3步打造专属地图导出器：Tiled插件开发实战指南

你是否还在为游戏地图格式不兼容发愁？是否想让Tiled直接导出引擎原生支持的地图文件？本文将带你从零开始开发Tiled插件，30分钟内打造专属地图导出器，彻底解决地图格式转换难题。读完本文你将掌握：JavaScript插件开发全流程、地图数据解析技巧、自定义导出器调试方法，以及发布插件的最佳实践。

插件开发准备工作

Tiled地图编辑器（Tiled Map Editor）提供了强大的插件系统，支持通过JavaScript扩展功能。开发自定义导出器前需要了解插件的工作环境和文件结构。

开发环境配置

Tiled插件使用JavaScript编写，支持ES6+特性。推荐使用VS Code配合TypeScript类型定义获得更好的开发体验：

npm install @mapeditor/tiled-api --save-dev

插件文件需放置在Tiled的扩展目录中，不同操作系统的默认路径如下：

操作系统	扩展目录路径
Windows	C:/Users/<USER>/AppData/Local/Tiled/extensions/
macOS	~/Library/Preferences/Tiled/extensions/
Linux	~/.config/tiled/extensions/

你也可以通过编辑 > 首选项 > 插件打开扩展目录。Tiled会自动监测扩展目录变化，无需重启即可加载更新的插件docs/manual/scripting.rst。

项目结构设计

一个标准的Tiled插件项目结构如下：

my-exporter/
├── main.mjs          # 插件入口文件
├── exporter.js       # 导出逻辑实现
├── icon.png          # 插件图标
└── README.md         # 使用说明

使用.mjs扩展名可以启用ES模块支持，避免全局作用域污染docs/manual/scripting.rst。我们将以导出JSON格式的简化地图数据为例，完整实现一个实用的地图导出器。

核心实现：3步打造导出器

第1步：注册导出格式

首先创建插件入口文件main.mjs，使用tiled.registerMapFormat API注册新的地图导出格式：

// main.mjs
import { exportCustomMap } from './exporter.js';

tiled.registerMapFormat('custom-json', {
    name: 'Custom JSON Map',
    extension: 'json',
    write: (map, fileName) => exportCustomMap(map, fileName)
});

console.log('Custom JSON exporter loaded!');

这段代码向Tiled注册了一个名为"Custom JSON Map"的导出格式，文件扩展名为.json，并指定了导出函数docs/manual/export-custom.rst。

第2步：实现地图数据解析

创建exporter.js文件，实现地图数据的解析和转换逻辑。以下代码演示如何提取地图基本信息、图层数据和 tileset 信息：

// exporter.js
export function exportCustomMap(map, fileName) {
    // 基本地图信息
    const mapData = {
        width: map.width,
        height: map.height,
        tileWidth: map.tileWidth,
        tileHeight: map.tileHeight,
        layers: []
    };

    // 遍历所有图层
    for (const layer of map.layers) {
        if (layer.isTileLayer) {
            mapData.layers.push(exportTileLayer(layer));
        }
    }

    // 保存为JSON文件
    const file = new TextFile(fileName, TextFile.WriteOnly);
    file.write(JSON.stringify(mapData, null, 2));
    file.commit();
}

function exportTileLayer(layer) {
    // 处理瓦片图层数据
    const layerData = {
        name: layer.name,
        width: layer.width,
        height: layer.height,
        data: []
    };

    // 提取瓦片ID数据
    for (let y = 0; y < layer.height; y++) {
        for (let x = 0; x < layer.width; x++) {
            const cell = layer.cellAt(x, y);
            layerData.data.push(cell.tileId || 0);
        }
    }

    return layerData;
}

这段代码实现了基本的瓦片图层导出功能，你可以根据需要扩展以支持对象层、图像层等更多元素docs/manual/scripting.rst。

第3步：添加自定义配置界面

对于复杂的导出需求，我们可以添加配置界面让用户调整导出选项。以下是添加导出配置对话框的示例：

// 在exportCustomMap函数中添加
const options = tiled.showPopupDialog(
    "Custom JSON Export Options",
    "请选择导出选项",
    [
        { text: "仅导出可见图层", checkable: true, checked: true },
        { text: "包含瓦片碰撞数据", checkable: true, checked: false }
    ]
);

if (!options) return false; // 用户取消导出

// 根据选项调整导出逻辑
const exportVisibleOnly = options[0].checked;
const includeCollision = options[1].checked;

Tiled提供了多种UI组件，可用于创建复杂的配置界面docs/manual/scripting.rst。

测试与调试

插件加载与测试

将插件文件夹复制到Tiled扩展目录后，通过文件 > 导出为菜单即可看到我们注册的"Custom JSON Map"格式。选择该格式并指定保存路径，即可导出地图文件。

推荐使用Tiled的控制台视图（视图 > 视图和工具栏 > 控制台）进行调试，可通过console.log输出调试信息，使用上下方向键查看历史命令docs/manual/scripting.rst。

常见问题解决

1. 插件不加载：检查文件扩展名是否正确（.mjs或.js），确保没有语法错误。
2. 导出无反应：检查权限问题，确保目标文件夹可写。
3. 数据不完整：确认是否正确处理了所有图层类型，Tiled支持瓦片层、对象层、图像层等多种图层类型。

高级功能与发布

添加自定义图标

为插件添加图标需要在注册格式时指定icon属性：

tiled.registerMapFormat('custom-json', {
    // ... 其他属性
    icon: 'icon.png' // 相对于插件目录的路径
});

图标建议使用24x24像素的PNG图片，支持透明背景docs/manual/scripting.rst。

发布与分享

开发完成的插件可以发布到Tiled扩展仓库，或直接分享给团队成员。推荐的项目结构应包含：

• 完整的README.md说明文件
• 插件图标和截图
• 版本历史和更新日志

Tiled官方扩展仓库提供了大量示例插件，可作为开发参考docs/manual/scripting.rst。

实战案例：游戏地图导出器

以下是一个完整的游戏地图导出器示例，支持导出为简化的JSON格式，包含图层数据和对象信息：

这个导出器可以将Tiled地图转换为游戏引擎直接可用的格式，大大简化了地图导入流程。类似地，你可以根据自己的游戏引擎需求，定制导出数据结构。

总结与展望

通过本文介绍的方法，可以快速开发Tiled插件扩展其功能。Tiled的JavaScript API功能丰富，除了自定义导出器，还可以开发自定义工具、自动化操作脚本等。

建议进一步学习：

• Tiled Scripting API完整文档docs/manual/scripting.rst
• TypeScript类型定义使用
• 高级UI组件和交互设计

希望本文能帮助你解决地图格式转换的痛点，提高游戏开发效率。如有任何问题或插件开发经验分享，欢迎在评论区留言交流！

本文示例代码基于Tiled 1.9版本，不同版本API可能略有差异，请参考对应版本的文档。