游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载TEngine 使用 Luban 作为游戏配置表Excel 定义、数据、类型与模板的生成与导出工具本篇文章围绕 luban-config.md 这份配置集成路由规范系统梳理配置源目录、luban.conf注册表、普通/懒加载两种导出模式、ConfigSystem运行时加载器、分片导出契约与二进制兼容性约束并给出配置变更从预检、生成到验证的闭环工作流。读完你可以准确回答配置放哪里、表怎么注册、怎么导出、运行时怎么加载、改字段要注意什么这一整条链路的问题并直接在仓库现有脚本与模板基础上落地操作。一、集成路由总览一条命令源一套生成目标TEngine 的配置集成遵循一个核心约定配置的维护入口只有一个即 luban-dev 技能文档它负责配置数据、类型、表注册、模板与导出的全部命令tengine-dev 的 luban-config.md 只负责说明路由与边界不在该处维护第二套命令避免两处命令漂移导致的不可复现问题。具体路由为配置源数据输入仓库根目录的Configs/GameConfig即从 Unity 项目出发的../Configs/GameConfig生成目录代码输出Unity 项目的Assets/GameScripts/HotFix/GameProto/GameConfig生成的 C# 表类与Tables管理器二进制数据输出Assets/AssetRaw/Configs/bytes供 YooAsset 收集、加载。需要特别强调两点边界这也是原文档的核心约束GameProto不能反向引用GameLogic.GameModule。生成的配置加载器模板通过ModuleSystem.GetModuleIResourceModule()获取资源模块而不是依赖业务侧的游戏模块保证配置程序集可以在热更业务GameLogic之外独立编译与加载ConfigSystem.cs是模板复制产物。它由导出脚本从Configs/GameConfig/CustomTemplate/ConfigSystem.cs复制到GameProto目录当前工作区未导出时该文件可能不存在不能宣称其已初始化或可运行。二、配置源目录结构解读先看配置源Configs/GameConfig的真实布局均已在仓库中确认存在路径角色Configs/GameConfig/luban.confLuban 项目配置分组、Schema、数据目录、导出目标Configs/GameConfig/Datas/__beans__.xlsxBean结构体定义表Configs/GameConfig/Datas/__enums__.xlsx枚举定义表Configs/GameConfig/Datas/__tables__.xlsx表注册表声明每张业务表及其 input/mode/indexConfigs/GameConfig/Datas/item.xlsx业务数据表示例物品表Configs/GameConfig/Defines/builtin.xml内置类型与 Unity 外部类型映射vector2/3/4 等Configs/GameConfig/CustomTemplate/ConfigSystem.cs客户端加载器模板复制产物Configs/GameConfig/CustomTemplate/ExternalTypeUtil.cs外部类型转换工具模板Configs/GameConfig/CustomTemplate/CustomTemplate_Client_LazyLoad/lazyload 模式的自定义模板目录Configs/GameConfig/gen_code_bin_to_project.bat/.shstandard普通 bin导出脚本Configs/GameConfig/gen_code_bin_to_project_lazyload.bat/.shlazyload懒加载 分片导出脚本Configs/GameConfig/gen_code_bin_to_server.bat/.sh服务端导出脚本从源码结构看__tables__.xlsx、__beans__.xlsx、__enums__.xlsx属于定义表不按业务行表的列格式处理详见 excel-format.md业务数据行表中##var、##type、##group等标记行的实际位置必须以现有 workbook 为准不要假设固定前四行。三、luban.conf注册表、分组与导出目标luban.conf是整套导出行为的总开关。仓库当前 luban.conf 全文如下{ groups: [ {names:[c], default:true}, {names:[s], default:true}, {names:[e], default:true} ], schemaFiles: [ {fileName:Defines, type:}, {fileName:Datas/__tables__.xlsx, type:table}, {fileName:Datas/__beans__.xlsx, type:bean}, {fileName:Datas/__enums__.xlsx, type:enum} ], dataDir: Datas, targets: [ {name:server, manager:Tables, groups:[s], topModule:GameConfig}, {name:client, manager:Tables, groups:[c], topModule:GameConfig}, {name:all, manager:Tables, groups:[c,s,e], topModule:GameConfig} ] }各字段的语义与注意点依据 luban-conf.mdgroups定义c客户端、s服务端、e编辑器/通用三个分组均带default: true。分组控制导出时的字段/表选择新增字段和表都要检查其对客户端/服务端的影响不要把c,s字符串与[c,s]数组机械互换语义不同。schemaFilesSchema 输入混合了DefinesXML 目录与三张 Excel 定义表fileName与typetable/bean/enum必须与实际文件相符。项目中还混用了 Defines/builtin.xml 定义的内置类型新增类型前先确认是否已在另一来源定义避免重复定义与命名空间漂移见 schema.md。dataDir数据目录指向Datas。targets导出目标。name用作命令行-t参数manager统一为Tables客户端topModule为GameConfig对应生成的命名空间。扩展参数当前 Luban 版本的LubanConfig.Xargs是字符串列表不使用旧文档中的对象数组示例-x keyvalue形态见下文导出脚本。作为最小合法结构参考仓库提供了回归用配置 examples/regression/luban.conf单分组c、单目标client它是测试 fixture不可覆盖生产注册表。四、两种导出模式lazyload 与 standardTEngine 支持两种客户端导出模式对应四份脚本。二者都写入Assets/GameScripts/HotFix/GameProto代码与Assets/AssetRaw/Configs/bytes数据差异如下依据 tengine-integration.md 的模式对照模式脚本产物特征lazyloadgen_code_bin_to_project_lazyload.bat/.shcs-bin 代码 分片数据skill 文档声明使用bin-sharded、dataExportersharded搭配自定义懒加载模板表按需加载standardgen_code_bin_to_project.bat/.shcs-bin 代码 普通bin数据标准Tables构造即加载lazyload复用分片导出与自定义模板standard必须显式选择它不是分片模式失败时的故障回退。以 gen_code_bin_to_project_lazyload.sh 为例脚本先固定自身目录随后把模板复制到生成目录再调用 Lubancd $(dirname $0) export WORKSPACE$(realpath ../../) export LUBAN_DLL${WORKSPACE}/Tools/Luban/Luban.dll export CONF_ROOT$(pwd) export DATA_OUTPATH${WORKSPACE}/UnityProject/Assets/AssetRaw/Configs/bytes/ export CODE_OUTPATH${WORKSPACE}/UnityProject/Assets/GameScripts/HotFix/GameProto/GameConfig/ # 模板复制ConfigSystem / ExternalTypeUtil 进入 GameProto cp -R ${CONF_ROOT}/CustomTemplate/ConfigSystem.cs \ ${WORKSPACE}/UnityProject/Assets/GameScripts/HotFix/GameProto/ConfigSystem.cs cp -R ${CONF_ROOT}/CustomTemplate/ExternalTypeUtil.cs \ ${WORKSPACE}/UnityProject/Assets/GameScripts/HotFix/GameProto/ExternalTypeUtil.cs dotnet ${LUBAN_DLL} \ -t client \ -c cs-bin \ -d bin \ --conf ${CONF_ROOT}/luban.conf \ --customTemplateDir ${CONF_ROOT}/CustomTemplate/CustomTemplate_Client_LazyLoad \ -x code.lineEndingcrlf \ -x outputCodeDir${CODE_OUTPATH} \ -x outputDataDir${DATA_OUTPATH}各参数在项目中的用法依据 command-reference.md参数本项目用法--confluban.conf路径相对脚本固定的 cwd-tclient服务端需走独立脚本/范围-ccs-binC# 二进制读取代码-dbin或bin-sharded分片二进制--customTemplateDirlazyload 的自定义模板目录standard 脚本不传-xoutputCodeDir、outputDataDir、code.lineEnding、dataExporter等扩展参数--validationFailAsError验证失败策略禁止为了放过错误而关闭注意事项lazyload 的.bat版本在命令末尾有if not defined AI_MODE pause即自动化设置了AI_MODE时不暂停、保留失败返回码交互运行则暂停等待查看不要把 Git Bash 的cmd //c写法搬进 PowerShell。另外-o不是通用输出目录它是outputTable参数仅生成代码、零输出或 watcher 启动成功都不等于导表完成。五、运行时加载器ConfigSystem 模板与模块边界运行时加载模板 ConfigSystem.cs 是理解配置怎么进内存的关键。其核心实现using Luban; using GameConfig; using TEngine; using UnityEngine; public class ConfigSystem { private static ConfigSystem _instance; public static ConfigSystem Instance _instance ?? new ConfigSystem(); private bool _init false; private Tables _tables; public Tables Tables { get { if (!_init) Load(); return _tables; } } private IResourceModule _resourceModule; public void Load() { _tables new Tables(LoadByteBuf); _init true; } private ByteBuf LoadByteBuf(string file) { if (_resourceModule null) { _resourceModule ModuleSystem.GetModuleIResourceModule(); } TextAsset textAsset _resourceModule.LoadAssetTextAsset(file); byte[] bytes textAsset.bytes; return new ByteBuf(bytes); } }从源码可提取出四个关键事实懒加载语义Tables首次被访问时才触发Load()_init惰性置位Tables构造时传入LoadByteBuf回调由生成的表类按需读取二进制文件相关读取基础见 ByteBuf.cs。普通生成standard模式则是在构造Tables时即加载全部表。模块获取方式加载器通过ModuleSystem.GetModuleIResourceModule()获取资源模块ModuleSystem.cs 的GetModuleT泛型入口这正是原文档强调的GameProto不能反向引用GameLogic.GameModule的落地体现。这也意味着ConfigSystem依赖ResourceModule已初始化相关用法可对照 ResourceExtComponent.Resource.cs 中对IResourceModule的获取模式。加载走 YooAssetLoadAssetTextAsset(file)通过资源模块加载配置 bytes而不是Resources.Load。数据文件由AssetRaw/Configs/bytes进入 AssetBundle/收集器体系。当前集成限制模板加载TextAsset后未释放。ClearPartitions只清除分片与路由索引的托管缓存不代表 YooAsset 已卸载。原文档明确要求修改所有权需单独测试不以文档保证已释放来掩盖这一现状详见 runtime.md 的运行时约束。外部类型映射builtin.xml ExternalTypeUtil配置表里常用的vector2/3/4等类型会映射为 Unity 的Vector2/3/4。映射定义在 Defines/builtin.xmlbean namevector2 valueType1 sep, var namex typefloat / var namey typefloat / mapper targetclient codeTargetcs-bin,cs-simple-json,cs-newtonsoft-json option nametype valueUnityEngine.Vector2 / option nameconstructor valueExternalTypeUtil.NewVector2 / /mapper /bean构造转换由模板 ExternalTypeUtil.cs 提供例如NewVector2(GameConfig.vector2 v)返回new Vector2(v.X, v.Y)vector3int映射到Vector3Int等。注意vector3int在 XML 中的目标类型写的是UnityEngine.Vector3与NewVector3Int的构造器并不一致——这类不一致恰恰印证了源类型名不保证等于 C# 类型见 type-system.md一切以当前 cs-bin 生成结果为准不要在游戏代码里新建同名类型替代官方映射。六、分片导出契约field / range / count当单表数据量过大时lazyload 模式支持按分片策略导出tags 语法partition...支持三种形式partitionfield#partition_fieldlevelId partitionrange#partition_fieldid#partition_size1000 partitioncount#partition_fieldid#partition_size1000契约要点依据 tengine-integration.md 的分片契约章节分片字段必须是导出的非空 int/long禁止负值range/count的 map 主键必须就是分片字段range从 key 直接计算分片count先排序后分组并维护路由 index插入早期 key 可能使后续分片重排field适合按关卡聚合的 list 表示例复合索引levelIdwaveIdfield表不能作为生成 ref 的目标因为仅凭行 key 无法推导分片归属生成 API 以实际表名为准field通过LoadTbXPartition(key)显式取表range/count通过 accessor 保留 key 查询再用对应ReleaseTbXPartition释放ClearPartitions清除分片与路由索引的托管缓存不清普通懒加载表也不自动释放 YooAsset 句柄。原文档特别强调普通与分片生成的 API 不同先读生成类不编造当前未生成的表成员——例如仓库当前并未生成TbItem、LoadTbWavePartition等成员当前GameProto/GameConfig生成目录未导出GameProto下仅有LubanLib任何引用这些 API 的写法都属于臆造。七、兼容性与版本约束二进制布局即契约配置的二进制读取依赖生成代码的行布局cs-bin 逐行反序列化由此导出几条硬性约束字段的增、删、改名、重排都必须让代码与数据版本同步匹配。新增字段也不能无条件宣称天然前向兼容旧客户端——旧代码按旧布局读新数据或反之都会错位代码、数据、分片策略、模板与路由 index 要作为同版本产物一起验证普通/分片切换属于显式决策不是自动降级表内引用ref可能延迟建立访问生成属性前检查 null 与跨分片引用行为热更发布前必须验证代码、bytes 与 index 同版本发布与缓存淘汰需要独立授权。校验应分四层递进依据 validators.mdhelper 预检 → Luban 生成校验Schema、主键、类型、ref/range/size→ 产物校验C#、bytes、分片/index、模板复制→ 运行时校验加载、边界、资源归属。前一层通过不替代后一层int#range[1,99]、string#refTbItem这类约束必须配套真实目标表与数据验证。YooAsset 地址能否加载要回到项目收集器与 Editor 验证不能把通用 path validator 当作资源系统等价验证。八、配置变更的闭环工作流配置改动不是改 Excel 后直接导这么简单skill 文档给出了一条带确认闸门的闭环见 luban-dev/SKILL.md读先读表注册、字段、数据和引用确认输入结构避免按关键词推断客户端/服务端分组改通过 helper 展示要修改的记录、字段与引用影响得到集中确认删除/重命名需单独说明兼容性影响校验helper 预检luban_helper.py真实--help为准缺 openpyxl 时阻塞不自动安装隔离验证工作流在隔离目录用当前 Luban 校验并导出不写生产产物预览与授权preview审查脚本/写入目标确认后approvehigh-risk再apply测试导出后检查产物模式、模板复制与数量再执行完整解决方案构建、Editor 编译与运行测试。从 Unity 项目执行 helper 的常用命令依据 operating-guide.mdpython .codex/skills/luban-dev/scripts/luban_helper.py --help python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table list python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas table get registered-name python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas field list registered-name python .codex/skills/luban-dev/scripts/luban_helper.py --data-dir ../Configs/GameConfig/Datas ref bean-or-enum操作纪律均为 skill 文档明确约定--data-dir在子命令之前写入字段显式给出 grouphelper 的关键词推断不是业务分组依据row update/delete的行索引不是默认的主键值删除 Bean/枚举先查 ref禁止用 force 忽略引用复杂/多行 Bean 表头不要使用假定单行扁平结构的 CRUDhelper 是低层编辑器而非事务服务其成功输出不能当完整业务校验操作后的源文件 diff、校验和导出证据一并交付。九、集成路由要点速查关注点结论维护入口只有 luban-dev/SKILL.md不维护第二套命令配置源 / 生成目录Configs/GameConfig→UnityProject/Assets/GameScripts/HotFix/GameProto/GameConfigUnityProject/Assets/AssetRaw/Configs/bytes程序集边界GameProto不引用GameLogic.GameModule加载器用ModuleSystem.GetModuleIResourceModule()模板复制ConfigSystem.cs/ExternalTypeUtil.cs由导出脚本复制未导出时不存在资源所有权模板加载 TextAsset 未释放ClearPartitions仅清托管缓存不等于 YooAsset 卸载二进制兼容行布局即契约字段增删改排需代码/数据版本匹配不宣称天然前向兼容生成 API普通/分片 API 不同先读生成类不编造TbItem、LoadTbWavePartition等未生成成员变更闭环读 → 确认 → helper 预检 → 隔离校验 → preview/approve/apply → 构建与运行测试整体来看TEngine 的 Luban 配置集成是一套源数据单一、路由清晰、边界严格的工程化方案数据维护、Schema 注册、导出脚本、加载模板四者各司其职而 tengine-dev/luban-config.md 就是这条链路的导航图。实际动手前建议先完整阅读 luban-dev 技能文档 及其 集成说明并以仓库当前生成产物与脚本参数为唯一事实依据。赞分享游戏开发【免费下载链接】TEngineUnity 商用级别开发框架原生内置 AI 工作流支持集成 HybridCLR 高性能热更、Obfuz 代码混淆加固、YooAssets 企业级资源管理方案构建高效、安全、可扩展的工业化开发底座。项目地址https://gitcode.com/gh_mirrors/teng/TEngine点击查看免费下载相关推荐TEngine 中 Luban 配置生成、表分片与加载器集成实战指南TEngine 中 Luban 配置生成、表分片与加载器集成实战指南 TEngine 仓库将 Luban 游戏配置的源数据定义、生成导出、运行时加载整理为一游戏开发TEngine Luban 四层校验体系从 Schema 到运行时的配置正确性保障实战TEngine Luban 四层校验体系从 Schema 到运行时的配置正确性保障实战 导读 本文聚焦 TEngine 项目中 Luban 配置系统的校游戏开发Umi 使用 Vue从安装预设到路由与运行时配置的完整指南Umi 使用 Vue从安装预设到路由与运行时配置的完整指南 本篇指南以 Umi 官方文档 use vue.en US.md https://link.gitc前端Web框架前端构建构建工具插件系统上一篇SVGR革命将SVG转化为React组件的终极工具指南下一篇如何在本地高效处理音频转录Buzz离线AI工具完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考