Unity导表工具解决方案-Luban使用教程

简介

是什么？

luban是一个强大、易用、优雅、稳定的游戏配置解决方案。它设计目标为满足从小型到超大型游戏项目的简单到复杂的游戏配置工作流需求。

官方文档：介绍 | Luban

优点

luban可以处理丰富的文件类型，支持主流的语言，可以生成多种导出格式，支持丰富的数据检验功能，具有良好的跨平台能力，并且生成极快。luban标准化了游戏配置开发工作流，可以极大提升策划和程序的工作效率。

缺点

由于功能强大，其配置规则相对复杂，所以学习曲线陡峭。

主要核心特性

|--------------------|-----------------------------------------------------------------------------|
| 丰富的源数据格式 | 支持excel族(csv,xls,xlsx,xlsm)、json、xml、yaml、lua等 |
| 丰富的导出格式 | 支持生成binary、json、bson、xml、lua、yaml等格式数据 |
| 完备的类型系统 | 不仅能表达常见的规范行列表，由于支持OOP类型继承，能灵活优雅表达行为树、技能、剧情、副本之类复杂GamePlay数据 |
| 支持多种的语言 | 支持生成c#、java、go、cpp、lua、python、typescript 等语言代码 |
| 支持所有主流的游戏引擎和平台 | 支持Unity、Unreal、Cocos、Godot、Laya、微信小游戏等 |
| 良好的跨平台能力 | 能在Win,Linux,Mac平台良好运行。 |
| 支持所有主流的热更新方案 | hybridclr、ilruntime、{x,t,s}lua、puerts等 |
| 支持主流的消息方案 | protobuf(schema + binary + json)、flatbuffers(schema + json)、msgpack(binary) |

环境配置

第一步 安装dotnet

浏览要下载的所有 .NET 版本| .NET

安装.NET 8.0即可

第二步 创建Excel管理文件夹

1、找到Unity项目的根目录

创建一个名为Excel文件夹（和Assets同级目录）

2、下载Luban模板工程

GitHub - focus-creative-games/luban_examples: luban example projects · GitHub

将MiniTemplate文件夹复制到Excel文件夹中

Datas里面保留beans、enums、tables三张表

将output文件夹中的所有文件删除

3、下载release版本luban

Releases · focus-creative-games/luban

解压后放到MiniTemplate下

4、 修改gen.bat文件

编辑gen.bat文件，将下列代码复制到bat文件中

set WORKSPACE=..\..
set LUBAN_DLL=%WORKSPACE%\Excel\MiniTemplate\Luban\Luban.dll
set CONF_ROOT=.
 
dotnet %LUBAN_DLL% ^
    -t all ^
    -d json ^
    -c cs-simple-json ^
    --conf %CONF_ROOT%\luban.conf ^
    -x outputDataDir=%WORKSPACE%\Assets\Resources\Data ^
    -x outputCodeDir=%WORKSPACE%\Assets\Scripts\Code
pause

在Unity中创建文件夹Resources/Data和Scripts/Code

第三步 Unity相关设置

1、在package Manager中安装Luban

https://gitee.com/focus-creative-games/luban_unity.git

第四步 配置数据

在Datas中添加测试Excel文件

第五步 开始导入配置数据

双击gen.bat进行运行

成功导入数据！！！

第五步 数据使用

using cfg;
using Luban.SimpleJSON;
using UnityEngine;

public class test : MonoBehaviour
{
    private void Start()
    {
        var tables = new Tables(LoadTable);
        //数据类里面实现了字典和列表两个容器，可以自由使用
        //得到字典容器中指定键的数据
        print(tables.Tbtest.Get(1001));
        //得到列表容器中指定位置的数据
        print(tables.Tbtest.DataList[0]);
        //遍历字典或列表容器中的数据
        foreach (var data in tables.Tbtest.DataList)
        {
            print(data);
        }
    }
    
    private JSONNode LoadTable(string table_name)
    {
        //读取配置的数据
        var textAsset = Resources.Load<TextAsset>($"Data/{table_name}");
        //返回数据
        return JSONNode.Parse(textAsset.text);
    }
}

配表规则

基础说明

1、基础表结构

|--------|-----------|-------------------------------------|
| 行序号 | 特殊标记 | 作用 |
| 第1行 | ##var | 字段名定义行，定义每个列对应的C#类属性名称。 |
| 第2行 | ##type | 字段类型定义行，定义每个字段的Luban数据类型。 |
| 第3行 | ##group | 分组行（可选），用于标记字段属于客户端(c)还是服务端(s)。 |
| 第4行 | ## | 注释行（可选），用于说明字段含义。 |
| 第5行及以后 | (无) | 数据行，从第5行开始才是真正的配置数据。 |

2、专用表

文件	作用	类比理解
__enums__.xlsx	定义枚举类型，为字段提供一组固定的可选值。	C# 中的 enum
__beans__.xlsx	定义复合类型，将多个字段组合成一个可复用的数据结构。	C# 中的 class
__tables__.xlsx	定义数据表的配置清单，指定哪些Excel文件应被识别为数据表及其关联类型。	配置文件的"目录"或"索引"

补充：Luban 支持一种快捷方式，无需在 __tables__.xlsx 中注册。如果数据表文件名以 # 开头（如 #Item.xlsx），Luban 会自动将其识别为一个独立的表，生成 TbItem 类。

配置类型

Luban支持的配置数据类型如下：

|---------------|--------------|---------------------------|------------------------|-------------------------------|
| 类别 | Luban类型 | 对应C#类型 | 配置示例 （##type行） | 说明 |
| 基础数据类型 | bool | bool | bool | 支持 true, false, 1 ,0等，大小写不敏感。 |
| 基础数据类型 | byte | byte | byte | 8 位无符号整数 |
| 基础数据类型 | short | short | short | 16 位有符号整数 |
| 基础数据类型 | int | int | int | 32位有符号整数。 |
| 基础数据类型 | long | long | long | 64位有符号整数。 |
| 基础数据类型 | float | float | float | 单精度浮点数。 |
| 基础数据类型 | double | double | double | 双精度浮点数。 |
| 基础数据类型 | string | string | string | 字符串。 |
| 基础数据类型 | text | string | text | 带本地化标签的字符串，用于多语言校验。 |
| 基础数据类型 | datetime | long | datetime | 存储自1970年1月1日以来的秒数（Unix时间戳）。 |
| 枚举类型 | enum | 生成的枚举 | enum,EQuality | 引用通过__enums__ 定义的枚举类型。 |
| 容器类型 | array | T[] | array,int | 固定长度的数组，元素类型可自定义。 |
| 容器类型 | list | List<T> | list,string | 可变长度的列表，元素类型可自定义。 |
| 容器类型 | map | Dictionary<TKey,TValue> | map,int,string | 键值对集合，需指定Key和Value的类型。 |
| 容器类型 | set | HashSet<T> | set,int | |
| 复杂/嵌套类型 | bean | 生成的Class | bean,Item | 引用另一个已定义的数据结构（类），实现嵌套。 |
| 复杂/嵌套类型 | 可空类型 | Nullable<T> | float? | 在基础类型后加? ，表示该字段可以留空。 |
| Unity专用类型 | vector2 | UnityEngine.Vector2 | vector2 | |
| Unity专用类型 | vector3 | UnityEngine.Vector3 | vector3 | |
| Unity专用类型 | vector4 | UnityEngine.Vector4 | vector4 | |

基础数据类型

枚举类型

先配置自定义枚举

容器类型

array数组类型

有两种格式，一种使用多个单元格，一种使用一个单元格但是用分割符

分隔符格式：(array#sep=分隔符)，数据类型

list列表类型

set集合类型

map字典类型

嵌套类型

在__beans__配表中配置对应的结构名和字段

Unity专用类型

配置格式

流式格式

1、多个单元格，按顺序读取

2、一个单元格，使用分割符分割后按照顺序读取

格式：(array#sep=分隔符)，数据类型

Lite格式

json格式

lua格式