Tutorial / 03 Toolchain / Lesson 02

最后一课 · 地图修改后,游戏为什么会变?

先试一个真正读取 LDtk .ldtk 项目 JSON 的双画面实验:左侧是关卡编辑数据,右侧是已经构建的运行时世界。修改墙壁并不会神奇地同步到正在运行的游戏;要经过读取数据 → 生成碰撞网格与实体 → 游戏运行。

本课使用真实 LDtk 字段:worlds → levels → layerInstances → Collisions.intGridCsv / Entities.entityInstances;不是自造的地图格式。运行时加载器、碰撞和寻路是本课独立写的教学代码,不是作者原版的 Haxe/Heaps 游戏。

① 改几格墙,再试着走过去

左边轻点格子修改关卡文件中的内容;右边是上次「应用地图」时构建出来的运行时状态。两边可以暂时不一样,这是刻意让你观察的数据边界。

点左侧地图时:
① LDtk 编辑数据尚无修改

点格子画墙或擦墙;也可以选择“移动起点/终点”。青色为起点,黄色为目标。

② 游戏运行时 Level第 1 次构建

键盘可使用 WASD / 方向键。每按一次移动一格,碰到墙会被真正挡住。

正在读取 LDtk .ldtk 文件…

运行时关卡构建—
编辑 / 运行时差异—
移动碰撞查询—
寻路扫描格数—
推荐只做三个动作:

① 用箭头走向目标,试试撞墙。② 左图选「擦除墙」,去掉挡路的一格,看看右图是否立即改变。③ 点击「应用地图」,再走一次或点「运行时寻路」。

② 这不是“绘制按钮”,而是一条数据流水线

LDtk 项目文件JSON / 网格 / 实体配置
→
加载与构建解析一次、复制碰撞数组、实例化角色
→
Level 运行时查询墙体 / 移动 / 寻路 / 目标判断
查看原始 LDtk 项目文件

导出保留 LDtk 的项目结构、layerInstances、IntGrid 和实体字段;导入目前只支持内嵌关卡、同名 Collisions / Entities 两层、且恰好有一个 PlayerStart 和 Goal 的教学约定。任意 LDtk 项目不一定符合这个简化运行时的要求。不会上传你的本地文件。

展开看看:修改前后实际保存在哪些 JSON 字段
等待读取数据…
Collisions.intGridCsv

按行展开的整数数组:index = x + y × width。教学约定 0=可通行、1=墙。它不是美术贴图。

Entities.entityInstances

__identifier 区分起点与终点;__grid 与 px 是相同实体的不同坐标表达。运行时需要自己解析并实例化。

应用地图

把当前编辑数据复制进运行时的网格,重建起点、目标和玩家状态。编辑器改动在应用前不会偷偷影响现有运行时。

③ 原版 Deepnight 是怎么连接 LDtk 的?

这次不是凭空画架构图:对照项目里的原始 World.hx、Level.hx、Game.hx。点击下面的代码看职责。

① 构建时生成类型
// gameBase/src/game/assets/World.hx
package assets;
private typedef _Tmp =
  haxe.macro.MacroType<[
    ldtk.Project.build("res/levels/sampleWorld.ldtk")
  ]>;

LDtk-Haxe API 在编译期从项目文件生成带类型的访问入口,而不是让业务逻辑到处手动找 JSON 键。

② Level 读碰撞数据
// gameBase/src/game/Level.hx
data = ldtkLevel;
cWid = data.l_Collisions.cWid;
cHei = data.l_Collisions.cHei;

if (data.l_Collisions.getInt(cx,cy)==1)
  marks.set(M_Coll_Wall,cx,cy);

把 LDtk 的 IntGrid 转成游戏使用的 MarkerMap。作者的 hasCollision 读的是这些运行时标记,不是反复解析 JSON。

③ 按需重新渲染
// gameBase/src/game/Level.hx
function invalidate() {
  invalidated = true;
}

// postUpdate():
if (invalidated) {
  invalidated = false;
  render();
}

数据、碰撞与绘制分开:标记 dirty,帧末决定是否重画。不要推断成每次碰撞查询都要重新构建地图。

④ 创建游戏关卡
// gameBase/src/game/Game.hx
startLevel(
  Assets.worldData.all_worlds
    .SampleWorld.all_levels.FirstLevel
);

// startLevel():
level = new Level(l);

Game 负责选择关卡,Level 负责自己的数据、碰撞和渲染。运行时的实体实例化需按项目代码明确实现。

完整引用与 Unity 类比见 LESSON.md 课件笔记。以上均为作者源码中对应位置的节选或省略式摘录;没有声称本课的 JS 类是原作者实现。

④ 性能:地图改一格,一定要重建全部吗?

读取 / 全量构建

IntGrid 有 N = 宽 × 高格,初始化运行时碰撞数组通常 O(N) 时间和空间。本课每次应用都完整复制,这是便于观察的教学选择。

单次碰撞查询

计算 x + y × width 直接索引,O(1),无需扫描所有墙,也不需要每帧读 JSON。

寻路的成本

本课使用 BFS,最坏时间与空间均为 O(N)。只在点击按钮时计算,不在每一帧做全地图寻路。队列用 head 指针避免频繁 shift。

运行时动态修改

如果真的需要运行时拆墙,可增量修改对应碰撞格并标记渲染 dirty,而不必反复完整导入 LDtk。要注意碰撞、导航缓存、贴图重绘等状态同步。

原版有 MarkerMap 和按需渲染机制;但这不意味着它直接支持这节课的热编辑器、导入文件或 BFS。这里的“编辑后应用重建”是独立教学工作流。

⑤ 三道自测题

完成全部七节课