YokiFrame

YokiFrame

📖 简介

YokiFrame 是一套用同一份 C# 业务代码同时支撑 Unity 2022.3+ 与 Godot .NET 的跨引擎游戏框架。它把游戏开发中最常见的基础工作拆成一组可独立组合的 Kit：组织业务服务、传递事件、管理状态、编排流程、加载资源、播放音频、保存数据、处理本地化和搭建 Unity UI。业务规则写在纯 C# Core 中，引擎 API、生命周期与默认后端由各自的宿主 Adapter 提供，因此换引擎不换业务代码。

✨ 核心特性

• 🚀 跨引擎 - 同一套 C# 业务代码，Unity 与 Godot .NET 通用，宿主差异由 Adapter 隔离
• 🧩 Kit 即插即用 - 每个 Kit 可独立引入、组合或移除，按需取用
• 🛠️ 统一工具链 - Avalonia Workbench 可视化观测、yoki CLI 脚本化操作、Installer 一键安装
• ⚙️ 可选依赖解耦 - UniTask、YooAsset、DOTween、Luban、Nino 等按需接入，不引入不依赖
• 🧹 零初始化仪式 - 无全局初始化入口，默认后端在第一次真实调用时惰性创建
• 🔍 可观测性 - 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;

// 1. 定义架构并注册业务服务
public sealed class GameArchitecture : Architecture<GameArchitecture>
{
    protected override void OnInit() => Register<SessionService>(new SessionService());
}

public readonly struct SessionStarted
{
}

// 2. 业务服务通过 EventKit 发布事件
public sealed class SessionService : AbstractService
{
    public void StartSession() => EventKit.Type.Send(new SessionStarted());
}

// 3. 在业务入口调用服务
GameArchitecture.Interface
    .GetService<SessionService>()
    .StartSession();

// 4. 订阅事件；返回的 link 用于在模块停用时注销
LinkUnRegister<SessionStarted> link =
    EventKit.Type.Register<SessionStarted>(_ => LogKit.Info("Session started"));

// 5. 用 ActionKit 编排异步流程
IActionController flow = ActionKit.Sequence()
    .Callback(() => LogKit.Info("Loading"))
    .Delay(0.5f)
    .Callback(() => LogKit.Info("Ready"))
    .Start();

GameArchitecture.Interface 第一次访问时创建架构并初始化服务。事件订阅由订阅方注销；仍在运行的动作由创建它的业务 owner 调用 Cancel()。更多生命周期约定见 生命周期与所有权。

🧩 核心模块

架构

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 演化的衍生框架。