Split game module documentation

game/docs/README.md

@@ -11,11 +11,27 @@
 ## References
 
 - `../assets/ASSETS.md`：全局资源槽位，包含字体、音频、PVF、NPK、SoundPack 和角色动画 fallback 路径。
+- `modules/README.md`：游戏模块文档索引，按源码模块拆分说明。
 - `controls.md`：玩家操作、平台输入映射和开发调试快捷键。
 - `engine_capability_audit.md`：引擎已有能力复盘，以及游戏层应优先复用的系统。
 - `game_skeleton.md`：当前游戏骨架如何接入引擎基础能力。
 - `scene_acceptance.md`：第一关场景骨架验收流程和最近一次验收结果。
 
+## Modules
+
+- `modules/core_services.md`：启动、服务、配置、资源路径。
+- `modules/assets.md`：资源槽位和素材落位。
+- `modules/data_map.md`：地图数据和 `LevelDefinition`。
+- `modules/stage_rendering.md`：场景分层和渲染。
+- `modules/scene_camera.md`：场景流程、摄像机、battle zone。
+- `modules/movement_collision.md`：横版移动和平台碰撞。
+- `modules/actor_player.md`：玩家 Actor、状态和动画。
+- `modules/input.md`：输入语义。
+- `modules/ui_overlay.md`：局内 UI overlay。
+- `modules/audio_save.md`：音频 cue 和存档。
+- `modules/debug_tools.md`：调试显示。
+- `modules/combat.md`：战斗模块预留和后续接入。
+
 ## Naming
 
 - 文件名使用小写 `snake_case`。

game/docs/game_skeleton.md

@@ -1,107 +1,59 @@
 # Game Skeleton
 
-本文档记录当前游戏骨架如何优先复用 Frostbite2D 引擎能力。目标是让游戏层只负责游戏语义，不重复实现引擎已经提供的资源、归档、音频、存档、场景和渲染基础设施。
+本文档只保留游戏骨架总览。具体模块细节已经拆分到 `modules/`，后续查实现优先看对应模块文档。
 
-## 当前接入状态
+## 总体目标
 
-### Application 基础服务
+当前游戏骨架的目标是：游戏层只负责 ACT 清版游戏语义，资源、归档、动画、音频、存档、场景、UI 和渲染基础设施尽量复用 Frostbite2D 引擎能力。
 
-由引擎 `Application::init()` 负责：
-
-- `Asset` 工作目录和资源路径解析。
-- `SaveSystem` 初始化。
-- SDL video/events/controller 初始化。
-- Window / Renderer / Camera 初始化。
-- PixelArt2D 渲染风格和虚拟分辨率。
-- `TaskSystem` 初始化。
-
-由引擎 `Application::shutdown()` 负责：
-
-- `SceneManager` 清理。
-- `Renderer` 清理。
-- `AudioSystem` 清理。
-- `NpkArchive` / `PvfArchive` / `SoundPackArchive` 清理。
-- 平台资源清理。
-
-### GameServices
-
-游戏层新增 `GameServices`，只做游戏项目需要的引擎服务接入和状态记录：
-
-- 初始化 `AudioSystem`。
-- 初始化 `FontManager`，有 `assets/fonts/debug.ttf` 或 `assets/fonts/ui.ttf` 时注册 debug 字体。
-- 探测并打开可选 `Script.pvf`。
-- 初始化 `NpkArchive`。
-- 初始化 `SoundPackArchive`。
-- 探测并加载可选 `AudioDatabase`。
-- 记录 `SaveSystem` 是否已由引擎初始化。
-
-这些服务是可选能力。缺少 `Script.pvf`、`ImagePacks2`、`SoundPacks`、字体、音频或 `audio.xml` 时，游戏仍然使用当前 PNG/白盒 fallback 启动。
-
-## 引擎能力接入点
-
-当前游戏骨架已把以下引擎能力接入到真实调用路径：
-
-- `Animation`：`PlayerActor` 会优先尝试 PVF `.ani`，失败后回退 NPK IMG，再回退 PNG spritesheet。
-- `NpkArchive` / `Sprite::createFromNpk`：角色资源和后续场景素材可从 `assets/ImagePacks2/*.npk` 进入。
-- `TextSprite` / `UIScene`：`GameUiOverlay` 已接入 UI scene stack；有字体时显示文字状态，没有字体时用色条 fallback。
-- `Sound` / `Music` / `AudioDatabase`：`GameAudio` 已支持 cue id，优先使用 `audio.xml`，否则读取 `assets/sounds/*.wav` 和 `assets/music/*.ogg`。
-- `SaveSystem`：`GameSave` 已保存/读取 debug overlay 开关状态。
-
-资源槽位见 `../assets/ASSETS.md`。
-
-## 地图资源入口
-
-新增 `StageMapResource` 和 `StageMapLoader`：
+## 当前主流程
 
 ```text
-LoadStageMapResource("map/stage_01.map")
-LoadStageMap("map/stage_01.map")
+main.cpp
+  -> Application::init()
+  -> GameServices::Initialize()
+  -> WhiteboxScene
+  -> LoadStageMap("map/stage_01.map")
+  -> LevelDefinition
+  -> StageRenderer / PlayerActor / DebugOverlay / GameUiOverlay
 ```
 
-读取优先级：
+## 模块文档入口
 
-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`
+- `modules/core_services.md`：启动、服务、配置、资源路径。
+- `modules/assets.md`：全局资源槽位、PVF/NPK/PNG fallback。
+- `modules/data_map.md`：`.map`、`StageMapLoader`、`LevelDefinition`。
+- `modules/stage_rendering.md`：场景分层、parallax、sprite/色块 fallback。
+- `modules/scene_camera.md`：`WhiteboxScene`、摄像机、battle zone。
+- `modules/movement_collision.md`：平台碰撞、横版移动。
+- `modules/actor_player.md`：玩家 Actor、动画、输入消费。
+- `modules/input.md`：PC/Switch 输入统一语义。
+- `modules/ui_overlay.md`：`UIScene`、`TextSprite`、fallback UI。
+- `modules/audio_save.md`：音频 cue、debug 存档。
+- `modules/debug_tools.md`：调试可视化。
+- `modules/combat.md`：战斗模块预留。
 
-当前状态：
+## 当前已接入的引擎能力
 
-- `game/assets/map/stage_01.map` 已接管第一关主数据。
-- `StageMapLoader` 会把 `.map` 文本解析成 `LevelDefinition`。
-- 已迁移世界尺寸、玩家出生点、相机边界、碰撞平台、视觉层、props、battle zone 和 spawn point。
-- `CreateWhiteboxLevel()` 优先读取 `.map`，读取或解析失败时才使用 C++ 白盒 fallback。
-- Windows 和 Switch 构建会把 `game/assets/*` 复制到产物 `assets/`，保证运行时 `assets/map/stage_01.map` 路径可用。
+- `Asset`：地图、贴图、字体、音频 fallback 路径。
+- `PvfArchive` / `ScriptParser`：`.map` 和 `.ani` 预留读取入口。
+- `NpkArchive` / `Sprite::createFromNpk`：角色资源 fallback。
+- `Animation`：玩家动画优先路径。
+- `AudioSystem` / `Sound` / `Music` / `AudioDatabase`：音频 cue。
+- `SaveSystem`：debug 开关存档。
+- `UIScene` / `TextSprite` / `FontManager`：局内 UI overlay。
+- `Scene` / `Actor` / `Renderer` / `Camera`：场景主循环、对象树、渲染和镜头。
 
-`.map` 当前支持的命令：
+## 当前 fallback 策略
 
-```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
-```
-
-## 仍待迁移的能力
-
-- 玩家动画：当前已接入 `Animation` 优先路径，但临时 PNG fallback 仍保留手写帧切换，等待正式 PVF/NPK 动画资源。
-- 场景视觉资源：`StageRenderer` 支持普通 PNG；若素材进入 NPK，后续补 stage layer 的 NPK sprite path。
-- 音频：调用路径已接入，等待正式音频资源和 `audio.xml`。
-- 地图：后续可把 `.map` 扩展为工具导出格式或 PVF 脚本格式，当前 C++ 地图只作为 fallback。
-- 输入配置：通过 `Asset` 或 PVF 读取 `InputConfig`。
+- 缺 PVF/NPK 时，玩家回退 PNG spritesheet。
+- 缺字体时，UI overlay 回退色条。
+- 缺音频资源时，音频 cue 静默跳过。
+- 缺 `.map` 或解析失败时，`whitebox_level.cpp` 提供 C++ 白盒 fallback。
 
 ## 原则
 
-- 优先使用引擎能力。
+- 引擎已有能力优先使用。
 - 游戏层只做数据转换和玩法语义。
 - 外部资源统一走 `Asset` / `PvfArchive`。
-- C++ 白盒数据只保留为 fallback。
+- C++ 白盒数据只保留为 fallback，不作为长期生产方式。

game/docs/modules/README.md

@@ -0,0 +1,25 @@
+# Game Modules
+
+本目录按游戏源码模块拆分说明文档。查具体代码时优先从这里进入；跨模块路线、阶段计划和验收流程仍放在 `../planning/`、`../game_skeleton.md` 和 `../scene_acceptance.md`。
+
+## 模块索引
+
+- `core_services.md`：游戏启动、`GameServices`、资源路径、基础配置。
+- `assets.md`：全局资源槽位、角色资源优先级、地图和 stage 资源落位。
+- `data_map.md`：`LevelDefinition`、`.map` 加载、地图数据格式。
+- `stage_rendering.md`：`StageRenderer`、场景分层、贴图/色块 fallback。
+- `scene_camera.md`：`WhiteboxScene`、摄像机跟随、battle zone 锁镜头。
+- `movement_collision.md`：`PlatformWorld`、`PlatformMover`、横版基础碰撞。
+- `actor_player.md`：`PlayerActor`、玩家状态、动画和音效触发。
+- `input.md`：`InputState`、PC/Switch 输入语义和后续配置计划。
+- `ui_overlay.md`：`GameUiOverlay`、`UIScene`、`TextSprite` 和 fallback UI。
+- `audio_save.md`：`GameAudio`、`GameSave`、音频 cue 和 debug 存档。
+- `debug_tools.md`：`DebugOverlay`、调试开关、可视化范围。
+- `combat.md`：当前 hitbox 预留和后续战斗模块拆分方向。
+
+## 维护规则
+
+- 新增源码模块时，同步新增或更新本目录对应文档。
+- 单个模块文档只写模块职责、入口文件、数据流、当前状态和下一步。
+- 跨模块验收结果写到 `../scene_acceptance.md`。
+- 长期计划写到 `../planning/`，不要塞进模块文档。

game/docs/modules/actor_player.md

@@ -0,0 +1,48 @@
+# Actor and Player
+
+## 职责
+
+Actor 模块负责游戏对象。当前已实现玩家，敌人、道具、投射物和特效后续按同样方式扩展。
+
+主要源码：
+
+- `game/src/actor/player_actor.*`
+- `game/src/actor/player_animation_assets.*`
+- `game/src/combat/hitbox.h`
+
+## `PlayerActor`
+
+当前能力：
+
+- 左右移动。
+- 跳跃。
+- 普通攻击触发。
+- idle/run/punch 三个临时状态。
+- 朝向翻转。
+- 基础平台碰撞。
+- 跳跃/攻击音效 cue。
+
+## 动画资源
+
+玩家动画加载顺序：
+
+```text
+PVF .ani
+  -> NPK IMG
+  -> PNG spritesheet fallback
+```
+
+如果使用 PVF `.ani`，由引擎 `Animation` 播放；如果回退 PNG，当前仍保留少量手写帧切换。
+
+## 当前限制
+
+- 还没有完整 ACT 状态机。
+- 攻击还没有命中判定。
+- 受击、击退、血量、硬直未接入。
+- PNG fallback 的帧数和帧时长仍在 C++ 中。
+
+## 下一步
+
+- 把 idle/move/jump/attack/hit/dead 做成互斥状态机。
+- 从 `Animation::GetCurrentFrameInfo()` 接入 attack box / damage box。
+- 新增 `EnemyActor` 时复用 Actor、PlatformWorld 和动画资源加载链路。

game/docs/modules/assets.md

@@ -0,0 +1,58 @@
+# Assets
+
+## 职责
+
+资源模块定义游戏素材落位规则，让代码只引用稳定路径，不关心素材最终来自普通文件、PVF、NPK 还是 SoundPack。
+
+主要文件：
+
+- `game/assets/ASSETS.md`
+- `game/assets/stage/stage_01/ASSETS.md`
+- `game/src/core/asset_paths.h`
+- `game/src/data/stage_asset_slots.h`
+
+## 全局资源槽位
+
+当前已预留：
+
+- `assets/fonts/`：UI/debug 字体。
+- `assets/sounds/`：直接读取的 wav 音效 fallback。
+- `assets/music/`：直接读取的 ogg 音乐 fallback。
+- `assets/audio/audio.xml`：音频 cue 表。
+- `assets/ImagePacks2/`：角色/场景 NPK 图片包。
+- `assets/SoundPacks/`：SoundPack 音频包。
+- `assets/Script.pvf`：PVF 脚本和动画资源。
+
+## 角色资源优先级
+
+玩家动画加载顺序：
+
+```text
+PVF .ani
+  -> NPK IMG
+  -> PNG spritesheet fallback
+```
+
+当前 PNG fallback 已能运行；正式素材到位后，优先把 `.ani` 和 `.img` 放到 `asset_paths.h` 约定的路径。
+
+## Stage 资源
+
+第一关资源放在：
+
+```text
+game/assets/stage/stage_01/
+```
+
+目录职责：
+
+- `background/`：远景、中景背景。
+- `tiles/`：地面、平台、墙体 tileset。
+- `props/`：后景/前景装饰。
+- `effects/`：场景特效。
+- `audio/`：关卡局部音频素材。
+
+## 下一步
+
+- 素材到位后先更新 `ASSETS.md` 的来源和授权。
+- 地图 tile 化后，把 tileset 路径写入 `.map` 数据。
+- 如果素材进入 NPK，补 stage layer 的 NPK sprite path 支持。

game/docs/modules/audio_save.md

@@ -0,0 +1,53 @@
+# Audio and Save
+
+## 职责
+
+音频和存档模块负责调用引擎已有 `Sound`、`Music`、`AudioDatabase` 和 `SaveSystem`。
+
+主要源码：
+
+- `game/src/core/game_audio.*`
+- `game/src/core/game_save.*`
+- `game/src/core/game_services.*`
+
+## 音频
+
+`GameAudio` 支持：
+
+- `PlaySoundCue(cueId)`
+- `PlayMusicCue(cueId)`
+
+路径解析优先级：
+
+```text
+AudioDatabase cue
+  -> assets/sounds/<cue>.wav
+  -> assets/music/<cue>.ogg
+```
+
+当前已接入 cue：
+
+- `stage_01`
+- `player_jump`
+- `player_attack`
+- `battle_zone_enter`
+
+缺音频资源时直接跳过，不影响场景运行。
+
+## 存档
+
+`GameSave` 当前用 `SaveSystem` slot `0` 保存 debug overlay 开关。
+
+保存内容：
+
+- debug 总开关。
+- 碰撞/网格显示。
+- 玩家包围盒。
+- battle zone/camera bounds。
+- spawn point。
+
+## 下一步
+
+- 正式设置、进度、角色成长继续走 `SaveSystem`。
+- 正式音频资源到位后补 `assets/audio/audio.xml`。
+- 根据 Switch 实机行为确认 save root 和权限。

game/docs/modules/combat.md

@@ -0,0 +1,47 @@
+# Combat
+
+## 职责
+
+战斗模块负责攻击、命中、受击、伤害、击退和状态互斥。当前只做了最小预留，还未进入正式玩法实现。
+
+主要源码：
+
+- `game/src/combat/hitbox.h`
+- `game/src/actor/player_actor.*`
+
+## 当前状态
+
+已有：
+
+- 玩家攻击输入。
+- punch 动画状态。
+- 攻击音效 cue。
+- `hitbox.h` 预留。
+
+未完成：
+
+- 攻击 hitbox。
+- hurtbox。
+- 命中检测。
+- 伤害数值。
+- 受击硬直。
+- 击退。
+- 血量。
+- 怪物受击和死亡。
+
+## 后续拆分建议
+
+优先保持轻量，不急着做复杂战斗框架：
+
+- `HitboxComponent`：攻击框、受击框。
+- `CombatStats`：血量、伤害、防御等固定数值。
+- `CombatResolver`：命中判定和伤害结算。
+- `HitReaction`：硬直、击退、受伤状态。
+
+## 接入顺序
+
+1. 从玩家 punch 状态产生一帧或多帧 hitbox。
+2. DebugOverlay 显示 hitbox/hurtbox。
+3. 新增一个最小 `EnemyActor`。
+4. 完成玩家攻击命中敌人的闭环。
+5. 再接 battle zone 清场。

game/docs/modules/core_services.md

@@ -0,0 +1,45 @@
+# Core Services
+
+## 职责
+
+核心模块负责游戏启动后的基础服务接入，不承载具体玩法逻辑。
+
+主要源码：
+
+- `game/src/main.cpp`
+- `game/src/core/game_config.h`
+- `game/src/core/game_services.*`
+- `game/src/core/asset_paths.h`
+- `game/src/core/debug_flags.h`
+
+## 当前接入
+
+`Application::init()` 由引擎负责初始化：
+
+- `Asset` 工作目录和资源路径。
+- `SaveSystem`。
+- SDL video/events/controller。
+- Window、Renderer、Camera。
+- PixelArt2D 渲染风格和虚拟分辨率。
+- `TaskSystem`。
+
+`GameServices` 只做项目级可选服务：
+
+- 初始化 `AudioSystem`。
+- 初始化 `FontManager`，尝试注册 `debug` 字体。
+- 探测并打开 `Script.pvf`。
+- 初始化 `NpkArchive`。
+- 初始化 `SoundPackArchive`。
+- 探测并加载 `AudioDatabase`。
+- 记录 `SaveSystem` 状态。
+
+## 运行原则
+
+- 缺少 PVF、NPK、SoundPack、字体或音频表时，游戏必须继续启动。
+- 游戏层只记录服务状态，不重新实现引擎服务。
+- Windows 和 Switch 通过同一个 `main.cpp` 入口进入游戏，平台差异放在编译分支和引擎平台层。
+
+## 下一步
+
+- 增加项目级日志分类，区分资源、地图、输入、场景和战斗。
+- 将 debug/service 状态接入更完整的调试面板。

game/docs/modules/data_map.md

@@ -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++。

game/docs/modules/debug_tools.md

@@ -0,0 +1,38 @@
+# Debug Tools
+
+## 职责
+
+调试模块负责白盒/灰盒阶段的可视化和开发开关。
+
+主要源码：
+
+- `game/src/debug/debug_overlay.*`
+- `game/src/core/debug_flags.h`
+- `game/docs/controls.md`
+
+## 当前显示项
+
+- 场景碰撞。
+- 场景网格。
+- 玩家包围盒。
+- battle zone 触发框。
+- battle zone camera bounds。
+- enemy spawn point。
+
+## 快捷键
+
+快捷键统一维护在 `../controls.md`。
+
+当前 debug 开关会通过 `GameSave` 保存，下次启动后恢复。
+
+## 约束
+
+- 调试绘制继续使用引擎 `Renderer::drawQuad`。
+- 不单独实现 debug render backend。
+- 正式版本需要能关闭或剥离开发快捷键。
+
+## 下一步
+
+- 增加输入状态显示。
+- 增加 hitbox/hurtbox 显示。
+- 增加地图加载错误和资源缺失提示面板。

game/docs/modules/input.md

@@ -0,0 +1,34 @@
+# Input
+
+## 职责
+
+输入模块负责把 PC、SDL 手柄和 Switch 输入统一成游戏语义。
+
+主要源码：
+
+- `game/src/core/input_state.*`
+- `game/docs/controls.md`
+
+## 当前语义
+
+`InputState` 只暴露游戏需要的动作：
+
+- `moveX`：水平输入，范围 `-1.0` 到 `1.0`。
+- `jumpPressed`：跳跃按下瞬间。
+- `attackPressed`：攻击按下瞬间。
+
+## 当前映射
+
+详细按键见 `../controls.md`。
+
+原则：
+
+- 角色逻辑只消费 `InputState`。
+- PC/Switch 差异只存在于 `InputStateProvider`。
+- 跳跃和攻击使用“按下瞬间”，避免长按每帧触发。
+
+## 下一步
+
+- 增加 `InputConfig`，并通过 `Asset` 或 PVF 读取。
+- 分离 gameplay 输入和 debug 输入。
+- 增加输入状态 debug 显示。

game/docs/modules/movement_collision.md

@@ -0,0 +1,42 @@
+# Movement and Collision
+
+## 职责
+
+移动碰撞模块负责横版基础移动和平台碰撞，是玩家、敌人和可移动物体共用的底层玩法能力。
+
+主要源码：
+
+- `game/src/movement/platform_world.*`
+- `game/src/data/level_definition.h`
+- `game/src/actor/player_actor.*`
+
+## 当前能力
+
+- 地面和平台矩形碰撞。
+- 重力。
+- 水平移动。
+- 落地检测。
+- 防止玩家穿过平台。
+- 平台数据来自 `LevelDefinition::collision`。
+
+## 当前使用方式
+
+`WhiteboxScene` 把关卡碰撞世界传给 `PlayerActor`：
+
+```text
+LevelDefinition.collision -> PlayerActor::SetMovementWorld()
+```
+
+`PlayerActor` 只提交移动意图，最终位置由 `PlatformMover` 约束。
+
+## 约束
+
+- 碰撞数据和视觉数据分离。
+- 不让 `StageRenderer` 反推碰撞。
+- 后续敌人也应复用 `PlatformWorld`，不要另写一套地形碰撞。
+
+## 下一步
+
+- 增加墙体/左右边界碰撞语义。
+- 增加防卡地形和异常状态重置。
+- 扩展成可服务敌人 AI 的移动查询接口。

game/docs/modules/scene_camera.md

@@ -0,0 +1,51 @@
+# Scene and Camera
+
+## 职责
+
+场景模块负责局内生命周期、关卡装配、摄像机和 battle zone 流程。
+
+主要源码：
+
+- `game/src/scene/whitebox_scene.*`
+- `game/src/scene/camera_controller.*`
+
+## `WhiteboxScene`
+
+当前负责：
+
+- 加载 `LevelDefinition`。
+- 创建玩家。
+- 配置摄像机。
+- 驱动 battle zone 状态。
+- 调用 `StageRenderer`。
+- 调用 `DebugOverlay`。
+- 推入 `GameUiOverlay`。
+- 播放关卡 BGM 和 battle zone 进入音效。
+- 保存 debug 开关。
+
+## 摄像机
+
+`CameraController` 当前支持：
+
+- 玩家横向跟随。
+- dead zone。
+- 平滑移动。
+- 世界边界 clamp。
+- battle zone 临时 camera bounds。
+
+进入/离开 battle zone 时，camera bounds 通过短过渡平滑切换，避免硬切瞬移。
+
+## Battle Zone
+
+当前 battle zone 还是场景骨架阶段：
+
+- 玩家进入触发区后激活。
+- 摄像机锁定到 zone camera bounds。
+- `F2` debug 清场后解除锁定。
+- enemy spawn point 只做 debug 显示，暂不刷敌。
+
+## 下一步
+
+- 用敌人清空结果替代 `F2` debug 清场。
+- 给 battle zone 增加入口/出口锁定数据。
+- 把场景切换、重置、加载/卸载流程独立成 SceneFlow 模块。

game/docs/modules/stage_rendering.md

@@ -0,0 +1,46 @@
+# Stage Rendering
+
+## 职责
+
+Stage 渲染模块负责把 `LevelDefinition` 的视觉层画出来，不处理玩法规则。
+
+主要源码：
+
+- `game/src/stage/stage_renderer.*`
+- `game/src/data/level_definition.h`
+
+## 当前分层
+
+```text
+BackgroundFar
+BackgroundMid
+LevelVisual
+PropsBack
+Actors
+PropsFront
+UI
+```
+
+`StageRenderer::Render()` 绘制 actor 之前的层；`RenderForeground()` 绘制 actor 之后的前景遮挡层。
+
+## 当前能力
+
+- 支持背景色。
+- 支持远景/中景/地面/平台/props 分层。
+- 支持 parallax。
+- 支持色块占位。
+- 支持普通 PNG texture path。
+- 支持 source rect。
+- 资源缺失时回退色块，不阻断场景运行。
+
+## 约束
+
+- 渲染继续使用引擎 `Renderer`。
+- `StageRenderer` 不直接解析 `.map`。
+- 碰撞和视觉分离，视觉 tile 不直接决定碰撞。
+
+## 下一步
+
+- 增加 tile entry 绘制路径。
+- 把 `level_visual` 长色块逐步替换为 tile。
+- 如果引擎提供统一 Texture cache，再迁移当前局部贴图缓存。

game/docs/modules/ui_overlay.md

@@ -0,0 +1,38 @@
+# UI Overlay
+
+## 职责
+
+UI 模块负责局内 HUD、状态显示和调试面板。当前只有最小 overlay。
+
+主要源码：
+
+- `game/src/ui/game_ui_overlay.*`
+
+## 当前能力
+
+`GameUiOverlay` 继承引擎 `UIScene`，通过 `SceneManager` 进入 UI scene stack。
+
+有字体时：
+
+- 使用 `TextSprite` 显示游戏状态。
+- 显示 debug 状态、battle zone、音频、存档、PVF、NPK、AudioDB 状态。
+
+缺字体时：
+
+- 使用 `Renderer::drawQuad` 画 fallback 色条。
+- 不因字体缺失阻断 PC/Switch 启动。
+
+## 资源
+
+字体候选：
+
+```text
+assets/fonts/debug.ttf
+assets/fonts/ui.ttf
+```
+
+## 下一步
+
+- 增加血量、连击、联机状态等 gameplay HUD。
+- 增加 debug 面板，替代部分 F 键调试。
+- 确认 Switch 字体资源进入 RomFS 后再启用正式文字 UI。