游戏引擎 / 系统课时
在场景中创建 Tilemap 图层
在场景中创建 Tilemap 图层
地图 JSON 已加载却没有地面,通常是因为还没把图块集图片绑定到地图,也没创建真正参与渲染的图层。本课以一张 40×20 格的 Tiled 地图为例,建立地面与装饰图层,并核对图层位置和地图像素尺寸。
学习目标
- 区分 Tilemap 数据、Tileset 贴图和可见的 TilemapLayer。
- 使用 Phaser 4.2.1 加载 Tiled JSON、注册图块集并创建两层地形。
- 通过控制台输出和世界坐标检查地图是否正确显示。
准备地图和贴图
以下使用 Phaser 4.2.1 与 Vite 的原生 JavaScript 工程;已有对应工程可跳过初始化。
npm create vite@latest tilemap-demo -- --template vanilla
cd tilemap-demo
npm install
npm install phaser@4.2.1预期结果:项目包含 index.html、src/main.js,且已安装 phaser@4.2.1;安装日志中的耗时与包数量依环境而异。
在 Tiled 中准备一张可复现的地图:
- 新建 Orthogonal(正交)、Fixed(固定大小) 地图,设为 40 列×20 行,每个瓦片 32×32 px。
- 使用一张按 32×32 px 网格排布、没有边距和间距的 PNG 图片创建单图图块集,命名为
terrain,将其嵌入地图,而不是只引用外部.tsx。 - 创建两个 Tile Layer,名称严格为
Ground和Decor;在Ground画地面,在Decor放少量装饰,两个图层均保持可见、偏移量为 0。 - 导出未压缩的 Tiled JSON 为
public/assets/level-01.json,图块集图片放在public/assets/terrain.png。
检查导出的 JSON:tilesets[0].name 应为 terrain,layers 内应有名为 Ground 和 Decor 的 tilelayer。Vite 会把 public/assets 下的文件映射到网址路径 /assets/。
地图数据怎样变成可见图层
tilemapTiledJSON 加载格子索引和图层数据,load.image 加载 PNG 像素;两者都不会单独把地图画出来。make.tilemap 从缓存取出地图,addTilesetImage('terrain', 'terrain-image') 把 Tiled 中的图块集名称与 Phaser 图片缓存键对应起来,最后 createLayer 才生成渲染对象。

本例的 Ground、Decor 是 地图图层名,terrain 是 Tiled 图块集名,terrain-image 是 Phaser 加载纹理时的键。三个名称承担不同职责,且都区分大小写。地图本身不是显示对象;真正能调整深度和位置的是 TilemapLayer。
创建并显示两层地形
将 Vite 模板的 src/main.js 替换为以下完整入口。模板 index.html 中的挂载容器应保留 id="app"。
import Phaser from 'phaser';
class LevelScene extends Phaser.Scene {
constructor() {
super('LevelScene');
}
preload() {
// 地图索引与实际贴图是两份独立资源
this.load.tilemapTiledJSON('level-01', '/assets/level-01.json');
this.load.image('terrain-image', '/assets/terrain.png');
}
create() {
const map = this.make.tilemap({ key: 'level-01' });
// Tiled 图块集名与 Phaser 纹理键分别匹配
const tileset = map.addTilesetImage('terrain', 'terrain-image');
if (!tileset) {
throw new Error('检查 terrain 图块集名称和 terrain-image 纹理');
}
const ground = map.createLayer('Ground', tileset, 0, 0);
const decor = map.createLayer('Decor', tileset, 0, 0);
if (!ground || !decor) {
throw new Error(`实际图层:${map.layers.map(l => l.name).join(', ')}`);
}
// 明确渲染顺序,后者显示在地面上方
ground.setDepth(0);
decor.setDepth(1);
this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
console.log(`地图:${map.width}×${map.height} 格`);
console.log(`瓦片:${map.tileWidth}×${map.tileHeight} px`);
console.log(`世界:${map.widthInPixels}×${map.heightInPixels} px`);
console.log(`图层:${ground.layer.name} / ${decor.layer.name}`);
}
}
new Phaser.Game({
type: Phaser.AUTO,
parent: 'app',
width: 800,
height: 450,
backgroundColor: '#e9eef2',
scene: [LevelScene]
});预期输出(使用上面指定的地图参数时,浏览器开发者工具 Console 中的关键四行):
地图:40×20 格
瓦片:32×32 px
世界:1280×640 px
图层:Ground / Decor运行 npm run dev,打开终端显示的本地地址。预期画面是一个 800×450 px 的视口,能看到地图左上部分:Ground 构成地面,Decor 叠在上方,没有放瓦片的区域露出背景色。
核对像素尺寸和渲染坐标
地图宽度和高度由 格子数×单格像素 得到:40×32=1280 px,20×32=640 px。游戏视口只有 800×450 px,因此起初看不到右侧 480 px 和下方 190 px 的世界区域,不代表地图加载不完整;后续移动摄像机才能看到这些位置。
本例图层起点是 (0, 0),瓦片坐标按列、行从 0 计数。第 (5, 3) 格左上角位于世界坐标 (5×32, 3×32)=(160, 96)。如果 createLayer 使用 (64, 32) 作为起点,该格就应位于 (224, 128)。检查装饰物是否落在相同格子上,可以快速发现图层偏移错误。
在浏览器开发者工具的 Network 中确认 level-01.json 与 terrain.png 均成功返回,再比对控制台尺寸。此处显式传入 0, 0 会覆盖 Tiled 图层原有偏移;若关卡需要保留编辑器中设置的偏移,应省略 createLayer 的位置参数并重新检查坐标。
创建失败时先查名称和资源
- 页面只有背景色:检查
public/assets下是否真有两个文件,Network 是否出现 404,以及Ground是否实际绘制过瓦片;不要通过file://直接打开页面。 - 无法绑定贴图:检查
addTilesetImage第一个参数是 Tiled 的terrain,第二个参数是load.image的terrain-image,不能把它们都误写成 PNG 文件名。 - 创建图层返回空值:核对 JSON 中的
layers[].name。createLayer面向瓦片层,不是对象层或图片层;若 Tiled 图层位于分组中,Phaser 的名称可能包含组名/图层名。 - 图片错位或图块切片混乱:确认 Tiled 和 PNG 使用同样的瓦片宽高、边距及间距;本例要求 32×32 px、边距 0、间距 0。外部
.tsx图块集需先嵌入地图再导出供本例使用。
通过验收的标志是:两个图层都能显示、控制台输出世界尺寸 1280×640、装饰图块与地面网格对齐。