xiang.li
/
luban
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

【完善】完善 README.md

main v2.0
walon 2020-12-14 17:46:55 +08:00
parent c87d6ccc2c
commit 6e127e3b7a
2 changed files with 185 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

344
README.md
View File

@ -12,16 +12,16 @@
## 介绍 ## 介绍
Luban是一个强大的对象生成与缓存工具。生成目标可以是类似protobuf的消息代码、游戏配置代码、游戏配置数据、数据库代码，也可以是游戏资源如assetbundle。 luban是一个相当完备成熟的游戏配置解决方案，同时也可以用作通用型对象生成与缓存工具。
luban创新性提出 **定义 + 数据源** 的设计，实现了完备的类型系统，增强了excel格式，同时提供json、xml、lua等多种数据源支持，统一了数据定义、加载、检验、数据导出及代码生成的Pipeline，彻底解决了中大型项目中难以在excel中配置复杂数据以及一个项目中excel、json等多种的配置方案并存的问题。 luban创新性提出 **定义 + 数据源** 的设计，实现了完备的类型系统，增强了excel格式，同时提供json、xml、lua等多种数据源支持，统一了数据定义、加载、检验、数据导出及代码生成的游戏配置Pipeline，彻底解决了中大型项目中难以在excel中配置复杂数据以及一个项目中excel、json等多种的配置方案并存的问题。
Luban适合有以下需求的开发者： Luban适合有以下需求的开发者：
1. 无法容忍传统excel导表工具的简陋功能，希望找一个快速强大经受过上线项目检验的满足中大型游戏项目配置需求的游戏配置解决方案 1. 无法容忍传统excel导表工具的简陋功能，希望找一个快速强大经受过上线项目检验的满足中大型游戏项目配置需求的游戏配置解决方案
2. 不想使用protobuf,希望针对项目需求方便地自定义消息生成，满足严苛的内存和性能的要求 2. 不想使用protobuf,希望针对项目需求方便地自定义消息生成，满足严苛的内存和性能的要求
3. 希望做其他自定义生成或者缓存 3. 希望做其他自定义生成或者缓存
Luban另一优点是生成过程极快。对于普通的导表工具，一个典型的MMORPG项目后期全量生成配置往往需要几十秒。Luban使用client/server的云生成模型，多线程生成+对象缓存，大多数情况下可以1s内完成整个生成过程 ^_^，加速了日常工作流的迭代过程，积少成多也能为程序和策划同学节省下可观的时间。 Luban另一优点是生成过程极快。对于普通的导表工具，一个典型的MMORPG项目后期全量生成配置往往需要几十秒。Luban使用client/server的云生成模型，通过多线程并发生成+对象缓存机制，大多数情况下可以1s内完成整个生成过程。
## 文档 ## 文档
@ -71,26 +71,26 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
- 其他所有支持lua的引擎和平台 - 其他所有支持lua的引擎和平台
- 其他所有支持js的引擎和平台 - 其他所有支持js的引擎和平台
## 快速入门 - 结构定义和数据配置 ## 结构定义与配置表填写
与常见的专注于excel的导表工具中定义和数据放在同一个excel文件的做法不同，luban的定义与数据分离，使用单独的xml定义 **表和结构**。 与常见的专注于excel的导表工具中定义和数据放在同一个excel文件的做法不同，luban的定义与数据分离，使用单独的xml定义 **表和结构**，数据文件只包含数据。
### 常规的原生数据 ### 常规的原生数据
``` ```
<bean name="DemoPrimitiveTypesTable"> <bean name="DemoPrimitiveTypesTable">
<var name="x1" type="bool"/> <var name="x1" type="bool"/>
<var name="x2" type="byte"/> <var name="x2" type="byte"/>
<var name="x3" type="short"/> <var name="x3" type="short"/>
<var name="x4" type="int?" /> <var name="x4" type="int" />
<var name="x5" type="long" /> <var name="x5" type="long" />
<var name="x6" type="float"/> <var name="x6" type="float"/>
<var name="x7" type="double"/> <var name="x7" type="double"/>
<var name="x10" type="string" /> <var name="x10" type="string" />
<var name="v2" type="vector2"/> <var name="v2" type="vector2"/>
<var name="v3" type="vector3"/> <var name="v3" type="vector3"/>
<var name="v4" type="vector4"/> <var name="v4" type="vector4"/>
<var name="t1" type="datetime"/> <var name="t1" type="datetime"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_2.png) ![](docs/images/examples/ex_2.png)
@ -100,16 +100,16 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
定义枚举类，同时强制配置中必须填写枚举名或者别名，提高配置阅读性。 定义枚举类，同时强制配置中必须填写枚举名或者别名，提高配置阅读性。
``` ```
<enum name="DemoEnum"> <enum name="DemoEnum">
<var name="RED" alias="红" value="1"/> <var name="RED" alias="红" value="1"/>
<var name="BLUE" alias="蓝" value="3"/> <var name="BLUE" alias="蓝" value="3"/>
<var name="GREEN" alias="绿" value="5"/> <var name="GREEN" alias="绿" value="5"/>
</enum> </enum>
<bean name="DemoEnumTable"> <bean name="DemoEnumTable">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="x2" type="DemoEnum"/> <var name="x2" type="DemoEnum"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_12.png) ![](docs/images/examples/ex_12.png)
@ -117,15 +117,15 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
### 自定义结构 bean ### 自定义结构 bean
``` ```
<bean name="IntRange"> <bean name="IntRange">
<var name="min" type="int"/> <var name="min" type="int"/>
<var name="max" type="int"/> <var name="max" type="int"/>
</bean> </bean>
<bean name="DemoBeanTable"> <bean name="DemoBeanTable">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="range" type="IntRange"/> <var name="range" type="IntRange"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_22.png) ![](docs/images/examples/ex_22.png)
@ -134,46 +134,44 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
支持OOP的类型的继承体系，方便表达多类型的数据，经常用于技能、AI等模块。 支持OOP的类型的继承体系，方便表达多类型的数据，经常用于技能、AI等模块。
``` ```
<bean name="Shape"> <bean name="Shape">
<var name="id" type="int"/> <var name="id" type="int"/>
<bean name="Circle"> <bean name="Circle">
<var name="radius" type="float"/> <var name="radius" type="float"/>
</bean>
<bean name="Rectangle" alias="长方形">
<var name="width" type="float"/>
<var name="height" type="float"/>
</bean>
<bean name="Curve">
<bean name="Line" alias="直线">
<var name="direction" type="vector2"/>
</bean> </bean>
<bean name="Rectangle" alias="长方形"> <bean name="Parabola" alias="抛物线">
<var name="width" type="float"/> <var name="param_a" type="float"/>
<var name="height" type="float"/> <var name="param_b" type="float"/>
</bean>
<bean name="Curve">
<bean name="Line" alias="直线">
<var name="direction" type="vector2"/>
</bean>
<bean name="Parabola" alias="抛物线">
<var name="param_a" type="float"/>
<var name="param_b" type="float"/>
</bean>
</bean> </bean>
</bean> </bean>
</bean>
<bean name="ShapeTable"> <bean name="ShapeTable">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="shape" type="Shape"/> <var name="shape" type="Shape"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_32.png) ![](docs/images/examples/ex_32.png)
### 可空数据类型 ### 可空数据类型
配置数据中经常有空值的语义需求，实际项目中往往混杂地使用0或-1表达空值，既不自然清晰也不统一。luban借鉴了c#中的可空变量的概念，特地提供可空数据支持。 配置数据中经常有空值的语义需求，实际项目中往往混杂地使用0或-1表达空值，既不自然清晰也不统一。luban借鉴了c#中的可空变量的概念，特地提供可空数据支持。除了string外的所有原生数据类型，以及enum类型都有相应的可空数据类型。定义方式为 <类型名>?，与c#里的Nullable类型定义方式相同。例如 bool?,int?,long?,double?, EColor?
除了string外的所有原生数据类型，以及enum类型都有相应的可空数据类型。定义方式为 <类型名>?，与c#里的Nullable类型定义方式相同。例如 bool?,int?,long?,double?, EColor?
``` ```
<bean name="NullableTable"> <bean name="NullableTable">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="min_level" type="int?"/> <var name="min_level" type="int?"/>
<var name="color" type="DemoEnum?"/> <var name="color" type="DemoEnum?"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_42.png) ![](docs/images/examples/ex_42.png)
@ -182,11 +180,11 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
一般来说，既可以在一个单元格内以 逗号","分隔填写，也可以每个单元格填写一个数据。注意！空单元格会被忽略。 一般来说，既可以在一个单元格内以 逗号","分隔填写，也可以每个单元格填写一个数据。注意！空单元格会被忽略。
``` ```
<bean name="CollectionTable"> <bean name="CollectionTable">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="items" type="list,int"/> <var name="items" type="list,int"/>
<var name="coefs" type="list,int"/> <var name="coefs" type="list,int"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_52.png) ![](docs/images/examples/ex_52.png)
@ -194,73 +192,73 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
### 结构列表 ### 结构列表
对于结构列表类型，有多种填写。策划根据具体情况，选择最合适的填法。 对于结构列表类型，有多种填写。策划根据具体情况，选择最合适的填法。
- 填法1。 全展开。 - 全展开。
``` ```
<bean name="Item"> <bean name="Item">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="name" type="string"/> <var name="name" type="string"/>
<var name="num" type="int"/> <var name="num" type="int"/>
</bean> </bean>
<bean name="CollectionTable2"> <bean name="CollectionTable2">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="items" type="list,Item"/> <var name="items" type="list,Item"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_61.png) ![](docs/images/examples/ex_61.png)
- 填法2。 每个Item在一个单元格内 - 每个Item在一个单元格内
``` ```
<bean name="Item" sep=","> <bean name="Item" sep=",">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="name" type="string"/> <var name="name" type="string"/>
<var name="num" type="int"/> <var name="num" type="int"/>
</bean> </bean>
<bean name="CollectionTable2"> <bean name="CollectionTable2">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="items" type="list,Item"/> <var name="items" type="list,Item"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_62.png) ![](docs/images/examples/ex_62.png)
- 填法3。所有数据都在一个单元格内 - 所有数据都在一个单元格内
``` ```
<bean name="Item" sep=","> <bean name="Item" sep=",">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="name" type="string"/> <var name="name" type="string"/>
<var name="num" type="int"/> <var name="num" type="int"/>
</bean> </bean>
<bean name="CollectionTable2"> <bean name="CollectionTable2">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="items" type="list,Item" sep="|"/> <var name="items" type="list,Item" sep="|"/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_63.png) ![](docs/images/examples/ex_63.png)
### 多态结构列表 ### 多态结构列表
``` ```
<bean name="CollectionTable3"> <bean name="CollectionTable3">
<var name="id" type="int"/> <var name="id" type="int"/>
<var name="shapes" type="list,Shape" sep=","/> <var name="shapes" type="list,Shape" sep=","/>
</bean> </bean>
``` ```
![](docs/images/examples/ex_71.png) ![](docs/images/examples/ex_71.png)
### 双主键表 ### 双主键表
``` ```
<bean name="TwoKeyTable"> <bean name="TwoKeyTable">
<var name="key1" type="int"/> <var name="key1" type="int"/>
<var name="key2" type="string"/> <var name="key2" type="string"/>
<var name="name" type="string"/> <var name="name" type="string"/>
</bean> </bean>
<table name="TbTowKey" value="TwoKeyTable" index="key1,key2" input="examples.xlsx"/> <table name="TbTowKey" value="TwoKeyTable" index="key1,key2" input="examples.xlsx"/>
``` ```
![](docs/images/examples/ex_91.png) ![](docs/images/examples/ex_91.png)
@ -270,14 +268,16 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
单例即代码模式中单例的含义，用于配置全局只有一份的数据。 单例即代码模式中单例的含义，用于配置全局只有一份的数据。
``` ```
<bean name="SingletonTable"> <bean name="SingletonTable">
<var name="init_gold_num" type="int"/> <var name="init_gold_num" type="int"/>
<var name="guild_module_open_level" type="int"/> <var name="guild_module_open_level" type="int"/>
</bean> </bean>
<table name="TbSingleton" value="SingletonTable" mode="one" input="examples.xlsx"/> <table name="TbSingleton" value="SingletonTable" mode="one" input="examples.xlsx"/>
``` ```
luban支持横表与纵表，默认为横表。对于单例表，纵表填写更舒服一些，因此我们在excel的B1单元格填上 row:0 表示它是纵表。
![](docs/images/examples/ex_a1.png) ![](docs/images/examples/ex_a1.png)
### json 数据源 ### json 数据源
@ -285,39 +285,39 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
定义 定义
``` ```
<bean name="DemoType2" > <bean name="DemoType2" >
<var name="x4" type="int" convert="DemoEnum"/> <var name="x4" type="int" convert="DemoEnum"/>
<var name="x1" type="bool"/> <var name="x1" type="bool"/>
<var name="x2" type="byte"/> <var name="x2" type="byte"/>
<var name="x3" type="short" ref="test.TbFullTypes"/> <var name="x3" type="short" ref="test.TbFullTypes"/>
<var name="x5" type="long" convert="DemoEnum"/> <var name="x5" type="long" convert="DemoEnum"/>
<var name="x5" type="long" convert="DemoEnum"/> <var name="x5" type="long" convert="DemoEnum"/>
<var name="x6" type="float"/> <var name="x6" type="float"/>
<var name="x7" type="double"/> <var name="x7" type="double"/>
<var name="x8_0" type="fshort"/> <var name="x8_0" type="fshort"/>
<var name="x8" type="fint"/> <var name="x8" type="fint"/>
<var name="x9" type="flong"/> <var name="x9" type="flong"/>
<var name="x10" type="string" path="normal;*.txt"/> <var name="x10" type="string" path="normal;*.txt"/>
<var name="x12" type="DemoType1"/> <var name="x12" type="DemoType1"/>
<var name="x13" type="DemoEnum"/> <var name="x13" type="DemoEnum"/>
<var name="x14" type="DemoDynamic" sep=","/>多态数据结构 <var name="x14" type="DemoDynamic" sep=","/>多态数据结构
<var name="v2" type="vector2"/> <var name="v2" type="vector2"/>
<var name="v3" type="vector3"/> <var name="v3" type="vector3"/>
<var name="v4" type="vector4"/> <var name="v4" type="vector4"/>
<var name="t1" type="datetime"/> <var name="t1" type="datetime"/>
<var name="k1" type="array,int"/> 使用;来分隔 <var name="k1" type="array,int"/> 使用;来分隔
<var name="k2" type="list,int"/> <var name="k2" type="list,int"/>
<var name="k3" type="linkedlist,int"/> <var name="k3" type="linkedlist,int"/>
<var name="k4" type="arraylist,int"/> <var name="k4" type="arraylist,int"/>
<var name="k5" type="set,int"/> <var name="k5" type="set,int"/>
<var name="k6" type="treeset,int"/> <var name="k6" type="treeset,int"/>
<var name="k7" type="hashset,int"/> <var name="k7" type="hashset,int"/>
<var name="k8" type="map,int,int"/> <var name="k8" type="map,int,int"/>
<var name="k9" type="list,DemoE2" sep="," index="y1"/> <var name="k9" type="list,DemoE2" sep="," index="y1"/>
<var name="k15" type="array,DemoDynamic" sep=","/> <var name="k15" type="array,DemoDynamic" sep=","/>
</bean> </bean>
<table name="TbDataFromJson" value="DemoType2" input="test/json_datas"/> <table name="TbDataFromJson" value="DemoType2" input="test/json_datas"/>
``` ```
以目录为数据源，递归遍历整个目录树，将每个json数据当作一个记录读入。 以目录为数据源，递归遍历整个目录树，将每个json数据当作一个记录读入。
@ -394,23 +394,23 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
<v3>1.2,2.3,3.4</v3> <v3>1.2,2.3,3.4</v3>
<v4>1.2,2.2,3.2,4.3</v4> <v4>1.2,2.2,3.2,4.3</v4>
<t1>1970-01-01 00:00:00</t1> <t1>1970-01-01 00:00:00</t1>
<k1> <item>1</item> <item>2</item> </k1> <k1> <item>1</item> <item>2</item> </k1>
<k2> <item>1</item> <item>2</item> </k2> <k2> <item>1</item> <item>2</item> </k2>
<k3> <item>1</item> <item>2</item> </k3> <k3> <item>1</item> <item>2</item> </k3>
<k4> <item>1</item> <item>2</item> </k4> <k4> <item>1</item> <item>2</item> </k4>
<k5> <item>1</item> <item>2</item> </k5> <k5> <item>1</item> <item>2</item> </k5>
<k6> <item>1</item> <item>2</item> </k6> <k6> <item>1</item> <item>2</item> </k6>
<k7> <item>1</item> <item>3</item> </k7> <k7> <item>1</item> <item>3</item> </k7>
<k8> <k8>
<item> <key>2</key><value>10</value></item> <item> <key>2</key><value>10</value></item>
<item> <key>3</key><value>30</value></item> <item> <key>3</key><value>30</value></item>
</k8> </k8>
<k9> <k9>
<item> <y1>1</y1> <y2>true</y2> </item> <item> <y1>1</y1> <y2>true</y2> </item>
<item> <y1>2</y1> <y2>false</y2> </item> <item> <y1>2</y1> <y2>false</y2> </item>
</k9> </k9>
<k15> <k15>
<item __type__="DemoD2"> <x1>1</x1> <x2>2</x2> </item> <item __type__="DemoD2"> <x1>1</x1> <x2>2</x2> </item>
</k15> </k15>
</data> </data>
``` ```
@ -419,11 +419,11 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
定义 定义
``` ```
<bean name="DemoType2"> <bean name="DemoType2">
<<定义同json>> <<定义同json>>
</bean> </bean>
<table name="TbDataFromLua" value="DemoType2" input="test/lua_datas"/> <table name="TbDataFromLua" value="DemoType2" input="test/lua_datas"/>
``` ```
以目录为数据源，递归遍历整个目录树，将每个lua数据当作一个记录读入。 以目录为数据源，递归遍历整个目录树，将每个lua数据当作一个记录读入。
@ -464,23 +464,33 @@ Luban另一优点是生成过程极快。对于普通的导表工具，一个典
``` ```
------ ------
## 生成代码与数据 ## 代码与数据生成
以lua为例： 以lua为例：
1. 定义全局环境变量LUBAN_SERVER_IP。如果本地已运行luban.server，则取地址为127.0.0.1；如果没有运行，也可以使用已经部属好的云luan服务（仅供快速测试，建议每个项目独立搭建luban-server），地址为 81.69.4.240 。 1. 定义全局环境变量LUBAN_SERVER_IP。如果本地已运行luban.server，则取地址为127.0.0.1；如果没有运行，也可以使用已经部属好的云luan服务（仅供快速测试，建议每个项目独立搭建luban-server），地址为 81.69.4.240 。
1. 进入 config 目录 1. 进入 config 目录 & 运行 "生成 lua 数据.bat"
1. 双击 生成 lua 数据.bat
生成的 output_lua 目录中即包含所有导出配置数据文件。如下图： 生成的 output_lua 目录包含所有生成的配置数据文件。如下图：
![](docs/images/examples/ex_a2.png) ![](docs/images/examples/ex_a2.png)
bat脚本中的 --output_data_dir 参数为输出lua数据目录，可根据实际情况修改。 命令中的 --output_data_dir 参数为输出的lua数据目录，可根据实际情况修改。
![](docs/images/examples/ex_a3.png) ```
..\src\Luban.Client\bin\Debug\net5.0\Luban.Client.exe ^
-h %LUBAN_SERVER_IP% ^
-j cfg ^
-- ^
-d Defines/root.xml ^
--input_data_dir Datas ^
--output_data_dir output_lua ^
-s client ^
--gen_types data_lua ^
--export_test_data
```
------ ------
## 程序使用示例 ## 代码使用示例
### Lua 使用示例 ### Lua 使用示例

BIN
docs/images/examples/ex_a1.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.2 KiB

After

Width:  |  Height:  |  Size: 5.8 KiB