游戏引擎 / 系统课时

从 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。

  1. 选择 File > New > New Map,设置 Orientation: Orthogonal、固定尺寸 40×18 格、Tile size: 32×32 px、Tile layer format: CSV,关闭 Infinite。
  2. 将源地图保存为 public/assets/maps/level-01.tmx。
  3. 选择 File > New > New Tileset,名称填 terrain,类型选 Based on Tileset Image,指定 terrain.png;图块宽高均为 32,Margin 与 Spacing 都为 0。
  4. 不勾选 Embed in map,将图块集源文件保存为 public/assets/tiles/terrain.tsx,方便其他关卡复用。

地图实际尺寸是 1280×576 像素;这张图块集有 64 块。若 PNG 宽高或边距不符合上述设置,Tiled 的切格预览就会错位,应先修正再绘制。

绘制图层并导出

将新地图自带的图块层改名为 Ground,用图块笔刷在最底部两行铺设地面;再从图层面板新增一个 Tile Layer,命名 Decor,在空中放置约 5 处装饰。让 Decor 位于 Ground 上方,且两个图层都保持可见。名称中的大小写必须固定,后续代码会按原名寻找图层。

  1. 打开 Edit > Preferences > General > Export Options,启用 Embed tilesets。这会把外部 .tsx 的定义写入导出的地图 JSON,但不会嵌入 PNG 像素。
  2. 通过 File > Export As 选择 JSON map files,导出到 public/assets/maps/level-01.json。保留 .tmx 和 .tsx 作为编辑源文件,不要用导出文件覆盖它们。
  3. 用文本编辑器打开 JSON,确认含有 layers 与 tilesets,且图块层的数据是数字数组,而不是压缩的 Base64 字符串。

Tiled 图层、JSON 与独立图块图片的数据流关系

核对图块编号和资源路径

导出的 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。

js
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 存在');

预期输出:

text
通过: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/。脚本检查通过、浏览器两项资源均能成功加载且地面与装饰正确显示,才算完成这张关卡地图的导出验收。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

从 Tiled 导出 JSON 地图

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通