# 场景搭建计划

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

## 1. 当前起点

已有内容：

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

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

第一轮场景骨架进度：

- `LevelDefinition` 已扩展世界尺寸、玩家出生点、镜头范围、分层视觉、battle zone 和敌人出生点数据。
- 第一关地图已扩展到 `6400 x 720`，当前主数据在 `game/assets/map/stage_01.map`。
- `StageRenderer` 已支持远景、中景、地面/平台、后景 props 分层绘制，当前先用色块占位。
- `DebugOverlay` 已能显示碰撞、玩家框、battle zone、camera lock 范围和 spawn point。
- `WhiteboxScene` 已支持 debug overlay，具体快捷键记录在 `../controls.md`。
- `CameraController` 已接入：修复场景 `OnUpdate()` 不被调用导致摄像机不动的问题，并提供跟随、dead zone、平滑和世界边界 clamp。
- `CameraZoneLock` 已接入：玩家进入 battle zone 后摄像机临时锁定到 zone camera bounds，debug 清场后恢复全关卡跟随。
- 已修复 zone camera bounds 小于 1280 视口导致摄像机锁死的问题；所有锁镜头范围必须不小于当前视口，debug 阶段玩家离开 zone 会自动清场解锁。
- 已修复进入 battle zone 时摄像机硬切的问题；zone camera bounds 表示摄像机可移动范围，进入/离开 zone 都通过短过渡平滑切换约束。
- `StageLayerSource` 已接入：`StageRect` 支持色块占位或 sprite 资源路径，资源不存在时回退色块。
- `StageAssetSlots` 已建立：`game/assets/stage/stage_01/` 已预留 background、tiles、props、effects、audio 目录和素材来源记录。
- `StageProps` 已统一：旧 `WhiteboxProp` 已移除，后景/前景 props 都走 `StageLayer`，其中 `props_front` 在角色之后绘制用于遮挡。
- `SceneDebug` 已扩展：支持 debug 总开关和碰撞/网格、玩家框、battle zone/camera、spawn point 分项开关，具体快捷键记录在 `../controls.md`。
- `SceneAcceptanceRun` 已建立：场景骨架验收流程和本轮构建结果记录在 `../scene_acceptance.md`。

## 2. 第一关场景目标

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

- 横向推进，当前 Mossy Cavern 测试关宽度为 6400 像素。
- 主要视口仍用 1280x720。
- 主路线先保持连续地面，避免当前平台碰撞不支持台阶/斜坡导致卡关；高度变化主要放在悬空平台上，用于测试跳跃和镜头推进。
- 至少预留 5 个战斗区域，每个区域宽度约 780 到 980 像素。
- 每个战斗区域有明确的入口、站位空间、敌人刷出点和退出方向。
- 保留一个跳跃测试段，用来验证移动手感。
- 保留一个窄平台/边缘段，用来验证镜头和碰撞。

## 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：加入战斗区域数据

当前 Mossy Cavern 大地图标出 5 个 battle zone：

- `zone_01_entrance`
- `zone_02_lower_cavern`
- `zone_03_main_hall`
- `zone_04_high_garden`
- `zone_05_exit`

每个区域包含：

- 触发矩形。
- 敌人刷出点。
- 镜头锁定范围。
- 清场后解锁出口。

第一版可以只画 debug 框，不立刻做敌人。

### Step 6：加入 debug 显示开关

需要能显示/隐藏：

- 碰撞矩形。
- 玩家 hurtbox。
- 攻击 hitbox。
- 敌人出生点。
- battle zone。

具体 debug 快捷键统一记录在 `../controls.md`。

## 7. 第一版验收标准

第一阶段完成时应该达到：

- 能启动 `Frostbite2DGame`。
- 第一关宽度至少 2400 像素。
- 玩家可以从起点跑到终点。
- 至少 5 个平台/地面碰撞块。
- 至少 2 层背景。
- 至少 8 个装饰物。
- 至少 5 个 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. 已完成：扩展关卡宽度到 6400 像素，并整理成 5 段 Mossy Cavern 推进节奏。
4. 已完成：加入 5 个 battle zone debug 标记，但暂不做刷敌逻辑。
5. 已完成：加入 spawn point debug 标记，用于后续接 `EnemyActor`。
6. 已完成：补 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、玩家包围盒。
- 关卡灰盒能从起点跑到终点，至少 5 个推进段和 5 个 battle zone 都能被观察到；具体验收流程见 `../scene_acceptance.md`。
- 素材目录、命名、来源记录文件已经准备好，后续放入 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` 补齐 debug 总开关，并预留/接入分项开关。
7. 已完成：`SceneAcceptanceRun` 建立场景骨架验收文档；PC 和 Switch 构建通过，PC 短启动通过。

### 场景骨架阶段结论

当前场景骨架已经达到“可直接放素材”的工程状态。后续素材接入主要修改 `game/assets/stage/stage_01/` 和关卡 layer 数据，不需要再重写 `WhiteboxScene` 主流程。

地图框架调整已完成第一步：优先复用引擎 `Asset`、`PvfArchive` 和 `ScriptParser` 能力，`stage_01.map` 已从占位文件升级为第一关主数据源。`StageMapLoader` 会把 `.map` 解析成 `LevelDefinition`，C++ 白盒地图仅作为读取或解析失败时的 fallback。详细复盘见 `../engine_capability_audit.md`。

第一轮引擎能力接入已完成：`GameServices` 统一接入音频、PVF、NPK、SoundPack、AudioDB、SaveSystem 状态；`StageMapResource` 负责从 Asset/PVF 读取 `map/stage_01.map`，`StageMapLoader` 负责转成游戏层 `LevelDefinition`。完整骨架说明见 `../game_skeleton.md`。

第二轮引擎能力接入已完成：

- `Animation` 已接入玩家资源加载链路，优先读取 PVF 内 `.ani`，不可用时回退到 NPK IMG，再回退到 PNG 精灵表。
- `NpkArchive` / `Sprite::createFromNpk` 已接入角色动画资源兜底链路，后续把角色 IMG 放入 `ImagePacks2` 后无需改玩家主流程。
- `TextSprite` / `UIScene` 已接入局内 UI overlay；有 debug 字体时显示文本状态，没有字体时回退成低依赖状态条。
- `Sound` / `Music` 已通过 `GameAudio` 接入 cue 播放；优先读取 `AudioDatabase`，缺少音频表时从 `assets/sounds` 和 `assets/music` 直读占位资源。
- `SaveSystem` 已用于保存/读取场景 debug 开关，避免每次启动后重复配置调试显示。
- 全局素材槽位已建立在 `game/assets/ASSETS.md`，字体、音乐、音效、PVF、NPK、SoundPack、角色 ANI/IMG/PNG 的落位规则已经记录。

### 下一轮建议任务

继续沿着“优先使用引擎能力”的方向，把地图从色块灰盒推进到可放素材的完整骨架。当前不进入敌人和战斗玩法，下一轮只处理地图视觉表达：

1. 已完成：给 `.map` 增加 `tileset` / `tile_rect` 约定，先不做编辑器，保证手写数据能表达重复地砖。
2. 已完成：在 `StageRenderer` 中增加 tile 绘制路径，复用当前 `Texture` 加载和 source rect 支持。
3. 已完成：把 `level_visual` 的长色块替换成 tile entries，碰撞仍独立保留在 `collision`。
4. 已完成：给 map loader 增加重复 tileset、未知 tileset、非法 tile rect 等错误日志。
5. 已完成：补轻量 map 验收流程：启动时日志确认加载 `.map`，Windows/Switch 产物确认存在 `assets/map/stage_01.map` 和全局素材槽位。

### 当前阶段：地图场景制作

从现在开始，重点从“场景骨架”切到“地图场景制作”。因为 `.map` 已经成为第一关主数据源，继续手写地图会拖慢制作效率，所以下一步先做一个简易 `.map` 地图编辑器。编辑器计划见 `../modules/map_editor.md`。

### 下一轮建议任务

继续围绕地图制作工具和地图视觉骨架，不进入战斗玩法：

1. 建立 `tools/map_editor/`，实现能打开/保存 `stage_01.map` 的最小编辑器。
2. 编辑器首版先支持 world、camera、player spawn、collision、tileset、tile_rect、battle zone、spawn point。
3. 在编辑器中提供网格吸附、视图平移、缩放和对象选择。
4. 保存后的 `.map` 必须能被 `StageMapLoader` 直接读取。
5. 编辑器稳定后，再给 `tile_rect` 增加二维 source index 或 tile id，接正式 tileset。

### Debug 快捷键

场景 debug 快捷键统一记录在 `../controls.md`。

### 素材落位标准

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

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

### Mossy Cavern 场景接入

当前第一关已经先接入 `X:\NS_unknown_game\asset\Mossy Cavern` 的场景图集，范围只包含地图视觉：

1. 已完成：把 Mossy 背景、平台、悬挂植物和装饰图集复制到 `game/assets/stage/stage_01/`，并统一为小写下划线路径。
2. 已完成：`stage_01.map` 的 `BackgroundFar`、`BackgroundMid`、`LevelVisual`、`PropsBack`、`PropsFront` 已改用 `rect_sprite_src` 裁切 Mossy 图集。
3. 已完成：碰撞、玩家出生点、camera bounds、battle zone 和 spawn point 保持原数据，不把视觉块当碰撞使用。
4. 已完成：贴图 `LevelVisual` 不再叠加灰盒辅助顶线，避免平台素材显示异常。
5. 已完成：参考 `asset\Mossy Cavern\参考图`，把 `stage_01.map` 扩展为 `6400 x 720` 的横向大地图，包含入口、下沉洞道、主洞厅、高低平台群和出口 5 个推进段。

暂不接入 `BlueWizard Animations`、`Plant Animations`、`Slimes` 和 hazard 玩法。下一步围绕地图编辑器继续微调场景块位置和碰撞对齐。