# Game Skeleton

本文档只保留游戏骨架总览。具体模块细节已经拆分到 `modules/`，后续查实现优先看对应模块文档。

## 总体目标

当前游戏骨架的目标是：游戏层只负责 ACT 清版游戏语义，资源、归档、动画、音频、存档、场景、UI 和渲染基础设施尽量复用 Frostbite2D 引擎能力。

## 当前主流程

```text
main.cpp
  -> Application::init()
  -> GameServices::Initialize()
  -> WhiteboxScene
  -> LoadStageMap("map/stage_01.map")
  -> LevelDefinition
  -> StageRenderer / PlayerActor / DebugOverlay / GameUiOverlay
```

## 模块文档入口

- `modules/core_services.md`：启动、服务、配置、资源路径。
- `modules/assets.md`：全局资源槽位、PVF/NPK/PNG fallback。
- `modules/data_map.md`：`.map`、`StageMapLoader`、`LevelDefinition`。
- `modules/stage_rendering.md`：场景分层、parallax、sprite/色块 fallback。
- `modules/scene_camera.md`：`WhiteboxScene`、摄像机、battle zone。
- `modules/movement_collision.md`：平台碰撞、横版移动。
- `modules/actor_player.md`：玩家 Actor、动画、输入消费。
- `modules/input.md`：PC/Switch 输入统一语义。
- `modules/ui_overlay.md`：`UIScene`、`TextSprite`、fallback UI。
- `modules/audio_save.md`：音频 cue、debug 存档。
- `modules/debug_tools.md`：调试可视化。
- `modules/combat.md`：战斗模块预留。

## 当前已接入的引擎能力

- `Asset`：地图、贴图、字体、音频 fallback 路径。
- `PvfArchive` / `ScriptParser`：`.map` 和 `.ani` 预留读取入口。
- `NpkArchive` / `Sprite::createFromNpk`：角色资源 fallback。
- `Animation`：玩家动画优先路径。
- `AudioSystem` / `Sound` / `Music` / `AudioDatabase`：音频 cue。
- `SaveSystem`：debug 开关存档。
- `UIScene` / `TextSprite` / `FontManager`：局内 UI overlay。
- `Scene` / `Actor` / `Renderer` / `Camera`：场景主循环、对象树、渲染和镜头。

## 当前 fallback 策略

- 缺 PVF/NPK 时，玩家回退 PNG spritesheet。
- 缺字体时，UI overlay 回退色条。
- 缺音频资源时，音频 cue 静默跳过。
- 缺 `.map` 或解析失败时，`whitebox_level.cpp` 提供 C++ 白盒 fallback。

## 原则

- 引擎已有能力优先使用。
- 游戏层只做数据转换和玩法语义。
- 外部资源统一走 `Asset` / `PvfArchive`。
- C++ 白盒数据只保留为 fallback，不作为长期生产方式。