面向 Unity 与 Godot .NET 的跨引擎 C# 游戏框架
YokiFrame 是一套装进 Unity 或 Godot .NET 后就能直接调用的跨引擎 C# 游戏框架。它没有必须安装的第三方库，也不需要先搭建运行时上下文：安装并完成编译后，直接使用 EventKit、LogKit、ActionKit 等 Kit API。
它把游戏开发中最常见的基础工作拆成一组可独立组合的 Kit：组织业务服务、传递事件、管理状态、编排流程、加载资源、播放音频、保存数据、处理本地化和搭建 Unity UI。业务规则写在纯 C# Core 中，引擎 API、生命周期与默认后端由各自的宿主 Adapter 提供，因此换引擎不换业务代码。
- 📦 开箱即用 - 安装到引擎后直接调用，不需要手写启动器或注册模块
- 🪶 无必须依赖 - 包本身不依赖第三方库；Unity 会自动发现已安装的可选库，并用宏切换对应 API
- 🧹 非必要无初始化仪式 - 没有全局初始化入口；默认后端在第一次真实业务调用时创建
- ✨ API 简单直接 -
EventKit.Type.Send、ActionKit.Sequence()、LogKit.Info，名称即用途 - 🏷️ 命名一致 - 能力统一以
Kit结尾，入口、状态和动作都使用同一套短名称 - 🚀 跨引擎 - 同一套 C# 业务代码，Unity 与 Godot .NET 通用，宿主差异由 Adapter 隔离
- 🧩 小巧灵活 - 每个 Kit 可单独使用或自由组合，不需要一次启用整套框架
- 🛠️ 统一工具链 - Avalonia Workbench 可视化观测、
yokiCLI 脚本化操作、Installer 一键安装 - 🔍 可观测性 - FileBridge 命令协议与共享内存遥测，为编辑器与 AI 工具提供可靠的诊断通道
| 环境 | 要求 |
|---|---|
| Unity | 2022.3 或更高 |
| Godot | 4.x .NET（当前开发与验证基线为 4.7，不支持非 .NET Godot） |
| 工具链 | Windows / macOS / Linux，构建 Workbench 与 yoki 时需 .NET 10 SDK |
| 业务代码 | C# 9.0 兼容语法 |
-
打开
Window > Package Manager，点击+，选择 Add package from git URL。 -
输入：
https://github.com/HinataYoki/YokiFrame.git -
等待导入和编译完成。
从完整 YokiFrame 源码包根目录运行对应脚本，传入 Godot 项目路径：
& "<packageRoot>\YokiFrameWorkbench~\scripts\runtime-bootstrap\install-godot.cmd" --project "<godotProjectRoot>"Linux / macOS 使用同目录下的 install-godot.sh 或 install-godot.command。脚本会构建 Runtime 并打开 Installer 图形界面，在 Installer 中选择 Godot local、确认 plan 并执行 apply 即可。安装完成后请关闭并重新打开 Godot 项目，让编辑器重新扫描已生成的托管程序集。
💡 提示：构建失败时查看 Installer 返回的 dotnet 编译输出；详细说明见 故障排查。
不想手动操作时，直接把本仓库地址（或本地源码包目录）和“安装 YokiFrame”一起交给 AI 即可。AI 会自动完成编译、Runtime 构建、安装计划与结果校验，详细流程见 AI 安装指引。
安装完成后不需要任何启动代码。日志、事件和动作流程可以直接调用：
using YokiFrame;
LogKit.Info("Ready");
EventKit.Type.Send(new SessionStarted());
IActionController flow = ActionKit.Sequence()
.Delay(0.5f)
.Callback(() => LogKit.Info("Loaded"))
.Start();SessionStarted 是普通的 readonly struct，GameState 是普通枚举；框架不会要求它们继承特殊基类。订阅事件时保存返回的 LinkUnRegister<T>，模块停用时调用 UnRegister()。仍在运行的动作由创建它的业务 owner 调用 Cancel()。
需要组合多个业务服务时，再使用 Architecture。它同样没有全局启动器，第一次访问 GameArchitecture.Interface 时才创建：
public sealed class GameArchitecture : Architecture<GameArchitecture>
{
protected override void OnInit() => Register<SessionService>(new SessionService());
}
GameArchitecture.Interface.GetService<SessionService>().StartSession();更多生命周期约定见 生命周期与所有权。
直接调用 Kit API 即可。宿主 Adapter 随包安装进入引擎，会话换代由 Unity 或 Godot 生命周期自动完成。日志、事件、状态机、对象池和动作编排都不需要预先安装第三方库。
Unity Editor 会自动扫描 UniTask、YooAsset、DOTween、Luban、Nino、ZString 和 Input System。库存在时自动添加对应宏，移除后自动清除；异步入口等 API 随之在 UniTask 与普通 Task 之间切换，业务代码不需要手写条件编译或注册接入层。Godot 项目保持纯 C# API，不使用这套 Unity 宏。
默认资源与音频后端也在第一次真实加载或播放时创建。只有项目主动替换实现，或使用没有默认数据来源的能力时，才需要提前配置：
| 场景 | 需要做什么 |
|---|---|
| 使用引擎默认资源或音频 | 无需配置，直接调用 |
| 使用自己的资源、音频或 YooAsset | 第一次调用前 SetProvider |
| 查询本地化文本 | 先 LocalizationKit.SetProvider |
| 定制 Unity UI 根节点 | 第一次打开面板前 UIKit.SetRootPrefab |
| 读取 Luban 数据表 | 先用 TableKit 生成项目代码 |
诊断和 Workbench 读取不会因为“看一眼”而创建这些业务后端。
API 名称按职责拆开，不使用 Manager、Helper 或编号后缀。日常玩法直接从对应 Kit 进入：
AudioVoiceHandle hit = AudioKit.PlaySfx("Audio/Hit");
AudioKit.PlayMusic("Audio/Bgm", loop: true);
SaveData progress = SaveKit.CreateSaveData();
progress.RegisterModule(new PlayerProgress());
SaveKit.Save(SaveTarget.Slot(0), progress);
InventoryPanel bag = UIKit.OpenPanel<InventoryPanel>();
SceneKit.LoadSceneAsync("Town", onComplete: _ => LogKit.Info("Entered town"));
LocalizationKit.SetLanguage(LanguageId.English);
string title = LocalizationKit.Get(1001);PlaySfx 和 PlayMusic 使用引擎默认音频后端。存档第一次写入时创建默认存储。OpenPanel 是 Unity UI 入口，Godot 项目继续使用 Godot 自己的界面。场景名和本地化文本来源需要项目自己提供；本地化在查询前还要先 SetProvider。
| 名称 | 含义 | 日常例子 |
|---|---|---|
Kit |
一组独立能力及其静态入口 | AudioKit.PlaySfx、SaveKit.Save、UIKit.OpenPanel |
Play / Load / Open |
开始一次播放、加载或打开 | PlayMusic、ResKit.Load<T>、OpenPanel<T> |
Handle |
这一次播放或加载的所有权 | AudioVoiceHandle、ResHandle<T>、SceneHandler |
Stop / Release / Close |
结束对应的所有权 | AudioKit.Stop(hit)、handle.Release()、UIKit.ClosePanel<T>() |
Save / Load / Slot |
存档写入、读取和槽位 | SaveTarget.Slot(0)、SaveKit.TryLoad |
Get / SetLanguage |
取文本和切换语言 | LocalizationKit.Get、SetLanguage |
Register / Send |
建立订阅和发布事件 | EventKit.Type.Register<T>、EventKit.Type.Send |
Sequence / Delay / Callback |
把等待和回调串成一段流程 | ActionKit.Sequence().Delay(0.5f).Callback(...) |
Allocate / Recycle |
从对象池借出和归还 | pool.Allocate()、pool.Recycle(bullet) |
Provider |
替换资源或音频来源，或安装本地化文本来源 | ResKit.SetProvider(...)、LocalizationKit.SetProvider(...) |
看到 Kit 就是能力入口，看到 Play、Load、Open、Save 就是在做这件事，看到 Handle 就要由创建它的模块负责结束。资源、音频和存档的普通调用碰不到 Provider；本地化没有默认文本来源，查询前要先安装。
| 模块 | 作用 | 文档 |
|---|---|---|
| Architecture | 组合服务、模型和系统，提供统一的业务边界 | Architecture |
| 模块 | 作用 | 文档 |
|---|---|---|
| EventKit | 类型事件、枚举事件和对象内事件 | EventKit |
| FsmKit | 有限状态机、状态转换和历史 | FsmKit |
| LogKit | 统一日志入口和宿主后端 | LogKit |
| PoolKit | 对象复用和池生命周期 | PoolKit |
| ResKit | 资源加载、Provider、handle 和卸载 | ResKit |
| SingletonKit | 纯 C# 单例 | SingletonKit |
| ToolClass | 通用集合、绑定值和字符串工具 | ToolClass |
| CodeGenKit | 编辑器代码生成基础能力 | CodeGenKit |
| InspectorKit | Unity Inspector 基础控件 | InspectorKit |
| 模块 | 作用 | 文档 |
|---|---|---|
| ActionKit | 顺序、并行、条件、延迟和异步动作 | ActionKit |
| AudioKit | 音频资源、总线和播放状态 | AudioKit |
| LocalizationKit | JSON 或 Luban 表格本地化 | LocalizationKit |
| SaveKit | 存档读写、版本和迁移 | SaveKit |
| SceneKit | 场景预加载、切换和卸载 | SceneKit |
| SpatialKit | HashGrid、Quadtree 和 Octree 空间查询 | SpatialKit |
| TableKit | Luban 配置生成和运行时读取 | TableKit |
| UIKit | Unity 面板、绑定、动画和代码生成 | UIKit |
| RoslynKit | 操作当前编辑器：进播放、查场景、调用已有服务；不退出播放时试行为 | RoslynKit |
| 工具 | 用途 |
|---|---|
| Workbench | Avalonia 桌面工具，实时查看项目状态、Kit 运行态与诊断信息 |
yoki CLI |
脚本化读取、诊断、宿主操作和受信任内存 C#。改变宿主状态前先看 RoslynKit 开关 |
| Installer | 图形化安装、更新与回滚，支持 Unity 本地 / Git URL 与 Godot 本地安装 |
工具链面向开发者和 AI 工具，运行时诊断不会进入 Player 构建。安装相关的自动化流程见 AI 安装指引。
YokiFrame/ # 包根（同时是 Unity Git URL 包根）
├── Core/ # 跨引擎核心
│ ├── Runtime/ # 纯 C# 业务能力（YokiFrame 程序集）
│ ├── Editor/ # Unity Editor 与 Godot Tools 共用的纯 C# 工具
│ ├── Adapters/ # 宿主适配层（Unity / Godot）
│ ├── Integrations/ # 可选第三方依赖接入
│ └── Tests/
├── Tools/ # 各 Kit（ActionKit / UIKit / SaveKit / ...）
├── YokiFrameWorkbench~/ # Workbench、CLI、Installer 源码（不参与 Unity 编译）
└── Documentation~/ # 文档（API、指南、第三方依赖建议）
| 项目 | 要求 |
|---|---|
| Unity | 2022.3 或更高 |
| Godot | 4.x .NET（当前开发与验证基线为 4.7） |
| .NET | 工具链（Workbench / CLI / Installer）基于 .NET 10 |
| C# | Runtime 业务代码保持 C# 9.0 兼容 |
| 平台 | 工具链支持 Windows、macOS、Linux |
| 文档 | 描述 |
|---|---|
| 框架概览 | 新手入口：适用场景、Kit 状态、默认后端与关键边界 |
| AI 安装指引 | 安装与 AI 自动化安装的完整流程 |
| 生命周期与所有权 | 事件、资源、动作与异步工作的 owner 约定 |
| 故障排查 | 常见问题与诊断方法 |
| 第三方依赖建议 | YooAsset、UniTask、DOTween、Luban 等接入建议 |
| Changelog | 版本更新记录 |
| License | MIT 开源许可 |
欢迎提交 Issue 和 Pull Request。
如果 YokiFrame 对你有帮助，欢迎 ⭐ Star 支持项目发展。
YokiFrame 是基于 QFramework 演化的衍生框架。