Skip to content

README.md

Latest commit

 

History

History
506 lines (364 loc) · 17.7 KB

README.md

File metadata and controls

506 lines (364 loc) · 17.7 KB

TEngine

TEngine Logo

Unity 框架解决方案

Unity Version License Last Commit Issues Top Language DeepWiki

📖 简介

TEngine 是一个简单（新手友好、开箱即用）且强大的 Unity 框架全平台解决方案。对于需要一套上手快、文档清晰、高性能且可拓展性极强的商业级解决方案的开发者或团队来说，TEngine 是一个很好的选择。

✨ 核心特性

  • 🚀 开箱即用 - 5 分钟即可上手整套开发流程，代码整洁，思路清晰
  • 🔥 高性能 - 基于 UniTask 的异步系统，零 GC 事件分发，严格的内存管理
  • 🧩 高内聚低耦合 - 模块化设计，可轻松移除或替换不需要的模块
  • 🔄 热更新支持 - 集成 HybridCLR，全平台热更新流程已跑通
  • 📦 资源管理 - 集成 YooAsset，支持 LRU、ARC 缓存策略，自动资源释放
  • 📊 配置表系统 - 集成 Luban，支持懒加载、异步加载、同步加载
  • 🎨 UI 框架 - 商业化 UI 开发流程，支持代码自动生成
  • 🌍 全平台支持 - Windows、Android、iOS、WebGL、微信小游戏等

📚 目录

🚀 快速开始

环境要求

  • Unity 版本: 2021.3.20f1c1（推荐）或更高
  • 支持版本: Unity 2019.4 / 2020.3 / 2021.3 / 2022.3
  • 开发环境: .NET 4.x
  • 支持平台: Windows、OSX、Android、iOS、WebGL

快速上手

  1. 克隆项目

    git clone https://github.com/ALEXTANGXIAO/TEngine.git

  2. 打开项目

    • 使用 Unity 2021.3.20f1c1 打开项目

  3. 编辑器模式运行

    • 选择顶部栏目 EditorMode 编辑器下的模拟模式
    • 点击 Launcher 开始运行

  4. 打包运行（热更新流程）

    • 运行菜单 HybridCLR/Install... 安装 HybridCLR
    • 运行菜单 HybridCLR/Define Symbols/Enable HybridCLR 开启热更新
    • 运行菜单 HybridCLR/Generate/All 进行必要的生成操作
    • 运行菜单 HybridCLR/Build/BuildAssets And CopyTo AssemblyPath 生成热更新 DLL
    • 运行菜单 YooAsset/AssetBundle Builder 构建 AB
    • 打开 Build Settings，点击 Build And Run

💡 提示: 遇到问题请查看 HybridCLR 常见错误

详细教程请参考：快速开始指南

🤖 AI 开发工作流

TEngine 深度集成了一套面向 Claude Code 的 AI 辅助开发工作流。通过 tengine-dev skill 按需查询架构、任务等级分级触发和会话内缓存机制，实现了规范驱动、高效的 AI 开发体验。

核心工具

工具 用途
tengine-dev Claude Code 专用 TEngine 开发技能，从 references/ 提供全模块规范
Unity-MCP Unity Editor 自动化操作（场景、资源、脚本）
openspec 规范驱动的变更管理
wiki-synchelper Wiki 文档同步助手（手动触发时使用）

整体工作流总览

flowchart TD
    A([用户发起任务]) --> B{判断任务等级}

    B -->|L1 简单\ntypo/注释/日志| C[直接编写代码]
    B -->|L2 调用\n单一 API 修改| D[触发 tengine-dev skill\n只查该主题]
    B -->|L3 功能\n新功能/跨文件| E[触发 tengine-dev skill\n全量相关主题]
    B -->|L4 架构\n系统设计/重构| F[触发 tengine-dev skill\n并行多主题]

    D --> G{会话缓存命中?}
    E --> G
    F --> G

    G -->|命中| H[复用已有规范摘要]
    G -->|未命中| I[skill 读取 references/\n提炼规范指引]

    I --> L[输出代码/方案]
    H --> L
    C --> L

    L --> M{规范与代码冲突?}
    M -->|有冲突| N[标注冲突点\n记录到 .claude/memory/]
    M -->|无冲突| O([任务完成])
    N --> O
Loading

时序图一：规范获取流程

核心优势：tengine-dev skill 直接从精炼的 references/ 文档提取规范，无多余上下文噪声。

sequenceDiagram
    participant U as 用户
    participant M as 主 Agent (Claude)
    participant S as tengine-dev (skill)
    participant R as references/

    U->>M: 请实现背包 UI
    Note over M: 判断等级: L3 功能
    M->>S: 触发 skill<br/>查询: UIWindow规范 + 资源管理规范

    activate S
    S->>R: 读取 ui-development.md
    S->>R: 读取 resource-management.md
    S->>R: 读取 event-system.md
    Note over S: 提炼关键规范指引
    S-->>M: 返回规范摘要
    deactivate S

    M-->>U: 输出符合规范的代码
Loading

时序图二：会话内缓存机制

核心优势：同一会话中相同主题只查询一次，后续任务直接复用，避免重复消耗。

sequenceDiagram
    participant U as 用户
    participant M as 主 Agent
    participant S as tengine-dev skill
    participant C as 会话缓存

    U->>M: 任务①: 实现登录界面 UI
    M->>S: 查询 UIWindow 规范
    S-->>M: 返回 UIWindow 规范摘要
    M->>C: 缓存: UIWindow 规范 ✅
    M-->>U: 输出登录界面代码

    U->>M: 任务②: 实现设置界面 UI
    M->>C: 检查缓存: UIWindow 规范
    C-->>M: 命中缓存 ✅ 直接复用
    Note over M: 无需重复触发 skill<br/>零等待，零额外消耗
    M-->>U: 输出设置界面代码

    U->>M: 任务③: 设置界面添加音效按钮
    M->>C: 检查缓存: UIWindow ✅ / Audio ❌
    C-->>M: UIWindow 命中，Audio 未命中
    M->>S: 仅补充查询 AudioModule 规范
    S-->>M: 返回 Audio 规范摘要
    M->>C: 缓存: Audio 规范 ✅
    M-->>U: 输出音效按钮代码
Loading

时序图三：并行多主题查询（L4 架构任务）

核心优势：架构级任务并行查询多个主题，汇总后统一决策，大幅减少串行等待。

sequenceDiagram
    participant U as 用户
    participant M as 主 Agent
    participant S1 as tengine-dev #1
    participant S2 as tengine-dev #2
    participant S3 as tengine-dev #3

    U->>M: 设计战斗系统架构<br/>涉及: UI + 事件 + FSM + 资源

    Note over M: 判断等级: L4 架构<br/>并行触发多主题查询

    par 并行查询
        M->>S1: 查询 UIWindow + UIWidget 规范
        M->>S2: 查询 GameEvent 事件系统规范
        M->>S3: 查询 FSM 状态机 + 资源加载规范
    end

    S1-->>M: UI 规范摘要
    S2-->>M: 事件系统摘要
    S3-->>M: FSM + 资源摘要

    Note over M: 汇总三份摘要<br/>统一架构决策
    M-->>U: 输出完整战斗系统架构方案
Loading

时序图四：规范冲突处理

核心优势：AI 主动检测 references 与代码的不一致，标注冲突并记录，以代码实现为最终依据。

sequenceDiagram
    participant M as 主 Agent
    participant S as tengine-dev skill
    participant Code as 项目代码
    participant Mem as .claude/memory/

    M->>S: 查询某 API 规范
    S-->>M: references 描述: API_X(param1, param2)

    M->>Code: 读取实际代码实现
    Code-->>M: 实际签名: API_X(param1, param2, param3)

    Note over M: 检测到冲突!<br/>references 描述与代码不符

    M->>Mem: 记录 problem_YYYY-MM-DD.md<br/>冲突详情 + 分析

    Note over M: 以代码实现为准<br/>在输出中标注差异

    M-->>U: 输出代码，并标注冲突点
Loading

工作流快速参考

┌─────────────────────────────────────────────────────────┐
│                   TEngine AI 工作流                      │
├─────────────────────────────────────────────────────────┤
│  Step 0  判断任务等级 L1/L2/L3/L4                        │
│  Step 1  L1 直接编码                                     │
│         L2-L4 触发 tengine-dev skill 获取规范            │
│         （会话内缓存命中则直接复用，无需重复触发）        │
│  Step 2  基于规范输出代码/方案                            │
│  Step 3  若规范与代码冲突，标注冲突，记录到 .claude/memory/│
└─────────────────────────────────────────────────────────┘

详细规范请参考：CLAUDE.md | AI 开发工作流指南

📚 文档导航

基础文档

文档 描述
📖 介绍 TEngine 框架介绍与核心特性
🏗️ 框架概览 框架架构与设计理念
🚀 快速开始 5 分钟快速上手教程
🌍 全平台运行 各平台运行截图展示
🤖 AI 开发工作流 openspec + tengine-dev AI 开发指南

核心模块文档

模块 文档 描述
📦 资源模块 3-1-资源模块 YooAsset 资源管理，支持 LRU/ARC 缓存
🎯 事件模块 3-2-事件模块 零 GC 事件系统，支持 MVE 架构
💾 内存池模块 3-3-内存池模块 轻量级内存池管理
🎮 对象池模块 3-4-对象池模块 游戏对象池管理
🎨 UI 模块 3-5-UI模块 商业化 UI 框架，支持代码生成
📊 配置表模块 3-6-配置表模块 Luban 配置表系统
🔄 流程模块 3-7-流程模块 商业化启动流程
🌐 网络模块 3-8-网络模块 网络通信模块

🧩 核心模块

资源模块 (ResourceModule)

  • ✅ 基于 YooAsset 的资源管理系统
  • ✅ 支持 EditorSimulateMode、OfflinePlayMode、HostPlayMode
  • ✅ AssetReference 资源引用标识，自动管理资源生命周期
  • ✅ AssetGroup 资源组管理
  • ✅ LRU/ARC 缓存策略
  • ✅ 同步/异步加载支持

事件模块 (GameEvent)

  • ✅ 零 GC 事件系统
  • ✅ 支持 string/int 事件 ID
  • ✅ 支持 MVE（Model-View-Event）架构
  • ✅ UI 生命周期自动绑定事件清理

UI 模块 (UIModule)

  • ✅ 纯 C# 实现，脱离 Mono 生命周期
  • ✅ 代码自动生成工具
  • ✅ UIWindow/UIWidget 分层设计
  • ✅ 支持全屏面板管理
  • ✅ 事件驱动架构

配置表模块 (ConfigSystem)

  • ✅ 集成 Luban 配置表解决方案
  • ✅ 支持懒加载、异步加载、同步加载
  • ✅ 强大的数据校验能力
  • ✅ 完善的本地化支持

流程模块 (ProcedureModule)

完整的商业化启动流程：

  • ProcedureLaunch → ProcedureSplash → ProcedureInitPackage
  • ProcedurePreload → ProcedureInitResources
  • ProcedureUpdateVersion → ProcedureUpdateManifest
  • ProcedureCreateDownloader → ProcedureDownloadFile
  • ProcedureDownloadOver → ProcedureClearCache
  • ProcedureLoadAssembly → ProcedureStartGame

📁 项目结构

Assets/
├── AssetArt/              # 美术资源目录
│   └── Atlas/            # 自动生成图集目录
├── AssetRaw/             # 热更资源目录
│   ├── UIRaw/            # UI 图片目录
│   │   ├── Atlas/        # 需要自动生成图集的 UI 素材目录
│   │   └── Raw/          # 不需要自动生成图集的 UI 素材目录
│   ├── Audios/           # 音频资源
│   ├── Effects/          # 特效资源
│   └── Scenes/           # 场景资源
├── Editor/               # 编辑器脚本目录
├── HybridCLRData/        # HybridCLR 相关目录
├── Scenes/               # 主场景目录
├── TEngine/              # 框架核心目录
│   ├── Editor/           # TEngine 编辑器核心代码
│   ├── Runtime/          # TEngine 运行时核心代码
│   └── AssetSetting/     # YooAsset 资源设置
└── GameScripts/          # 程序集目录
    ├── Main/             # 主程序程序集（启动器与流程）
    └── HotFix/           # 游戏热更程序集目录
        ├── GameBase/     # 游戏基础框架程序集 [Dll]
        ├── GameProto/    # 游戏配置协议程序集 [Dll]
        └── GameLogic/    # 游戏业务逻辑程序集 [Dll]
            ├── GameApp.cs                  # 热更主入口
            └── GameApp_RegisterSystem.cs   # 热更主入口注册系统

💻 系统要求

Unity 版本

  • 推荐版本: Unity 2021.3.20f1c1
  • 支持版本: Unity 2019.4 / 2020.3 / 2021.3 / 2022.3

平台支持

  • ✅ Windows (Standalone)
  • ✅ macOS (Standalone)
  • ✅ Android
  • ✅ iOS
  • ✅ WebGL
  • ✅ 微信小游戏

开发环境

  • .NET 4.x
  • Visual Studio 2019+ 或 Rider

🌐 服务器支持

TEngine 本身为纯净的客户端框架，不强绑定任何服务器。但针对个人开发以及中小型公司开发双端，我们推荐使用 C# 服务器。

为什么选择 .NET Core？

.NET Core 8.0 在性能和设计上具有显著优势：

  • ⚡ 高性能 - AOT、JIT 混合编译
  • 🔧 组件化结构 - 模块化设计
  • 🔥 热重载 - 提升开发效率
  • 📈 性能测试 - 除 C++ 外，性能表现优异

服务器框架推荐

  • GameNetty - 源于 ETServer，首次拆分最新的 ET8.1 的前后端解决方案（包），客户端最精简约 750k，几乎零成本无侵入嵌入
  • Fantasy - 源于 ETServer 但极为简洁，更好上手的商业级服务器框架（Fantasy 分支已集成）

🌟 开源项目推荐

项目 描述 链接
YooAsset 商业级经历百万 DAU 游戏验证的资源管理系统 GitHub
HybridCLR 特性完整、零成本、高性能、低内存的近乎完美的 Unity 全平台原生 C# 热更方案 GitHub
Luban 最佳游戏配置解决方案 GitHub
Fantasy 源于 ETServer 但极为简洁，更好上手的商业级服务器框架 GitHub
GameNetty 源于 ETServer，首次拆分最新的 ET8.1 的前后端解决方案 GitHub
JEngine 使 Unity 开发的游戏支持热更新的解决方案 GitHub

社区 Demo

🎮 Demo 项目

最新的 Demo 飞机大战位于 demo 分支，欢迎体验！

git checkout demo

💡 为什么要使用 TEngine？

1. 开箱即用

  • ✅ 5 分钟即可上手整套开发流程
  • ✅ 代码整洁，思路清晰，功能强大
  • ✅ 高内聚低耦合，可轻松移除或替换不需要的模块

2. 商业级解决方案

  • ✅ 严格按照商业要求使用次世代的 HybridCLR 进行热更新
  • ✅ 最佳的 Luban 配置表（支持懒加载、异步加载、同步加载）
  • ✅ 百万 DAU 游戏验证过的 YooAsset 资源框架
  • ✅ 全平台热更新流程已跑通

3. 严格的内存管理

  • ✅ YooAsset 资源自动释放
  • ✅ 支持 LRU、ARC 严格管理资源内存
  • ✅ 防止内存泄漏

4. 商业化流程

  • ✅ 商业化的热更新流程
  • ✅ 商业化的 UI 开发流程
  • ✅ 商业化的资源管理

5. 全平台验证

  • ✅ 已有项目使用 TEngine 上架 Steam
  • ✅ 已有项目使用 TEngine 上架 微信小游戏
  • ✅ 已有项目使用 TEngine 上架 App Store

🤝 贡献与支持

🙏 感谢所有为 TEngine 做出贡献的开发者

Contributors

贡献

欢迎提交 Issue 和 Pull Request！

支持项目

如果 TEngine 对您有帮助，欢迎支持项目发展：

☕ 请我喝杯奶茶

您的赞助会让我们做得更快更好！如果觉得 TEngine 对您有帮助，不妨请我可爱的女儿买杯奶茶吧~ 🥤

Made with ❤️ by TEngine Team

⭐ Star | 🐛 Issues | 📖 Wiki