游戏引擎 / 系统课时
读取对象层中的出生点和终点
读取对象层中的出生点和终点
把玩家出生点和终点写死在代码里,每次改关卡都要重新量坐标。本篇用 Tiled 的对象层保存一个点标记和一个矩形区域,再在 Phaser 4.2.1 中读取它们,完成玩家放置、终点检测和一次性通关提示。
学习目标
- 在 Tiled 中为
spawn和goal设置可读取的名称、坐标与尺寸。 - 使用
getObjectLayer()将点对象映射到玩家,将矩形对象映射到 Arcade Physics 触发区。 - 根据坐标与碰撞范围验证关卡入口和出口。
在 Tiled 中布置标记
以 Tiled 1.11 及以上版本为例,新建正交地图:宽 40 格、高 12 格,每格 32×32 像素,地图总尺寸 1280×384 像素。图块层可以暂时留空;本例只读取对象层,不依赖图块图片。
- 在「图层」面板新增「对象层(Object Layer)」,命名为
Markers。 - 选中该层,使用点对象工具(快捷键
I)放一个点;在「属性」面板将名称设为spawn,位置设为x=64, y=160。 - 使用矩形工具(快捷键
R)绘制终点区域;名称设为goal,x=1120, y=112,宽64、高96,旋转保持0°。 - 通过「文件 → 导出为(Export As)」选择 JSON 地图格式,保存为项目中的
public/maps/level01.json。检查导出的layers数组中存在name: Markers、type: objectgroup,并且有且仅有一个spawn和一个goal。
Markers 是层名,spawn、goal 是对象名,三者区分大小写。点对象的宽高为 0,适合标记位置;矩形对象必须有非零宽高,才能形成触发范围。
从 JSON 创建玩家和终点
下面用 Vite 的原生 JavaScript 模板搭建最小项目,安装固定版本 Phaser。终端执行:
npm create vite@latest tiled-markers-demo -- --template vanilla
cd tiled-markers-demo
npm install
npm install phaser@4.2.1
npm run dev预期结果:Vite 打印本地开发地址(通常为 http://localhost:<PORT>/,实际端口可能不同)。保持开发服务器运行,把上一节的地图 JSON 放入 public/maps/,再用以下完整代码替换 src/main.js:
import Phaser from 'phaser';
class LevelScene extends Phaser.Scene {
constructor() {
super('LevelScene');
}
preload() {
this.load.tilemapTiledJSON('level01', '/maps/level01.json');
}
create() {
const map = this.make.tilemap({ key: 'level01' });
const markers = map.getObjectLayer('Markers');
if (!markers) throw new Error('地图缺少 Markers 对象层');
// 名称作为关卡约定;缺失或重名都应在初始化时报告。
const spawns = markers.objects.filter((o) => o.name === 'spawn');
const goals = markers.objects.filter((o) => o.name === 'goal');
if (spawns.length !== 1 || goals.length !== 1) {
throw new Error('需要且只能有一个 spawn 和一个 goal');
}
const spawn = spawns[0];
const end = goals[0];
if (end.width <= 0 || end.height <= 0) {
throw new Error('goal 必须是有尺寸的矩形对象');
}
this.physics.world.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
this.add.rectangle(map.widthInPixels / 2, 190, map.widthInPixels, 2, 0xcbd5e1);
// 点标记定义角色中心;矩形标记定义触发区左上角。
this.player = this.add.rectangle(spawn.x, spawn.y, 24, 32, 0x159c92);
this.physics.add.existing(this.player);
this.player.body.setAllowGravity(false).setCollideWorldBounds(true);
const goal = this.add.rectangle(
end.x + end.width / 2, end.y + end.height / 2,
end.width, end.height, 0xf4ac61, 0.35
).setStrokeStyle(2, 0xba7424);
this.physics.add.existing(goal, true);
this.finished = false;
// overlap 只检查相交;避免角色停在终点时每帧重复通关。
this.physics.add.overlap(this.player, goal, () => {
if (this.finished) return;
this.finished = true;
this.player.body.setVelocity(0, 0);
this.add.text(goal.x, goal.y - 65, '已到达终点', {
fontSize: '24px', color: '#243746'
}).setOrigin(0.5);
});
this.keys = this.input.keyboard.createCursorKeys();
this.cameras.main.startFollow(this.player);
}
update() {
if (this.finished) return;
const direction = Number(this.keys.right.isDown) - Number(this.keys.left.isDown);
this.player.body.setVelocityX(direction * 180);
}
}
new Phaser.Game({
type: Phaser.AUTO,
parent: 'app',
width: 640,
height: 384,
backgroundColor: '#f7f9fc',
physics: { default: 'arcade', arcade: { debug: false } },
scene: [LevelScene]
});预期结果:浏览器出现青绿色玩家方块;按住右方向键,玩家以每秒 180 像素向右移动,镜头跟随;进入橙色矩形区域后显示一次“已到达终点”并停止。这里有意不渲染图块层,以便只验证对象层读取与触发逻辑。
校准世界坐标与触发范围
Tiled 点对象的 (64,160) 直接作为玩家中心点;代码中的 Phaser 矩形默认以中心定位,所以无需额外偏移。终点是 Tiled 普通矩形,其 (1120,112) 表示左上角,宽 64、高 96,因此 Phaser 中应使用中心 (1152,160),而不是 (1120,112)。

这套映射假定地图与物理世界的左上角都是 (0,0),没有额外缩放或独立平移。如果实际角色精灵以脚底中心为原点 (0.5,1),就应让 Tiled 的出生点标记脚底位置,并统一使用同一约定,不能混用本例的中心点语义。
验证与修正常见偏移
打开浏览器开发者工具的 Network 面板,确认 /maps/level01.json 返回成功,而不是 404;随后在场景运行时逐项检查:
- 初始化报缺层或重名:核对 Tiled 的对象层是否确实叫
Markers,对象名是否是小写spawn、goal,并检查是否重复放置。 - 出生点偏移半个角色高度:检查项目里的 Sprite
origin。若出生点表示脚底而角色用中心原点,必须按角色半高换算,不能在多个文件各自加一个魔法常量。 - 终点触发范围向右下偏移:常见原因是直接把 Tiled 矩形左上角传给 Phaser 的中心定位接口;改用
x + width / 2和y + height / 2。 - 视觉重叠却不触发:确认双方都有 Arcade Body,注册的是
this.physics.add.overlap()而不是仅创建普通显示对象。若在创建静态 Body 之后调整其位置或尺寸,还需要调用goal.body.updateFromGameObject()同步。
验收时,把 Tiled 中的 spawn 从 x=64 改成 x=128 并重新导出、刷新页面;玩家应随地图数据向右移动 64 像素,而无需修改 JavaScript。这样才能证明出生点真正由对象层驱动。