From c1096f0ed5d175020d9cfc8ae411a056314d1af2 Mon Sep 17 00:00:00 2001
From: 1165565692-lang <1165565692@qq.com>
Date: Tue, 9 Jun 2026 14:17:58 +0800
Subject: [PATCH] Expand architecture plan for online ACT prototype

---
 game/docs/planning/game_architecture_board.md | 172 +++++++++++++++++-
 1 file changed, 171 insertions(+), 1 deletion(-)

diff --git a/game/docs/planning/game_architecture_board.md b/game/docs/planning/game_architecture_board.md
index 2c45c49..6cf3745 100644
--- a/game/docs/planning/game_architecture_board.md
+++ b/game/docs/planning/game_architecture_board.md
@@ -14,12 +14,22 @@ mindmap
       近战连段
       关卡节奏
     游戏循环
+      登录入口
+      房间匹配
       进入关卡
       探索与移动
       触发战斗区域
       击败敌人
       解锁推进
+      局内重置
       结算与升级
+    底层框架
+      客户端服务端分离
+      基础热更
+      日志输出
+      异常捕获
+      资源异步加载
+      容错兜底
     角色系统
       玩家
         输入
@@ -28,12 +38,14 @@ mindmap
         攻击
         受击
         动画状态机
+        血量
       敌人
         巡逻
         追击
         攻击
         受击硬直
         死亡
+        固定数值
       NPC与可交互物
         对话
         机关
@@ -70,11 +82,21 @@ mindmap
       关卡配置
       攻击配置
       掉落配置
+    联网原型
+      房间匹配
+      2到4人联机
+      玩家状态同步
+      战斗同步
+      怪物同步
+      断线检测
+      简易重连
     工具与调试
       白盒编辑
       碰撞可视化
       战斗区域可视化
       Hitbox可视化
+      联机状态提示
+      简单调试面板
       帧率与日志
       构建文档
       NS平台构建
@@ -104,6 +126,12 @@ mindmap
 +----------------------+      +----------------------+      +----------------------+
 |        Data          | ---> |       Debug          | ---> |       Build          |
 | 配置表/关卡/参数     |      | 可视化/日志/测试     |      | PC/Switch/资源复制   |
++----------------------+      +----------------------+      +----------------------+
+          |
+          v
++----------------------+      +----------------------+      +----------------------+
+|      Foundation      | ---> |        UI            | ---> |       Network        |
+| 日志/异常/热更/加载  |      | 登录/匹配/状态/调试  |      | 房间/同步/断线重连   |
 +----------------------+      +----------------------+      +----------------------+
 ```
 
@@ -144,6 +172,7 @@ mindmap
 - 装载关卡数据。
 - 创建玩家、敌人、道具和场景对象。
 - 控制镜头、战斗区域、关卡推进。
+- 支持单局场景重置：重置玩家、敌人、battle zone、掉落和临时状态。
 
 已有：
 
@@ -155,6 +184,7 @@ mindmap
 - 抽象 `GameplayScene` 作为通用玩法场景基类。
 - `WhiteboxScene` 只保留第一关测试内容。
 - 引入 battle zone 触发逻辑。
+- 增加局内 reset 入口，用于卡状态、死亡重开和联机重同步。
 
 ### 3. Stage
 
@@ -184,6 +214,7 @@ mindmap
 
 - 表达游戏对象：玩家、敌人、道具、投射物、可破坏物。
 - 每个 Actor 只处理自身状态，不直接管理全局流程。
+- 玩家和怪物都要支持血量、受击、击退、死亡/销毁基础生命周期。
 
 已有：
 
@@ -194,6 +225,7 @@ mindmap
 - 增加 `EnemyActor`。
 - 增加 `BreakablePropActor`。
 - 抽出 `CharacterActor` 作为玩家和敌人的共同基类。
+- 增加 `HealthComponent` 或等价数据结构，统一玩家/怪物血量与死亡判定。
 - 将玩家动画切换改为数据驱动。
 
 ### 5. Movement
@@ -201,7 +233,9 @@ mindmap
 职责：
 
 - 处理速度、重力、平台落地、边界限制。
+- 支持横版手感：左右平移、加速、移动减速、单次跳跃、重力落地、空中姿态锁定。
 - 后续支持斜坡、墙体、击退、空中状态。
+- 兜底防卡：防卡地形、防穿模、异常位置重置。
 
 已有：
 
@@ -212,9 +246,11 @@ mindmap
 下一步：
 
 - 支持水平墙体阻挡。
+- 支持移动加速/减速参数。
 - 支持击退速度覆盖。
 - 支持落地事件。
 - 支持移动调试可视化。
+- 增加卡地形检测和安全出生点/检查点回退。
 
 ### 6. Combat
 
@@ -222,6 +258,8 @@ mindmap
 
 - 管理攻击盒、受击盒、伤害结算、击退、硬直、命中特效。
 - 保证战斗逻辑不散落在 Actor 内部。
+- 表达普通攻击前摇/后摇、命中窗口、固定伤害数值、受击反馈。
+- 支持跨玩家攻击命中和怪物状态同步的网络事件接口。
 
 已有：
 
@@ -232,6 +270,8 @@ mindmap
 - 增加 `CombatSystem`。
 - 每帧收集 active hitbox / hurtbox。
 - 支持 team 过滤、重复命中过滤、伤害事件。
+- 增加攻击前摇/后摇时间线。
+- 增加伤害、击退、僵直和血量变化事件。
 - 增加 debug hitbox 绘制。
 
 ### 7. Animation
@@ -240,6 +280,7 @@ mindmap
 
 - 管理 spritesheet 帧、动画状态、播放速度、循环和过渡。
 - 避免每个 Actor 手写帧切换。
+- 与动作状态机配合，保证 idle/移动/跳跃/攻击/受击 状态互斥，杜绝动作冲突。
 
 当前状态：
 
@@ -249,6 +290,7 @@ mindmap
 
 - 增加 `AnimationClip`。
 - 增加 `SpriteAnimator`。
+- 增加 `CharacterStateMachine`，管理 idle/move/jump/attack/hitstun/dead。
 - 增加动画配置表。
 - 攻击动画和 hitbox active frame 绑定。
 
@@ -258,6 +300,8 @@ mindmap
 
 - 将玩法参数从 C++ 硬编码逐步迁移到数据。
 - 支持关卡、敌人、动画、攻击、掉落配置。
+- 支持角色/怪物血量、伤害、速度、追击范围等固定数值配置。
+- 支持后续热更清单：资源版本、配置版本、加载失败兜底资源。
 
 当前状态：
 
@@ -268,6 +312,7 @@ mindmap
 - 先用 C++ struct 稳定字段。
 - 再迁移到 JSON 或编辑器导出格式。
 - 资源路径统一记录，避免散落字符串。
+- 增加配置默认值和缺失字段兜底。
 
 ### 9. Render 与资源
 
@@ -275,6 +320,8 @@ mindmap
 
 - 绘制角色、关卡、背景、道具、特效和调试图形。
 - 管理资源目录和运行时拷贝。
+- 支持场景、角色、贴图的极简异步加载。
+- 加载失败时使用占位图/色块兜底，避免场景直接崩溃。
 
 已有：
 
@@ -288,6 +335,8 @@ mindmap
 - 引入 tileset、背景、props。
 - 增加视差背景绘制。
 - 建立素材来源和授权记录。
+- 增加 `AssetManifest`，记录 stage/character/effect 资源槽位。
+- 增加异步加载队列和加载中/加载失败调试提示。
 
 ### 10. Debug 与工具
 
@@ -295,6 +344,8 @@ mindmap
 
 - 提供开发时必要的可视化和状态观察。
 - 降低调试碰撞、战斗和关卡触发的成本。
+- 输出基础日志、异常捕获信息、资源加载失败原因、联机状态。
+- 提供简单调试面板：FPS、场景、玩家状态、网络状态、重置按钮。
 
 下一步：
 
@@ -303,6 +354,8 @@ mindmap
 - 绘制平台碰撞、battle zone、camera lock 和 spawn point。
 - 绘制 hitbox / hurtbox。
 - 输出当前场景、角色状态、FPS。
+- 增加日志分级和异常状态重置入口。
+- 增加网络延迟、房间号、连接状态显示。
 
 ### 11. Platform
 
@@ -310,6 +363,7 @@ mindmap
 
 - 保持 PC 和 NS 共用游戏逻辑。
 - 只在入口、构建、资源部署、平台输入处做差异化。
+- 为后续客户端/服务端分离保留平台抽象：本地单机、局域网、公网房间都走统一会话接口。
 
 已有：
 
@@ -323,6 +377,102 @@ mindmap
 - 在 Ryujinx 或真机上验证主循环、shader 和角色纹理。
 - 如果 RomFS 不可用，再补 SD 卡外部资源部署脚本。
 
+### 12. Foundation
+
+职责：
+
+- 建立底层框架基础：客户端/服务端分离思路、日志、异常捕获、热更清单、资源加载兜底。
+- 单机开发阶段先以本地会话模拟服务端，后续再替换为真实网络服务端。
+- 所有系统要能在异常状态下恢复到可继续测试的状态。
+
+当前状态：
+
+- 已有 PC/Switch 构建入口。
+- 已有资源工作目录和 RomFS/SDMC 基础路径。
+- 还没有独立日志系统、异常捕获边界、热更 manifest。
+
+下一步：
+
+- 增加 `GameSession`：本地单机/联机都通过同一会话驱动场景。
+- 增加 `AssetManifest`：记录资源版本、资源槽位和 fallback。
+- 增加统一日志输出入口，至少支持 info/warn/error。
+- 增加异常状态重置入口：位置异常、状态卡死、资源加载失败。
+
+### 13. UI
+
+职责：
+
+- 提供基础 UI：登录入口、房间匹配、联机状态提示、简单调试面板。
+- 原型期 UI 不追求美术，只要求流程可达、状态清楚、可调试。
+
+当前状态：
+
+- 还没有游戏层 UI。
+
+下一步：
+
+- 增加 `LoginScene` 或入口面板：本地游玩、创建房间、加入房间。
+- 增加 `RoomPanel`：显示房间号、玩家列表、准备状态。
+- 增加 `NetworkStatusPanel`：显示连接状态、延迟、断线/重连状态。
+- 增加 `DebugPanel`：显示 FPS、场景名、玩家状态、怪物数量、重置按钮。
+
+### 14. Enemy AI
+
+职责：
+
+- 实现极简怪物 AI：固定巡逻、玩家进入范围追击、近战攻击、受击掉血、死亡销毁。
+- 怪物行为要能被 battle zone 控制生成和清场。
+
+当前状态：
+
+- 还没有 `EnemyActor`。
+
+下一步：
+
+- 增加 `EnemyActor`：idle/patrol/chase/attack/hitstun/dead。
+- 增加巡逻范围、追击范围、攻击范围、血量、伤害配置。
+- 接入 `BattleZone` 的 spawn point。
+- 预留网络同步字段：位置、状态、血量、目标玩家。
+
+### 15. Networking
+
+职责：
+
+- 多人网游原型核心：局域网/公网极简房间匹配，支持 2 到 4 人联机。
+- 服务端同步所有玩家位置、动作状态、血量状态。
+- 同步跨玩家攻击命中、怪物状态、清场进度。
+- 支持断线检测、简易重连、网络延迟适配。
+
+当前状态：
+
+- 还没有网络模块。
+- 先不阻塞场景和 ACT 手感开发，但架构上要预留服务端权威状态。
+
+下一步：
+
+- 增加 `NetworkSession` 接口：offline/local/online 三种模式。
+- 增加 `PlayerStateSnapshot`：位置、速度、动作状态、血量、朝向。
+- 增加 `CombatEvent` / `EnemyStateSnapshot`：攻击命中、怪物状态、死亡事件。
+- 增加断线检测和重连状态机。
+
+### 16. Game Loop Closure
+
+职责：
+
+- 做单局闭环：进入场景 -> 战斗交互 -> 怪物清空 -> 局内重置。
+- 做核心 bug 兜底：防卡地形、防穿模、防状态卡死、异常状态重置。
+
+当前状态：
+
+- 当前只有进入白盒场景和玩家移动。
+
+下一步：
+
+- 增加 `RunState`：loading/playing/cleared/failed/resetting。
+- 增加局内重置：重置玩家、怪物、battle zone、摄像机和临时效果。
+- 增加安全点：玩家卡地形或掉出世界时回到最近检查点。
+- 增加状态超时兜底：攻击/受击/重连状态超过上限自动恢复。
+
 ## 数据流白板
 
 ```text
@@ -368,21 +518,27 @@ mindmap
 
 目标：验证 ACT 基础手感。
 
+- 基础日志、资源加载兜底和调试面板可用。
 - 玩家移动、跳跃、出拳稳定。
 - 第一关横向推进可从头跑到尾。
 - battle zone 可触发、锁镜头、解锁。
 - 有 1 种敌人占位。
 - 有 hitbox/hurtbox debug。
+- 有局内重置入口，能重置玩家、怪物、battle zone 和摄像机。
 
 ### Milestone 2：灰盒战斗验证
 
 目标：验证清版节奏。
 
+- `CharacterStateMachine` 管理 idle/move/jump/attack/hitstun/dead。
 - 玩家 2 到 3 段基础连击。
+- 攻击前摇/后摇和命中窗口可配置。
+- 受击僵直、击退、血量变化可见。
 - 敌人追击、攻击、受击、死亡。
 - 每个 battle zone 有敌人波次。
 - 有简单掉落或奖励。
 - 关卡能完整结算。
+- 防卡地形、防穿模、防状态卡死有基础兜底。
 
 ### Milestone 3：第一关美术测试
 
@@ -394,7 +550,18 @@ mindmap
 - 保留 debug overlay。
 - 记录素材来源和授权。
 
-### Milestone 4：数据化
+### Milestone 4：联机原型
+
+目标：跑通 2 到 4 人多人原型。
+
+- 有登录/入口 UI。
+- 有创建房间、加入房间、玩家列表和准备状态。
+- 支持局域网或公网极简房间匹配。
+- 服务端同步玩家位置、动作状态、血量。
+- 服务端同步怪物状态、攻击命中、清场进度。
+- 有断线检测、简易重连和联机状态提示。
+
+### Milestone 5：数据化与热更
 
 目标：降低后续扩展成本。
 
@@ -402,11 +569,14 @@ mindmap
 - 攻击参数数据化。
 - 敌人参数数据化。
 - 关卡数据逐步外部化。
+- 资源 manifest、配置版本和 fallback 规则可用。
 
 ## 当前优先级
 
 当前调整为先做场景。理由：先把第一关的世界宽度、分层数据、镜头范围、视觉层和 debug 标记搭起来，后续 `BattleZone`、敌人刷出和战斗系统才有稳定承载位置。
 
+新增的底层框架、UI、联网和闭环兜底会作为架构约束提前预留接口，但短期实现仍以“场景骨架 -> ACT 手感 -> 单局闭环”为主。多人联网在 Milestone 4 集中实现，当前阶段只避免把玩法逻辑写死成无法同步的本地状态。
+
 下一步建议按这个顺序做：
 
 1. `CameraZoneLock`：让 battle zone 可以临时锁定摄像机范围，清场后恢复跟随。