Split game module documentation

2026-06-09 23:11:08 +08:00
parent d41f9d1096
commit 0257c8058e
15 changed files with 647 additions and 88 deletions
@@ -0,0 +1,66 @@
+# Data and Map
+
+## 职责
+
+数据模块负责把外部关卡数据转换成游戏运行时使用的 `LevelDefinition`。
+
+主要源码：
+
+- `game/src/data/level_definition.h`
+- `game/src/data/stage_map_resource.*`
+- `game/src/data/stage_map_loader.*`
+- `game/src/data/whitebox_level.cpp`
+- `game/assets/map/stage_01.map`
+
+## 数据流
+
+```text
+stage_01.map
+  -> StageMapResource
+  -> StageMapLoader
+  -> LevelDefinition
+  -> WhiteboxScene / StageRenderer / DebugOverlay
+```
+
+读取优先级：
+
+1. `Asset` 普通文本资源：`map/stage_01.map`
+2. `Asset` fallback：`assets/map/stage_01.map`
+3. `PvfArchive` 二进制脚本：`map/stage_01.map`
+4. `PvfArchive` 文本内容：`map/stage_01.map`
+
+## `LevelDefinition`
+
+当前包含：
+
+- 世界宽高。
+- 玩家出生点。
+- 摄像机边界。
+- 平台碰撞世界。
+- 场景视觉层。
+- battle zone。
+- enemy spawn point。
+
+## `.map` 当前命令
+
+```text
+map <id>
+world <width> <height>
+camera <x> <y> <width> <height>
+player_spawn <x> <y>
+collision <x> <y> <width> <height>
+layer <id> <BackgroundFar|BackgroundMid|LevelVisual|PropsBack|PropsFront> <parallax>
+rect <x> <y> <width> <height> <r> <g> <b> <a>
+rect_sprite <x> <y> <width> <height> <r> <g> <b> <a> <texture>
+rect_sprite_src <x> <y> <width> <height> <r> <g> <b> <a> <texture> <sx> <sy> <sw> <sh>
+endlayer
+battle_zone <id> <trigger_x> <trigger_y> <trigger_w> <trigger_h> <camera_x> <camera_y> <camera_w> <camera_h>
+spawn <id> <x> <y>
+endbattle_zone
+```
+
+## 下一步
+
+- 给 `.map` 增加 tileset/tile entry。
+- 增加重复 block、空 layer、battle zone 无 spawn、tile 引用不存在等错误日志。
+- 保留 `whitebox_level.cpp` 作为 fallback，不再把主地图写死在 C++。