Skip to content

Commit 619f478

Browse files
pirunxipirunxi
committed
重构和完善了luban新手文档
1 parent 6c258f1 commit 619f478

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1010
-152
lines changed

‎docs/beginner/addtoproject.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# 接入Luban到项目
2+
3+
## 安装 dotnet SDK
4+
5+
按[快速上手](./quickstart)要求，安装[dotnet sdk 8.0](https://dotnet.microsoft.com/download/dotnet/8.0)。
6+
7+
## 下载[luban_examples项目](https://github.com/focus-creative-games/luban_examples)
8+
9+
使用git clone或者下载zip的方式下载luban_examples项目。
10+
11+
## 编译Luban（可选）
12+
13+
一般来说`luban_examples/Tools/Luban`目录已经包含了最新的Luban二进制代码。如果想自己编译，按以下步骤：
14+
15+
- 将[Luban](https://gitee.com/focus-creative-games/luban) Clone到luban_examples同级目录（即luban和luban_examples在同一个目录下），目录名必须为luban
16+
- 运行 `luban_examples/Tools/build-luban.bat`
17+
18+
如果一切顺利，`luban_examples/Tools/Luban`目录会替换为Luban最新版本的二进制代码。
19+
20+
## 复制Luban工具到你的项目
21+
22+
大多数项目一般有一个专用目录放这些第三方的工具，比如说 `{proj}/Tools`，将`luban_examples/Tools/Luban`复制到任意合适的目录即可。
23+
24+
## 创建策划配置目录
25+
26+
将`luban_examples/MiniTemplate`复制到项目的合适位置，如`{proj}`。建议将MiniTemplate改名为DataTables或者别的名字，MiniTemplates下的子目录建议保持原名。
27+
28+
## 修改luban.conf
29+
30+
每个项目的Luban工具的位置不同，需要修改`gen.bat`（或gen.sh）命令中Luban.dll的路径。假设你将MiniTemplate目录复制到了你项目的`{DataTables}`目录。
31+
打开`DataTbles\luban.conf`，将`set LUBAN_DLL=%WORKSPACE%\Tools\Luban\Luban.dll`中`%WORKSPACE%\Tools\Luban\Luban.dll`替换成实际的Luban.dll的目录。
32+
Luban.dll在Luban工具目录下。
33+
34+
此时运行 `{DataTables}/gen.bat`，确保可以正确运行。
35+
36+
## 新增客户端和服务器的gen.bat脚本
37+
38+
在客户端的合适位置创建 gen_client.bat脚本，内容大致如下：
39+
40+
```bat
41+
set GEN_CLIENT={Luban.dll的路径}
42+
set CONF_ROOT={DataTables目录的路径}
43+
44+
dotnet %GEN_CLIENT% ^
45+
-t client ^
46+
-c cs-simple-json ^
47+
-d json ^
48+
--conf %CONF_ROOT%\luban.conf ^
49+
-x outputCodeDir={生成的代码的路径} ^
50+
-x outputDataDir={生成的数据的路径}
51+
52+
```
53+
54+
请根据实际所用的语言和导出数据格式替换 `-c cs-simple-json`和`-d json`。
55+
56+
:::warning
57+
58+
Luban生成时会删除outputCodeDir目录下的所有其他文件，请为它提供一个单独的目录，千万不要指向`Assets/Scripts`目录，它会删除掉其他代码文件！outputDataDir同理。
59+
60+
:::
61+
62+
在服务器的合适位置创建 gen_server.bat脚本，内容大致如下：
63+
64+
```bat
65+
set GEN_CLIENT={Luban.dll的路径}
66+
set CONF_ROOT={DataTables目录的路径}
67+
68+
dotnet %GEN_CLIENT% ^
69+
-t server ^
70+
-c cs-dotnet-json ^
71+
-d json ^
72+
--conf %CONF_ROOT%\luban.conf ^
73+
-x outputCodeDir={生成的代码的路径} ^
74+
-x outputDataDir={生成的数据的路径}
75+
76+
```
77+
78+
请根据实际所用的语言和导出数据格式替换 `-c cs-dotnet-json`和`-d json`。
79+
80+
81+
## 运行时加载配置
82+
83+
请看下一节[运行时加载配置](./loadinruntime)。

‎docs/beginner/generatecodeanddata.md

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# 生成代码和数据
2+
3+
Luban不仅支持导出配置数据，也内置支持生成多种语言的代码，用于运行时加载配置。同时Luban也支持protobuf、flatbuffers、msgpack等流行的消息框架。
4+
你使用的语言即使不在默认支持的语言列表，也可以通过这些消息框架来支持。
5+
6+
## 支持的语言
7+
8+
- c++ (11+)
9+
- c# (.net framework 2+. dotnet core 2+)
10+
- java (1.6+)
11+
- go (1.10+)
12+
- lua (5.1+)
13+
- typescript (3.0+)
14+
- python (2.7+ 及 3.0+)
15+
- gdscript (4.0+)
16+
- php
17+
- rust
18+
19+
## 支持数据格式
20+
21+
- bin （**推荐用于正式发布的项目**）
22+
- json
23+
- lua
24+
- xml
25+
- yaml
26+
27+
## 生成数据
28+
29+
命令行参数 `-d {dataTarget}`用于指定生成的数据类型，参数`-x outputDataDir={dataOutputDir}`用于指定代码输出目录。假设我们要生成json数据，示例如下：
30+
31+
```bat
32+
set GEN_CLIENT={Luban.dll的路径}
33+
set CONF_ROOT={DataTables目录的路径}
34+
35+
dotnet %GEN_CLIENT% ^
36+
-t client ^
37+
-d json ^
38+
--conf %CONF_ROOT%\luban.conf ^
39+
-x outputDataDir=..\GenerateDatas\json
40+
41+
pause
42+
```
43+
44+
更多的dataTarget可见 [DataTarget列表](../manual/commandtools.md#data-target)。
45+
46+
## 生成代码
47+
48+
命令行参数 `-c {codeTarget}`用于指定生成的代码类型，参数 `-x outputCodeDir={codeOutputDir}`用于指定代码输出目录。假设我们要生成加载json数据的c#代码，示例如下：
49+
50+
```bat
51+
52+
set GEN_CLIENT={Luban.dll的路径}
53+
set CONF_ROOT={DataTables目录的路径}
54+
55+
dotnet %GEN_CLIENT% ^
56+
-t client ^
57+
-c cs-simple-json ^
58+
--conf %CONF_ROOT%\luban.conf ^
59+
-x outputCodeDir=Assets/Gen
60+
61+
pause
62+
```
63+
64+
codeTarget `cs-simple-json`中`cs`表示生成c#语言代码，`simple`表示使用SimpleJson加载json文件，`json`表示加载json数据。所有的codeTarget都遵循这个命名规则。
65+
66+
对于同一种数据格式（如json）,为所有语言生成的数据文件都是一样的。也就是导出数据不受`-c`参数影响。
67+
68+
更多的codeTarget可见 [CodeTarget列表](../manual/commandtools.md#code-target)。
69+
70+
:::warning
71+
72+
请不将`outputCodeDir`和`outputDataDir`指向相同目录，它们会互相覆盖！
73+
:::
74+
75+
## 同时生成代码和数据
76+
77+
运行两次命令分别生成代码和数据不仅麻烦，也增加了生成时间。Luban支持一次生成代码和数据，示例如下：
78+
79+
```bat
80+
81+
set GEN_CLIENT={Luban.dll的路径}
82+
set CONF_ROOT={DataTables目录的路径}
83+
84+
dotnet %GEN_CLIENT% ^
85+
-t client ^
86+
-c cs-simple-json ^
87+
-d json ^
88+
--conf %CONF_ROOT%\luban.conf ^
89+
-x outputCodeDir=Assets/Gen ^
90+
-x outputDataDir=..\GenerateDatas\json
91+
```
92+
93+
一次性生成多种语言和数据格式也是可以的，只要指定多个`-c`和`-d`参数即可，不过要求它们必须是相同的分组（即-t 参数相同）。很显然，它们不应该被输出到相同目录。Luban支持[层级参数机制](../manual/cascadingoption)，当有多个codeTarget或者dataTarget
94+
时，可以通过`{codeTarget}.outputCodeDir=xxx`和`{dataTarget}.outputDataDir=xxx`来分别指定它们的输出目录。示例如下：
95+
96+
```bat
97+
set GEN_CLIENT={Luban.dll的路径}
98+
set CONF_ROOT={DataTables目录的路径}
99+
100+
dotnet %GEN_CLIENT% ^
101+
-t client ^
102+
-c cs-simple-json ^
103+
-c cs-bin ^
104+
-d json ^
105+
-d bin ^
106+
--conf %CONF_ROOT%\luban.conf ^
107+
-x cs-simple-json.outputCodeDir=Assets/Gen/Json ^
108+
-x bin.outputCodeDir=Assets/Gen/Bin ^
109+
-x cs-simple-json.outputDataDir=..\GenerateDatas\json ^
110+
-x bin.outputDataDir=..\GenerateDatas\bin
111+
112+
```
113+
114+
:::warning
115+
116+
请不将多个`outputCodeDir`指向相同目录，也不要将多个`outputDataDir`指向相同目录，它们会互相覆盖！
117+
:::

‎docs/beginner/loadinruntime.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# 运行时加载配置
2+
3+
我们已经在[Projects](https://github.com/focus-creative-games/luban_examples/tree/main/Projects)下提供了大量示例项目。
4+
5+
我们以最常见的 Unity + c# + json 为例，示例项目为 [Csharp_Unity_Json](https://github.com/focus-creative-games/luban_examples/tree/main/Projects/Csharp_Unity_json)，
6+
其他类型请参考 Projects目录下的相应项目。
7+
8+
## 安装 com.code-philosophy.luban
9+
10+
在Package Manager中安装com.code-philosophy.luban包，地址 `https://gitee.com/focus-creative-games/luban_unity.git`或`https://github.com/focus-creative-games/luban_unity.git`。
11+
12+
## 生成代码和配置
13+
14+
请根据[接入Luban到项目](./addtoproject)文档接入Luban，同时准备好相应的生成脚本gen.bat。如果有疑惑，可以参考 `Csharp_Unity_Json`项目的`gen.bat`文件。
15+
16+
运行该脚本，如果一切正常，会产生一系列日志，最终一行是 `bye~`。
17+
18+
:::warning
19+
20+
Luban生成时会删除outputCodeDir目录下的所有其他文件，请为它提供一个单独的目录，千万不要指向`Assets/Scripts`目录，它会删除掉其他代码文件！outputDataDir同理。
21+
22+
:::
23+
24+
## 加载配置
25+
26+
只需一行代码即可加载所有配置表。整个游戏运行期间只加载一次（除非要运行中重新加载配置）。实践中在创建tables后将它保存起来，以便后续使用。
27+
28+
```csharp
29+
30+
string gameConfDir = "<outputDataDir>"; // 替换为gen.bat中outputDataDir指向的目录
31+
var tables = new cfg.Tables(file => JSON.Parse(File.ReadAllText($"{gameConfDir}/{file}.json")));
32+
33+
```
34+
35+
:::tips
36+
37+
默认生成的代码不支持异步加载，而在android之类的平台不能直接读取StreamingAssets目录，因此需要自己做一些特殊处理，比如先将所有配置数据文件加载到内存后再使用`new Tables`加载。
38+
39+
你可以通过修改[代码模板](../manual/template)来支持异步加载。
40+
41+
:::
42+
43+
## 使用配置
44+
45+
cfg.Tables 里包含所有配置表的一个实例字段。加载完 cfg.Tables 后，用 `tables.<表名>` 获得那个表实例，接着对该表做后续操作。
46+
例如我们要打印Reward表id = 1001 的那个奖励信息，代码如下：
47+
48+
```csharp
49+
cfg.demo.Reward reward = tables.TbReward.Get(1001);
50+
Console.WriteLine("reward:{0}", reward);
51+
```
52+
53+
你可能会注意到，reward表字段名 id,name,desc的首字母被大写了。这是因为工具会根据输出的语言，自动作相应代码风格的字段名转换，也即 boo_bar 会被转换为 BooBar 这样的名字。
54+
因此推荐配置中字段名时统一使用 xx_yy_zz 的风格。
55+
56+

‎docs/beginner/quickstart.md

Lines changed: 6 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
## 准备配置工程
1515

16-
直接使用luban_examples项目中的MiniTemplate，后续操作在此基础上修改。你也可以复制MiniTemplate到其他目录后再作修改，但需要修改 `MiniTemplate/gen.bat`文件中相关路径。
16+
直接使用luban_examples项目中的MiniTemplate，后续操作在此基础上修改。
1717

1818
## 创建Reward表
1919

@@ -40,73 +40,12 @@ luban并没有限制标题头行的位置和数量。像`##xxx`之类的行可
4040

4141
至此完成reward表的创建工作！
4242

43-
## 项目准备
43+
## 生成配置数据
4444

45-
以最常见的 unity + c# + json 为例。示例参考项目为 [Csharp_Unity_Json](https://github.com/focus-creative-games/luban_examples/tree/main/Projects/Csharp_Unity_json)，
46-
其他类型请参考 Projects目录下的相应项目。
45+
直接运行`MiniTemplate/gen.bat`（Win平台）或`MinTemplate/gen.sh`(MacOS或者Linux平台)。
4746

48-
在Package Manager中安装com.code-philosophy.luban包，地址 `https://gitee.com/focus-creative-games/luban_unity.git`或`https://github.com/focus-creative-games/luban_unity.git`(或者从`https://github.com/focus-creative-games/luban_unity`下载)。
47+
如果运行成功，命令行界面会类似这样，以一个`byte~`结束。
4948

49+
![gen](/img/gen.jpg)
5050

51-
## 准备生成脚本
52-
53-
:::warning
54-
如果你的excel文件目录不像MiniTemplates那样为luban.conf文件同级目录的Datas目录，则需要修改luban.conf中的dataDir字段。
55-
:::
56-
57-
创建`gen.bat`文件，放到项目下（位置无要求）。
58-
59-
```bat
60-
61-
set LUBAN_DLL=<Luban.dll路径>
62-
set CONF_ROOT=<DataTables路径>
63-
64-
dotnet %LUBAN_DLL% ^
65-
-t client ^
66-
-c cs-simple-json ^
67-
-d json ^
68-
--conf %CONF_ROOT%\luban.conf ^
69-
-x outputCodeDir=<cs代码输出目录> ^
70-
-x outputDataDir=<json数据输出目录>
71-
72-
pause
73-
```
74-
75-
简单介绍bat文件中各项参数：
76-
77-
- LUBAN_DLL Luban.dll文件的路径。 指向 `luban_examples/Tools/Luban/Luban.dll`
78-
- CONF_ROOT 配置项目的路径。指向 `luban_examples/DataTables`
79-
- '-t' 生成目标。可以为 client、server、all之类的值
80-
- '-c' 生成的代码类型。 `cs-simple-json`为生成使用SimpleJSON加载json数据的c#代码
81-
- '-d' 生成的数据类型
82-
- 'outputCodeDir' c#代码的输出目录
83-
- 'outputDataDir' json数据的输出目录
84-
85-
调整bat文件中各项配置路径为恰当的值。如果有疑惑，可以参考 `Csharp_Unity_Json`项目的`gen.bat`文件。运行该脚本，如果一切正常，会产生一系列日志，最终一行是 `bye~`。
86-
87-
## 加载配置
88-
89-
只需一行代码即可加载所有配置表。整个游戏运行期间只加载一次（除非要运行中重新加载配置）。实践中在创建tables后将它保存起来，以便后续使用。
90-
91-
```csharp
92-
93-
string gameConfDir = "<outputDataDir>"; // 替换为gen.bat中outputDataDir指向的目录
94-
var tables = new cfg.Tables(file => JSON.Parse(File.ReadAllText($"{gameConfDir}/{file}.json")));
95-
96-
```
97-
98-
## 使用配置
99-
100-
cfg.Tables 里包含所有配置表的一个实例字段。加载完 cfg.Tables 后，用 `tables.<表名>` 获得那个表实例，接着对该表做后续操作。
101-
例如我们要打印Reward表id = 1001 的那个奖励信息，代码如下：
102-
103-
```csharp
104-
cfg.demo.Reward reward = tables.TbReward.Get(1001);
105-
Console.WriteLine("reward:{0}", reward);
106-
```
107-
108-
你可能会注意到，reward表字段名 id,name,desc的首字母被大写了。这是因为工具会根据输出的语言，自动作相应代码风格的字段名转换，也即 boo_bar 会被转换为 BooBar 这样的名字。
109-
因此推荐配置中字段名时统一使用 xx_yy_zz 的风格。
110-
111-
至此完成配置使用示例!
112-
51+
在`MiniTemplate/output`目录下生成了json配置数据，可自行打开查看。

‎docs/beginner/streamandcolumnformat.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# 使用流式与列限定格式
2+
3+
像结构与容器都是包含多个元素的数据类型，Luban提供了4种方式读取这种复合数据类型：
4+
5+
- 流式格式，多个单元格，按顺序读取
6+
- 流式格式，一个单元格，使用分割符分割后按顺序读取
7+
- 限定列格式，多个单元格，显式指定每个字段所占的列，然后读取
8+
- 多行读取。此方式只对容器类型有效。 读取元素时可以使用以上三种方式读取
9+
10+
详细数据文档见[Excel格式（高级）](../manual/exceladvanced)。
11+
12+
## 预备工作
13+
14+
假设Item结构包含两个字段， item_id和count。我们在后面演示Item结构相关的流式与列限定模式用法。
15+
16+
## 流式格式，多个单元格，按顺序读取
17+
18+
流式格式有个特点：它按顺序读取复合数据的每个元素（字段）。由于它无法限定每个字段的范围，它会跳过读到的所有空白单元格。
19+
当字段不多时，这个并不是问题，可当字段变多时，很容易因为漏填了一个字段导致后续字段读取错误。
20+
21+
如以下item字段的填法，无论是在开始、中间、最后插入一个空单元格，都不影响数据读取。
22+
23+
![item](/img/use_stream1.jpg)
24+
25+
## 流式格式，一个单元格，使用分割符分割后按顺序读取
26+
27+
使用sep分割后，将每个数据当作一个单元格，它的填法与第一种方法相同。
28+
29+
![item](/img/use_stream2.jpg)
30+
31+
## 限定列格式，多个单元格，显式指定每个字段所占的列，然后读取
32+
33+
通过新增子标题头行来为结构指定子字段的列。子标题头行第一列必须是'##var'。
34+
35+
![item](/img/use_column.jpg)
36+
37+
:::tip
38+
39+
限定列格式可以有多层*：即如果结构的某个子字段也是结构，仍然可以新增一行子标题头行，为子字段的子字段指定列。
40+
41+
:::
42+
43+
## 多行读取
44+
45+
只有容器类型才能使用多行读取方式。在字段名前加'*'，表示此字段以多行方式读取。在读取每行数据时，既支持流式格式，也支持列限定格式。
46+
47+
![item](/img/use_rows.jpg)

0 commit comments

Comments
 (0)