NS_unknown_game/game/docs/game_skeleton.md

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。
• 探测并打开可选 Script.pvf。
• 初始化 NpkArchive。
• 初始化 SoundPackArchive。
• 探测并加载可选 AudioDatabase。
• 记录 SaveSystem 是否已由引擎初始化。

这些服务是可选能力。缺少 Script.pvf、ImagePacks2、SoundPacks 或 audio.xml 时，游戏仍然使用当前 PNG/白盒 fallback 启动。

地图资源入口

新增 StageMapResource：

LoadStageMapResource("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 占位文件。
• CreateWhiteboxLevel() 会读取地图资源并记录来源。
• 地图内容尚未接管 LevelDefinition，当前仍使用 C++ 白盒数据作为 fallback。

下一步：

• 实现 StageMapLoader，把 .map 转成 LevelDefinition。
• 将 whitebox_level.cpp 中的硬编码平台、props、battle zone 迁移到 .map。
• 失败时保留 CreateFallbackWhiteboxLevel()。

仍待迁移的能力

• 玩家动画：从手写 spritesheet 帧切换迁移到引擎 Animation / PVF ANI。
• 场景视觉资源：如果素材进入 NPK，迁移到 NpkArchive / Sprite::createFromNpk。
• 音频：使用 AudioSystem、Sound、Music、AudioDatabase。
• 地图：完成 .map parser，不再用 C++ 手写地图。
• 输入配置：通过 Asset 或 PVF 读取 InputConfig。

原则

• 优先使用引擎能力。
• 游戏层只做数据转换和玩法语义。
• 外部资源统一走 Asset / PvfArchive。
• C++ 白盒数据只保留为 fallback。