游戏引擎 / 系统课时

在场景中创建 Tilemap 图层

在场景中创建 Tilemap 图层

地图 JSON 已加载却没有地面,通常是因为还没把图块集图片绑定到地图,也没创建真正参与渲染的图层。本课以一张 40×20 格的 Tiled 地图为例,建立地面与装饰图层,并核对图层位置和地图像素尺寸。

学习目标

  • 区分 Tilemap 数据、Tileset 贴图和可见的 TilemapLayer。
  • 使用 Phaser 4.2.1 加载 Tiled JSON、注册图块集并创建两层地形。
  • 通过控制台输出和世界坐标检查地图是否正确显示。

准备地图和贴图

以下使用 Phaser 4.2.1 与 Vite 的原生 JavaScript 工程;已有对应工程可跳过初始化。

bash
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 中准备一张可复现的地图:

  1. 新建 Orthogonal(正交)、Fixed(固定大小) 地图,设为 40 列×20 行,每个瓦片 32×32 px。
  2. 使用一张按 32×32 px 网格排布、没有边距和间距的 PNG 图片创建单图图块集,命名为 terrain,将其嵌入地图,而不是只引用外部 .tsx。
  3. 创建两个 Tile Layer,名称严格为 Ground 和 Decor;在 Ground 画地面,在 Decor 放少量装饰,两个图层均保持可见、偏移量为 0。
  4. 导出未压缩的 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"。

js
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 中的关键四行):

text
地图: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、装饰图块与地面网格对齐。

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

目录与阅读设置

阅读设置

17

记录一个想法

在场景中创建 Tilemap 图层

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

登录哪都通