Split stage rendering and debug overlay

game/docs/ARCHITECTURE.md

@@ -17,8 +17,10 @@ game/
    ├─ combat/           碰撞箱、伤害判定和战斗解算类型
    ├─ core/             共享配置、输入快照和资源路径
    ├─ data/             关卡和游戏数据定义
+   ├─ debug/            调试可视化叠层
    ├─ movement/         可复用的移动和碰撞辅助工具
    ├─ scene/            游戏场景和关卡编排
+   ├─ stage/            关卡视觉层渲染
    └─ main.cpp          游戏可执行文件入口点
 ```
 
@@ -37,7 +39,9 @@ main.cpp
       -> PlayerActor 通过 PlatformMover 移动
       -> PlayerActor 更新动画
       -> WhiteboxScene 更新摄像机
-      -> WhiteboxScene 绘制白盒关卡
+      -> StageRenderer 绘制关卡视觉层
+      -> Actor 渲染
+      -> DebugOverlay 绘制调试叠层
 ```
 
 ## 模块职责
@@ -47,6 +51,7 @@ main.cpp
 - `game_config.h` 存储共享的调整常数，如虚拟分辨率、
   重力、玩家速度和攻击持续时间
 - `asset_paths.h` 存储稳定的运行时资源路径
+- `debug_flags.h` 集中控制开发期调试显示开关
 - `input_state.*` 将原始 SDL 键盘状态转换为与引擎无关的
   `InputState` 快照。玩家逻辑使用此快照而不是直接读取
   SDL
@@ -74,7 +79,17 @@ main.cpp
 `scene`
 
 - `WhiteboxScene` 编排当前关卡：加载关卡数据、创建
-  角色、绘制白盒几何和控制摄像机
+  角色、委托关卡渲染、委托调试叠层并控制摄像机
+
+`stage`
+
+- `StageRenderer` 绘制当前关卡视觉层，包括背景、网格、白盒道具和平台
+- 后续 tileset、视差背景和 props 渲染都应该优先接入该模块
+
+`debug`
+
+- `DebugOverlay` 绘制碰撞矩形和玩家包围盒
+- `DebugFlags` 决定哪些调试层启用
 
 `combat`
 

game/docs/GAME_ARCHITECTURE_BOARD.md

@@ -121,11 +121,11 @@ mindmap
 - `core/game_config.h`
 - `core/asset_paths.h`
 - `core/input_state.*`
+- `core/debug_flags.h`
 
 下一步：
 
 - 增加 `GameContext`，统一传递全局服务。
-- 增加 `DebugFlags`，集中管理调试开关。
 - 输入层支持键盘和手柄统一映射。
 
 ### 2. Scene
@@ -159,10 +159,10 @@ mindmap
 - `data/level_definition.h`
 - `data/whitebox_level.cpp`
 - `movement/platform_world.*`
+- `stage/stage_renderer.*`
 
 下一步：
 
-- 增加 `StageRenderer`。
 - 增加 `StageLayer` 数据结构。
 - 关卡宽度扩展到 2400 到 3200 像素。
 - 引入远景/中景/地面三层绘制。
@@ -287,6 +287,7 @@ mindmap
 
 下一步：
 
+- `debug/debug_overlay.*` 已经提供碰撞和玩家包围盒绘制。
 - `F1` 切换 debug overlay。
 - 绘制平台碰撞。
 - 绘制 battle zone。
@@ -378,12 +379,11 @@ mindmap
 
 下一步建议按这个顺序做：
 
-1. `StageRenderer`：让关卡视觉层从 Scene 中独立出来。
-2. `DebugOverlay`：显示碰撞、战斗区域和出生点。
-3. `BattleZone`：做清版推进的核心框架。
-4. `EnemyActor`：做第一个敌人占位。
-5. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。
-6. `SpriteAnimator`：把玩家动画从硬编码改成组件。
+1. `BattleZone`：做清版推进的核心框架。
+2. `EnemyActor`：做第一个敌人占位。
+3. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。
+4. `SpriteAnimator`：把玩家动画从硬编码改成组件。
+5. `StageLayer`：把白盒视觉层扩展为背景、tiles 和 props。
 
 ## 素材协作提示