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：

LoadStageMapResource("map/stage_01.map")
LoadStageMap("map/stage_01.map")

读取优先级：

Asset 普通文本资源：map/stage_01.map
Asset fallback：assets/map/stage_01.map
PvfArchive 二进制脚本：map/stage_01.map
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 当前支持的命令：

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。

4.3 KiB Raw Blame History Unescape Escape