Gitlon

TEngine 阅读笔记 ​

阅读对象：Alex-Rachel/TEngine main 分支。
阅读时间：2026-06-28。
说明：本笔记基于 GitHub README、Books/ 文档目录、关键目录树和核心源码页面阅读；未本地克隆完整仓库，未使用 Unity 打开项目，未构建或运行。

1. 一句话结论 ​

TEngine 是一套面向商业 Unity 项目的客户端开发框架：它把热更新、资源管理、配置表、UI、事件、流程、对象池、FSM、音频、本地化和调试能力预先拼成一套可直接落地的项目底座。

它的重点不是提供单个轻量库，而是提供一套“Unity 项目工程化模板”：主包启动、HybridCLR 热更、YooAsset 资源生命周期、Luban 配置生成、业务热更入口和编辑器工具链一起交付。

2. 它想解决什么问题 ​

Unity 商业项目常见的重复工程问题包括：

  1. 热更新链路难统一。
  2. 资源加载和释放容易散落在业务层。
  3. 配置表生成、协议和客户端代码容易各自为政。
  4. UI 生命周期、事件解绑、对象池、流程状态机需要每个项目重做。
  5. 新团队成员很难快速理解启动流程和资源约定。

TEngine 的做法是把这些问题收敛到固定目录、固定模块和固定启动流程中。业务代码可以按框架约定写在 GameScripts/HotFix，框架能力集中在 Assets/TEngine，配置和工具链放在仓库根部的 Configs、Tools、BuildCLI。

3. 项目结构 ​

仓库根目录的分层比较清楚：

text
Books/                 文档和模块说明
BuildCLI/              构建相关入口
Configs/GameConfig/    Luban 配置表定义、数据、生成脚本
Tools/                 FileServer、Luban、事件代码生成器等工具
UnityProject/          Unity 工程主体

Unity 工程内的重点目录：

text
UnityProject/Assets/
  AssetArt/            美术资源
  AssetRaw/            热更资源
  Editor/              项目编辑器脚本
  GameScripts/         游戏侧代码
  Launcher/            启动场景相关资源
  Plugins/             第三方插件
  Scenes/              场景
  TEngine/             框架核心

Assets/TEngine 又分成：

text
TEngine/
  Editor/              框架编辑器工具
  Extension/           框架扩展
  Libraries/           依赖库
  Runtime/             运行时代码
  Settings/            框架配置资产

运行时核心在 Runtime：

text
Runtime/
  Core/                ModuleSystem、异常、日志、工具类等基础设施
  Extension/           Json、Material、Tween 等扩展
  Module/              Audio、Resource、Procedure、UI、FSM 等模块

4. 启动路径 ​

主程序入口是 UnityProject/Assets/GameScripts/GameEntry.cs。

GameEntry.Awake() 里做了几件关键事：

  1. 通过 ModuleSystem.GetModule<T>() 初始化 IUpdateDriver、IResourceModule、IDebuggerModule、IFsmModule。
  2. 调用 Settings.ProcedureSetting.StartProcedure().Forget() 启动流程系统。
  3. DontDestroyOnLoad(this) 保持入口对象跨场景存在。

README 中给出的商业化流程是：

text
ProcedureLaunch
  -> ProcedureSplash
  -> ProcedureInitPackage
  -> ProcedurePreload
  -> ProcedureInitResources
  -> ProcedureUpdateVersion
  -> ProcedureUpdateManifest
  -> ProcedureCreateDownloader
  -> ProcedureDownloadFile
  -> ProcedureDownloadOver
  -> ProcedureClearCache
  -> ProcedureLoadAssembly
  -> ProcedureStartGame

这说明 TEngine 把启动流程设计成显式状态链。资源包初始化、版本检查、Manifest 更新、下载、清缓存、加载热更程序集、进入游戏逻辑都被拆成独立 Procedure。

5. 模块系统 ​

核心模块管理在 UnityProject/Assets/TEngine/Runtime/Core/ModuleSystem.cs。

它的核心设计很直接：

  1. 所有模块继承 Module。
  2. 外部按接口取模块，例如 GetModule<IResourceModule>()。
  3. 默认按命名约定从接口名推导实现类：IResourceModule 对应 ResourceModule。
  4. 模块用 Activator.CreateInstance 延迟创建。
  5. 模块按 Priority 插入链表。
  6. 实现 IUpdateModule 的模块会进入更新列表。
  7. Shutdown() 按反向顺序关闭模块，并清理内存池和 Marshal 缓存。

这个设计的优点是模块接入成本低，调用侧只依赖接口。代价是实现类命名和程序集位置需要遵守约定，否则运行时才会暴露错误。

6. 热更分层 ​

业务热更代码在 UnityProject/Assets/GameScripts/HotFix。

当前结构里主要有：

text
HotFix/
  GameLogic/
    IEvent/
    Module/
    SingletonSystem/
    UI/
    GameApp.cs
    GameModule.cs
  GameProto/

GameApp.cs 是热更域入口。Entrance(object[] objects) 会：

  1. 初始化 GameEventHelper。
  2. 接收主工程传入的热更程序集列表。
  3. 注册 Unity 销毁监听，在销毁时释放 SingletonSystem。
  4. 启动业务逻辑，目前示例中展示 BattleMainUI。

文件里还有 ENABLE_OBFUZ 条件编译，说明热更入口会配合 Obfuz 做混淆兼容处理，避免入口类名或方法名被破坏。

7. 核心模块画像 ​

从 README 和目录看，TEngine 的核心模块主要包括：

  • ResourceModule：基于 YooAsset，覆盖编辑器模拟、离线和远端模式，提供资源引用、资源组、LRU/ARC 缓存策略和同步/异步加载。
  • GameEvent：事件系统，强调低 GC，支持 string/int 事件 ID，UI 生命周期可自动清理绑定。
  • UIModule：纯 C# UI 管理，脱离 Mono 生命周期，支持 UIWindow / UIWidget 分层和代码生成。
  • ConfigSystem：集成 Luban，支持懒加载、异步加载、同步加载和本地化。
  • ProcedureModule：承载启动、更新、下载、加载程序集、进入游戏的流程状态机。
  • ObjectPoolModule / MemoryPool：把对象复用和内存管理框架化。
  • FsmModule、TimerModule、AudioModule、LocalizationModule、SceneModule：补齐常见游戏客户端基础能力。

整体上，它更像一个“完整客户端脚手架”，不是只关注某一层的库。

8. 工具链 ​

Tools/ 目录包含：

text
FileServer/
GameEventSourceGenerator/
Luban/
build-luban.bat
build-luban.sh

Configs/GameConfig/ 包含：

text
CustomTemplate/
Datas/
Defines/
gen_code_bin_to_project.*
gen_code_bin_to_project_lazyload.*
gen_code_bin_to_server.*
luban.conf

这条线说明配置表不是运行时附属功能，而是项目工程流程的一部分：表结构、数据、模板、客户端代码、二进制数据和服务端导出都放在仓库里统一管理。

9. AI 工作流 ​

README 明确提到 TEngine 内置面向 Claude Code 的 AI 开发工作流，核心是：

  1. 用 tengine-dev skill 查询模块规范。
  2. 按任务等级决定查单主题、多主题还是直接改。
  3. 用会话缓存避免重复读规范。
  4. 当规范和源码冲突时，以源码为准并记录冲突。

这部分比较特别：它不是单纯写一份 AGENTS.md，而是把 AI 使用方式作为框架文档和开发流程的一部分。对大型 Unity 项目来说，这能降低 agent 误读框架约定的概率。

10. 适合的场景 ​

TEngine 更适合：

  1. 需要热更新、远端资源和配置表体系的商业 Unity 项目。
  2. 希望直接沿用一套完整工程结构的小团队。
  3. 需要快速搭起客户端底座，而不是从零拼 HybridCLR、YooAsset、Luban、UI、事件、流程系统。
  4. 愿意接受框架约定，并围绕这些约定写业务代码的团队。

不太适合：

  1. 只想要一个轻量工具库的项目。
  2. 已经有成熟工程体系，只需要局部替换资源或 UI 模块的项目。
  3. 不想引入 HybridCLR、YooAsset、Luban 等完整链路的简单 Demo。

11. 阅读后的判断 ​

TEngine 的价值在“集成度”和“项目模板化”，不是某个单点算法特别复杂。它把 Unity 商业项目里最容易反复踩坑的启动、热更、资源、配置、UI 和事件管理都放进固定流程。

代码层面最值得先读三条线：

  1. GameEntry 到 Procedure*：理解主工程如何启动和进入热更。
  2. ModuleSystem 到各 Runtime/Module/*：理解框架服务如何注册、更新和关闭。
  3. HotFix/GameLogic/GameApp 到 UI/事件/业务模块：理解热更域如何接管业务。

如果后续要实际接入，优先验证 Unity 版本、第三方插件、HybridCLR 生成步骤、YooAsset 包构建、Luban 表生成和目标平台热更流程。只读源码还不足以判断这些链路在本地环境是否可以一次跑通。

12. 参考入口 ​

基于 VitePress 的个人知识库骨架

Copyright © 2026 GitLon