NS_unknown_game/game/docs/planning/game_architecture_board.md

游戏整体架构计划：思维导图与白板

目标：把项目从“能跑的白盒 Demo”推进为可持续扩展的横板 2D ACT 清版游戏工程。本文先作为整体架构白板，后续每个模块再拆成独立任务文档。

思维导图

mindmap
  root((横板 2D ACT 游戏))
    核心体验
      横向推进
      清版战斗
      平台移动
      近战连段
      关卡节奏
    游戏循环
      登录入口
      房间匹配
      进入关卡
      探索与移动
      触发战斗区域
      击败敌人
      解锁推进
      局内重置
      结算与升级
    底层框架
      客户端服务端分离
      基础热更
      日志输出
      异常捕获
      资源异步加载
      容错兜底
    角色系统
      玩家
        输入
        移动
        跳跃
        攻击
        受击
        动画状态机
        血量
      敌人
        巡逻
        追击
        攻击
        受击硬直
        死亡
        固定数值
      NPC与可交互物
        对话
        机关
        可破坏物
    战斗系统
      Hitbox
      Hurtbox
      伤害结算
      击退
      霸体
      连击窗口
      命中特效
      调试显示
    关卡系统
      场景数据
      碰撞数据
      视觉层
      战斗区域
      敌人出生点
      镜头限制
      出入口
    渲染与资源
      Sprite
      Tileset
      背景视差
      前景遮挡
      特效
      音频
      资源清单
    数据驱动
      动画表
      角色参数
      敌人配置
      关卡配置
      攻击配置
      掉落配置
    联网原型
      房间匹配
      2到4人联机
      玩家状态同步
      战斗同步
      怪物同步
      断线检测
      简易重连
    工具与调试
      白盒编辑
      碰撞可视化
      战斗区域可视化
      Hitbox可视化
      联机状态提示
      简单调试面板
      帧率与日志
      构建文档
      NS平台构建

白板总览

+----------------------+      +----------------------+      +----------------------+
|      Game Loop       | ---> |       Scene          | ---> |       Stage          |
|  关卡进入/推进/结算  |      |  场景编排与生命周期  |      |  关卡数据与视觉层    |
+----------------------+      +----------------------+      +----------------------+
          |                              |                              |
          v                              v                              v
+----------------------+      +----------------------+      +----------------------+
|       Actor          | ---> |      Movement        | ---> |      Collision       |
| 玩家/敌人/道具/物体  |      |  重力/速度/平台移动  |      |  地面/平台/边界      |
+----------------------+      +----------------------+      +----------------------+
          |                              |
          v                              v
+----------------------+      +----------------------+      +----------------------+
|       Combat         | ---> |      Animation       | ---> |       Render         |
| Hitbox/伤害/击退     |      | 状态机/帧表/过渡     |      | Sprite/Tile/特效     |
+----------------------+      +----------------------+      +----------------------+
          |
          v
+----------------------+      +----------------------+      +----------------------+
|        Data          | ---> |       Debug          | ---> |       Build          |
| 配置表/关卡/参数     |      | 可视化/日志/测试     |      | PC/Switch/资源复制   |
+----------------------+      +----------------------+      +----------------------+
          |
          v
+----------------------+      +----------------------+      +----------------------+
|      Foundation      | ---> |        UI            | ---> |       Network        |
| 日志/异常/热更/加载  |      | 登录/匹配/状态/调试  |      | 房间/同步/断线重连   |
+----------------------+      +----------------------+      +----------------------+

模块白板

1. Core

职责：

• 管理游戏级常量、资源路径、输入快照、运行配置。
• 隔离 SDL 等底层输入细节，让角色逻辑只消费 InputState。
• 为后续手柄、Switch Joy-Con、键位配置留接口。

已有：

• core/game_config.h
• core/asset_paths.h
• core/input_state.*
• core/debug_flags.h
• InputStateProvider 已聚合键盘、SDL GameController 和 Switch 原生 PadState。

当前输入映射：

• 移动：键盘 A/D、方向键、手柄左摇杆、方向键、Switch 左摇杆/方向键。
• 跳跃：键盘 Space/W/Up、手柄 A/B、Switch A/B。
• 攻击：键盘 J/K、手柄 X/Y、Switch X/Y。

下一步：

• 增加 GameContext，统一传递全局服务。
• 增加可配置键位表，让 PC 和 NS 可以分别覆盖默认映射。

2. Scene

职责：

• 管理场景生命周期。
• 装载关卡数据。
• 创建玩家、敌人、道具和场景对象。
• 控制镜头、战斗区域、关卡推进。
• 支持单局场景重置：重置玩家、敌人、battle zone、掉落和临时状态。

已有：

• scene/whitebox_scene.*
• scene/camera_controller.*：玩家跟随、dead zone、平滑和世界边界 clamp。
• CameraZoneLock：玩家进入 battle zone 后摄像机平滑切换到 zone camera bounds，可移动锁定范围会防御性保证不小于视口，当前用 F2 或离开 zone 做 debug 清场解锁。

下一步：

• 抽象 GameplayScene 作为通用玩法场景基类。
• WhiteboxScene 只保留第一关测试内容。
• 将 battle zone debug 清场替换为敌人清空自动解锁。
• 增加局内 reset 入口，用于卡状态、死亡重开和联机重同步。

3. Stage

职责：

• 表达关卡世界：碰撞、视觉层、背景、道具、出生点、镜头范围。
• 将白盒数据逐步替换为 tileset 和 props。

已有：

• data/level_definition.h
• data/whitebox_level.cpp
• movement/platform_world.*
• stage/stage_renderer.*
• StageLayer 灰盒数据已接入：远景、中景、地面/平台、后景 props 先用色块占位。
• 第一关宽度已扩展到 3200 像素，并加入 3 个 battle zone 占位与敌人出生点。

下一步：

• 将 StageLayer 色块替换为 tileset、背景图和 props 素材。
• 将 battle zone 占位升级为触发、锁镜头、清场解锁逻辑。
• 将敌人出生点接入 EnemyActor。

4. Actor

职责：

• 表达游戏对象：玩家、敌人、道具、投射物、可破坏物。
• 每个 Actor 只处理自身状态，不直接管理全局流程。
• 玩家和怪物都要支持血量、受击、击退、死亡/销毁基础生命周期。

已有：

• actor/player_actor.*

下一步：

• 增加 EnemyActor。
• 增加 BreakablePropActor。
• 抽出 CharacterActor 作为玩家和敌人的共同基类。
• 增加 HealthComponent 或等价数据结构，统一玩家/怪物血量与死亡判定。
• 将玩家动画切换改为数据驱动。

5. Movement

职责：

• 处理速度、重力、平台落地、边界限制。
• 支持横版手感：左右平移、加速、移动减速、单次跳跃、重力落地、空中姿态锁定。
• 后续支持斜坡、墙体、击退、空中状态。
• 兜底防卡：防卡地形、防穿模、异常位置重置。

已有：

• MovementBody
• PlatformWorld
• PlatformMover

下一步：

• 支持水平墙体阻挡。
• 支持移动加速/减速参数。
• 支持击退速度覆盖。
• 支持落地事件。
• 支持移动调试可视化。
• 增加卡地形检测和安全出生点/检查点回退。

6. Combat

职责：

• 管理攻击盒、受击盒、伤害结算、击退、硬直、命中特效。
• 保证战斗逻辑不散落在 Actor 内部。
• 表达普通攻击前摇/后摇、命中窗口、固定伤害数值、受击反馈。
• 支持跨玩家攻击命中和怪物状态同步的网络事件接口。

已有：

• combat/hitbox.h

下一步：

• 增加 CombatSystem。
• 每帧收集 active hitbox / hurtbox。
• 支持 team 过滤、重复命中过滤、伤害事件。
• 增加攻击前摇/后摇时间线。
• 增加伤害、击退、僵直和血量变化事件。
• 增加 debug hitbox 绘制。

7. Animation

职责：

• 管理 spritesheet 帧、动画状态、播放速度、循环和过渡。
• 避免每个 Actor 手写帧切换。
• 与动作状态机配合，保证 idle/移动/跳跃/攻击/受击 状态互斥，杜绝动作冲突。

当前状态：

• PlayerActor 内部硬编码 idle/run/punch 动画。

下一步：

• 增加 AnimationClip。
• 增加 SpriteAnimator。
• 增加 CharacterStateMachine，管理 idle/move/jump/attack/hitstun/dead。
• 增加动画配置表。
• 攻击动画和 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。
• 增加视差背景绘制。
• 建立素材来源和授权记录。
• 增加 AssetManifest，记录 stage/character/effect 资源槽位。
• 增加异步加载队列和加载中/加载失败调试提示。

10. Debug 与工具

职责：

• 提供开发时必要的可视化和状态观察。
• 降低调试碰撞、战斗和关卡触发的成本。
• 输出基础日志、异常捕获信息、资源加载失败原因、联机状态。
• 提供简单调试面板：FPS、场景、玩家状态、网络状态、重置按钮。

下一步：

• debug/debug_overlay.* 已经提供碰撞和玩家包围盒绘制。
• F1 切换 debug overlay。
• 绘制平台碰撞、battle zone、camera lock 和 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。

下一步：

• 在 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、摄像机和临时效果。
• 增加安全点：玩家卡地形或掉出世界时回到最近检查点。
• 增加状态超时兜底：攻击/受击/重连状态超过上限自动恢复。

数据流白板

输入
  SDL Keyboard / Controller / Switch PadState
    -> 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。
• 有局内重置入口，能重置玩家、怪物、battle zone 和摄像机。

Milestone 2：灰盒战斗验证

目标：验证清版节奏。

• CharacterStateMachine 管理 idle/move/jump/attack/hitstun/dead。
• 玩家 2 到 3 段基础连击。
• 攻击前摇/后摇和命中窗口可配置。
• 受击僵直、击退、血量变化可见。
• 敌人追击、攻击、受击、死亡。
• 每个 battle zone 有敌人波次。
• 有简单掉落或奖励。
• 关卡能完整结算。
• 防卡地形、防穿模、防状态卡死有基础兜底。

Milestone 3：第一关美术测试

目标：替换白盒视觉。

• 场景有 2 到 3 层视差背景。
• 地面和平台使用 tileset。
• props 丰富空间轮廓。
• 保留 debug overlay。
• 记录素材来源和授权。

Milestone 4：联机原型

目标：跑通 2 到 4 人多人原型。

• 有登录/入口 UI。
• 有创建房间、加入房间、玩家列表和准备状态。
• 支持局域网或公网极简房间匹配。
• 服务端同步玩家位置、动作状态、血量。
• 服务端同步怪物状态、攻击命中、清场进度。
• 有断线检测、简易重连和联机状态提示。

Milestone 5：数据化与热更

目标：降低后续扩展成本。

• 动画配置数据化。
• 攻击参数数据化。
• 敌人参数数据化。
• 关卡数据逐步外部化。
• 资源 manifest、配置版本和 fallback 规则可用。

当前优先级

当前调整为先做场景。理由：先把第一关的世界宽度、分层数据、镜头范围、视觉层和 debug 标记搭起来，后续 BattleZone、敌人刷出和战斗系统才有稳定承载位置。

新增的底层框架、UI、联网和闭环兜底会作为架构约束提前预留接口，但短期实现仍以“场景骨架 -> ACT 手感 -> 单局闭环”为主。多人联网在 Milestone 4 集中实现，当前阶段只避免把玩法逻辑写死成无法同步的本地状态。

下一步建议按这个顺序做：

1. StageLayerSource：让 StageLayer 同时支持色块占位和 sprite 资源路径。
2. StageAssetSlots：建立 stage_01 资源槽位和素材来源记录，做到素材可直接落位。
3. StageProps：把后景/前景 props 统一到 layer 数据。
4. BattleZone：把 F2 debug 清场替换为敌人清空自动解锁。
5. EnemyActor：做第一个敌人占位，接入出生点。
6. CombatSystem：把 hitbox/hurtbox 真正跑起来。
7. SpriteAnimator：把玩家动画从硬编码改成组件。
8. InputConfig：把默认键位/手柄映射迁移到可配置数据。

素材协作提示

你找素材时优先找：

• 横版 tileset：地面、平台、墙面。
• 远景/中景背景：可以横向拼接。
• props：箱子、桶、路障、门、灯、标牌。
• 敌人临时素材：有 idle/run/attack/hurt/death 最好。
• 特效：命中火花、尘土、落地、破坏碎片。

素材回来后先不急着追求最终题材，先按 stage_01 做一个可玩的美术测试关。