# 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。