YokiFrame

YokiFrame

📖 简介

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 可视化观测、yoki CLI 脚本化操作、Installer 一键安装
• 🔍 可观测性 - FileBridge 命令协议与共享内存遥测，为编辑器与 AI 工具提供可靠的诊断通道

📚 目录

• 快速开始
• 为什么容易上手
• 核心模块
• 工具链
• 项目结构
• 系统要求
• 文档导航
• 贡献与支持

🚀 快速开始

环境要求

安装：Unity

1. 打开 Window > Package Manager，点击 +，选择 Add package from git URL。

2. 输入：

   https://github.com/HinataYoki/YokiFrame.git
   

3. 等待导入和编译完成。

安装：Godot .NET

从完整 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 编译输出；详细说明见 故障排查。

交给 AI 安装

不想手动操作时，直接把本仓库地址（或本地源码包目录）和“安装 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 宏。

默认资源与音频后端也在第一次真实加载或播放时创建。只有项目主动替换实现，或使用没有默认数据来源的能力时，才需要提前配置：

诊断和 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 就是能力入口，看到 Play、Load、Open、Save 就是在做这件事，看到 Handle 就要由创建它的模块负责结束。资源、音频和存档的普通调用碰不到 Provider；本地化没有默认文本来源，查询前要先安装。

🧩 核心模块

架构

Core Kit

Tool Kit

🛠️ 工具链

工具链面向开发者和 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、指南、第三方依赖建议）

💻 系统要求

📚 文档导航

🤝 贡献与支持

欢迎提交 Issue 和 Pull Request。

如果 YokiFrame 对你有帮助，欢迎 ⭐ Star 支持项目发展。

源框架

YokiFrame 是基于 QFramework 演化的衍生框架。