# 游戏整体架构计划：思维导图与白板 目标：把项目从“能跑的白盒 Demo”推进为可持续扩展的横板 2D ACT 清版游戏工程。本文先作为整体架构白板，后续每个模块再拆成独立任务文档。 ## 思维导图 ```mermaid mindmap root((横板 2D ACT 游戏)) 核心体验 横向推进 清版战斗 平台移动 近战连段 关卡节奏 游戏循环 进入关卡 探索与移动 触发战斗区域 击败敌人 解锁推进 结算与升级 角色系统 玩家 输入 移动 跳跃 攻击 受击 动画状态机 敌人 巡逻 追击 攻击 受击硬直 死亡 NPC与可交互物 对话 机关 可破坏物 战斗系统 Hitbox Hurtbox 伤害结算 击退 霸体 连击窗口 命中特效 调试显示 关卡系统 场景数据 碰撞数据 视觉层 战斗区域 敌人出生点 镜头限制 出入口 渲染与资源 Sprite Tileset 背景视差 前景遮挡 特效 音频 资源清单 数据驱动 动画表 角色参数 敌人配置 关卡配置 攻击配置 掉落配置 工具与调试 白盒编辑 碰撞可视化 战斗区域可视化 Hitbox可视化 帧率与日志 构建文档 NS平台构建 ``` ## 白板总览 ```text +----------------------+ +----------------------+ +----------------------+ | Game Loop | ---> | Scene | ---> | Stage | | 关卡进入/推进/结算 | | 场景编排与生命周期 | | 关卡数据与视觉层 | +----------------------+ +----------------------+ +----------------------+ | | | v v v +----------------------+ +----------------------+ +----------------------+ | Actor | ---> | Movement | ---> | Collision | | 玩家/敌人/道具/物体 | | 重力/速度/平台移动 | | 地面/平台/边界 | +----------------------+ +----------------------+ +----------------------+ | | v v +----------------------+ +----------------------+ +----------------------+ | Combat | ---> | Animation | ---> | Render | | Hitbox/伤害/击退 | | 状态机/帧表/过渡 | | Sprite/Tile/特效 | +----------------------+ +----------------------+ +----------------------+ | v +----------------------+ +----------------------+ +----------------------+ | Data | ---> | Debug | ---> | Build | | 配置表/关卡/参数 | | 可视化/日志/测试 | | PC/Switch/资源复制 | +----------------------+ +----------------------+ +----------------------+ ``` ## 模块白板 ### 1. Core 职责： - 管理游戏级常量、资源路径、输入快照、运行配置。 - 隔离 SDL 等底层输入细节，让角色逻辑只消费 `InputState`。 - 为后续手柄、Switch Joy-Con、键位配置留接口。 已有： - `core/game_config.h` - `core/asset_paths.h` - `core/input_state.*` - `core/debug_flags.h` 下一步： - 增加 `GameContext`，统一传递全局服务。 - 输入层支持键盘和手柄统一映射。 ### 2. Scene 职责： - 管理场景生命周期。 - 装载关卡数据。 - 创建玩家、敌人、道具和场景对象。 - 控制镜头、战斗区域、关卡推进。 已有： - `scene/whitebox_scene.*` 下一步： - 抽象 `GameplayScene` 作为通用玩法场景基类。 - `WhiteboxScene` 只保留第一关测试内容。 - 引入 battle zone 触发逻辑。 ### 3. Stage 职责： - 表达关卡世界：碰撞、视觉层、背景、道具、出生点、镜头范围。 - 将白盒数据逐步替换为 tileset 和 props。 已有： - `data/level_definition.h` - `data/whitebox_level.cpp` - `movement/platform_world.*` - `stage/stage_renderer.*` 下一步： - 增加 `StageLayer` 数据结构。 - 关卡宽度扩展到 2400 到 3200 像素。 - 引入远景/中景/地面三层绘制。 ### 4. Actor 职责： - 表达游戏对象：玩家、敌人、道具、投射物、可破坏物。 - 每个 Actor 只处理自身状态，不直接管理全局流程。 已有： - `actor/player_actor.*` 下一步： - 增加 `EnemyActor`。 - 增加 `BreakablePropActor`。 - 抽出 `CharacterActor` 作为玩家和敌人的共同基类。 - 将玩家动画切换改为数据驱动。 ### 5. Movement 职责： - 处理速度、重力、平台落地、边界限制。 - 后续支持斜坡、墙体、击退、空中状态。 已有： - `MovementBody` - `PlatformWorld` - `PlatformMover` 下一步： - 支持水平墙体阻挡。 - 支持击退速度覆盖。 - 支持落地事件。 - 支持移动调试可视化。 ### 6. Combat 职责： - 管理攻击盒、受击盒、伤害结算、击退、硬直、命中特效。 - 保证战斗逻辑不散落在 Actor 内部。 已有： - `combat/hitbox.h` 下一步： - 增加 `CombatSystem`。 - 每帧收集 active hitbox / hurtbox。 - 支持 team 过滤、重复命中过滤、伤害事件。 - 增加 debug hitbox 绘制。 ### 7. Animation 职责： - 管理 spritesheet 帧、动画状态、播放速度、循环和过渡。 - 避免每个 Actor 手写帧切换。 当前状态： - `PlayerActor` 内部硬编码 idle/run/punch 动画。 下一步： - 增加 `AnimationClip`。 - 增加 `SpriteAnimator`。 - 增加动画配置表。 - 攻击动画和 hitbox active frame 绑定。 ### 8. Data 职责： - 将玩法参数从 C++ 硬编码逐步迁移到数据。 - 支持关卡、敌人、动画、攻击、掉落配置。 当前状态： - 关卡仍由 `CreateWhiteboxLevel()` 硬编码。 下一步： - 先用 C++ struct 稳定字段。 - 再迁移到 JSON 或编辑器导出格式。 - 资源路径统一记录，避免散落字符串。 ### 9. Render 与资源 职责： - 绘制角色、关卡、背景、道具、特效和调试图形。 - 管理资源目录和运行时拷贝。 已有： - `game/assets/character/male/` - `game/assets/shaders/` - `xmake.lua` 自动复制 `game/assets` 下一步： - 增加 `game/assets/stage/stage_01/`。 - 引入 tileset、背景、props。 - 增加视差背景绘制。 - 建立素材来源和授权记录。 ### 10. Debug 与工具 职责： - 提供开发时必要的可视化和状态观察。 - 降低调试碰撞、战斗和关卡触发的成本。 下一步： - `debug/debug_overlay.*` 已经提供碰撞和玩家包围盒绘制。 - `F1` 切换 debug overlay。 - 绘制平台碰撞。 - 绘制 battle zone。 - 绘制 spawn point。 - 绘制 hitbox / hurtbox。 - 输出当前场景、角色状态、FPS。 ### 11. Platform 职责： - 保持 PC 和 NS 共用游戏逻辑。 - 只在入口、构建、资源部署、平台输入处做差异化。 已有： - `game/src/main.cpp`：统一游戏入口，通过 `__SWITCH__` 区分 Windows/PC 与 Switch/NS。 - `Frostbite2DGame`：Windows 游戏目标。 - `Frostbite2DGameSwitch`：Switch 游戏目标，生成 `NSUnknownGame.nro`。 - Switch NRO 已内嵌 `game/` 为 RomFS，运行时优先读取 `romfs:/assets`。 下一步： - 将 Switch Joy-Con 输入接入 `InputStateProvider`。 - 在 Ryujinx 或真机上验证主循环、shader 和角色纹理。 - 如果 RomFS 不可用，再补 SD 卡外部资源部署脚本。 ## 数据流白板 ```text 输入 SDL Keyboard / Controller -> InputStateProvider -> InputState -> PlayerActor 移动 PlayerActor / EnemyActor -> MovementBody -> PlatformMover -> PlatformWorld -> 更新 Actor position / grounded 战斗 Actor 当前攻击状态 -> 生成 Hitbox -> CombatSystem -> Hurtbox 匹配 -> DamageEvent -> Actor 受击/击退/死亡 关卡 LevelDefinition -> Scene 创建 Actor -> StageRenderer 绘制视觉层 -> PlatformWorld 提供碰撞 -> BattleZone 控制推进 渲染 Scene::Render -> StageRenderer -> Actor::Render -> Effects -> DebugOverlay ``` ## 开发路线白板 ### Milestone 1：白盒玩法闭环 目标：验证 ACT 基础手感。 - 玩家移动、跳跃、出拳稳定。 - 第一关横向推进可从头跑到尾。 - battle zone 可触发、锁镜头、解锁。 - 有 1 种敌人占位。 - 有 hitbox/hurtbox debug。 ### Milestone 2：灰盒战斗验证 目标：验证清版节奏。 - 玩家 2 到 3 段基础连击。 - 敌人追击、攻击、受击、死亡。 - 每个 battle zone 有敌人波次。 - 有简单掉落或奖励。 - 关卡能完整结算。 ### Milestone 3：第一关美术测试 目标：替换白盒视觉。 - 场景有 2 到 3 层视差背景。 - 地面和平台使用 tileset。 - props 丰富空间轮廓。 - 保留 debug overlay。 - 记录素材来源和授权。 ### Milestone 4：数据化 目标：降低后续扩展成本。 - 动画配置数据化。 - 攻击参数数据化。 - 敌人参数数据化。 - 关卡数据逐步外部化。 ## 当前优先级 下一步建议按这个顺序做： 1. `BattleZone`：做清版推进的核心框架。 2. `SwitchInput`：把 Joy-Con/手柄输入接入 `InputStateProvider`。 3. `EnemyActor`：做第一个敌人占位。 4. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。 5. `SpriteAnimator`：把玩家动画从硬编码改成组件。 6. `StageLayer`：把白盒视觉层扩展为背景、tiles 和 props。 ## 素材协作提示 你找素材时优先找： - 横版 tileset：地面、平台、墙面。 - 远景/中景背景：可以横向拼接。 - props：箱子、桶、路障、门、灯、标牌。 - 敌人临时素材：有 idle/run/attack/hurt/death 最好。 - 特效：命中火花、尘土、落地、破坏碎片。 素材回来后先不急着追求最终题材，先按 `stage_01` 做一个可玩的美术测试关。