# Scene Acceptance

本文档记录第一关场景骨架的验收流程。每次改动场景、摄像机、关卡数据、输入或渲染层后，至少执行构建检查；涉及跑图手感时再执行手动跑图检查。

## 验收范围

- 场景入口：`WhiteboxScene`
- 关卡数据：`game/assets/map/stage_01.map`
- 关卡 fallback：`CreateWhiteboxLevel()` 内置 C++ 白盒数据
- 世界尺寸：`2105 x 720`
- 玩家出生点：`(1030, 346)`
- 关卡边界：`0 -> 2105`
- 视口：`1280 x 720`
- Battle zones：`zone_01_left_platform`、`zone_02_center_platform`、`zone_03_right_platform`
- 资源槽位：`game/assets/stage/stage_01/`
- 地图资源：`game/assets/map/stage_01.map`
- 参考底图：`game/assets/stage/stage_01/reference/mossy_cavern_reference_4hibzc.png`
- 全局资源槽位：`game/assets/ASSETS.md`
- UI overlay：`GameUiOverlay`，有字体时使用 `TextSprite`，无字体时使用 fallback 色条。
- 音频 cue：`stage_01`、`player_jump`、`player_attack`、`battle_zone_enter`。

## 构建检查

### Windows

```powershell
& 'C:\Program Files\xmake\xmake.exe' f -c -p windows -a x64 -m release -y
& 'C:\Program Files\xmake\xmake.exe' -b Frostbite2DGame
```

短启动检查：

```powershell
$exe = Join-Path (Get-Location) 'build\windows\x64\release\Frostbite2DGame.exe'
$p = Start-Process -FilePath $exe -WorkingDirectory (Get-Location) -PassThru -WindowStyle Hidden
Start-Sleep -Seconds 3
if (!$p.HasExited) { Stop-Process -Id $p.Id -Force }
```

资源路径检查：

```powershell
Test-Path build\windows\x64\release\assets\map\stage_01.map
Test-Path build\windows\x64\release\assets\ASSETS.md
Test-Path build\windows\x64\release\assets\fonts
Test-Path build\windows\x64\release\assets\stage\stage_01\reference\mossy_cavern_reference_4hibzc.png
```

### Switch

```powershell
& 'C:\Program Files\xmake\xmake.exe' f -c -p switch -a aarch64 -m release --toolchain=cross --sdk='C:\devkitPro\devkitA64' --bin='C:\devkitPro\devkitA64\bin' --cross='aarch64-none-elf-' -y
& 'C:\Program Files\xmake\xmake.exe' -b Frostbite2DGameSwitch
```

产物：

```text
build\switch\aarch64\release\switch_game\NSUnknownGame.nro
```

RomFS 地图检查：

```powershell
Test-Path build\switch\aarch64\release\switch_game\romfs\assets\map\stage_01.map
Test-Path build\switch\aarch64\release\switch_game\romfs\assets\ASSETS.md
Test-Path build\switch\aarch64\release\switch_game\romfs\assets\fonts
Test-Path build\switch\aarch64\release\switch_game\romfs\assets\stage\stage_01\reference\mossy_cavern_reference_4hibzc.png
```

## 手动跑图检查

操作映射见 `controls.md`。

1. 启动 Windows 版 `Frostbite2DGame.exe`。
2. 从出生点向右移动，确认摄像机横向跟随且不露出世界外黑边。
3. 依次进入 3 个 battle zone，确认 camera bounds 平滑切换，没有硬切瞬移。
4. 通过 debug 清场或离开区域解除锁定，确认摄像机恢复全关卡跟随。
5. 使用 debug 分项开关检查：
   - 碰撞矩形和场景网格。
   - 玩家包围盒。
   - battle zone 触发框和 camera bounds。
   - 敌人出生点。
6. 从起点移动到终点附近，确认所有平台、props、前景遮挡和背景层没有闪烁或黑屏。
7. 确认 UI overlay 可见；若没有字体资源，应显示左上角色条 fallback。
8. 切换 F1/F3/F4/F5/F6 后重启，确认 debug 开关能通过 `SaveSystem` 记住。

## 当前验收结果

日期：2026-06-09

- Windows release 构建：通过。
- Windows 3 秒短启动：通过。
- Switch `Frostbite2DGameSwitch` 构建：通过。
- Switch RomFS：已包含 character、shader、`stage_01` 资源槽位和 `assets/map/stage_01.map`。
- 地图加载：`stage_01.map` 已作为第一关主数据源；C++ 白盒数据仅作为 fallback。
- 地图视觉：`stage_01.map` 已重做为 `4HibZC.jpg` 的一比一参考图复刻版，当前通过 `reference/mossy_cavern_reference_4hibzc.png` 作为完整底图表达。
- 引擎能力接入：`Animation`/NPK/PNG 角色资源优先级、`UIScene`/`TextSprite` UI、`Sound`/`Music` cue、`SaveSystem` debug 存档已接入。
- 手动跑图：未在本轮执行，等待后续素材/战斗区域进一步接入时复测。

## 后续补充

- 增加输入状态 debug 显示后，把输入检查纳入本流程。
- 增加 `EnemyActor` 后，把 battle zone 自动清场纳入本流程。
- 增加 hitbox/hurtbox 后，把战斗 debug 绘制纳入本流程。