Split game module documentation
This commit is contained in:
+40
-88
@@ -1,107 +1,59 @@
|
||||
# Game Skeleton
|
||||
|
||||
本文档记录当前游戏骨架如何优先复用 Frostbite2D 引擎能力。目标是让游戏层只负责游戏语义，不重复实现引擎已经提供的资源、归档、音频、存档、场景和渲染基础设施。
|
||||
本文档只保留游戏骨架总览。具体模块细节已经拆分到 `modules/`，后续查实现优先看对应模块文档。
|
||||
|
||||
## 当前接入状态
|
||||
## 总体目标
|
||||
|
||||
### Application 基础服务
|
||||
当前游戏骨架的目标是：游戏层只负责 ACT 清版游戏语义，资源、归档、动画、音频、存档、场景、UI 和渲染基础设施尽量复用 Frostbite2D 引擎能力。
|
||||
|
||||
由引擎 `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")
|
||||
main.cpp
|
||||
-> Application::init()
|
||||
-> GameServices::Initialize()
|
||||
-> WhiteboxScene
|
||||
-> LoadStageMap("map/stage_01.map")
|
||||
-> LevelDefinition
|
||||
-> StageRenderer / PlayerActor / DebugOverlay / GameUiOverlay
|
||||
```
|
||||
|
||||
读取优先级：
|
||||
## 模块文档入口
|
||||
|
||||
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`
|
||||
- `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`：战斗模块预留。
|
||||
|
||||
当前状态：
|
||||
## 当前已接入的引擎能力
|
||||
|
||||
- `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` 路径可用。
|
||||
- `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`：场景主循环、对象树、渲染和镜头。
|
||||
|
||||
`.map` 当前支持的命令：
|
||||
## 当前 fallback 策略
|
||||
|
||||
```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`。
|
||||
- 缺 PVF/NPK 时，玩家回退 PNG spritesheet。
|
||||
- 缺字体时，UI overlay 回退色条。
|
||||
- 缺音频资源时，音频 cue 静默跳过。
|
||||
- 缺 `.map` 或解析失败时，`whitebox_level.cpp` 提供 C++ 白盒 fallback。
|
||||
|
||||
## 原则
|
||||
|
||||
- 优先使用引擎能力。
|
||||
- 引擎已有能力优先使用。
|
||||
- 游戏层只做数据转换和玩法语义。
|
||||
- 外部资源统一走 `Asset` / `PvfArchive`。
|
||||
- C++ 白盒数据只保留为 fallback。
|
||||
- C++ 白盒数据只保留为 fallback，不作为长期生产方式。
|
||||
|
||||
Reference in New Issue
Block a user