108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
# Game Skeleton
|
||
|
||
本文档记录当前游戏骨架如何优先复用 Frostbite2D 引擎能力。目标是让游戏层只负责游戏语义，不重复实现引擎已经提供的资源、归档、音频、存档、场景和渲染基础设施。
|
||
|
||
## 当前接入状态
|
||
|
||
### Application 基础服务
|
||
|
||
由引擎 `Application::init()` 负责：
|
||
|
||
- `Asset` 工作目录和资源路径解析。
|
||
- `SaveSystem` 初始化。
|
||
- SDL video/events/controller 初始化。
|
||
- Window / Renderer / Camera 初始化。
|
||
- PixelArt2D 渲染风格和虚拟分辨率。
|
||
- `TaskSystem` 初始化。
|
||
|
||
由引擎 `Application::shutdown()` 负责：
|
||
|
||
- `SceneManager` 清理。
|
||
- `Renderer` 清理。
|
||
- `AudioSystem` 清理。
|
||
- `NpkArchive` / `PvfArchive` / `SoundPackArchive` 清理。
|
||
- 平台资源清理。
|
||
|
||
### GameServices
|
||
|
||
游戏层新增 `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 启动。
|
||
|
||
## 引擎能力接入点
|
||
|
||
当前游戏骨架已把以下引擎能力接入到真实调用路径：
|
||
|
||
- `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`。
|
||
|
||
## 地图资源入口
|
||
|
||
新增 `StageMapResource` 和 `StageMapLoader`：
|
||
|
||
```text
|
||
LoadStageMapResource("map/stage_01.map")
|
||
LoadStageMap("map/stage_01.map")
|
||
```
|
||
|
||
读取优先级：
|
||
|
||
1. `Asset` 普通文本资源：`map/stage_01.map`
|
||
2. `Asset` fallback：`assets/map/stage_01.map`
|
||
3. `PvfArchive` 二进制脚本：`map/stage_01.map`
|
||
4. `PvfArchive` 文本内容：`map/stage_01.map`
|
||
|
||
当前状态：
|
||
|
||
- `game/assets/map/stage_01.map` 已接管第一关主数据。
|
||
- `StageMapLoader` 会把 `.map` 文本解析成 `LevelDefinition`。
|
||
- 已迁移世界尺寸、玩家出生点、相机边界、碰撞平台、视觉层、props、battle zone 和 spawn point。
|
||
- `CreateWhiteboxLevel()` 优先读取 `.map`，读取或解析失败时才使用 C++ 白盒 fallback。
|
||
- Windows 和 Switch 构建会把 `game/assets/*` 复制到产物 `assets/`，保证运行时 `assets/map/stage_01.map` 路径可用。
|
||
|
||
`.map` 当前支持的命令：
|
||
|
||
```text
|
||
map <id>
|
||
world <width> <height>
|
||
camera <x> <y> <width> <height>
|
||
player_spawn <x> <y>
|
||
collision <x> <y> <width> <height>
|
||
layer <id> <BackgroundFar|BackgroundMid|LevelVisual|PropsBack|PropsFront> <parallax>
|
||
rect <x> <y> <width> <height> <r> <g> <b> <a>
|
||
rect_sprite <x> <y> <width> <height> <r> <g> <b> <a> <texture>
|
||
rect_sprite_src <x> <y> <width> <height> <r> <g> <b> <a> <texture> <sx> <sy> <sw> <sh>
|
||
endlayer
|
||
battle_zone <id> <trigger_x> <trigger_y> <trigger_w> <trigger_h> <camera_x> <camera_y> <camera_w> <camera_h>
|
||
spawn <id> <x> <y>
|
||
endbattle_zone
|
||
```
|
||
|
||
## 仍待迁移的能力
|
||
|
||
- 玩家动画：当前已接入 `Animation` 优先路径，但临时 PNG fallback 仍保留手写帧切换，等待正式 PVF/NPK 动画资源。
|
||
- 场景视觉资源：`StageRenderer` 支持普通 PNG；若素材进入 NPK，后续补 stage layer 的 NPK sprite path。
|
||
- 音频：调用路径已接入，等待正式音频资源和 `audio.xml`。
|
||
- 地图：后续可把 `.map` 扩展为工具导出格式或 PVF 脚本格式，当前 C++ 地图只作为 fallback。
|
||
- 输入配置：通过 `Asset` 或 PVF 读取 `InputConfig`。
|
||
|
||
## 原则
|
||
|
||
- 优先使用引擎能力。
|
||
- 游戏层只做数据转换和玩法语义。
|
||
- 外部资源统一走 `Asset` / `PvfArchive`。
|
||
- C++ 白盒数据只保留为 fallback。
|