421 lines
10 KiB
Markdown
421 lines
10 KiB
Markdown
# 游戏整体架构计划：思维导图与白板
|
||
|
||
目标：把项目从“能跑的白盒 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`：Windows/PC 游戏入口。
|
||
- `game/src/switch_game_main.cpp`：Switch/NS 游戏入口。
|
||
- `Frostbite2DGame`：Windows 游戏目标。
|
||
- `Frostbite2DGameSwitch`：Switch 游戏目标，生成 `NSUnknownGame.nro`。
|
||
|
||
下一步：
|
||
|
||
- 将 Switch Joy-Con 输入接入 `InputStateProvider`。
|
||
- 整理资源部署脚本，把 `assets` 放到 `/switch/Frostbite2D/NS Unknown Game/assets`。
|
||
- 在 Ryujinx 或真机上验证主循环、shader 和角色纹理。
|
||
|
||
## 数据流白板
|
||
|
||
```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` 做一个可玩的美术测试关。
|