Logger（日志）
01ILogger分类日志：按构建分级的日志等级、分类过滤。线程安全。
Common Game System
面向 Unity 6.3 LTS、PC 单机项目的 headless（无渲染）纯 C# 底层框架。headless 的意思是：它是代码，不是场景——导入之后你的 Hierarchy 不会有任何变化。存档、输入、场景流程、音频、UI 面板、补间、状态机等 23 个服务，由一次自动的 Bootstrap.Run() 全部启动。不用配 DI 容器，不用往场景里摆单例，游戏脚本里也不需要任何初始化代码。
Unity 6.3 LTS23 个服务7 个程序集0 第三方依赖IL2CPP 就绪不绑定渲染管线面向 AI 协作
文档 Wiki — 逐个服务、逐步讲解 →从这里开始
六步上手
CGS 是代码，不是场景。导入之后，场景 Hierarchy 里不会出现任何东西——框架在看不见的地方运转。看得见的部分是 Welcome 窗口和演示场景。下面是最快的一圈游览：
- 1从 Unity Asset Store 导入 Common Game System（Window > Package Manager > My Assets）。
- 2Welcome 窗口会自动打开。关掉了也没关系：随时可以从 Tools > Common Game System > Welcome 再次打开（Window > Common Game System > Welcome 下也有）。
- 3点击 Welcome 窗口顶部的 Open Demo Scene。MotionLab 场景随即打开——零配置。
- 4按下 Play。补间缓动画廊动起来，调度器计时器在走，补间序列展示开始播放。
- 5把 Time Scale 滑块拖到 0。游戏玩法当场冻结，而 UI 时钟转轮仍按自己的时钟继续转。
- 6打开 Console 窗口。看到
bootstrap complete (v2.1.0, 23 services)这一行，就说明所有服务都启动成功了。
想离线阅读？包内自带一本分页 PDF 手册，带目录和标注截图，位于 Documentation/CGS-Manual.pdf。
概览
你会得到什么
引擎
Unity 6.3 LTS (6000.3.11f1) · .NET Standard 2.1
服务
23 个——在你的第一个脚本运行之前，由一次自动引导全部启动
运行时程序集
7 个——Core（18 个零包引用的服务）+ Input / UI / Localization / Assets / AddressableScene / Bootstrap。不用的 Unity 包（Input System / uGUI / Addressables）可以直接移除——依赖它的程序集会自动排除，Bootstrap 安全回退，不会弄坏你的构建
第三方依赖
0 个——只有 Unity 引擎，加上官方的 Addressables / Input System / uGUI（自 2.0.0 起均为可选）
脚本后端
Mono 与 IL2CPP 双支持。框架自带保留规则（[Preserve] + 按模块拆分的 link.xml）。CI 每次推送都会用 IL2CPP 打一个 Standalone 播放器
渲染管线
URP / HDRP / Built-in / 自定义管线都能用——框架内没有一行渲染代码
测试
2,600 多个自动化测试随包发布、默认隐藏。在 Welcome 窗口一键即可导入
演示场景
MotionLab.unity——打开按 Play 即可，零配置。补间缓动画廊、补间序列、调度器计时器，还有一个把游戏玩法冻住、UI 时钟却继续转的 Time Scale 滑块
示例
6 个，均可在 Welcome 窗口导入——3 个可直接运行的场景（UI Panel Stack · Save/Load + Seeded Random · Command Console）和 3 个脚本模板（Scene Flow · Localization · RPG Starter）
手册与文档
一本带目录和标注截图的分页 PDF 手册（Documentation/CGS-Manual.pdf），外加每个服务一页平实易懂的参考文档（Documentation/Modules/）
编辑器工具
Welcome 窗口（每个包版本自动打开一次；可从 Tools > Common Game System > Welcome 重新打开）+ 运行时 Service Debugger
许可协议
专有软件——Unity Asset Store EULA
平台
PC（Windows / macOS / Linux），单机
快速上手
你的第一个脚本——20 行
框架自己启动，没有任何初始化代码要调。下面的脚本粘贴进去就能编译——挂到第一个场景里的任意 GameObject 上试试。
using CommonGameSystem.Core;
using UnityEngine;
[DefaultExecutionOrder(100)] // see "Consumer conventions" below
public sealed class MyGame : MonoBehaviour
{
[SerializeField] private AudioClip mainTheme; // assign any music clip in the Inspector
private IAudioService _audio;
private IScheduler _scheduler;
private void Start()
{
// Bootstrap already registered all 23 services before Start() ran.
_audio = ServiceLocator.Resolve<IAudioService>();
_scheduler = ServiceLocator.Resolve<IScheduler>();
_audio.PlayMusic(mainTheme, fadeInSeconds: 2f);
_scheduler.After(3f, () => Debug.Log("Three seconds of game time later."));
}
}就这些——你的 Start() 执行之前，23 个服务就已经全部注册完毕。
好习惯
使用约定（Consumer conventions）
- 凡是调用 ServiceLocator.Resolve<T>() 的脚本，都加上 [DefaultExecutionOrder(100)]。框架先于所有场景脚本启动；这个特性把执行顺序从碰运气变成显式约定。
- Resolve 一次并缓存实例。Resolve<T>() 每次都是一次字典查找——放在 Start() 里没问题，放进 Update() 就是浪费。
- 用 IL2CPP 构建？把你自己的设置、事件与存档数据类型写进项目的 link.xml，免得被 Unity 的代码裁剪剥掉。
- 关掉一个服务只要一行：ServiceLocator.Replace<IAudioService>(new NullAudio())。每个服务都自带一个遵守同一契约的 Null 空实现。
参考
23 个服务
Object Pool（对象池）
02IObjectPoolService基于 IPoolable 生命周期的预制体池——按类别分池、预热、自动回收。
Time Service（时间服务）
03ITimeService按时钟计算的时间、暂停与慢动作——Gameplay / UI / Background 三个时钟各走各的。
Event Bus（事件总线）
04IEventBus类型安全的发布 / 订阅，用于解耦的全局消息传递。
Save / Load（存档）
05ISaveServiceJSON 存档槽位、安全的原子写入、带版本的迁移钩子。
Configuration（配置）
06IConfiguration强类型设置分组（音频 / 画面 / 输入），改完立即持久化。
Input Key Map（按键映射）
07IInputKeyMapSource持有 Input Actions 资产，并跨会话保存玩家的按键重绑定。
Input（输入）
08IInputServiceInput System 封装——action map 上下文与按键重绑定。
Audio（音频）
09IAudioService架在 AudioMixer 上的音乐 / SFX / 语音通道——源池化、淡入淡出、音量绑定。
UI Panel Stack（UI 面板栈）
10IPanelStack面板压栈 / 出栈，支持模态窗口与完整的手柄 / 键盘焦点管理。
Scene Flow（场景流程）
11ISceneService异步场景加载，带加载界面与取消；另支持叠加式加载 / 卸载。
Localization（本地化）
12ILocalizationService键 → 字符串查询与运行时语言切换——已绑定文本即时更新，无需重启。
Achievements / Stats（成就与统计）
13IAchievementService本地统计与成就，达阈值自动解锁，经存档服务持久化。
Scheduler / Timer（调度器）
14IScheduler感知暂停与慢动作的 After / Every / NextFrame 计时器，外加回到主线程的派发。
Tween / Easing（补间与缓动）
15ITweenService感知暂停的数值补间——31 条缓动曲线，封闭的强类型 To/From 重载。
Asset Provider（资源加载）
16IAssetProvider基于 Addressables 的异步加载——引用计数 + 作用域结束自动卸载。
Seeded Random（种子随机）
17IRandomService确定性种子随机——具名可分叉的随机流，快照 / 恢复与存档严丝合缝。
State Machine（状态机）
18IStateMachineService扁平有限状态机工厂，跑在你自定义的上下文类型之上，状态转换可加守卫条件。
Pushdown State Stack（下推状态栈）
19IPushdownStackService可恢复游戏状态作用域的栈——对话压在玩法之上、菜单返回栈。
Tween Sequencing（补间序列）
20ITweenSequenceService架在补间服务之上的顺序 + 并行时间线，用链式构建器组装。
Addressable Scene
21IAddressableSceneService从 Addressables 目录叠加加载 / 卸载场景——按 key 引用计数。
Deferred Event Queue（延迟事件队列）
22IDeferredBus此刻先把事件入队，在你选定的 Flush() 时机再发布——例如挪出物理回调。
Command Registry（命令注册表）
23ICommandRegistry运行时命令注册表——注册 / 分词 / 执行、历史、自动补全。控制台 UI 由你自己写。
每个服务在包内都配有一页平实易懂的参考文档（Documentation/Modules/），以及一行代码即可换上的 Null 空实现。
工作原理
60 秒读懂架构
- 没有 DI 容器。一个静态 ServiceLocator 保存服务接口与实例的对应关系。
- 你的代码：var audio = ServiceLocator.Resolve<IAudioService>()——Resolve 一次并缓存，永远不要在 Update() 里 Resolve。
- 框架内部：Bootstrap 构造每一个服务，依赖通过构造函数传入，因此每个实现都可以独立测试。
- 运行时程序集共 7 个：Core 装着 18 个零包引用的服务；Input、UI、Localization、Assets、AddressableScene 和 Bootstrap 分层架在其上。不用的 Unity 包可以直接删掉——依赖它的程序集会自动排除，Bootstrap 会跳过它们的注册（UI 面板栈降级为空实现），而不是弄坏你的构建。
- 每个服务都可以被替换或关闭。每个服务都自带 Null 空实现：ServiceLocator.Replace<IAudioService>(new NullAudio()) 一行就让音频全局静默，调用方一处都不用动。
- 面向 AI 协作：内置 AI 助手规格说明（Documentation/AI/AGENT.md）与 5 个任务技能，适用于 Claude Code、Cursor 和 GitHub Copilot。
版本发布
更新日志
v2.1.02026-08-03
写给新手的版本——文档与打包全部重做，让从未见过 CGS 的人几分钟内就能上手。所有运行时文件夹和参考文档现在都使用平实的英文名称（Bootstrap、SaveLoad、Tween……）；旧的内部编号前缀已从文件夹名和文件名中消失。包内新增一个看得见的演示场景 Assets/CommonGameSystem.Core/Demo/MotionLab.unity——打开按 Play 即可，零配置。它展示补间缓动画廊、补间序列、调度器计时器，以及一个把游戏玩法冻住、UI 时钟却继续转的 Time Scale 滑块；只需要内置的 uGUI 包。Welcome 窗口围绕“60 秒试玩演示”重新设计：每个包版本自动打开一次，Tools > Common Game System > Welcome 和 Window > Common Game System > Welcome 两处都能打开，提供一键导入示例、快捷链接（PDF 手册 / 文档 / 更新日志 / 模块参考）以及折叠起来的环境自检。示例现在是 6 个——UI Panel Stack、Save/Load + Seeded Random、Command Console 是可运行场景；Scene Flow、Localization、RPG Starter 是带分步说明的脚本模板。（Motion Lab 从示例升格为常驻可见的演示。）一本带目录和标注截图的分页 PDF 手册随包发布于 Documentation/CGS-Manual.pdf；AI 助手文件移至 Documentation/AI/。2,600 多个自动化测试仍随包发布，但现在保持隐藏——在 Welcome 窗口一键导入之前，它们不会编译进任何买家项目。依旧是 23 个服务、0 个第三方依赖。
v2.0.02026-07-30
七程序集拆分版。原本单一的 CommonGameSystem.Core 运行时程序集现在拆成七个——Core（18 个零包依赖的服务，外加纯 UI 契约）、Input、UI、Localization、Assets、AddressableScene、Bootstrap——只引用你用得到的。破坏性变更只影响自带 asmdef 的项目，而且只动引用列表：源码零改动，命名空间全部保持 CommonGameSystem.Core，Assembly-CSharp 项目不受影响。不用的 UPM 包（Addressables / Input System / UGUI）现在可以直接移除：依赖它的程序集——随包发布的测试与示例程序集也在内——会经 defineConstraints 自动排除，Bootstrap 跳过它们的注册（UI Panel Stack 降级为 NullPanelStack）。三个包默认仍会自动安装。link.xml 改为按模块拆分，每个可选程序集的 IL2CPP preserve 条目随它一并带走。场景加载的取消换上了一份诚实的契约（行为上的破坏性变更）：旧的承诺——“阻止激活、新场景的 OnEnable 永不执行”——根本无法实现，因为 Unity 会让整条 AsyncOperation 队列卡在一个未激活的加载后面，一次取消就把此后进程里所有的场景加载全部冻住。现在：在后端加载发出之前取消，是真正的取消；发出之后取消，场景切换照常完成，并在激活之前发布 SceneLoadCanceled——此时旧场景里的订阅者都还在。修复：编辑器退出 Play 的拆卸此前是个悄无声息的空操作（注册表在 LIFO Dispose 链之前就被清空，成就落盘与资源句柄释放全被跳过）；SFX 自动回收跑在受缩放的游戏时间上，而音频播放走的是真实时间（现改用不受缩放的时间，并把 pitch 计算在内）；TimeServiceTicker 现在声明 [DefaultExecutionOrder(-100)]，你的脚本不会再和它抢当帧的 delta；IConfiguration.Set<T> 现在存入一份私有副本，而不是在原地 clamp 你传入的实例。新增：InputServiceOptions.AlwaysEnabledMaps（让 UI / Debug action map 跨上下文切换保持常开）、IPanelVisual（可选启用的面板淡入淡出转场，外加选项里一直承诺的模态背景遮罩）、GraphicsSettingsApplier（画质 / 分辨率 / 全屏 / 垂直同步 / 帧率上限现在真的会应用到 Unity）、ISaveStorageBackend（存档介质可注入——加密存档、自定义位置、Steam Cloud，并新增一篇 Steam 接入指南）、FileLogger（可选启用的轮转文件日志，重启之后依然还在），另外延迟写入的设置现在在失去焦点时也会落盘。依旧是 23 个服务、0 个第三方依赖；2,665 个自动化 EditMode 测试。
v1.15.02026-07-25
首个正式发布的版本。相比未发布的 1.14.0 构建，新增了 3 个 Core 服务（20 → 23），同样由那一句 Bootstrap.Run() 装配完成：Addressable Scene（IAddressableSceneService——从 Addressables 目录异步叠加加载 / 卸载场景，按 key 引用计数，运行时数据出错不抛异常）、Deferred Event Queue（IDeferredBus——此刻先采集事件，之后在你选定的 Flush() 时机再发布）、Command Registry（ICommandRegistry——运行时命令内核，注册 / 分词 / 执行，带历史记录与前缀自动补全；游戏内控制台 UI 仍由你自己写）。示例增加到 7 个可导入，其中 4 个是搭好就能跑的完整场景：Motion Lab（8 条缓动曲线的补间画廊、路点序列，以及最出彩的按 Clock 分离演示——把 gameplay 的 TimeScale 调到 0，画廊静止不动，UI 的转圈照常运转）、Save/Load + Seeded Random（Load 之后接下来三次种子随机的结果，与 Save 时立下的预言分毫不差）、M25 Command Console（能用的游戏内开发者控制台，带历史与自动补全），外加一个 RPG Starter 代码模板。Tools ▸ Common Game System 下新增编辑器工具：Welcome / Quick Start 窗口（环境自检、一键导入示例）与运行时 Service Debugger（实时服务注册表、各 Clock 的时间缩放、当前 tween / FSM / 音频 / 命令统计）。修复：已持久化的音频设置现在会在启动时正确生效（mixer 早期初始化竞态）；UI 示例的音量 / 静音控件即时响应，并随包附带一段《D 大调卡农》BGM 循环（乐曲属公有领域，录音为我方合成自制），这样你能听得出来它确实在工作；面板导航的 NullReferenceException；“No cameras rendering”水印；以及退出 Play 时的拆卸异常。依旧是 0 个第三方依赖、IL2CPP 就绪、不绑定渲染管线、2,550 个自动化 EditMode 测试。
v1.14.02026-06-14
已提交审核，但从未发布。该构建于 2026-06-15 提交至 Unity Asset Store，但一直没有进入审核，因此从未到达任何人手里——它保留在这里是作为工程记录的一部分，而不是一个你曾经可以安装的版本。20 个生产级服务，由一句 Bootstrap.Run() 装配完成——Service Locator、Logger、Event Bus、Save/Load、Configuration、Input、Time、Object Pool、Audio、UI Panel Stack、Scene Flow（含叠加）、Localization、Achievements/Stats、Scheduler、Tween、Asset Provider、Random、FSM、Pushdown Stack、Tween Sequencing。0 个第三方依赖，IL2CPP 就绪，不绑定渲染管线，面向 AI 协作（AGENT.md + 5 个任务技能）。1.14.0 之前的各版本均为内部开发里程碑。
完整的逐版本工程更新日志随包发布（CHANGELOG.md）。
法律条款
许可协议
Common Game System 是专有软件，仅通过 Unity Asset Store 分发，使用须遵守 Unity Asset Store EULA。
- ✓ 可用于在 Unity 支持的平台上发行的商业与非商业游戏。
- ✓ 可自由修改调用框架公开 API 的自有代码。
- ✗ 不得将本框架（或其实质性衍生版本）在任何资源商店重新发布。
- ✗ 不得移除版权 / 许可声明，也不得对源码再授权。
0 个第三方运行时依赖；随包引用的 Unity 官方包适用 Unity Companion License（详见 THIRD-PARTY-NOTICES.md）。Copyright © 2026 JoGyoungJun. All Rights Reserved.
支持