NS_unknown_game/game/docs/planning/scene_build_plan.md

场景搭建计划

目标：先把第一关从白盒推进到可替换素材的灰盒/美术测试场景。当前游戏方向暂定为横板 2D ACT 清版，因此场景需要服务于移动、跳跃、攻击判定、敌人刷出、镜头推进和战斗节奏。

1. 当前起点

已有内容：

• WhiteboxScene：当前白盒场景入口。
• CreateWhiteboxLevel()：第一版关卡数据，包含平台碰撞和白盒装饰块。
• PlatformWorld / PlatformMover：基础平台碰撞和重力移动。
• PlayerActor：玩家移动、跳跃、出拳和基础动画。
• Frostbite2DGame：Windows 游戏目标，可直接构建运行。

当前白盒只解决“能跑、能跳、能看到关卡结构”。下一步要把场景拆成数据层、视觉层和玩法层。

第一轮场景骨架进度：

• LevelDefinition 已扩展世界尺寸、玩家出生点、镜头范围、分层视觉、battle zone 和敌人出生点数据。
• 第一关灰盒宽度已扩展到 3200 像素。
• StageRenderer 已支持远景、中景、地面/平台、后景 props 分层绘制，当前先用色块占位。
• DebugOverlay 已能显示碰撞、玩家框、battle zone、camera lock 范围和 spawn point。
• WhiteboxScene 已支持 F1 切换 debug overlay。

2. 第一关场景目标

第一关不急着做最终题材，先做通用 ACT 测试关：

• 横向推进，总宽度先控制在 2400 到 3200 像素。
• 主要视口仍用 1280x720。
• 地面以平路为主，加入 2 到 3 段平台高低差。
• 至少预留 3 个战斗区域，每个区域宽度 480 到 720 像素。
• 每个战斗区域有明确的入口、站位空间、敌人刷出点和退出方向。
• 保留一个跳跃测试段，用来验证移动手感。
• 保留一个窄平台/边缘段，用来验证镜头和碰撞。

3. 场景分层

后续场景按以下层拆：

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。

建议素材目录：

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. 当前执行顺序

本轮开始先做场景，不等待最终素材。第一阶段目标是把第一关变成可替换素材的灰盒场景骨架，让后续素材只需要填到既定层级和数据结构里。

先做工程骨架

1. 已完成：扩展 LevelDefinition，加入世界尺寸、玩家出生点、镜头限制、敌人出生点、battle zone 占位数据。
2. 已完成：扩展 StageRenderer，支持背景层、地面/平台视觉层、后景 props，第一版继续用色块。
3. 已完成：扩展白盒关卡宽度到 3200 像素，并整理成 3 段推进节奏。
4. 已完成：加入 3 个 battle zone debug 标记，但暂不做锁镜头和刷敌逻辑。
5. 已完成：加入 spawn point debug 标记，用于后续接 EnemyActor。
6. 已完成：补 F1 debug 开关，可切换碰撞、battle zone、spawn point。

素材回来后再替换

1. 整理素材到 game/assets/stage/stage_01/。
2. 记录素材来源和授权。
3. 先接背景图，验证相机移动。
4. 再接地面/平台 tiles，验证碰撞对齐。
5. 再接 props，丰富场景轮廓。
6. 最后接 effects 和音频。

10. 下一轮建议任务

当前目标调整为：先完成“可直接放素材”的场景骨架，而不是立刻进入素材替换。骨架完成后，素材只需要整理到约定目录并填入 layer/prop/tile 数据，不再改场景主流程。

完整场景骨架完成定义

完成后应达到：

• 摄像机能跟随玩家横向推进，不再固定在起点视口。
• 摄像机遵守关卡边界，不露出世界外黑边。
• 摄像机能被 battle zone 临时锁定到指定范围，清场后恢复跟随。
• LevelDefinition 能表达世界尺寸、玩家出生点、相机边界、碰撞、视觉层、props、battle zone、spawn point。
• StageRenderer 能按层绘制远景、中景、地面/平台、后景 props、前景 props，并支持资源图和色块占位两种来源。
• DebugOverlay 能显示碰撞、battle zone、camera lock、spawn point、玩家包围盒。
• 关卡灰盒能从起点跑到终点，至少 3 个推进段和 3 个 battle zone 都能被观察到。
• 素材目录、命名、来源记录文件已经准备好，后续放入 PNG 后只改资源引用。

场景骨架实施顺序

1. CameraController：修复当前摄像机不会动的问题，实现玩家跟随、边界 clamp、dead zone 和平滑参数。
2. CameraZoneLock：让 battle zone 可以锁定摄像机范围，先只做 debug 触发和解锁占位。
3. StageLayerSource：扩展 StageLayer，让每个 rect 支持色块占位或 sprite 资源路径。
4. StageAssetSlots：创建并记录 stage_01 资源槽位，不要求已有最终素材。
5. StageProps：把 props 从旧 WhiteboxProp 迁移到统一 layer 数据，支持 back/front 两层。
6. SceneDebug：补齐 F1 debug 总开关，并预留分项开关。
7. SceneAcceptanceRun：PC 和 Switch 都构建通过，PC 能从起点移动到终点并看到相机推进。

素材落位标准

素材准备好后只做这些操作：

1. 放入 game/assets/stage/stage_01/background/、tiles/、props/、effects/。
2. 在 stage_01_assets 或后续关卡数据中填写资源路径。
3. 把灰盒 StageLayer 的色块替换成 sprite/tile 条目。
4. 对齐视觉块和碰撞块，误差控制在 4 像素以内。
5. 更新素材来源和授权记录。