游戏架构

该项目将游戏层与 Frostbite2D 引擎分离开来。引擎保留在 Frostbite2D/ 目录下；游戏特定代码位于 game/ 目录下。

目录结构

game/
├─ assets/
│  ├─ character/        运行时角色精灵图
│  └─ shaders/          游戏目标使用的运行时着色器
├─ docs/
│  └─ ARCHITECTURE.md   本文档
└─ src/
   ├─ actor/            游戏角色，如玩家、敌人、抛射物
   ├─ combat/           碰撞箱、伤害判定和战斗解算类型
   ├─ core/             共享配置、输入快照和资源路径
   ├─ data/             关卡和游戏数据定义
   ├─ debug/            调试可视化叠层
   ├─ movement/         可复用的移动和碰撞辅助工具
   ├─ scene/            游戏场景和关卡编排
   ├─ stage/            关卡视觉层渲染
   └─ main.cpp          游戏可执行文件入口点

运行时流程

main.cpp
  -> Application::init()
  -> SceneManager::ReplaceScene(WhiteboxScene)
  -> WhiteboxScene::onEnter()
      -> CreateWhiteboxLevel()
      -> 创建 PlayerActor
      -> 将 PlatformWorld 传递给 PlayerActor
  -> 每一帧：
      -> PlayerActor 采样 InputState
      -> PlayerActor 通过 PlatformMover 移动
      -> PlayerActor 更新动画
      -> WhiteboxScene 更新摄像机
      -> StageRenderer 绘制关卡视觉层
      -> Actor 渲染
      -> DebugOverlay 绘制调试叠层

模块职责

core

game_config.h 存储共享的调整常数，如虚拟分辨率、重力、玩家速度和攻击持续时间
asset_paths.h 存储稳定的运行时资源路径
debug_flags.h 集中控制开发期调试显示开关
input_state.* 将原始 SDL 键盘状态转换为与引擎无关的 InputState 快照。玩家逻辑使用此快照而不是直接读取 SDL

movement

PlatformWorld 拥有关卡边界和平台矩形
MovementBody 是可复用的位置/尺寸/速度容器
PlatformMover 应用重力、限制水平边界并解算基本的顶面平台着陆

data

LevelDefinition 组合碰撞和白盒道具
CreateWhiteboxLevel() 当前返回第一个硬编码的阻挡关卡。稍后可以替换为 JSON、Tiled、LDtk 或自定义编辑器导出，而无需更改 PlayerActor

actor

PlayerActor 拥有玩家精灵、玩家状态和动画
它依赖于 InputStateProvider 和 PlatformMover，因此输入和移动可以被敌人复用或独立更改

scene

WhiteboxScene 编排当前关卡：加载关卡数据、创建角色、委托关卡渲染、委托调试叠层并控制摄像机

stage

StageRenderer 绘制当前关卡视觉层，包括背景、网格、白盒道具和平台
后续 tileset、视差背景和 props 渲染都应该优先接入该模块

debug

DebugOverlay 绘制碰撞矩形和玩家包围盒
DebugFlags 决定哪些调试层启用

combat

hitbox.h 定义早期的 Hitbox 和 Hurtbox 结构体及团队过滤。完整的 ACT 战斗应该建立在此基础上，而不是在角色中嵌入打击判定

当前构建目标

xmake.lua 为 Windows 定义 Frostbite2DGame。它编译桌面游戏入口 game/src/main.cpp 和所有通用游戏源码，链接到 Frostbite2D，并在构建后将 game/assets 复制到可执行文件旁边。

构建命令：

xmake -b Frostbite2DGame

输出：

build/windows/x64/release/Frostbite2DGame.exe

Switch/NS 游戏框架目标为 Frostbite2DGameSwitch。它复用 game/src/main.cpp，入口内部通过 __SWITCH__ 编译分支处理平台差异，并复用同一套 Scene、Stage、Actor、Movement、Debug 和 Data 模块。

构建命令：

xmake -b Frostbite2DGameSwitch

输出：

build/switch/aarch64/release/Frostbite2DGame.elf
build/switch/aarch64/release/switch_game/NSUnknownGame.nro

Switch 运行时资源目录优先使用内嵌 RomFS：

romfs:/assets

后续架构步骤

添加 actor/enemy_actor.* 并复用 PlatformMover
添加 combat/CombatSystem 来收集每一帧的活跃碰撞箱和伤害判定箱、解算打击并发出伤害事件
用数据定义替换 PlayerActor 中的硬编码动画时序
当第一个白盒循环稳定后，将 CreateWhiteboxLevel() 迁移到外部关卡格式
如果多个关卡共享生成、摄像机、战斗和暂停逻辑，则添加 scene/gameplay_scene 基类

4.4 KiB Raw Blame History