强力配置工具Luban使用教程

github 主页：https://github.com/focus-creative-games/luban
gitee 主页：https://gitee.com/focus-creative-games/luban
官方文档：https://focus-creative-games.github.io/luban-doc/
视频教程：https://www.bilibili.com/video/BV1xS4y1M7Aj
示例项目 (github) (gitee)

介绍

luban 是你的最佳游戏配置解决方案。

luban 高效地处理游戏开发中常见的 excel、json、xml 之类的数据，检查数据错误，生成 c# 等各种语言的代码，导出成 bytes 或 json 等多种格式。

luban 统一了游戏配置开发工作流，极大提升了策划和程序的工作效率。

核心特性

强大的数据解析和转换能力 {excel(csv,xls,xlsx)、json、bson、xml、yaml、lua、unity ScriptableObject} => {binary、json、bson、xml、lua、yaml、erlang、 custom format}

通用型生成和缓存工具。也可以用于生成协议、数据库之类的代码，甚至可以用作对象缓存服务。

良好支持主流引擎、全平台、主流热更新方案、主流前后端框架。支持 Unity、Unreal、Cocos2dx、Godot、微信小游戏等主流引擎。工具自身跨平台，能在 Win，Linux，Mac 平台良好工作。

安装与运行 - 以 Unity 项目为例

1. 安装 dotnet sdk 6.0 或以上版本的SDK安装程序
   下载地址：https://dotnet.microsoft.com/zh-cn/download/dotnet/6.0
   

2. 下载 luban_examples 项目。该项目中包含：

   • DesignerConfigs 一个较复杂的用于测试的配置项目。
   • MiniTemplate 一个最简单的配置模板，用于快速创建一个新的配置项目。
   • Projects 一些覆盖常见平台、引擎、语言的示例项目，可以直接运行。
   • Tools 包含编译好的Luban工具。

   luban经历了大规模的重构，和旧版本有一定的差异。使用旧版本luban的开发者请切换到classic分支。

3. 项目准备。以最常见的 unity + c# + json 为例。示例参考项目为 Csharp_Unity_Json，其他类型请参考 Projects 目录下的相应项目。
   拷贝 Csharp_Unity_Json 项目中的 Assets\LubanLib 目录到你的 Unity 项目中，位置没有要求。然后在 Unity 的 PlayerSettings 里开启 unsafe 选项（如果你们项目要求不开启unsafe，请到群里求助）。此时尝试编译项目，如果没有编译错误，表示成功引入了 Luban 相关库代码。

4. 配置准备。从 luban_examples 复制工具库 Tools/Luban 和 MiniTemplate 文件夹到任意目录下，并修改 MiniTemplate/gen.bat 文件中相关路径。

5. 编辑生成命令。修改 gen.bat 文件，位置无要求。调整 gen.bat 文件中各项配置路径为恰当的值。如果有疑惑，可以参考 Csharp_Unity_Json 项目的 gen.bat 文件（苹果则为 .sh 文件）。

   set LUBAN_DLL=<Luban.dll路径>
   set CONF_ROOT=<DesignerConfigs路径>
   
   dotnet %LUBAN_DLL% ^
       -t client ^
       -c cs-simple-json ^
       -d json  ^
       --schemaPath %CONF_ROOT%\Defines\__root__.xml ^
       -x inputDataDir=%CONF_ROOT%\Datas ^
       -x outputCodeDir=<cs代码输出目录> ^
       -x outputDataDir=<json数据输出目录>
   
   pause
   

   简单介绍 bat 文件中各项参数：

   • LUBAN_DLL Luban.dll 文件的路径。指向 luban_examples/Tools/Luban/Luban.dll
   • CONF_ROOT 配置项目的路径。指向 luban_examples/DesignerConfigs
   • -t 生成目标。可以为 client、server、all 之类的值
   • -c 生成的代码类型。 cs-simple-json 为生成使用 SimpleJSON 加载 json 数据的 c# 代码
   • -d 生成的数据类型
   • inputDataDir 配置表（如 xlsx ）的根目录
   • outputCodeDir c# 代码的输出目录
   • outputDataDir json 数据的输出目录

   运行该脚本，如果一切正常，会产生一系列日志，最终一行是 bye~。

6. 加载配置。只需一行代码即可加载所有配置表。整个游戏运行期间只加载一次（除非要运行中重新加载配置）。实践中在创建tables后将它保存起来，以便后续使用。

   string gameConfDir = "<outputDataDir>"; // 替换为gen.bat中outputDataDir指向的目录
   var tables = new cfg.Tables(fileName => JSON.Parse(File.ReadAllText($"{gameConfDir}/{fileName}.json")));
   

7. 使用配置。cfg.Tables 里包含所有配置表的一个实例字段。加载完 cfg.Tables 后，用 tables.<表名> 获得那个表实例，接着对该表做后续操作。例如我们要打印 Reward 表 id = 1001 的那个奖励信息，代码如下：

   cfg.demo.Reward reward = tables.TbReward.Get(1001);
   Console.WriteLine("reward:{0}", reward);
   

定义配置表的数据结构

Luban 支持的基本类型：bool，byte，short，int，long，float，double，string，datetime。

• bool：true、false、0、1 都能被识别，大小写不敏感，如 True、TRUE 也是有效值。
• datetime：类型为 C# 里的 long，值为自 UTC 1970-01-01 00:00:00 以来的秒数。
• 其他基本类型都和 C# 中的保持一致。

Luban 的容器类型：

• array：对应 C# 的数组，定义方式为 array,<eleType>，eleType 不能为可空类型。
• list：对应 C# 的 List，定义方式为 list,<eleType>，eleType 不能为可空类型。
• set：对应 C# 的 HashSet，定义方式为 set,<eleType>，eleType 不能为可空类型。
• map：对应 C# 的 Dictionary，定义方式为 map,<keyType>,<valueType>，keyType 只能为基本类型或 enum 类型，keyType 与 valueType 都不能为可空类型。

Luban 的自定义类型：

• enum：枚举类，对应 C# 的 enum。
• bean：复合类型，对应 C# 的 class 或 struct。bean 支持类型继承和多态。
• table：索引表，为大多数语言生成代码时会为每个 table 生成一个类，管理这个表的所有数据。

Luban 的可空类型：基本类型和自定义类型都支持可空类型，容器类型不支持可空，容器的 key 或 value 类型也不支持可空。定义方式为 <类型>?（如 int?, Color?，与 C# 的语法相同。

Luban 的特殊类型

• tables：为大多数语言生成代码时会包含一个所有表的管理类，类名在全局 schema 的 target.TopModule 字段定义。一般取名为 Tables。

自定义类型 - 枚举类型定义

典型的 enum 文件格式如下：

表字段说明：

字段	可空	默认值	说明
full_name	否		类型全名，既可以是不包含命名空间，如 Hello，也可以包含命名空间如 item.Item
flags	是	false	是否为 bit 标志位类型，对应 C# 的 FlagsAttribute 语义。如果为 true，则允许使用 READ|WRITE 这种写法
unique	是	false	当前 enum 内的所有枚举值是否必须唯一
group	是		导出分组，可以为 0 到多个，以 ‘,’ 号分割。实践中前后端需要的数据表和表内字段经常是不一样的，这种根据输出目标对输出内容的分类，对应 Luban 内的概念为 group
comment	是		注释。如果非空，生成代码时会包含注释
tags	是		自定义 tag 对。tags 主要有两个用途：校验器和特殊代码生成
items	否		枚举项列表
var.name	否		枚举项名
var.alias	是		枚举项别名。策划填写数据时可以填写别名，方便一些英语不好的策划，如 Circle 类也能填 ‘圆’ 来表达
var.value	是		枚举值。如果不填，则值为上一个枚举项的值 +1，如果是第一个枚举项则值为 0
var.comment	是		注释。如果非空，生成枚举项时会包含注释。如果为空，又定义了 alias，则会取 alias 为注释
var.tags	是		自定义tag对

自定义类型 - bean 类型定义

典型的 bean 文件格式如下：

表字段说明：

字段	可空	默认值	说明
full_name	否		类型全名，既可以是不包含命名空间，如 Hello，也可以包含命名空间如 item.Item
parent	是		父类名，如果名字不包含命名空间，会优先从当前命名空间找，再从全局命名空间找
valueType	是	false	是否为值类型，例如为 C# 这种支持值类型的语言生成代码时，生成 struct 而不是 class 类型，对于 java 这种语言没有效果
sep	是		分割符。指定该结构以复合模式填写，字段之间以分割符分割。如在一个单元格内 1,2,3 表达一个 Vector3 结构，而不是强行占据多个单元格。sep 可以是多个字符，表示用 sep 中任意一个字符分割，而不是整个sep作为分割符
alias	是	false	别名
comment	是		注释
group	是		导出分组，可以为 0 到多个
tags	是		自定义tag对
fields	否		字段列表
var.name	否		字段名。推荐使用 xx_yy_zz 格式的名称，因为生成代码时，默认会生成符合语言推荐代码风格的字段名
var.type	否		类型名。可以是任何 Luban 类型系统 支持的数据类型
var.group	是		导出分组，可以为 0 到多个。如不填则该字段属于所有分组
var.comment	是		注释
var.tags	是		自定义tag对

自定义类型 - table 类型定义

table 是数据表的逻辑表示。table 并非类型，不能用于 field 的 type 定义。典型的 table 文件格式如下：

表字段说明：

字段	可空	默认值	说明
full_name	否		类型全名，既可以是不包含命名空间，如 Hello，也可以包含命名空间如 item.Item
value_type	否		表记录类型
read_schema_from_file	是	false	是否从 input 的 excel 文件的标题头和属性栏读取 value_type 定义。如果为 true 则不能再定义 value_type 对应的 bean，否则会出现定义重复的错误
input	否		输入的数据文件列表。填写以 Datas 为根目录的路径
index	是		索引字段列表，可为0到多个。如果 index 为空，并且 mode = map 或空，则自动取 valueType 第一个字段为 index。当 table 有多个主键时，如果是联合主键，则以 key1+key2+,,,+keyn 方式填写，如果是独立主键， 则以 key1,key2,,,keyn 方式配置。
mode	是		表模式枚举。可取 one(或 singleton)、map、list。留空则根据 index 决定具体 mode 值：如果 index 为空或 1 个主键则为 map，index 为 valueType 的第 1 个字段；如果 index 为多个主键，则 mode 为 list。
group	是		导出分组，可以为 0 到多个
comment	是		注释
tags	是		自定义tag对
output	否		输出的文件名，如果为空，则取 FullName.LowerCase().Replace('.', '_')

input 指定了多个输入数据源，定义方式极其灵活。每个数据源可以是以下值：

• 来自某个 excel 文件的所有单元薄。例如 xxx.xlsx
• 来自某个 excel 文件的指定单元薄。例如 sheet@xxx.xlsx
• 来自 json、xml、lua、yaml、unity scriptable asset 文件。例如 xx.json 或 xx.xml 或 xx.lua 或 xx.yml
• 来自 json、xml、lua、yaml、unity scriptable asset 子字段。例如 *items@item_module.json 或 item.consts@item_module.json 之类，其他格式同理
• 来自目录。目录树下所有文件（包含递归子目录）都会被当作数据源读入，每个文件（excel 族例外）对应一个记录。例如 skill_json_dir
• 以上的随意组合。如 xx.xlsx,sheet2@yy.xls,abc@zz.json,ccc_dir

mode 数据表模式：

• one，即单例表模式。有一些配置全局只有一份，比如 公会模块的开启等级，背包初始大小，背包上限。此时使用单例表来配置这些数据比较合适。
• map，普通key-value表。可以在 index 属性中指定主键字段名，如果 index 为空，使用表的第一个字段作为主键。
• list，普通的list表，但支持多主键联合索引和多主键独立索引。