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 项目为例安装 dotnet sdk 6.0 或以上版本的SDK安装程序 下载地址:https://dotnet.microsoft.com/zh-cn/download/dotnet/6.0
下载 luban_examples 项目。该项目中包含:
DesignerConfigs 一个较复杂的用于测试的配置项目。MiniTemplate 一个最简单的配置模板,用于快速创建一个新的配置项目。Projects 一些覆盖常见平台、引擎、语言的示例项目,可以直接运行。Tools 包含编译好的Luban工具。luban经历了大规模的重构,和旧版本有一定的差异。使用旧版本luban的开发者请切换到classic分支。
项目准备。以最常见的 unity + c# + json 为例。示例参考项目为 Csharp_Unity_Json,其他类型请参考 Projects 目录下的相应项目。 拷贝 Csharp_Unity_Json 项目中的 Assets\LubanLib 目录到你的 Unity 项目中,位置没有要求。然后在 Unity 的 PlayerSettings 里开启 unsafe 选项(如果你们项目要求不开启unsafe,请到群里求助)。此时尝试编译项目,如果没有编译错误,表示成功引入了 Luban 相关库代码。
配置准备。从 luban_examples 复制工具库 Tools/Luban 和 MiniTemplate 文件夹到任意目录下,并修改 MiniTemplate/gen.bat 文件中相关路径。
编辑生成命令。修改 gen.bat 文件,位置无要求。调整 gen.bat 文件中各项配置路径为恰当的值。如果有疑惑,可以参考 Csharp_Unity_Json 项目的 gen.bat 文件(苹果则为 .sh 文件)。
set LUBAN_DLL=set CONF_ROOT=dotnet %LUBAN_DLL% ^-t client ^-c cs-simple-json ^-d json ^--schemaPath %CONF_ROOT%\Defines\__root__.xml ^-x inputDataDir=%CONF_ROOT%\Datas ^-x outputCodeDir= ^-x outputDataDir=pause简单介绍 bat 文件中各项参数:
LUBAN_DLL Luban.dll 文件的路径。指向 luban_examples/Tools/Luban/Luban.dllCONF_ROOT 配置项目的路径。指向 luban_examples/DesignerConfigs-t 生成目标。可以为 client、server、all 之类的值-c 生成的代码类型。 cs-simple-json 为生成使用 SimpleJSON 加载 json 数据的 c# 代码-d 生成的数据类型inputDataDir 配置表(如 xlsx )的根目录outputCodeDir c# 代码的输出目录outputDataDir json 数据的输出目录运行该脚本,如果一切正常,会产生一系列日志,最终一行是 bye~。
加载配置。只需一行代码即可加载所有配置表。整个游戏运行期间只加载一次(除非要运行中重新加载配置)。实践中在创建tables后将它保存起来,以便后续使用。
string gameConfDir = ""; // 替换为gen.bat中outputDataDir指向的目录var tables = new cfg.Tables(fileName => JSON.Parse(File.ReadAllText($"{gameConfDir}/{fileName}.json")));使用配置。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 不能为可空类型。list:对应 C# 的 List,定义方式为 list,,eleType 不能为可空类型。set:对应 C# 的 HashSet,定义方式为 set,,eleType 不能为可空类型。map:对应 C# 的 Dictionary,定义方式为 map,,,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.Itemflags是false是否为 bit 标志位类型,对应 C# 的 FlagsAttribute 语义。如果为 true,则允许使用 READ|WRITE 这种写法unique是false当前 enum 内的所有枚举值是否必须唯一group是导出分组,可以为 0 到多个,以 ‘,’ 号分割。实践中前后端需要的数据表和表内字段经常是不一样的,这种根据输出目标对输出内容的分类,对应 Luban 内的概念为 groupcomment是注释。如果非空,生成代码时会包含注释tags是自定义 tag 对。tags 主要有两个用途:校验器和特殊代码生成items否枚举项列表var.name否枚举项名var.alias是枚举项别名。策划填写数据时可以填写别名,方便一些英语不好的策划,如 Circle 类也能填 ‘圆’ 来表达var.value是枚举值。如果不填,则值为上一个枚举项的值 +1,如果是第一个枚举项则值为 0var.comment是注释。如果非空,生成枚举项时会包含注释。如果为空,又定义了 alias,则会取 alias 为注释var.tags是自定义tag对 自定义类型 - bean 类型定义典型的 bean 文件格式如下:
表字段说明:
字段可空默认值说明full_name否类型全名,既可以是不包含命名空间,如 Hello,也可以包含命名空间如 item.Itemparent是父类名,如果名字不包含命名空间,会优先从当前命名空间找,再从全局命名空间找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.Itemvalue_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_dirmode 数据表模式:
one,即单例表模式。有一些配置全局只有一份,比如 公会模块的开启等级,背包初始大小,背包上限。此时使用单例表来配置这些数据比较合适。map,普通key-value表。可以在 index 属性中指定主键字段名,如果 index 为空,使用表的第一个字段作为主键。list,普通的list表,但支持多主键联合索引和多主键独立索引。