Warning
持续开发中 · 当前为非稳定版本 —— 抢先体验必须到 Discussions 联系作者
一套基于 Unity 2022.3、以 DOTS / ECS 数据驱动 为核心的轻量级游戏开发框架。
内置配置管线、多语言本地化、ECS UI、输入 / 热键、过场演出与可视化行为树,并配套完整的编辑器工具链,帮助中大型 Unity 项目快速搭建、稳定迭代。
- DOTS / ECS 数据驱动架构:以
World+ 分层ComponentSystemGroup更新阶梯组织游戏逻辑;配置、本地化、行为树全部以不可变 Blob 存储,运行期零托管分配、可 Burst 友好遍历。 - 配置管线(Config):Excel / 模板驱动,生成期把行烘焙为 blittable 结构体与
BlobAssetReference;运行期以世界无关的ConfigManager静态表提供无分配查询。 - 多语言本地化(Loc):基于 Blob 的多语言系统,支持 key 查询、
string.Format占位符、运行时切语言、MonoBehaviour 自动刷新与敏感词过滤。 - ECS UI 系统:UI 即 ECS System(而非 MonoBehaviour 窗口管理器)。
UIManager统一管理分层 Canvas 与 Addressables 实例化,ComponentBinderTable生成强类型组件绑定。 - 输入 / 热键(Input):基于 Unity InputSystem 的 action-name 分发热键中心,支持 Press / Hold、设备切换、键盘 / 手柄导航模式与静音 / 打断控制。
- 过场演出(Timeline):轻量过场导演,维护播放队列、支持跳过,片段播放由游戏层重写
PlayClip接入(Timeline / Playable / 视频皆可)。 - 可视化行为树(BT):
BTTreeAsset可视化编辑 → 序列化为BTRootBlob→BTManager注册 →BTInterpreterSystem逐帧解释执行;支持自定义节点与运行时黑板。 - 编辑器工具链:Excel 配置自动生成、组件绑定代码生成、本地化 Key 管理、行为树可视化编辑器与校验器,大幅降低手工出错率。
| 依赖 | 版本 |
|---|---|
| Unity | 2022.3 或以上 |
com.unity.addressables |
1.21.21 |
com.unity.entities(DOTS / ECS) |
>= 1.0.16(Unity 2022.3 验证;Unity 6.x 以 #if UNITY_6000_0_OR_NEWER 分版本适配) |
| NPOI(仅编辑器,Excel 本地化导入) | — |
⚠️ 包位于com.hyc.framework/子目录,安装 URL 必须带?path=com.hyc.framework(漏了 Unity 会找不到包)。
Unity 菜单 Window → Package Manager → 左上角 + → Add package from git URL,填入:
https://github.com/HYClub/hyc-framework.git?path=com.hyc.framework
在工程的 Packages/manifest.json 的 dependencies 中追加:
{
"dependencies": {
"com.hyc.framework": "https://github.com/HYClub/hyc-framework.git?path=com.hyc.framework"
}
}💡 可追加
#<tag>或#<commit>锁定版本,例如https://github.com/HYClub/hyc-framework.git?path=com.hyc.framework#v2.1.0(建议基于当前main打一个 tag,便于可复现地引用某个发布版本)。
框架的数据流可概括为四个阶段,配置 / 本地化 / 行为树三者产物都是不可变 Blob:
- 生成期(Editor):Excel / 配置模板经
ConfigGenerator产出[BlobGenerate]的 blittablestruct(命名空间HYC.Framework.Config.Generated),经ConfigExportService烘焙成BlobAssetReference<BlobRoot<TRow>>;本地化表经LocalizedExcelReader(NPOI) 产出id/lang/filter与每语言{lang}.langBlob;行为树在BTTreeAsset中可视化编辑,由BTBlobBuilder.Build序列化为纯数据BTRootBlob。三者均可在运行期用BlobAssetReference<T>.TryRead直接读入,无需反序列化托管对象。 - 引导期(A0 / A1 数据阶段):游戏 Bootstrap 把 Blob 读入,调用
ConfigManager.Register(table)(世界无关静态表)、LocalizationManager.Reload(folder)(或LocalizationBlobSystem自动从StreamingAssets/Localization加载)、BTManager.Register(treeId, blobRef)。 - 运行期(A2 / A3 玩法阶段):玩法系统从
ConfigManager查行(无需 World 句柄)、从LocalizationManager取文本;行为树由BTInterpreterSystem(ISystem)对挂RunningBT的实体逐帧Tick,BTInterpreter以指针遍历BTRootBlob,通过BTContext.GameHandler把GameCustom节点派发到BTNodeRuntimeRegistry(反射缓存的BTCustomNode子类),并读写BTBlackboardRuntime(每树实例一个,定义只读、实例可写)。 - 表现期(B9,最后运行):UI 系统(
UIManager+AbsUISystem)最后运行,读玩法阶段产生的最新状态刷新 HUD / 窗口;单帧MessageEntity/EventMessage在玩法阶段被消费,帧末由MessageExpirySystem/MessageClearSystem清理,消息绝不过帧。
UI 如何挂在 ECS 上:AbsUISystem([DisableAutoCreation])由游戏显式 CreateSystemManaged 并加入某 UpdateGroup(通常 B9 内);其 PrefabKey 是 Addressable key,UIManager 在打开时 Addressables.InstantiateAsync 实例化 Prefab 并挂到分层 Canvas 下。视图内组件通过 ComponentBinderTable 配置、由 ComponentBinderCodeGenerator 生成强类型 class X : IComponentBinder,在视图(重)显示时 Reset 重新绑定,避免跨场景后引用失效。
框架的启动宿主与 ECS 更新阶梯——用 IFrameworkInstaller 组合安装世界、以双模式(Live / Sim)启动,并通过单帧消息实体在系统间解耦通信。
⚠️ FrameworkBootstrap不会被 Entities 的ICustomBootstrap自动发现(避免与游戏自有 bootstrap 冲突)。游戏需直接调用Initialize,或自定义ICustomBootstrap来new FrameworkWorld()。
// 1) 自定义安装器,把系统挂进世界
class MyInstaller : HYC.Framework.Runtime.IFrameworkInstaller
{
public void Install(World world)
=> world.GetOrCreateSystemManaged<MyGameSystem>();
}
// 2) 注册安装器并启动(Live 模式)
HYC.Framework.Runtime.FrameworkBootstrap.Installers.Add(new MyInstaller());
HYC.Framework.Runtime.FrameworkBootstrap.BootMode = HYC.Framework.Dots.SimulationBootstrap.Live;
new HYC.Framework.Runtime.FrameworkBootstrap().Initialize("Game World");
// 3) 在系统内发一条单帧引导消息(UI 系统的 OpenGuide 内部即如此实现)
var beginSim = world.GetExistingSystemManaged<BeginSimulationEntityCommandBufferSystem>();
var ecb = beginSim.CreateCommandBuffer();
var e = ecb.CreateEntity();
ecb.AddComponent<HYC.Framework.Dots.MessageEntity>(e);
ecb.AddComponent(e, new HYC.Framework.Dots.EventMessage { EventID = 1001, IsRepeated = false });
// 帧末由 MessageClearSystem 自动销毁,无需手动回收更新阶梯顺序:Root → A0(引导) → A1(数据) → A2(场景) → A3(玩法) → B9(UI 最后)。
双模式语义:Live = 1 联网 / 正常;Sim = 2 离线确定性模拟,SimOnly 标记的系统只应在模拟会话中运行。
核心类型:FrameworkWorld、IFrameworkInstaller、FrameworkBootstrap、SimulationState、SimOnly、SimulationBootstrap、UpdateGroup_*、Message / MessageEntity / EventMessage、MessageClearSystem / MessageExpirySystem。
Excel / 模板驱动的「不可变 Blob 配置表」——生成期把行烘焙为 [BlobGenerate] blittable 结构体,运行期以世界无关的 ConfigManager 静态表提供无分配查询。
// 1) 生成期由 Excel / 模板产出(示意,真实由 ConfigGenerator 生成):
// namespace HYC.Framework.Config.Generated
// [HYC.Framework.Config.BlobGenerate("Item")]
// public struct ItemCfg : Unity.Entities.IComponentData, System.IEquatable<ItemCfg>
// { public long Id; public int Price; public int StackMax; }
// 2) 运行期从 .blob 读取并注册(id 取行内 Id 字段)
BlobAssetReference<BlobRoot<ItemCfg>> blobRef = /* BlobAssetReference<BlobRoot<ItemCfg>>.TryRead(...) */;
var table = ConfigBlobTable<ItemCfg>.FromBlob(blobRef, row => row.Id);
HYC.Framework.Config.ConfigManager.Register(table);
// 3) 任意处读取(无需 World 句柄)
if (HYC.Framework.Config.ConfigManager.TryGet<ItemCfg>(itemId, out var cfg))
int price = cfg.Price;注意:
- 行结构体必须 blittable(
ConfigBlobTable<TRow> where TRow : unmanaged);ConfigValidator会在编辑器菜单HYC Framework/Tools/Validate Config校验缺[BlobGenerate]标记或非 blittable 字段。 ConfigManager的读访问是世界无关的——UI 与玩法层查表都不需要 World 句柄。
核心类型:ConfigManager、ConfigBlobTable<TRow>、BlobRoot<TRow>、ConfigTemplate、ConfigEnumDefinition、CfgAssetAttribute、IConfigIdProvider、BlobGenerateAttribute。
基于 Blob 的多语言系统——从 id / lang / filter 文件 + 每语言 {lang}.lang Blob 加载,提供 key 查询、运行时切语言、MonoBehaviour 自动刷新与敏感词过滤。
// 1) 代码取文本(支持 {0}{1} 占位符,走 string.Format)
string s = HYC.Framework.Loc.LocalizationManager.GetText("ui/start");
string s2 = HYC.Framework.Loc.LocalizationManager.GetText("ui/welcome", playerName);
// 2) 运行时切换语言
HYC.Framework.Loc.LocalizationManager.SetLanguage(HYC.Framework.Loc.Locale.Chinese);
// 3) 在 Prefab 上挂 LocalizedTMP 组件,Inspector 设 Key = "ui/start",
// 切语言时 onLanguageChanged → 组件自动 Refresh,无需手写。
// 4) 从 StreamingAssets 重新加载(LocalizationBlobSystem 在 BeforeSceneLoad 已自动调一次)
HYC.Framework.Loc.LocalizationManager.Reload(Application.streamingAssetsPath + "/Localization");注意:LocalizedExcelReader 用真实 UTF-8 字节数分配,专门修复中文被截断的问题;GetTextByLang 在 key 不存在时返回 "未找到Key : {key}"。
核心类型:LocalizationManager、Locale、LocaleUtil、CfgLocalization、LocalizationBlobSystem、LocalizationExtension、LocalizedBase / LocalizedText / LocalizedTMP、SensitiveWordManager。
用 ECS System(而非 MonoBehaviour 窗口管理器)承载 UI——UIManager 拥有根节点 / 分层 Canvas,AbsUISystem 通过 Addressables 实例化 Prefab 视图,并由 ComponentBinderTable 生成强类型 IComponentBinder 绑定组件。
// 1) 定义一个窗口系统([DisableAutoCreation],由游戏 bootstrap 显式创建并加入分组)
public class BagWindow : HYC.Framework.UI.AbsUISystem
{
public override string PrefabKey => "UI/Bag"; // Addressable key
protected override void OnViewOpen()
{
base.OnViewOpen();
var title = FindComponent<TMPro.TextMeshProUGUI>("Title");
RegisterHotkey(HYC.Framework.Input.HotkeyActionNames.UI_Func_Close,
ctx => { /* 关闭窗口 */ });
}
}
// UIManager 在打开时通过 Addressables.InstantiateAsync(PrefabKey) 实例化视图并挂到 Canvas 下
// 2) 打开 / 关闭
HYC.Framework.UI.UIManager.OpenHudNotice(typeof(BagWindow));
HYC.Framework.UI.UIManager.Close<BagWindow>();
// 3) 编辑器生成强类型 Binder:在 ComponentBinderTable 上配字段后点 Generate,
// 产出 class BagBinder : IComponentBinder,挂到 Prefab 上交由 UIManager 自动 Reset 绑定注意:UIManager 与 AbsUISystem 均标 [DisableAutoCreation],必须由游戏 bootstrap 显式创建并加入某 UpdateGroup;热键改用 HotkeyActionNames 常量字符串分发(已取代原 HotkeyID 枚举)。
核心类型:UIManager、AbsUISystem、BaseWindowSystem / AbsParentBaseWindowSystem、BaseDialogSystem / BaseHudSystem / BaseLoadingSystem、BaseWindowPart、IGameFunctionWindow、UIGroup、IComponentBinder、Binder、ComponentBinderTable、UIAnimationHook。
基于 Unity InputSystem 的「按 action 名分发」热键中心——HotkeyManager 静态注册表把 action 名映射到 Action<HotkeyInputContext> 回调,提供 Press / Hold、设备切换、导航模式与静音等运行时控制。
// 1) 启动时绑定一次 InputActionAsset(会清空旧注册并订阅 InputSystem.onActionChange)
HYC.Framework.Input.HotkeyManager.BindAsset(myInputActionAsset);
// 2) 按 action 名注册热键(返回 HotkeyHandle 用于后续注销)
var handle = HYC.Framework.Input.HotkeyManager.RegisterHotkey(
HYC.Framework.Input.HotkeyActionNames.UI_Func_Bag,
ctx => { OpenBag(); },
holdTime: 0,
parent: transform,
text: "打开背包",
style: HYC.Framework.Input.HotkeyElementStyle.UI,
priority: 0);
// 3) 读摇杆值(手柄 / 键鼠统一上下文)
HYC.Framework.Input.HotkeyManager.RegisterHotkey(
HYC.Framework.Input.HotkeyActionNames.UI_UGUI_Horizontal,
ctx => { float v = ctx.ReadValue<float>(); });
// 4) 注销
HYC.Framework.Input.HotkeyManager.UnregisterHotkey(handle);注意:用 action-name 替代游戏枚举,摆脱原 InputManager 强耦合;holdTime > 0 即 HotkeyMode.Hold,否则 Press;SetSilence 可屏蔽回调,StopCurrentInvokeList() 可打断当前派发列表。
核心类型:HotkeyManager、HotkeyHandle、HotkeyMode、InputDevice、HotkeyInputContext、HotkeyInputPhase、BaseHotkeyElement、IHotkeyElement、HotkeyElementStyle、HotkeyActionNames。
简单的过场导演——维护过场队列、按顺序播放、支持跳过;具体「片段如何播放」由游戏层重写 PlayClip 实现(框架只管调度)。
class MyDirector : HYC.Framework.Timeline.CutsceneDirector
{
// 框架只调度队列,片段具体怎么播由游戏实现
protected override void PlayClip(HYC.Framework.Timeline.Cutscene clip)
{
// 用 Addressables 加载 clip.AssetKey 的 Timeline / Playable,播放结束必须调:
// NotifyFinished();
}
}
var director = new MyDirector();
director.Enqueue(new HYC.Framework.Timeline.Cutscene { Id = 1, AssetKey = "Cutscene/Intro", Loop = false });
director.Play(1);
// 需要跳过时:director.Skip();核心类型:Cutscene、CutsceneDirector。
可视化编辑(BTTreeAsset)→ 序列化为纯数据 BTRootBlob(Burst 友好)→ 运行期 BTManager 注册 → BTInterpreterSystem 对挂 RunningBT 的实体逐帧 Tick,由 BTInterpreter 递归解释执行的完整 DOTS 行为树方案。
// 1) 编辑器:Create → HYC/BT/Tree 建 BTTreeAsset,可视化连好节点,
// 保存即被 BTBlobBuilder 烘焙为 BTRootBlob
// 2) 运行期注册树(从资源加载出 BlobAssetReference<BTRootBlob> 后)
HYC.Framework.BT.BTManager.Register(treeId, blobRef);
// 3) 给实体挂 RunningBT,BTInterpreterSystem 每帧自动 Tick
var e = ecb.CreateEntity();
ecb.AddComponent(e, new HYC.Framework.BT.RunningBT
{
TreeId = treeId,
RunState = new HYC.Framework.BT.BTRunState { TreeId = treeId, RootNode = 0 }
});
// 4) 自定义一个游戏节点(自动被 BTNodeRuntimeRegistry 反射扫描,无需手动注册)
public class FindNearestEnemy : HYC.Framework.BT.BTCustomNode
{
public override long SubType => 1;
public override string NodeName => "找最近敌人";
public override HYC.Framework.BT.BTCustomNodeKind Kind => HYC.Framework.BT.BTCustomNodeKind.Condition;
public override HYC.Framework.BT.BTNodeState Execute(ref HYC.Framework.BT.BTContext ctx, ref HYC.Framework.BT.BTNodeView view)
=> /* 读 ctx.GameContext.Data 判断 */ HYC.Framework.BT.BTNodeState.Success;
}
框架默认的 BTInterpreterSystem 构造的 BTContext.GameHandler = null。这意味着 BTNodeType.GameCustom(= 128)节点在默认情况下会返回 Failed。要让自定义节点真正执行,游戏必须把 GameHandler 接到 BTNodeRuntimeRegistry.Execute:
// 在驱动 BT 的系统中,构造 ctx 时设置 GameHandler
ctx.GameHandler = (ref HYC.Framework.BT.BTContext c, ref HYC.Framework.BT.BTNodeView v) =>
{
long sub = v.Node.LongCount > 0 ? v.GetLong(0) : 0;
HYC.Framework.BT.BTNodeRuntimeRegistry.Execute(HYC.Framework.BT.BTTreeKind.AI, sub, ref c, ref v, out var r);
return r;
};其它要点:
- 内建节点:Sequence / Selector / Parallel / Random* / Invert / Repeat / UntilSuccess / UntilFail / Always* / CooldownGate / Conditional / TimeLimit / CheckDistance / CheckBlackboard / Wait / NoOp / SubTree,均在
BTInterpreter.EvaluateNodeInner的switch内实现。 - 树实例状态(
RunningBT/BTRunState,含Stack[16]、Trace[32])挂在实体上跨帧保留,解释器保留执行轨迹用于调试高亮;BTManager.ToggleBreakpoint(treeId, nodeIndex)支持断点调试。 - 黑板
BTBlackboardRuntime每树实例一个(定义只读、实例可写),键用 FNV-1a 哈希;TimeLimit/CooldownGate/Wait/Check*等节点依赖ctx.Blackboard.IsCreated,未创建黑板时返回Failed。 - 自定义节点采用双注册机制:编辑器
BTCustomNodeScanner写入BTGameNodeRegistry(供节点面板显示),运行期BTNodeRuntimeRegistry反射扫描BTCustomNode子类并缓存;二者以(BTTreeKind, SubType)为键,技能树与 AI 树的子类型数字互不冲突。
核心类型:BTManager、BTInterpreter / BTInterpreterSystem、BTBlackboardRuntime、BTContext、BTCustomNode、BTGameNodeRegistry、BTNodeRuntimeRegistry、BTRootBlob / BTNodeBlob、BehaviourTreeFieldAttribute(标记 long 为行为树引用)、BTValidator / BTBlobBuilder / BTTreeAsset(编辑器侧)。
- 日志:
Log(写persistentDataPath/logs滚动文件)、GameLog(写log.json,带时间戳)。HYC.Framework.Runtime.Log.Info("启动完成"); HYC.Framework.Runtime.Log.Error("加载失败: " + path);
- 数据模型:
DataModel/DataItem/DataStatistics提供简单的物品与数值统计设施(NewItemFlagSystem为预留扩展点)。 - 命令行参数:
GameCommandArgs单例解析--account/--token/--appid/--serverip/--serverport/--lang/--width/--height/--fullscreen。var lang = HYC.Framework.Runtime.GameCommandArgs.Instance.Lang; // --lang 的值
- ToolTip:
ToolTipManager+AbsTipView<T>/AbsTipComponent提供 12 向自动停靠的提示系统,沿基类链查找渲染器。
| 工具 | 作用 |
|---|---|
ConfigGenerator / ConfigValidator / ExcelReader |
从 Excel / 模板生成 blittable 配置结构体并校验 |
ComponentBinderCodeGenerator |
由 ComponentBinderTable 生成强类型 IComponentBinder |
LocaleWindow / LocalizedExcelReader / LocalizedKeyPickerWindow |
多语言 Key 浏览、Excel 导入(NPOI,修复中文截断)、Key 选取 |
SensitiveWordWindow |
敏感词管理 |
BTGraphWindow / BTGraphIMGUI / BTNodeCreatorWindow / BTValidator / BTBlobBuilder |
行为树可视化编辑、自定义节点生成、校验与 Blob 构建 |
框架包内的 com.hyc.framework/Documentation~/ 提供 29 篇 中文深度文档(架构 / 配置管线 / 多语言 / ECS UI / 输入 / 过场 / 消息 / 行为树 / Blob 约定 / 文件与类索引),每篇 = 架构 + 关键类 + 用法 + 坑。
🤖 这套文档专门做了「AI 友好」处理:结构固定、基于源码实测、关键信息内联。 把
com.hyc.framework/Documentation~/提供给 AI 助手(Copilot / WorkBuddy / Cursor 等),它就能在不通读源码的情况下准确理解并修改本框架。
hyc-framework/ ← 仓库根
├── README.md ← 本文件(GitHub 主页)
└── com.hyc.framework/ ← Unity 包(package.json 在此)
├── Documentation~/ ← 完整文档(29 篇,AI 友好),PM「查看文档」可打开
├── package.json / LICENSE / CHANGELOG.md / README.md
├── Runtime/ # 运行时(HYC.Framework.Runtime.asmdef)
│ ├── 引导与生命周期:Bootstrap / BootstrapSystems / UpdateGroups / Simulation / Settings / StartupSetting / GameCommandArgs
│ ├── 配置:ConfigManager / BlobTable / ConfigTemplate / ConfigEnumDefinition / DataModel
│ ├── 本地化:LocalizationManager / LocalizationBlobSystem / LocalizationExtension / SensitiveWordManager
│ ├── UI:UIManager / AbsUISystem / UIGroup / Base*System / Binder / ComponentBinderTable
│ ├── 输入与热键:HotkeyManager / Hotkey* / InputDevice / BaseHotkeyElement
│ ├── 过场演出:CutsceneDirector
│ ├── 消息与日志:MessageEntity / Log / GameLog
│ ├── Attributes/ # 17 个编辑器增强特性(Group/InfoBox/File/ListDrawer...)
│ ├── BT/ # 行为树运行时(解释器 / 管理器 / 黑板 / 事件总线 / Blob 定义)
│ ├── Components/ # LocalizedText / LocalizedTMP / LocalizedTextMesh
│ └── ToolTip/ # ToolTipManager / Tip 视图
└── Editor/ # 编辑器工具(HYC.Framework.Editor.asmdef)
├── 配置管线:ConfigGenerator / ConfigValidator / ExcelReader
├── 组件绑定:ComponentBinderTableEditor / ComponentBinderCodeGenerator / ComponentBinderSetting*
├── 本地化:LocaleWindow / LocalizedExcelReader / LocalizedKeyPickerWindow / LocalizationSettings / SensitiveWordWindow
├── BT/ # 行为树可视化编辑器(IMGUI 画布,10 个文件)
├── DataEditor/ # 配置数据编辑器(44 个文件 + FrameworkTemplates/)
├── Loc/Editor/ # Key 使用扫描(LocaleKeyUsageWindow)
└── Dlls/ # NPOI / SharpZipLib / BouncyCastle(Excel 导入依赖,仅编辑器)
欢迎 Issue 与 PR。提交前请运行编辑器菜单 HYC Framework / Tools / Validate Config 与行为树校验,确保配置结构体 blittable、行为树无孤立节点。
本项目以 MIT 许可证 开源,详见 LICENSE。