# 通用游戏 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(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(assetPath) → Task` | 异步加载资源 | | `LoadSync(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 | 一次逻辑帧更新调用 |