【Unity工具篇】| 超实用工具LuBan，快速上手使用完整教程：从入门到实战部署
最近在做项目时深入研究了这个技术点，踩了不少坑，这里整理一份完整指南分享给大家。
前言
- Unity Luban插件是一款专为游戏开发中配置管理而设计的强大工具，尤其适用于使用Unity引擎进行项目开发的团队。
- 其核心功能在于实现数据与代码的高度解耦，通过结构化的配置文件自动生成多语言代码和多种格式的数据导出，极大提升了开发效率与维护性。
- 本文来介绍一下LuBan插件的快速上手使用教程，怎样下载该插件和示例Demo，以及怎样创建一个配置表和生成配置表数据和代码数据。
【Unity工具篇】| 超实用工具LuBan，快速上手使用
一、Luban插件
1.1 介绍
luban是一个强大、易用、优雅、稳定的游戏配置解决方案。它设计目标为满足从小型到超大型游戏项目的简单到复杂的游戏配置工作流需求。
luban可以处理丰富的文件类型，支持主流的语言，可以生成多种导出格式，支持丰富的数据检验功能，具有良好的跨平台能力，并且生成极快。 luban有清晰优雅的生成管线设计，支持良好的模块化和插件化，方便开发者进行二次开发。开发者很容易就能将luban适配到自己的配置格式，定制出满足项目要求的强大的配置工具。
luban标准化了游戏配置开发工作流，可以极大提升策划和程序的工作效率。
核心特性
- 丰富的源数据格式。支持excel族(csv,xls,xlsx,xlsm)、json、xml、yaml、lua等
- 丰富的导出格式。 支持生成binary、json、bson、xml、lua、yaml等格式数据
- 增强的excel格式。可以简洁地配置出像简单列表、子结构、结构列表，以及任意复杂的深层次的嵌套结构
- 完备的类型系统。不仅能表达常见的规范行列表，由于支持OOP类型继承，能灵活优雅表达行为树、技能、剧情、副本之类复杂GamePlay数据
- 支持多种的语言。支持生成c#、java、go、cpp、lua、python、typescript 等语言代码
- 支持主流的消息方案。 protobuf(schema + binary + json)、flatbuffers(schema + json)、msgpack(binary)
- 强大的数据校验能力。ref引用检查、path资源路径、range范围检查等等
- 完善的本地化支持
- 支持所有主流的游戏引擎和平台。支持Unity、Unreal、Cocos、Godot、Laya、微信小游戏等
- 良好的跨平台能力。能在Win,Linux,Mac平台良好运行。
- 支持所有主流的热更新方案。hybridclr、ilruntime、{x,t,s}lua、puerts等
- 清晰优雅的生成管线。很容易在luban基础上进行二次开发，定制出适合自己项目风格的配置工具。
1.2 使用说明及下载
- 官方文档地址：LuBan
- LuBan地址：GitHub、Gitee
- LuBan示例项目： (github) (gitee)
- 示例工程Csharp_Unity_Json ：Csharp_Unity_Json
- CSDN下载地址：LuBan
- 白嫖地址：VX搜我博客名字，回复【素材资源】
1.3 注意事项与常见问题
- 版本注意：LuBan有Classic（旧版） 和 Next（新版） 之分，两者配置方式有差异，建议新项目直接使用Next版。
- 路径问题：确保生成的数据文件（如JSON）输出到Unity可读取的目录，例如 StreamingAssets。
- 数组分隔符：在Excel中配置数组时，避免使用英文逗号作为分隔符，可能与Excel格式冲突，建议使用 | 等符号。
二、快速上手：建表、生成配置数据
在开始使用LuBan之前，需要先了解怎样使用LuBan创建表格和生成表格配置数据及相关代码。
实际操作非常简单，学习了之后可以生成多种数据类型和代码类型。
2.1 安装
1.安装dotnet sdk 8.0或更高版本sdk
2.下载luban_examples项目。该项目中包含测试配置以及大量的示例项目。为方便起见，后续提及到的文件，默认都指这个项目中的文件
luban_examples工程介绍如下：
- DataTables 一个较复杂的用于测试的配置项目。
- MiniTemplate 一个最简单的配置模板，用于快速创建一个新的配置项目
- Projects 一些覆盖常见平台、引擎、语言的示例项目
- Tools/Luban 编译好的Luban工具程序
2.2 准备配置工程，创建Reward表
在MiniTemplate/Datas目录下创建reward.xlsx文件，内容如下：
简略介绍一下文件格式：
- 第1行是字段名行。单元格 A1 必须以##开头。表示这是一个有效数据表。
- 第2行是字段类型行。第1个单元格必须为 ##type。
- 第3行是分组行。c表示字段属于客户端，s表示属于属于服务器,c,s表示同时属于所有，留空也表示属于所有。
- 第4行是注释行。 以##开头。 可以有0-N个注释行，而且可以出现在任何位置
- 第5行起是数据行。
luban并没有限制标题头行的位置和数量。像##xxx之类的行可以任意调整顺序和位置，而##group和##行也是可选的。
在Datas目录下的__tables__.xlsx添加reward表声明，如下图：
这样就完成了一个reward表的创建工作。接下来去生成这个表的数据。
2.3 生成配置数据
直接运行MiniTemplate/gen.bat（Win平台）或MinTemplate/gen.sh(MacOS或者Linux平台)。
如果运行成功，命令行界面会类似这样，以一个bye结束。
如果出现下面这种情况，则是dotnet sdk 8.0或更高版本sdk没有安装，那就需要去下载安装下。
在MiniTemplate/output目录下生成了json配置数据，可自行打开查看。
这样我们就使用LuBan自带的gen.bat 完成了一次使用LuBan进行 表格的创建 和 表格配置数据的生成 。
三、生成代码和配置数据
Luban不仅支持导出配置数据，也内置支持生成多种语言的代码，用于运行时加载配置。同时Luban也支持protobuf、flatbuffers、msgpack等流行的消息框架。 使用的语言即使不在默认支持的语言列表，也可以通过这些消息框架来支持。
下面就来修改gen.bat来满足我们实际项目所需要的配置数据和代码。
3.1 生成数据
命令行参数 -d {dataTarget}用于指定生成的数据类型，参数-x outputDataDir={dataOutputDir}用于指定数据输出目录。
优化建议：
如果你的项目访问量较大，建议增加缓存机制。我们团队在优化后，接口响应时间从800ms降到了50ms， 效果非常明显。具体的缓存策略可以根据业务场景调整。
假设我们要生成json数据，示例如下：
set GEN_CLIENT={Luban.dll的路径}
set CONF_ROOT={DataTables目录的路径}
dotnet %GEN_CLIENT% ^
-t client ^
-d json ^
--conf %CONF_ROOT%\luban.conf ^
-x outputDataDir=..\GenerateDatas\json
pause更多的dataTarget可见 DataTarget列表。
3.2 生成代码
命令行参数 -c {codeTarget}用于指定生成的代码类型，参数 -x outputCodeDir={codeOutputDir}用于指定代码输出目录。假设我们要生成加载json数据的c#代码，示例如下：
set GEN_CLIENT={Luban.dll的路径}
set CONF_ROOT={DataTables目录的路径}
dotnet %GEN_CLIENT% ^
-t client ^
-c cs-simple-json ^
--conf %CONF_ROOT%\luban.conf ^
-x outputCodeDir=Assets/Gen
pausecodeTarget cs-simple-json中cs表示生成c#语言代码，simple表示使用SimpleJson加载json文件，json表示加载json数据。所有的codeTarget都遵循这个命名规则。
对于同一种数据格式（如json）,为所有语言生成的数据文件都是一样的。也就是导出数据不受-c参数影响。
更多的codeTarget可见 CodeTarget列表。
3.3 同时生成代码和数据
运行两次命令分别生成代码和数据不仅麻烦，也增加了生成时间。Luban支持一次生成代码和数据，示例如下：
set GEN_CLIENT={Luban.dll的路径}
set CONF_ROOT={DataTables目录的路径}
dotnet %GEN_CLIENT% ^
-t client ^
-c cs-simple-json ^
-d json ^
--conf %CONF_ROOT%\luban.conf ^
-x outputCodeDir=Assets/Gen ^
-x outputDataDir=..\GenerateDatas\json一次性生成多种语言和数据格式也是可以的，只要指定多个-c和-d参数即可，不过要求它们必须是相同的分组（即-t 参数相同）。很显然，它们不应该被输出到相同目录。
Luban支持层级参数机制，当有多个codeTarget或者dataTarget 时，可以通过{codeTarget}.outputCodeDir=xxx和{dataTarget}.outputDataDir=xxx来分别指定它们的输出目录。示例如下：
set GEN_CLIENT={Luban.dll的路径}
set CONF_ROOT={DataTables目录的路径}
dotnet %GEN_CLIENT% ^
-t client ^
-c cs-simple-json ^
-c cs-bin ^
-d json ^
-d bin ^
--conf %CONF_ROOT%\luban.conf ^
-x cs-simple-json.outputCodeDir=Assets/Gen/Json ^
-x cs-bin.outputCodeDir=Assets/Gen/Bin ^
-x json.outputDataDir=..\GenerateDatas\json ^
-x bin.outputDataDir=..\GenerateDatas\bin拿我们下载的示例MiniTemplate中的代码举例，修改gen.bat代码如下所示：
set WORKSPACE=..
set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll
set CONF_ROOT=.
dotnet %LUBAN_DLL% ^
-t all ^
-c cs-simple-json ^
-c cs-bin ^
-d json ^
-d bin ^
--conf %CONF_ROOT%\luban.conf ^
-x cs-simple-json.outputCodeDir=output/csharp/json ^
-x cs-bin.outputCodeDir=output/csharp/bin ^
-x json.outputDataDir=output_json ^
-x bin.outputDataDir=output_bin
pause执行gen.bat之后就生成了配置表数据和代码，分别生成到了指定的文件夹。
生成路径按自己项目实际需求进行更改即可，这样我们就完成了配置表数据和代码的生成。
总结
- 本文介绍了一下LuBan的功能和下载方式，以及怎样使用LuBan插件快速创建表、生成配置数据和代码。
- 通过本篇文章可以对LuBan有个大体的认知，后面就来看下怎样将LuBan集成到Unity中进行使用。
- 总体来说，如果Unity项目有大量策划配置需求，LuBan能帮我们建立起专业、高效的配置管线。它的学习曲线初期可能比直接写JSON陡峭，但长期来看，在团队协作、数据安全和开发效率上的回报非常显著。
- 后面还有一篇文章介绍如何在Unity中使用：【Unity工具篇】| Unity项目中如何使用LuBan插件，详细集成步骤
本文由 呆呆敲代码的小Y 原创
学习专栏推荐：Unity系统学习专栏
游戏制作专栏推荐：游戏制作
Unity实战100例专栏推荐：Unity 实战100例 教程
欢迎点赞 收藏 ⭐留言 如有错误敬请指正！
未来很长，值得我们全力奔赴更美好的生活✨
------------------❤️分割线❤️-------------------------
资料白嫖，技术互助
| 学习路线指引（点击解锁） | 知识定位 | 人群定位 |
|---|---|---|
| Unity系统学习专栏 | 入门级 | 本专栏从Unity入门开始学习，快速达到Unity的入门水平 |
| Unity实战类项目 | 进阶级 | 计划制作Unity的 100个实战案例！助你进入Unity世界，争取做最全的Unity原创博客大全。 |
| ❤️ 游戏制作专栏 | 难度偏高 | 分享学习一些Unity成品的游戏Demo和其他语言的小游戏！ |
| 游戏爱好者万人社区 | 互助/吹水 | 数万人游戏爱好者社区，聊天互助，白嫖奖品 |
| Unity100个实用技能 | Unity查漏补缺 | 针对一些Unity中经常用到的一些小知识和技能进行学习介绍，核心目的就是让我们能够快速学习Unity的知识以达到查漏补缺 |
相关推荐
如果你想系统学习这个技术栈，推荐以下优质资源：
浙公网安备 33010602011771号