diff --git a/game/docs/README.md b/game/docs/README.md index 74ecc44..82ce974 100644 --- a/game/docs/README.md +++ b/game/docs/README.md @@ -10,6 +10,7 @@ ## References - `controls.md`:玩家操作、平台输入映射和开发调试快捷键。 +- `scene_acceptance.md`:第一关场景骨架验收流程和最近一次验收结果。 ## Naming diff --git a/game/docs/planning/game_architecture_board.md b/game/docs/planning/game_architecture_board.md index 35d49b1..18dd9d5 100644 --- a/game/docs/planning/game_architecture_board.md +++ b/game/docs/planning/game_architecture_board.md @@ -586,11 +586,12 @@ mindmap 1. 已完成:`StageLayerSource` 让 `StageLayer` 同时支持色块占位和 sprite 资源路径。 2. 已完成:`StageAssetSlots` 建立 `stage_01` 资源槽位和素材来源记录,做到素材可直接落位。 3. 已完成:`StageProps` 把后景/前景 props 统一到 layer 数据。 -4. `BattleZone`:把 debug 清场替换为敌人清空自动解锁。 -5. `EnemyActor`:做第一个敌人占位,接入出生点。 -6. `CombatSystem`:把 hitbox/hurtbox 真正跑起来。 -7. `SpriteAnimator`:把玩家动画从硬编码改成组件。 -8. `InputConfig`:把默认键位/手柄映射迁移到可配置数据。 +4. 已完成:`SceneAcceptanceRun` 建立场景骨架验收流程,记录 PC/Switch 构建和跑图检查项。 +5. `BattleZone`:把 debug 清场替换为敌人清空自动解锁。 +6. `EnemyActor`:做第一个敌人占位,接入出生点。 +7. `CombatSystem`:把 hitbox/hurtbox 真正跑起来。 +8. `SpriteAnimator`:把玩家动画从硬编码改成组件。 +9. `InputConfig`:把默认键位/手柄映射迁移到可配置数据。 ## 素材协作提示 diff --git a/game/docs/planning/scene_build_plan.md b/game/docs/planning/scene_build_plan.md index 0024eb4..621ad8d 100644 --- a/game/docs/planning/scene_build_plan.md +++ b/game/docs/planning/scene_build_plan.md @@ -29,6 +29,7 @@ - `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. 第一关场景目标 @@ -251,7 +252,7 @@ game/assets/stage/stage_01/ - `LevelDefinition` 能表达世界尺寸、玩家出生点、相机边界、碰撞、视觉层、props、battle zone、spawn point。 - `StageRenderer` 能按层绘制远景、中景、地面/平台、后景 props、前景 props,并支持资源图和色块占位两种来源。 - `DebugOverlay` 能显示碰撞、battle zone、camera lock、spawn point、玩家包围盒。 -- 关卡灰盒能从起点跑到终点,至少 3 个推进段和 3 个 battle zone 都能被观察到。 +- 关卡灰盒能从起点跑到终点,至少 3 个推进段和 3 个 battle zone 都能被观察到;具体验收流程见 `../scene_acceptance.md`。 - 素材目录、命名、来源记录文件已经准备好,后续放入 PNG 后只改资源引用。 ### 场景骨架实施顺序 @@ -262,7 +263,11 @@ game/assets/stage/stage_01/ 4. 已完成:`StageAssetSlots` 创建并记录 `stage_01` 资源槽位,不要求已有最终素材。 5. 已完成:`StageProps` 把 props 从旧 `WhiteboxProp` 迁移到统一 layer 数据,支持 back/front 两层。 6. 已完成:`SceneDebug` 补齐 debug 总开关,并预留/接入分项开关。 -7. `SceneAcceptanceRun`:PC 和 Switch 都构建通过,PC 能从起点移动到终点并看到相机推进。 +7. 已完成:`SceneAcceptanceRun` 建立场景骨架验收文档;PC 和 Switch 构建通过,PC 短启动通过。 + +### 场景骨架阶段结论 + +当前场景骨架已经达到“可直接放素材”的工程状态。后续素材接入主要修改 `game/assets/stage/stage_01/` 和关卡 layer 数据,不需要再重写 `WhiteboxScene` 主流程。 ### Debug 快捷键 diff --git a/game/docs/scene_acceptance.md b/game/docs/scene_acceptance.md new file mode 100644 index 0000000..ac7c24e --- /dev/null +++ b/game/docs/scene_acceptance.md @@ -0,0 +1,76 @@ +# Scene Acceptance + +本文档记录第一关场景骨架的验收流程。每次改动场景、摄像机、关卡数据、输入或渲染层后,至少执行构建检查;涉及跑图手感时再执行手动跑图检查。 + +## 验收范围 + +- 场景入口:`WhiteboxScene` +- 关卡数据:`CreateWhiteboxLevel()` +- 世界尺寸:`3200 x 720` +- 玩家出生点:`(160, 380)` +- 关卡边界:`0 -> 3200` +- 视口:`1280 x 720` +- Battle zones:`zone_01_intro`、`zone_02_platform`、`zone_03_exit` +- 资源槽位:`game/assets/stage/stage_01/` + +## 构建检查 + +### 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 } +``` + +### 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 +``` + +## 手动跑图检查 + +操作映射见 `controls.md`。 + +1. 启动 Windows 版 `Frostbite2DGame.exe`。 +2. 从出生点向右移动,确认摄像机横向跟随且不露出世界外黑边。 +3. 依次进入 3 个 battle zone,确认 camera bounds 平滑切换,没有硬切瞬移。 +4. 通过 debug 清场或离开区域解除锁定,确认摄像机恢复全关卡跟随。 +5. 使用 debug 分项开关检查: + - 碰撞矩形和场景网格。 + - 玩家包围盒。 + - battle zone 触发框和 camera bounds。 + - 敌人出生点。 +6. 从起点移动到终点附近,确认所有平台、props、前景遮挡和背景层没有闪烁或黑屏。 + +## 当前验收结果 + +日期:2026-06-09 + +- Windows release 构建:通过。 +- Windows 3 秒短启动:通过。 +- Switch `Frostbite2DGameSwitch` 构建:通过。 +- Switch RomFS:已包含 character、shader 和 `stage_01` 资源槽位。 +- 手动跑图:未在本轮执行,等待后续素材/战斗区域进一步接入时复测。 + +## 后续补充 + +- 增加输入状态 debug 显示后,把输入检查纳入本流程。 +- 增加 `EnemyActor` 后,把 battle zone 自动清场纳入本流程。 +- 增加 hitbox/hurtbox 后,把战斗 debug 绘制纳入本流程。