游戏引擎 / 系统课时
从 Tiled 导出 JSON 地图
从 Tiled 导出 JSON 地图
制作一张 40×18 格的横向关卡,使用 32×32 像素图块,分别保存地面和装饰图层,再导出 Phaser 4 能读取的 JSON。完成后还能核对图块编号、贴图引用和文件路径,避免关卡加载后出现空白或错误贴图。
学习目标
- 用 Tiled 创建固定尺寸的正交地图和图片图块集。
- 将地图导出为包含图块集定义的 JSON,读懂图层数据与全局编号。
- 通过 Node.js 脚本验证地图结构和 PNG 路径。
创建地图与图块集
以下步骤适用于 Tiled 1.11~1.12。先准备一张 256×256 像素的 terrain.png:每块 32×32,共 8 列、8 行,图块之间没有留白。把图片放在 Vite 项目的 public/assets/tiles/terrain.png。
- 选择
File > New > New Map,设置Orientation: Orthogonal、固定尺寸40×18格、Tile size: 32×32 px、Tile layer format: CSV,关闭Infinite。 - 将源地图保存为
public/assets/maps/level-01.tmx。 - 选择
File > New > New Tileset,名称填terrain,类型选Based on Tileset Image,指定terrain.png;图块宽高均为32,Margin与Spacing都为0。 - 不勾选
Embed in map,将图块集源文件保存为public/assets/tiles/terrain.tsx,方便其他关卡复用。
地图实际尺寸是 1280×576 像素;这张图块集有 64 块。若 PNG 宽高或边距不符合上述设置,Tiled 的切格预览就会错位,应先修正再绘制。
绘制图层并导出
将新地图自带的图块层改名为 Ground,用图块笔刷在最底部两行铺设地面;再从图层面板新增一个 Tile Layer,命名 Decor,在空中放置约 5 处装饰。让 Decor 位于 Ground 上方,且两个图层都保持可见。名称中的大小写必须固定,后续代码会按原名寻找图层。
- 打开
Edit > Preferences > General > Export Options,启用Embed tilesets。这会把外部.tsx的定义写入导出的地图 JSON,但不会嵌入 PNG 像素。 - 通过
File > Export As选择JSON map files,导出到public/assets/maps/level-01.json。保留.tmx和.tsx作为编辑源文件,不要用导出文件覆盖它们。 - 用文本编辑器打开 JSON,确认含有
layers与tilesets,且图块层的数据是数字数组,而不是压缩的 Base64 字符串。

核对图块编号和资源路径
导出的 JSON 中,地图 width=40、height=18、tilewidth=32、tileheight=32。每个固定尺寸图块层的 data 应有 40×18=720 个元素,按行存放。GID 0 表示空格;若只有一个图块集,其 firstgid 通常是 1,因此 GID 1 对应图块集本地 ID 0,GID 2 对应本地 ID 1。
本例的 tilesets[0] 应包含 name: terrain、firstgid: 1、columns: 8、tilecount: 64,以及类似 ../tiles/terrain.png 的 image 相对路径。这个路径相对于 JSON 所在目录,而 source: ../tiles/terrain.tsx 表示外部图块集尚未内嵌,Phaser 内置 Tiled 解析器不能直接使用这种外部引用。
用脚本验收导出
在工程根目录创建 scripts/check-map.mjs,使用 Node.js 20 或更高版本运行。脚本按本例规格验证尺寸、图层数组长度、图块集是否内嵌以及相对图片路径。保存后执行 node scripts/check-map.mjs。
import { existsSync, readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
const file = resolve('public/assets/maps/level-01.json');
const map = JSON.parse(readFileSync(file, 'utf8'));
// 地图必须是固定尺寸、未压缩 CSV 图块层。
if (map.orientation !== 'orthogonal' || map.infinite ||
map.width !== 40 || map.height !== 18 ||
map.tilewidth !== 32 || map.tileheight !== 32) {
throw new Error('地图规格不符');
}
for (const name of ['Ground', 'Decor']) {
const layer = map.layers.find(x => x.type === 'tilelayer' && x.name === name);
if (!layer || !Array.isArray(layer.data) || layer.data.length !== 720) {
throw new Error(`${name} 图层缺失或非 CSV 数组`);
}
}
// Phaser 内置解析器需要导出文件携带 tileset 定义。
const set = map.tilesets.find(x => x.name === 'terrain');
if (!set || set.source || set.firstgid !== 1 ||
set.columns !== 8 || set.tilecount !== 64 ||
set.tilewidth !== 32 || set.tileheight !== 32) {
throw new Error('terrain 图块集定义不符');
}
if (!set.image || !existsSync(resolve(dirname(file), set.image))) {
throw new Error('找不到 terrain PNG');
}
console.log('通过:40×18;Ground/Decor 各 720 格;terrain 64 块;PNG 存在');预期输出:
通过:40×18;Ground/Decor 各 720 格;terrain 64 块;PNG 存在如果报 图层缺失或非 CSV 数组,回到 Map > Map Properties 检查 Tile Layer Format,再重新导出;如果提示找不到 PNG,检查导出目录和图块集的图片来源,修正后再次导出。
在 Phaser 中对应加载
Phaser 4.2.1 的 preload() 需要分别调用 this.load.tilemapTiledJSON('level', 'assets/maps/level-01.json') 和 this.load.image('terrain-image', 'assets/tiles/terrain.png')。在 create() 中从键 level 创建 Tilemap,再用 map.addTilesetImage('terrain', 'terrain-image') 绑定图片,最后按 Ground、Decor 这两个名称创建图层。
注意 terrain 是 Tiled 图块集名称,terrain-image 是 Phaser 图片缓存键,二者不要求相同,但必须分别对应正确。Vite 的 public 文件夹只是静态资源根目录,浏览器地址里不应包含 public/。脚本检查通过、浏览器两项资源均能成功加载且地面与装饰正确显示,才算完成这张关卡地图的导出验收。