488 lines
12 KiB
Markdown
488 lines
12 KiB
Markdown
# 通用游戏 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 | 一次逻辑帧更新调用 |
|