Load stage map into level definition

game/docs/engine_capability_audit.md

@@ -8,7 +8,7 @@
 
 最重要的调整是：**场景地图不要继续在 C++ 里手写 `Rect`，下一步应接入 `.map` 文件加载，并优先通过引擎 `Asset` / `PvfArchive` / `ScriptParser` 读取和解析。**
 
-当前第一轮骨架接入已完成：游戏启动时通过 `GameServices` 探测/初始化 `AudioSystem`、`PvfArchive`、`NpkArchive`、`SoundPackArchive`、`AudioDatabase` 和 `SaveSystem` 状态，并通过 `StageMapResource` 接入 `.map` 资源读取入口。详细状态见 `game_skeleton.md`。
+当前第一轮骨架接入已完成：游戏启动时通过 `GameServices` 探测/初始化 `AudioSystem`、`PvfArchive`、`NpkArchive`、`SoundPackArchive`、`AudioDatabase` 和 `SaveSystem` 状态，并通过 `StageMapResource` + `StageMapLoader` 接入 `.map` 资源读取和解析入口。详细状态见 `game_skeleton.md`。
 
 推荐方向：
 
@@ -74,15 +74,15 @@
 - `Asset` 被引擎纹理加载间接使用。
 - Windows / Switch 的资源根目录、RomFS 路径已经由引擎 `Asset` 解析。
 
-未充分使用：
+当前状态：
 
-- 游戏层目前没有直接用 `Asset::readTextFile` / `readBinaryFile` 读取地图和配置。
-- `stage_01` 地图仍写死在 C++。
+- `StageMapResource` 已直接使用 `Asset::readFileToString` 读取 `map/stage_01.map` 或 `assets/map/stage_01.map`。
+- Windows 和 Switch 构建会把 `game/assets/*` 复制到产物 `assets/`，保证 `assets/map/stage_01.map` 路径可用。
+- `stage_01` 主地图已迁移到外部 `.map` 文件。
 
 下一步：
 
-- `.map` 普通文件先用 `Asset` 读取。
-- 同一套 loader 后续支持从 PVF 中读取。
+- 继续把输入配置、角色动画配置等文本/脚本配置接入 `Asset` 或 PVF。
 
 ### PVF / ScriptParser
 
@@ -98,8 +98,9 @@
 
 当前状态：
 
-- 游戏层还没使用。
-- 引擎已经具备从 `Script.pvf` 按逻辑路径取脚本文件的能力。
+- `StageMapResource` 已能在 `PvfArchive` 打开后尝试读取 `map/stage_01.map`。
+- 若资源像 PVF 二进制脚本，会先用 `ScriptParser` 解析出 script values。
+- 若资源是 PVF 文本，会作为普通 `.map` 文本交给 `StageMapLoader`。
 - `ScriptParser` 支持 PVF 脚本二进制格式，不是普通文本 parser。
 
 地图结论：
@@ -185,20 +186,17 @@
 
 - `game/src/data/whitebox_level.cpp`
 
-问题：
+当前状态：
 
-- 世界尺寸、平台、视觉层、props、battle zone、spawn point 全部写在 C++。
-- 这不适合后续反复调地图，也不适合你要的 `.map` 工作流。
+- 已新增 `game/assets/map/stage_01.map`。
+- 已新增 `StageMapLoader`，把 `.map` 文本解析成 `LevelDefinition`。
+- `CreateWhiteboxLevel()` 已改为优先加载 `.map`，失败时才回退 C++ 白盒数据。
+- C++ 中保留的世界尺寸、平台、视觉层、props、battle zone、spawn point 现在只作为 fallback。
 
-建议：
+后续建议：
 
-- 新增 `StageMapLoader`。
-- 创建 `game/assets/stage/stage_01/stage_01.map` 或 `game/assets/map/stage_01.map`。
-- 让 `CreateWhiteboxLevel()` 临时变成：
-
-```cpp
-return LoadStageMap("map/stage_01.map").value_or(CreateFallbackWhiteboxLevel());
-```
+- 继续扩展 `.map` 的 tileset/tile entry 表达。
+- 逐步把 `level_visual` 的长色块替换成 tile 数据。
 
 ### 2. 手写动画帧切换
 
@@ -245,13 +243,13 @@ return LoadStageMap("map/stage_01.map").value_or(CreateFallbackWhiteboxLevel());
 
 ### 加载优先级
 
-第一阶段先支持普通资源文件：
+第一阶段已支持普通资源文件：
 
 ```text
 Asset::readTextFile("map/stage_01.map")
 ```
 
-第二阶段支持 PVF：
+第二阶段已预留 PVF：
 
 ```text
 PvfArchive::getFileContent("map/stage_01.map")
@@ -312,10 +310,10 @@ StageMapLoader
 
 ## 推荐执行顺序
 
-1. `StageMapResource`：定义地图文件路径、普通资源读取和 PVF 读取优先级。
-2. `StageMapLoader`：把 `.map` 转成 `LevelDefinition`。
-3. `stage_01.map`：把当前 `whitebox_level.cpp` 数据迁移成外部地图文件。
-4. `CreateWhiteboxLevel()`：改为加载 `stage_01.map`，失败时回退旧白盒数据。
+1. 已完成：`StageMapResource` 定义地图文件路径、普通资源读取和 PVF 读取优先级。
+2. 已完成：`StageMapLoader` 把 `.map` 转成 `LevelDefinition`。
+3. 已完成：`stage_01.map` 把当前 `whitebox_level.cpp` 数据迁移成外部地图文件。
+4. 已完成：`CreateWhiteboxLevel()` 改为加载 `stage_01.map`，失败时回退旧白盒数据。
 5. `StageRenderer`：继续消费 `LevelDefinition`，不直接关心 `.map`。
 6. 文档：把地图编辑流程写入 `scene_acceptance.md` 和场景计划。