From b6bc29ae191f03c541e31eb2a28a9189b3709ede Mon Sep 17 00:00:00 2001
From: 1165565692-lang <1165565692@qq.com>
Date: Tue, 9 Jun 2026 00:07:21 +0800
Subject: [PATCH] Add game architecture board

---
 game/docs/GAME_ARCHITECTURE_BOARD.md | 398 +++++++++++++++++++++++++++
 1 file changed, 398 insertions(+)
 create mode 100644 game/docs/GAME_ARCHITECTURE_BOARD.md

diff --git a/game/docs/GAME_ARCHITECTURE_BOARD.md b/game/docs/GAME_ARCHITECTURE_BOARD.md
new file mode 100644
index 0000000..d09df14
--- /dev/null
+++ b/game/docs/GAME_ARCHITECTURE_BOARD.md
@@ -0,0 +1,398 @@
+# 游戏整体架构计划：思维导图与白板
+
+目标：把项目从“能跑的白盒 Demo”推进为可持续扩展的横板 2D ACT 清版游戏工程。本文先作为整体架构白板，后续每个模块再拆成独立任务文档。
+
+## 思维导图
+
+```mermaid
+mindmap
+  root((横板 2D ACT 游戏))
+    核心体验
+      横向推进
+      清版战斗
+      平台移动
+      近战连段
+      关卡节奏
+    游戏循环
+      进入关卡
+      探索与移动
+      触发战斗区域
+      击败敌人
+      解锁推进
+      结算与升级
+    角色系统
+      玩家
+        输入
+        移动
+        跳跃
+        攻击
+        受击
+        动画状态机
+      敌人
+        巡逻
+        追击
+        攻击
+        受击硬直
+        死亡
+      NPC与可交互物
+        对话
+        机关
+        可破坏物
+    战斗系统
+      Hitbox
+      Hurtbox
+      伤害结算
+      击退
+      霸体
+      连击窗口
+      命中特效
+      调试显示
+    关卡系统
+      场景数据
+      碰撞数据
+      视觉层
+      战斗区域
+      敌人出生点
+      镜头限制
+      出入口
+    渲染与资源
+      Sprite
+      Tileset
+      背景视差
+      前景遮挡
+      特效
+      音频
+      资源清单
+    数据驱动
+      动画表
+      角色参数
+      敌人配置
+      关卡配置
+      攻击配置
+      掉落配置
+    工具与调试
+      白盒编辑
+      碰撞可视化
+      战斗区域可视化
+      Hitbox可视化
+      帧率与日志
+      构建文档
+```
+
+## 白板总览
+
+```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.*`
+
+下一步：
+
+- 增加 `GameContext`，统一传递全局服务。
+- 增加 `DebugFlags`，集中管理调试开关。
+- 输入层支持键盘和手柄统一映射。
+
+### 2. Scene
+
+职责：
+
+- 管理场景生命周期。
+- 装载关卡数据。
+- 创建玩家、敌人、道具和场景对象。
+- 控制镜头、战斗区域、关卡推进。
+
+已有：
+
+- `scene/whitebox_scene.*`
+
+下一步：
+
+- 抽象 `GameplayScene` 作为通用玩法场景基类。
+- `WhiteboxScene` 只保留第一关测试内容。
+- 引入 battle zone 触发逻辑。
+
+### 3. Stage
+
+职责：
+
+- 表达关卡世界：碰撞、视觉层、背景、道具、出生点、镜头范围。
+- 将白盒数据逐步替换为 tileset 和 props。
+
+已有：
+
+- `data/level_definition.h`
+- `data/whitebox_level.cpp`
+- `movement/platform_world.*`
+
+下一步：
+
+- 增加 `StageRenderer`。
+- 增加 `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 与工具
+
+职责：
+
+- 提供开发时必要的可视化和状态观察。
+- 降低调试碰撞、战斗和关卡触发的成本。
+
+下一步：
+
+- `F1` 切换 debug overlay。
+- 绘制平台碰撞。
+- 绘制 battle zone。
+- 绘制 spawn point。
+- 绘制 hitbox / hurtbox。
+- 输出当前场景、角色状态、FPS。
+
+## 数据流白板
+
+```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. `StageRenderer`：让关卡视觉层从 Scene 中独立出来。
+2. `DebugOverlay`：显示碰撞、战斗区域和出生点。
+3. `BattleZone`：做清版推进的核心框架。
+4. `EnemyActor`：做第一个敌人占位。
+5. `CombatSystem`：把 hitbox/hurtbox 真正跑起来。
+6. `SpriteAnimator`：把玩家动画从硬编码改成组件。
+
+## 素材协作提示
+
+你找素材时优先找：
+
+- 横版 tileset：地面、平台、墙面。
+- 远景/中景背景：可以横向拼接。
+- props：箱子、桶、路障、门、灯、标牌。
+- 敌人临时素材：有 idle/run/attack/hurt/death 最好。
+- 特效：命中火花、尘土、落地、破坏碎片。
+
+素材回来后先不急着追求最终题材，先按 `stage_01` 做一个可玩的美术测试关。