NS_unknown_game/game/docs/game_skeleton.md

Game Skeleton

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

总体目标

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

当前主流程

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，不作为长期生产方式。