文档记录

2026-05-15 15:38:40 +08:00
parent d7b09891dc
commit 019703d2a8
18 changed files with 4221 additions and 1 deletions
--- a/docs/game-core-requirements.md
+++ b/docs/game-core-requirements.md
@@ -0,0 +1,487 @@
+# 通用游戏 Core 需求文档
+
+## 文档说明
+
+本文档描述一份**通用的游戏 Core 模块模板**——不绑定具体游戏类型，适用于 RPG、FPS、RTS、解谜等任何品类。每个项目基于此模板补充具体的数值和细节即可。
+
+---
+
+## 1. 架构总览
+
+Core 是游戏的底层基础设施，不包含任何业务逻辑。它的职责是为上层业务提供可复用的系统服务。
+
+```
+┌──────────────────────────────────────────────┐
+│                 业务层 (Game Logic)           │
+│          各游戏自行定义，不归 Core 管          │
+├──────────────────────────────────────────────┤
+│                  Core 层                     │
+├──────────┬──────────┬──────────┬─────────────┤
+│  Game    │  State   │  Input   │   Scene     │
+│  Loop    │ Machine  │  System  │  Manager    │
+├──────────┼──────────┼──────────┼─────────────┤
+│  Event   │  Data    │  Audio   │     UI      │
+│  System  │ Manager  │  System  │  Framework  │
+├──────────┼──────────┼──────────┼─────────────┤
+│  Save    │ Config   │  Time    │   Asset     │
+│  System  │ System   │  System  │   Loader    │
+└──────────┴──────────┴──────────┴─────────────┘
+```
+
+---
+
+## 2. 模块依赖与构建顺序
+
+Core 模块之间存在依赖关系，必须按层构建：
+
+```
+第一层（无依赖）：Game Loop, Event System, Time System, Asset Loader
+第二层（依赖一层）：Config System, Input System, State Machine
+第三层（依赖前两层）：Data Manager, Scene Manager, Audio System, UI Framework
+第四层（依赖前三层）：Save System
+```
+
+---
+
+## 3. 通用验收规则
+
+这些规则适用于 Core 的所有模块，不分优先级：
+
+| 规则 | 说明 |
+|------|------|
+| 零业务耦合 | Core 不包含任何游戏业务逻辑，只提供服务 |
+| 接口稳定 | Core API 一旦确定，业务层不因 Core 变动而改动 |
+| 可独立测试 | 每个模块可在无其他模块的情况下单元测试 |
+| 日志完备 | 关键操作（加载、切换、错误）有结构化日志 |
+| 文档自洽 | 每个接口有参数说明和返回值约定 |
+
+---
+
+## 4. 模块详细描述
+
+每个模块按统一模板编写：目标 → 职责 → 接口 → 依赖 → 验收标准。
+
+---
+
+### 4.1 Game Loop（主循环）
+
+#### 目标
+
+驱动整个游戏帧更新，控制初始化、运行、暂停、退出流程。
+
+#### 状态
+
+```
+Init → Loading → Running → Paused → Quitting
+```
+
+#### 职责
+
+- 固定频率调用各子系统 Tick（逻辑帧）
+- 渲染帧与逻辑帧解耦（可选）
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Start()` | 启动游戏循环 |
+| `Pause()` | 暂停所有子系统 Tick |
+| `Resume()` | 恢复所有子系统 Tick |
+| `Quit()` | 退出并释放资源 |
+| `OnFixedUpdate(dt)` | 逻辑帧回调 |
+| `OnUpdate(dt)` | 渲染帧回调 |
+
+#### 依赖
+
+无（最底层）
+
+#### 验收标准
+
+- [ ] 启动 → Loading → Running 流程正常
+- [ ] 暂停时所有子系统停止 Tick
+- [ ] 退出时正确释放资源
+
+---
+
+### 4.2 State Machine（状态机）
+
+#### 目标
+
+管理游戏全局状态和各模块局部状态的切换。
+
+#### 职责
+
+- 状态注册、切换、查询
+- 状态切换时触发 Enter/Exit 回调
+- 支持状态栈（push/pop）用于暂停/恢复场景
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Register(stateId, state)` | 注册一个状态 |
+| `SwitchTo(stateId)` | 切换到指定状态 |
+| `Push(stateId)` | 压栈当前状态并切换 |
+| `Pop()` | 弹栈恢复上一个状态 |
+| `CurrentState` | 当前状态 ID（只读） |
+
+#### 依赖
+
+Event System
+
+#### 验收标准
+
+- [ ] 切换状态时 Enter/Exit 回调正确执行
+- [ ] Push/Pop 不破坏前一个状态
+- [ ] 不存在的状态切换抛出明确错误
+
+---
+
+### 4.3 Input System（输入系统）
+
+#### 目标
+
+统一处理键鼠、手柄、触屏输入，向上层提供抽象的输入动作。
+
+#### 职责
+
+- 原始输入 → 逻辑动作映射（Move/Jump/Attack）
+- 支持运行时切换输入方案
+- 支持输入录制/回放（用于测试/回放系统）
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `BindAction(actionName, callback)` | 绑定动作回调 |
+| `EnableScheme(schemeName)` | 启用指定输入方案 |
+| `GetAxis(axisName) → float` | 获取轴向值 |
+| `IsPressed(actionName) → bool` | 查询动作是否按下 |
+
+#### 依赖
+
+Config System（键位配置读取）
+
+#### 验收标准
+
+- [ ] 键鼠和手柄可无缝切换
+- [ ] 自定义键位后立即生效
+- [ ] 同一帧多次读取结果一致
+
+---
+
+### 4.4 Scene Manager（场景管理）
+
+#### 目标
+
+管理场景/关卡的加载、卸载、切换。
+
+#### 职责
+
+- 同步/异步加载场景
+- 切换时显示 Loading 界面
+- 支持附加式加载（Additive）实现流式开放世界
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `LoadScene(sceneName, additive)` | 加载场景 |
+| `UnloadScene(sceneName)` | 卸载场景 |
+| `OnSceneLoaded → callback` | 场景加载完成回调 |
+| `OnSceneUnloading → callback` | 场景卸载前回调 |
+
+#### 依赖
+
+Asset Loader, Event System
+
+#### 验收标准
+
+- [ ] 场景切换时无黑屏闪烁
+- [ ] 异步加载期间有进度反馈
+- [ ] 卸载场景后内存正确释放
+
+---
+
+### 4.5 Event System（事件总线）
+
+#### 目标
+
+模块间解耦通信，替代直接引用。
+
+#### 职责
+
+- 事件注册、派发、注销
+- 支持泛型事件（带 payload）
+- 支持事件优先级
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Subscribe(eventId, handler)` | 订阅事件 |
+| `Unsubscribe(eventId, handler)` | 取消订阅 |
+| `Dispatch(eventId, payload)` | 派发事件 |
+
+#### 依赖
+
+无
+
+#### 验收标准
+
+- [ ] handler 注销后不再收到事件
+- [ ] 循环派发不会死循环（深度限制或检测）
+- [ ] 事件丢失时有日志警告
+
+---
+
+### 4.6 Data Manager（数据管理）
+
+#### 目标
+
+统一管理运行时数据（配置表、存档、缓存）。
+
+#### 职责
+
+- 配置表加载与热更新
+- 运行时数据容器的 CRUD
+- 数据变更通知
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `LoadConfig(tableName)` | 加载配置表 |
+| `Get<T>(key) → T` | 按主键获取数据 |
+| `Set(key, value)` | 写入数据 |
+| `OnDataChanged(key) → event` | 数据变更通知 |
+
+#### 依赖
+
+Asset Loader, Event System
+
+#### 验收标准
+
+- [ ] 配置表加载失败使用默认值并报警
+- [ ] Get 不存在的 key 返回 default(T) 而非报错
+
+---
+
+### 4.7 Audio System（音频系统）
+
+#### 目标
+
+统一管理 BGM、SFX、环境音的播放控制。
+
+#### 职责
+
+- 音频资源池化
+- 分通道音量控制（Master/BGM/SFX/Voice）
+- 3D 空间音频
+- 音频淡入淡出
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `PlayBGM(clipId, fadeIn)` | 播放背景音乐 |
+| `PlaySFX(clipId, position)` | 播放音效（支持 3D 位置） |
+| `SetVolume(channel, value)` | 设置通道音量 |
+| `StopAll()` | 停止所有音频 |
+
+#### 依赖
+
+Data Manager, Config System
+
+#### 验收标准
+
+- [ ] 同一 SFX 快速重复播放不卡顿
+- [ ] 场景切换时 BGM 可配置是否延续
+- [ ] 音量设置持久化到存档
+
+---
+
+### 4.8 UI Framework（UI 框架）
+
+#### 目标
+
+管理 UI 面板的打开、关闭、层级、动画。
+
+#### 职责
+
+- 面板栈管理（打开新面板压栈，关闭弹栈）
+- 面板缓存与复用
+- 统一的打开/关闭动画
+- 遮罩与模态控制
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Open(panelId, params)` | 打开面板 |
+| `Close(panelId)` | 关闭面板 |
+| `CloseAll()` | 关闭所有面板 |
+| `IsOpen(panelId) → bool` | 查询面板状态 |
+
+#### 依赖
+
+Event System, Asset Loader
+
+#### 验收标准
+
+- [ ] 打开新面板时下层面板交互自动屏蔽
+- [ ] 连续打开/关闭 10 次无内存泄漏
+- [ ] 面板动画未播完时可打断
+
+---
+
+### 4.9 Save System（存档系统）
+
+#### 目标
+
+游戏数据的持久化存储与读取。
+
+#### 职责
+
+- 多存档位管理
+- 增量存档（只存变更）
+- 存档版本迁移（旧版存档兼容）
+- 自动存档触发
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Save(slotId)` | 保存到指定存档位 |
+| `Load(slotId)` | 从指定存档位加载 |
+| `Delete(slotId)` | 删除存档 |
+| `ListSaves() → saveInfo[]` | 列出所有存档 |
+| `OnAutoSaveTrigger → event` | 自动存档触发事件 |
+
+#### 依赖
+
+Data Manager, Event System
+
+#### 验收标准
+
+- [ ] 存档过程中断电，旧存档不被损坏（双写机制）
+- [ ] 旧版本存档能正确迁移到新版本
+- [ ] 自动存档不造成可感知的卡顿
+
+---
+
+### 4.10 Config System（配置系统）
+
+#### 目标
+
+管理游戏全局配置和用户偏好设置。
+
+#### 职责
+
+- 分层配置：默认值 → 项目配置 → 用户配置
+- 运行时修改用户配置并持久化
+- 配置项变更通知
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `Get(key) → value` | 获取配置值 |
+| `Set(key, value, persist)` | 设置配置值（可选持久化） |
+| `ResetToDefault()` | 重置为默认配置 |
+
+#### 依赖
+
+Save System
+
+#### 验收标准
+
+- [ ] 用户配置覆盖优先级正确
+- [ ] 非法配置值回退到默认值
+- [ ] 配置修改后立即生效
+
+---
+
+### 4.11 Time System（时间系统）
+
+#### 目标
+
+提供统一的时间源，控制游戏时间流速。
+
+#### 职责
+
+- 真实时间 vs 游戏时间分离
+- 时间缩放（慢动作、加速）
+- 帧间 deltaTime 提供者
+- 定时器/冷却器管理
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `deltaTime → float` | 受缩放影响的帧间隔 |
+| `unscaledDeltaTime → float` | 不受缩放影响的帧间隔 |
+| `timeScale` | 时间缩放倍率（读写） |
+| `SetTimer(duration, callback) → timerId` | 设置定时器 |
+| `CancelTimer(timerId)` | 取消定时器 |
+
+#### 依赖
+
+无
+
+#### 验收标准
+
+- [ ] timeScale = 0 时所有依赖 deltaTime 的逻辑冻结
+- [ ] 定时器在暂停后恢复时正确续计
+- [ ] 时间精度不随游戏运行时长漂移
+
+---
+
+### 4.12 Asset Loader（资源加载）
+
+#### 目标
+
+统一管理资源的加载、缓存、卸载、引用计数。
+
+#### 职责
+
+- 同步/异步加载
+- 引用计数自动回收
+- 加载优先级
+- 内存监控与阈值卸载
+
+#### 接口
+
+| 接口 | 说明 |
+|------|------|
+| `LoadAsync<T>(assetPath) → Task<T>` | 异步加载资源 |
+| `LoadSync<T>(assetPath) → T` | 同步加载资源 |
+| `Release(asset)` | 释放资源引用 |
+| `ForceUnloadUnused()` | 强制卸载未使用资源 |
+
+#### 依赖
+
+无
+
+#### 验收标准
+
+- [ ] 引用归零的资源在下一帧自动卸载
+- [ ] 异步加载失败有重试机制
+- [ ] 同一资源并发加载只触发一次实际 IO
+
+---
+
+## 5. 术语表
+
+| 术语 | 定义 |
+|------|------|
+| Game Loop | 游戏主循环，驱动每帧更新的入口 |
+| Feature | 自包含的业务特性模块，拥有独立的资源和生命周期 |
+| Scene | 游戏场景，可包含一个或多个 Feature |
+| Data Class | 按业务域拆分的运行时数据容器，保持纯 C# |
+| ViewModel | MVVM 模式中的视图模型，连接 Data 和 UI Panel |
+| Panel | UI 面板，由 UI Framework 管理生命周期 |
+| Scope | DI 容器的子作用域，随 Feature 创建和销毁 |
+| Handle | 资源引用句柄，Dispose 时减少引用计数 |
+| Config Row | 配置表中的单行数据，必须带有 Id 字段 |
+| Tick | 一次逻辑帧更新调用 |