# 第七课（最后一课）· LDtk 关卡数据驱动

**课件地址**：https://deepnight.47-103-217-57.nip.io/03-Toolchain/Lesson-02-LDtk-Data/

源码目录：D:\CursorProject\DeepnightLab\Tutorial\03-Toolchain\Lesson-02-LDtk-Data

## 学习目标

亲手修改墙体、起点和终点，观察 LDtk 文件结构中的改动为什么不会自动影响已创建的 Level；按一次“应用地图并重建”，再用 WASD / 手机方向键真正撞墙，或用 BFS 检查是否还能从起点走到目标。

本课的核心教学路径：

1. **体验游戏**：运行时 Level 从真实 LDtk IntGrid 建立墙体缓存。移动按键查询缓存，碰壁不能前进。
2. **改变数据但不构建**：在左侧画一堵墙，右侧地图仍旧保持原状，碰撞状态也不改变。
3. **应用编辑结果**：点击重建，运行时复制新的碰撞数组，从 PlayerStart 生成玩家并把 Goal 转换为胜利条件。
4. **更换实体位置、寻路和文件导出**：移动目标后查看 BFS 是否仍可达，并下载修改后、保留原项目结构的 .ldtk。
5. **对照作者 Haxe 源码**：重点看 World.hx 在编译期生成类型、Level.hx 在初始化时构建 MarkerMap、Game.hx 选择关卡。

## 实际 LDtk 数据来自哪里

本课的数据文件为 data/learning-world.ldtk（项目版本 jsonVersion 1.5.0）。它由 scripts/create-ldtk-course-fixture.cjs 从被冻结的原作者 GameBase 示例文件 third_party/gameBase/res/levels/sampleWorld.ldtk 派生：保留 LDtk 项目世界、定义、layerInstances 等真实字段，同时把地图独立缩小为 12×9、16 像素/格，去掉原项目美术依赖，设置新的墙体布局，并添加一个 Goal 实体定义和实例。生成逻辑不会修改第三方原文件。

真实字段层级：

- worlds[0].levels[0]：本课程的 Playground 关卡。
- layerInstances：Entities 和 Collisions 两层。
- Collisions.intGridCsv：108 个数字，0 为地面、1 为不可通过墙；行优先，index = x + y × 12。
- Entities.entityInstances：恰好两个实体，PlayerStart 和 Goal；有 __identifier、__grid、px、defUid、iid 等 LDtk 字段。
- defs.entities：包含 PlayerStart、Goal 的实体定义；为了不依赖原有 Aseprite 图片，设为 Rectangle 渲染模式。

**关键限制**：网页只支持这个教学约定的内嵌关卡格式，导入的 .ldtk 必须含 Collisions 和 Entities 层以及恰好一个 PlayerStart 和 Goal；不支持外置 .ldt 文件、复杂 auto-tiles、多个层级、其他 IntGrid 类型的所有语义。因此这是依据真实 LDtk JSON 写出的**简化教学运行时**，不是 LDtk 编辑器本体，也不是全面兼容所有项目的 LDtk 加载器。导出的文件结构以 LDtk 1.5.0 示例为基础；没有在 LDtk 图形编辑器中验证所有编辑操作和跨版本兼容性，不承诺可在任意版本打开。

## 和 Unity 类比

| LDtk / Deepnight | Unity 中接近的对应物 | 限制 |
|---|---|---|
| LDtk .ldtk / IntGrid | Tilemap 数据 / ScriptableObject / 场景中的关卡资源 | 数据不等于物理碰撞本身 |
| World.hx 的 Project.build 宏 | 根据资产自动生成类型安全的代码/访问器 | 真正生成发生于 Haxe 构建期，不是每帧反射 JSON |
| Level.hx 初始化 MarkerMap | Unity 的地图碰撞缓存 / 逻辑网格构建 | 原项目具体代码使用 dn.MarkerMap |
| Game.startLevel | 场景或关卡流程管理器 | 决定要切换哪个关卡及清理旧运行时状态 |
| Level.invalidate / postUpdate | Dirty Flag + 延迟重绘 | 不会每次碰撞查询都重建渲染 |

## 原作者真实源码（冻结的 GameBase）

1. third_party/gameBase/src/game/assets/World.hx：

~~~haxe
package assets;
private typedef _Tmp =
    haxe.macro.MacroType<[ ldtk.Project.build("res/levels/sampleWorld.ldtk") ]>;
~~~

2. third_party/gameBase/src/game/Level.hx：

~~~haxe
data = ldtkLevel;
cWid = data.l_Collisions.cWid;
cHei = data.l_Collisions.cHei;
marks = new dn.MarkerMap(cWid, cHei);
for (cy in 0...cHei)
for (cx in 0...cWid) {
    if (data.l_Collisions.getInt(cx,cy)==1)
        marks.set(M_Coll_Wall,cx,cy);
}

public inline function hasCollision(cx,cy) : Bool {
    return !isValid(cx,cy) ? true : marks.has(M_Coll_Wall,cx,cy);
}
~~~

3. 第三方 Level.hx 的 invalidate() 将 invalidated 设为 true，postUpdate() 中只在脏状态下执行 render()，之后清除该标记。该行为属于渲染，不意味着所有碰撞查询都触发重建。

4. third_party/gameBase/src/game/Game.hx：从 Assets.worldData.all_worlds.SampleWorld.all_levels.FirstLevel 中选取关卡，startLevel 创建 new Level(l)，并处理旧关卡生命周期。

原作者 GameBase 仓库：https://github.com/deepnight/gameBase （本地快照固定在 a7af1d70dbbf62d7fc09cb05431ced606e0ed809）。

项目资料：https://ldtk.io/ 和 https://ldtk.io/json/

## 教学运行时与作者原版的区别

- 本课使用网页 JS 对 .ldtk 做一次 JSON.parse（真正读取文件），把 intGridCsv 复制到 Uint8Array，之后走一步只做一次 O(1) 数组索引碰撞查询。
- 作者 GameBase 使用 **Haxe + LDtk 生成类型 + dn.MarkerMap + Heaps**，不是这个 JS 教学模型。
- 浏览器的左侧模拟一个极简编辑器。按“应用并重建”将编辑数据重新复制为 Level；并不宣称原版支持运行时热编辑或按按钮导入整个关卡。
- 本课还实现 BFS 以说明导航缓存/遍历成本；并不是作者框架直接提供或使用这一段 BFS。

## 性能审计

- **首次加载**：解析 JSON 和读出 N 格，时间和空间为 O(N)（项目其它元数据也占大小）；本课大小为 12×9 = 108 格，不能由此估算大型世界的精确帧耗时。
- **重建 Level**：每次完整 Uint8Array.from() 复制碰撞数组，O(N) 时间和空间；适合教学，不必等同于最佳动态地图更新策略。
- **运行时单格移动**：计算目标格位置、读取固定下标碰撞，O(1)，无须查找所有墙或重新解析 LDtk 文件。
- **BFS 寻路**：在二维栅格上 O(V+E)；四邻居意味着 O(N) 时间与空间。教学使用整型 parent/queue 缓冲，每次点击才进行，而不是每帧做一遍。
- **真正动态拆墙**：值得考虑“只写对应格 + 标记渲染 dirty + 按需更新导航缓存”，避免每一处变化都导入全套关卡。
- **JSON 与资产开销**：大项目还可能使用外置 level 文件、图层、tileset、美术资源，不能仅凭 IntGrid 数组就估算渲染和加载总成本。

## 自测

1. 编辑器改成空地后，为什么运行时的角色仍撞到旧墙？
2. Level.hasCollision 读取的是 IntGrid JSON 还是已经建立的运行时标记？
3. 输入地图数据文件、构建实体和实时绘制三件事，是否一定必须由同一个类完成？
4. 如果一个大型地图每秒拆除多格墙，哪些缓存需要同步，又有哪些操作不必全量重建？

### 验收命令

在二号机 DeepnightLab 根目录：

~~~powershell
node Tutorial\tests\run-tests.cjs
node scripts\test-ldtk-lesson.cjs
~~~

第二条需要本地课件服务运行；测试包含真正的手机/桌面浏览器交互、数据编辑与运行时隔离、碰撞、BFS、LDtk 导出与导入。