Add scene build plan

game/docs/SCENE_BUILD_PLAN.md

@@ -0,0 +1,210 @@
+# 场景搭建计划
+
+目标：先把第一关从白盒推进到可替换素材的灰盒/美术测试场景。当前游戏方向暂定为横板 2D ACT 清版，因此场景需要服务于移动、跳跃、攻击判定、敌人刷出、镜头推进和战斗节奏。
+
+## 1. 当前起点
+
+已有内容：
+
+- `WhiteboxScene`：当前白盒场景入口。
+- `CreateWhiteboxLevel()`：第一版关卡数据，包含平台碰撞和白盒装饰块。
+- `PlatformWorld` / `PlatformMover`：基础平台碰撞和重力移动。
+- `PlayerActor`：玩家移动、跳跃、出拳和基础动画。
+- `Frostbite2DGame`：Windows 游戏目标，可直接构建运行。
+
+当前白盒只解决“能跑、能跳、能看到关卡结构”。下一步要把场景拆成数据层、视觉层和玩法层。
+
+## 2. 第一关场景目标
+
+第一关不急着做最终题材，先做通用 ACT 测试关：
+
+- 横向推进，总宽度先控制在 2400 到 3200 像素。
+- 主要视口仍用 1280x720。
+- 地面以平路为主，加入 2 到 3 段平台高低差。
+- 至少预留 3 个战斗区域，每个区域宽度 480 到 720 像素。
+- 每个战斗区域有明确的入口、站位空间、敌人刷出点和退出方向。
+- 保留一个跳跃测试段，用来验证移动手感。
+- 保留一个窄平台/边缘段，用来验证镜头和碰撞。
+
+## 3. 场景分层
+
+后续场景按以下层拆：
+
+```text
+background_far      远景天空、城市、山体、洞窟深处等，不参与碰撞
+background_mid      中景建筑、树、墙面、远处平台，不参与碰撞
+level_collision     地面、平台、墙体，只负责碰撞
+level_visual        和碰撞对齐的地面/墙面贴图
+props_back          柱子、牌子、箱子、草丛等后景装饰
+actors              玩家、敌人、道具、投射物
+props_front         前景遮挡物、栏杆、近景草等
+effects             攻击特效、命中特效、尘土、碎片
+ui                  HUD、提示、调试信息
+```
+
+白盒阶段先实现：
+
+- `level_collision`
+- `level_visual`
+- `props_back`
+- `actors`
+
+前景遮挡和特效后面再加。
+
+## 4. 素材寻找清单
+
+你先找这些素材，优先像素风，尺寸最好能和 128x128 角色兼容。
+
+### 必需素材
+
+- 地面 tileset：至少包含平地、左边缘、右边缘、平台中段。
+- 墙面或背景 tileset：用于挡板、台阶、平台侧面。
+- 远景背景：一张或多张可横向拼接背景。
+- 中景背景：建筑、树、管线、洞窟墙等可以做视差的图层。
+- 基础装饰物：箱子、桶、路灯、告示牌、碎石、草丛等。
+- 关卡边界标识：门、路障、出口牌、传送门等任选。
+
+### ACT 玩法相关素材
+
+- 敌人站位/出生点可用的临时标记图。
+- 可破坏物：木箱、罐子、障碍物。
+- 攻击命中特效：小型 hit spark。
+- 落地/跑步尘土：小型 dust effect。
+
+### 可选素材
+
+- 前景遮挡：栏杆、柱子、近景树叶。
+- 光照叠加图：窗口光、路灯光、火光等。
+- 环境动画：旗子、火焰、流水、机器灯。
+- 背景音乐和环境音。
+
+## 5. 素材规格建议
+
+角色当前是 128x128 帧，场景素材建议：
+
+- tileset 单格优先 `32x32`、`48x48` 或 `64x64`。
+- 平台碰撞块可以和视觉块分离，不要求每张图都精准碰撞。
+- 背景图宽度最好大于 1280，或能无缝横向重复。
+- PNG 优先，透明背景用于 props 和 effects。
+- 同一套素材尽量保持统一像素密度。
+- 文件名使用英文小写和下划线，例如 `factory_floor_tiles.png`。
+
+建议素材目录：
+
+```text
+game/assets/stage/stage_01/
+├─ background/
+├─ tiles/
+├─ props/
+├─ effects/
+└─ audio/
+```
+
+## 6. 工程实现步骤
+
+### Step 1：扩展关卡数据结构
+
+把 `LevelDefinition` 从纯白盒数据扩展为：
+
+- 世界宽高。
+- 碰撞平台列表。
+- 视觉 tile/prop 列表。
+- 玩家出生点。
+- 敌人出生点。
+- 战斗区域触发范围。
+- 镜头限制范围。
+
+### Step 2：实现 StageRenderer
+
+新增 `scene` 或 `stage` 模块，负责绘制：
+
+- 背景色。
+- 远景背景。
+- 中景背景。
+- tile 层。
+- prop 层。
+- debug 碰撞层。
+
+第一版可以继续用 `Renderer::drawQuad` 和 `Sprite`，不急着做 tilemap 优化。
+
+### Step 3：替换白盒视觉
+
+保持碰撞数据不变，先把地面和平台换成 tileset。
+
+验收标准：
+
+- 玩家仍然能正常落地和跳跃。
+- 视觉地面和碰撞地面误差不超过 4 像素。
+- 镜头移动时背景不黑屏、不闪烁。
+
+### Step 4：加入视差背景
+
+远景和中景随相机不同速度移动：
+
+- 远景速度：相机速度的 20% 到 35%。
+- 中景速度：相机速度的 45% 到 65%。
+- 地面和角色速度：100%。
+
+### Step 5：加入战斗区域数据
+
+在关卡中标出 3 个 battle zone：
+
+- `zone_01_intro`
+- `zone_02_platform`
+- `zone_03_exit`
+
+每个区域包含：
+
+- 触发矩形。
+- 敌人刷出点。
+- 镜头锁定范围。
+- 清场后解锁出口。
+
+第一版可以只画 debug 框，不立刻做敌人。
+
+### Step 6：加入 debug 显示开关
+
+需要能显示/隐藏：
+
+- 碰撞矩形。
+- 玩家 hurtbox。
+- 攻击 hitbox。
+- 敌人出生点。
+- battle zone。
+
+建议先用键盘 `F1` 切换。
+
+## 7. 第一版验收标准
+
+第一阶段完成时应该达到：
+
+- 能启动 `Frostbite2DGame`。
+- 第一关宽度至少 2400 像素。
+- 玩家可以从起点跑到终点。
+- 至少 5 个平台/地面碰撞块。
+- 至少 2 层背景。
+- 至少 8 个装饰物。
+- 至少 3 个 battle zone debug 标记。
+- 场景资源路径集中在 `game/assets/stage/stage_01/`。
+- 文档记录已使用素材来源和授权信息。
+
+## 8. 素材回来后的落地顺序
+
+素材准备好后按这个顺序处理：
+
+1. 整理素材到 `game/assets/stage/stage_01/`。
+2. 记录素材来源和授权。
+3. 先接背景图，验证相机移动。
+4. 再接地面/平台 tiles，验证碰撞对齐。
+5. 再接 props，丰富场景轮廓。
+6. 最后接 effects 和音频。
+
+## 9. 下一轮建议任务
+
+你找到素材后，下一轮优先做：
+
+- 创建 `stage_01` 资源目录。
+- 新增 `StageRenderer`。
+- 扩展 `LevelDefinition`。
+- 把当前白盒平台替换成第一版 tile 视觉。
+- 保留 debug 碰撞显示。