Wire engine feature services into game skeleton

game/docs/engine_capability_audit.md

@@ -4,11 +4,11 @@
 
 ## 结论
 
-当前游戏层已经用了引擎的核心框架，但地图和角色动画仍有明显“游戏层自造/硬编码”倾向。
+当前游戏层已经用了引擎核心框架，并且已把地图、动画、UI、音频、存档和 NPK/SoundPack 资源入口接到真实调用路径。
 
-最重要的调整是：**场景地图不要继续在 C++ 里手写 `Rect`，下一步应接入 `.map` 文件加载，并优先通过引擎 `Asset` / `PvfArchive` / `ScriptParser` 读取和解析。**
+最重要的调整已经完成：场景地图不再以 C++ 硬编码为主，`stage_01.map` 通过 `Asset` / `PvfArchive` / `ScriptParser` 读取入口进入 `LevelDefinition`。
 
-当前第一轮骨架接入已完成：游戏启动时通过 `GameServices` 探测/初始化 `AudioSystem`、`PvfArchive`、`NpkArchive`、`SoundPackArchive`、`AudioDatabase` 和 `SaveSystem` 状态，并通过 `StageMapResource` + `StageMapLoader` 接入 `.map` 资源读取和解析入口。详细状态见 `game_skeleton.md`。
+当前骨架接入状态：游戏启动时通过 `GameServices` 探测/初始化 `AudioSystem`、`FontManager`、`PvfArchive`、`NpkArchive`、`SoundPackArchive`、`AudioDatabase` 和 `SaveSystem` 状态；`PlayerActor` 已接入 `Animation`/NPK/PNG 优先级；`WhiteboxScene` 已接入 `UIScene`、音频 cue 和 debug 存档。详细状态见 `game_skeleton.md`。
 
 推荐方向：
 
@@ -60,6 +60,7 @@
 
 - `StageRenderer` 已复用引擎 Renderer 和 Texture。
 - `CameraController` 使用引擎 `Camera` 做位置控制。
+- `GameUiOverlay` 通过 `UIScene` 进入 UI scene stack。
 - 游戏入口已设置像素风渲染风格。
 
 需要调整：
@@ -79,6 +80,7 @@
 - `StageMapResource` 已直接使用 `Asset::readFileToString` 读取 `map/stage_01.map` 或 `assets/map/stage_01.map`。
 - Windows 和 Switch 构建会把 `game/assets/*` 复制到产物 `assets/`，保证 `assets/map/stage_01.map` 路径可用。
 - `stage_01` 主地图已迁移到外部 `.map` 文件。
+- `GameAudio`、`GameServices`、`PlayerAnimationAssets` 都通过 `Asset` 检查可选资源。
 
 下一步：
 
@@ -122,19 +124,19 @@
 
 当前状态：
 
-- 玩家现在使用 `Sprite::createFromFile` 加载 PNG spritesheet。
-- 玩家动画帧切换在 `PlayerActor` 内手写。
-- 还没有使用 `Animation`、`.ani`、`.als`、PVF 动画数据或 NPK 图包。
+- 玩家动画加载顺序为 PVF `.ani` -> NPK IMG -> PNG fallback。
+- 如果 PVF 中存在 `character/male/*.ani`，`PlayerActor` 会使用引擎 `Animation`。
+- 如果 NPK 中存在 `sprite/character/male/*.img`，会使用 `Sprite::createFromNpk`。
+- 当前仓库没有正式 PVF/NPK 动画资源，因此运行时仍会回退到 PNG spritesheet。
 
 风险：
 
-- 如果继续手写动画，后续敌人、玩家连招、受击、死亡都会重复造动画系统。
+- 只要正式动画资源未进入 PVF/NPK，临时 PNG fallback 仍需要少量手写帧切换。
 
 下一步建议：
 
-- 在地图框架后，角色动画应迁移到引擎 `Animation`。
-- 若素材来自 NPK/PVF 体系，优先用 `Animation + NpkArchive + parseAniFromPvf`。
-- 若当前临时素材仍是 PNG spritesheet，可以短期保留，但不要扩展成复杂自研动画状态系统。
+- 为玩家和敌人补齐 PVF `.ani` 或 NPK IMG 后，逐步移除 PNG fallback 的手写帧切换。
+- 将 attack/damage box 从 `Animation::GetCurrentFrameInfo()` 接入战斗 hitbox。
 
 ### Audio / Save
 
@@ -149,12 +151,29 @@
 
 当前状态：
 
-- 游戏层尚未使用音频和存档。
+- `GameAudio` 已接入 `Sound`、`Music` 和 `AudioDatabase` 查询。
+- `WhiteboxScene` 会尝试播放 `stage_01` BGM 和 battle zone 进入音效。
+- `PlayerActor` 会尝试播放跳跃、攻击音效。
+- `GameSave` 已用 `SaveSystem` 保存 debug overlay 开关。
 
 后续原则：
 
-- 音效、BGM、环境音直接接引擎音频系统。
-- 设置、进度、调试存档优先用 `SaveSystem`，不要在游戏层重新写文件存档服务。
+- 正式音效、BGM、环境音直接放入资源槽位或 `audio.xml`。
+- 设置、进度继续用 `SaveSystem`，不要在游戏层重新写文件存档服务。
+
+### UI / Text
+
+引擎已有：
+
+- `UIScene`
+- `TextSprite`
+- `FontManager`
+
+当前状态：
+
+- `GameUiOverlay` 已作为 `UIScene` 接入。
+- 有 `assets/fonts/debug.ttf` 或 `assets/fonts/ui.ttf` 时，状态 UI 使用 `TextSprite`。
+- 缺字体时使用 `Renderer::drawQuad` 色条 fallback，避免 Switch/PC 因字体缺失黑屏。
 
 ### Event / Input
 
@@ -198,20 +217,20 @@
 - 继续扩展 `.map` 的 tileset/tile entry 表达。
 - 逐步把 `level_visual` 的长色块替换成 tile 数据。
 
-### 2. 手写动画帧切换
+### 2. PNG fallback 手写动画帧切换
 
 文件：
 
 - `game/src/actor/player_actor.cpp`
 
-问题：
+当前状态：
 
-- idle/run/punch 都在 C++ 里硬编码帧数、帧时间和 source rect。
+- 已接入 `Animation` 和 NPK 优先路径。
+- 临时 PNG fallback 仍在 C++ 里硬编码帧数、帧时间和 source rect。
 
 建议：
 
-- 先记录为短期可接受。
-- 后续迁移到引擎 `Animation`，尤其当角色素材进入 PVF/NPK/ANI 体系后。
+- 等正式 `.ani` / `.img` 资源补齐后，删除 PNG fallback 的手写帧切换。
 
 ### 3. 游戏层贴图缓存