FlowScope/docs/game-core-requirements.md

通用游戏 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	一次逻辑帧更新调用