Wire engine feature services into game skeleton
This commit is contained in:
@@ -10,6 +10,7 @@
|
||||
|
||||
## References
|
||||
|
||||
- `../assets/ASSETS.md`：全局资源槽位，包含字体、音频、PVF、NPK、SoundPack 和角色动画 fallback 路径。
|
||||
- `controls.md`：玩家操作、平台输入映射和开发调试快捷键。
|
||||
- `engine_capability_audit.md`：引擎已有能力复盘，以及游戏层应优先复用的系统。
|
||||
- `game_skeleton.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. 游戏层贴图缓存
|
||||
|
||||
|
||||
@@ -28,13 +28,26 @@
|
||||
游戏层新增 `GameServices`，只做游戏项目需要的引擎服务接入和状态记录：
|
||||
|
||||
- 初始化 `AudioSystem`。
|
||||
- 初始化 `FontManager`，有 `assets/fonts/debug.ttf` 或 `assets/fonts/ui.ttf` 时注册 debug 字体。
|
||||
- 探测并打开可选 `Script.pvf`。
|
||||
- 初始化 `NpkArchive`。
|
||||
- 初始化 `SoundPackArchive`。
|
||||
- 探测并加载可选 `AudioDatabase`。
|
||||
- 记录 `SaveSystem` 是否已由引擎初始化。
|
||||
|
||||
这些服务是可选能力。缺少 `Script.pvf`、`ImagePacks2`、`SoundPacks` 或 `audio.xml` 时，游戏仍然使用当前 PNG/白盒 fallback 启动。
|
||||
这些服务是可选能力。缺少 `Script.pvf`、`ImagePacks2`、`SoundPacks`、字体、音频或 `audio.xml` 时，游戏仍然使用当前 PNG/白盒 fallback 启动。
|
||||
|
||||
## 引擎能力接入点
|
||||
|
||||
当前游戏骨架已把以下引擎能力接入到真实调用路径：
|
||||
|
||||
- `Animation`：`PlayerActor` 会优先尝试 PVF `.ani`，失败后回退 NPK IMG，再回退 PNG spritesheet。
|
||||
- `NpkArchive` / `Sprite::createFromNpk`：角色资源和后续场景素材可从 `assets/ImagePacks2/*.npk` 进入。
|
||||
- `TextSprite` / `UIScene`：`GameUiOverlay` 已接入 UI scene stack；有字体时显示文字状态，没有字体时用色条 fallback。
|
||||
- `Sound` / `Music` / `AudioDatabase`：`GameAudio` 已支持 cue id，优先使用 `audio.xml`，否则读取 `assets/sounds/*.wav` 和 `assets/music/*.ogg`。
|
||||
- `SaveSystem`：`GameSave` 已保存/读取 debug overlay 开关状态。
|
||||
|
||||
资源槽位见 `../assets/ASSETS.md`。
|
||||
|
||||
## 地图资源入口
|
||||
|
||||
@@ -80,9 +93,9 @@ endbattle_zone
|
||||
|
||||
## 仍待迁移的能力
|
||||
|
||||
- 玩家动画：从手写 spritesheet 帧切换迁移到引擎 `Animation` / PVF ANI。
|
||||
- 场景视觉资源：如果素材进入 NPK，迁移到 `NpkArchive` / `Sprite::createFromNpk`。
|
||||
- 音频：使用 `AudioSystem`、`Sound`、`Music`、`AudioDatabase`。
|
||||
- 玩家动画：当前已接入 `Animation` 优先路径，但临时 PNG fallback 仍保留手写帧切换，等待正式 PVF/NPK 动画资源。
|
||||
- 场景视觉资源：`StageRenderer` 支持普通 PNG；若素材进入 NPK，后续补 stage layer 的 NPK sprite path。
|
||||
- 音频：调用路径已接入，等待正式音频资源和 `audio.xml`。
|
||||
- 地图：后续可把 `.map` 扩展为工具导出格式或 PVF 脚本格式，当前 C++ 地图只作为 fallback。
|
||||
- 输入配置：通过 `Asset` 或 PVF 读取 `InputConfig`。
|
||||
|
||||
|
||||
@@ -273,15 +273,24 @@ game/assets/stage/stage_01/
|
||||
|
||||
第一轮引擎能力接入已完成：`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 entry 约定，先不做编辑器，只保证工具或手写数据能表达重复地砖。
|
||||
2. 在 `StageRenderer` 中增加 tile 绘制路径，复用当前 `Texture` 加载和 source rect 支持。
|
||||
3. 把 `level_visual` 的长色块逐步替换成 tile entries，碰撞仍独立保留在 `collision`。
|
||||
4. 给 map loader 增加更严格的错误日志，例如重复 block、空 layer、battle zone 无 spawn 的提示。
|
||||
5. 补一个轻量 map 验收流程：启动时日志确认加载 `.map`，RomFS/Windows 产物确认存在 `assets/map/stage_01.map`。
|
||||
4. 给 map loader 增加更严格的错误日志，例如重复 block、空 layer、battle zone 无 spawn、tile 引用不存在的提示。
|
||||
5. 补一个轻量 map 验收流程：启动时日志确认加载 `.map`，Windows/Switch 产物确认存在 `assets/map/stage_01.map` 和全局素材槽位。
|
||||
|
||||
### Debug 快捷键
|
||||
|
||||
|
||||
@@ -14,6 +14,9 @@
|
||||
- Battle zones：`zone_01_intro`、`zone_02_platform`、`zone_03_exit`
|
||||
- 资源槽位：`game/assets/stage/stage_01/`
|
||||
- 地图资源：`game/assets/map/stage_01.map`
|
||||
- 全局资源槽位：`game/assets/ASSETS.md`
|
||||
- UI overlay：`GameUiOverlay`，有字体时使用 `TextSprite`，无字体时使用 fallback 色条。
|
||||
- 音频 cue：`stage_01`、`player_jump`、`player_attack`、`battle_zone_enter`。
|
||||
|
||||
## 构建检查
|
||||
|
||||
@@ -37,6 +40,8 @@ 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
|
||||
```
|
||||
|
||||
### Switch
|
||||
@@ -56,6 +61,8 @@ 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
|
||||
```
|
||||
|
||||
## 手动跑图检查
|
||||
@@ -72,6 +79,8 @@ Test-Path build\switch\aarch64\release\switch_game\romfs\assets\map\stage_01.map
|
||||
- battle zone 触发框和 camera bounds。
|
||||
- 敌人出生点。
|
||||
6. 从起点移动到终点附近，确认所有平台、props、前景遮挡和背景层没有闪烁或黑屏。
|
||||
7. 确认 UI overlay 可见；若没有字体资源，应显示左上角色条 fallback。
|
||||
8. 切换 F1/F3/F4/F5/F6 后重启，确认 debug 开关能通过 `SaveSystem` 记住。
|
||||
|
||||
## 当前验收结果
|
||||
|
||||
@@ -82,6 +91,7 @@ Test-Path build\switch\aarch64\release\switch_game\romfs\assets\map\stage_01.map
|
||||
- Switch `Frostbite2DGameSwitch` 构建：通过。
|
||||
- Switch RomFS：已包含 character、shader、`stage_01` 资源槽位和 `assets/map/stage_01.map`。
|
||||
- 地图加载：`stage_01.map` 已作为第一关主数据源；C++ 白盒数据仅作为 fallback。
|
||||
- 引擎能力接入：`Animation`/NPK/PNG 角色资源优先级、`UIScene`/`TextSprite` UI、`Sound`/`Music` cue、`SaveSystem` debug 存档已接入。
|
||||
- 手动跑图：未在本轮执行，等待后续素材/战斗区域进一步接入时复测。
|
||||
|
||||
## 后续补充
|
||||
|
||||
Reference in New Issue
Block a user