From c77d29730f3e65d5c9ef2ce953df676f18bdf6ee Mon Sep 17 00:00:00 2001 From: bug Date: Mon, 16 Nov 2020 00:55:20 +0800 Subject: [PATCH] update doc --- README.md | 110 ++++++++++++++++++++++------------------- docs/data_excel.md | 121 +++++++++++++++++++++++++++++++++++++++------ docs/faq.md | 9 ++++ 3 files changed, 174 insertions(+), 66 deletions(-) create mode 100644 docs/faq.md diff --git a/README.md b/README.md index 321c482..d4dcdb6 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,89 @@ -[//]: # (Author: bug) -[//]: # (Date: 2020-10-20 20:24:07) +[//]: # "Author: bug" +[//]: # "Date: 2020-10-20 20:24:07" # Luban -[![license](http://img.shields.io/badge/license-MIT-blue.svg)] + +[![license](http://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Build Status](https://travis-ci.com/focus-creative-games/luban.svg?branch=main)](https://travis-ci.com/focus-creative-games/luban) ![](docs/images/icon.png) ## 介绍 - - Luban 是一个强大的配置生成与缓存工具。 - - Luban 最初是为了解决传统excel导出工具功能过于薄弱，无法很好处理 MMORPG 游戏复杂配置需求的痛点问题。 - - 生成目标可以是常规代码、配置数据、类似 protobuf 的消息代码，也可以是游戏资源如 assetbundle。 - - 在大型项目中，由于配置或资源数据庞大，生成对象可能会花费相当多的时间。 - - 比如一个典型的MMORPG项目，后期全量生成配置，即使用了多线程加速，所需时间也在10秒的级别。 - - 因此除了使用缓存，还使用了 client/server 模式，来加速生成过程。 - - 自2015年以来，经历过 MMORPG、卡牌、SLG 等多个上线项目的考验， - - 实际项目过程中不断迭代和优化，最终由一个增强型的配置工具成为一个相对完备的游戏配置数据解决方案。 +- Luban 是一个强大的配置生成与缓存工具。 +- Luban 最初是为了解决传统 excel 导出工具功能过于薄弱，无法很好处理 MMORPG 游戏复杂配置需求的痛点问题。 +- 生成目标可以是常规代码、配置数据、类似 protobuf 的消息代码，也可以是游戏资源如 assetbundle。 +- 在大型项目中，由于配置或资源数据庞大，生成对象可能会花费相当多的时间。 + - 比如一个典型的 MMORPG 项目，后期全量生成配置，即使用了多线程加速，所需时间也在 10 秒的级别。 + - 因此除了使用缓存，还使用了 client/server 模式，来加速生成过程。 +- 自 2015 年以来，经历过 MMORPG、卡牌、SLG 等多个上线项目的考验， +- 实际项目过程中不断迭代和优化，最终由一个增强型的配置工具成为一个相对完备的游戏配置数据解决方案。 -## 文档 -* [主页](https://focus-creative-games.github.io/luban/index.html) -* 各语言的简介: [English](README.en-us.md), [简体中文](README.md) -* [特性](docs/traits.md) -* [使用说明](docs/catalog.md) +## 快速布署一个 lua 例子 + * [下载例子]并解压至临时目录 + * 双击 bat 生成 ## 使用示例 - * Lua 使用示例 - ``` Lua - local data = require("TbDataFromJson") - local cfg = data[32] - print(cfg.name) - ``` - - * C# 使用示例 - ``` C# - // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 - var tables = new cfg.Tables(file => return new ByteBuf(File.ReadAllBytes("output_data/" + file))); - // 访问一个单例表 - Console.WriteLine(tables.TbSingleton.Name); - // 访问普通的 key-value 表 - Console.WriteLine(tables.TbDataFromJson.Get(12).X1); - // 访问 双键表 - Console.WriteLine(tables.TbTwoKey.Get(1, 10).X8); - ``` - * [更多语言的例子](docs/samples.md) + +- Lua 使用示例 + ```Lua + local data = require("TbDataFromJson") + local cfg = data[32] + print(cfg.name) + ``` +- C# 使用示例 + ```C# + // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 + var tables = new cfg.Tables(file => return new ByteBuf(File.ReadAllBytes("output_data/" + file))); + // 访问一个单例表 + Console.WriteLine(tables.TbSingleton.Name); + // 访问普通的 key-value 表 + Console.WriteLine(tables.TbDataFromJson.Get(12).X1); + // 访问 双键表 + Console.WriteLine(tables.TbTwoKey.Get(1, 10).X8); + ``` +- [更多语言的例子](docs/samples.md) + + +## 文档 + +- [主页](https://focus-creative-games.github.io/luban/index.html) +- [特性](docs/traits.md) +- [使用说明](docs/catalog.md) +- [常见问题](docs/faq.md) ## RoadMap -- [ ] 新增 unity 内置编辑器 -- [ ] 新增 unreal 内置编辑器 -- [ ] 补充单元测试 -- [ ] 支持多国家和地区本地化所需的表merge操作 -## 布署 - TODO +- [ ] 新增 unity 内置编辑器 +- [ ] 新增 unreal 内置编辑器 +- [ ] 补充单元测试 +- [ ] 支持多国家和地区本地化所需的表 merge 操作 ## 开发环境架设 -* 安装 VS2019 社区版 -* 安装 .dotnet core sdk 3.1 + +- 安装 [VS2019 社区版](https://visualstudio.microsoft.com/zh-hans/vs/) +- 安装 [.dotnet core sdk 3.1](https://dotnet.microsoft.com/download/dotnet-core/3.1) ## 如何贡献? -* [Contributing](CONTRIBUTING.md) explains what kinds of changes we welcome + +- [Contributing](CONTRIBUTING.md) explains what kinds of changes we welcome - [Workflow Instructions](docs/workflow/README.md) explains how to build and test ## Useful Links -* [.NET Core source index](https://source.dot.net) -* 社区的其它实现 - * [tabtoy](https://github.com/davyxu/tabtoy) +- [.NET Core source index](https://source.dot.net) +- 社区的其它实现 + - [tabtoy](https://github.com/davyxu/tabtoy) ## 支持和联系 - QQ 群: 692890842 - 邮箱: taojingjian#gmail.com - + +``` + QQ 群: 692890842 + 邮箱: taojingjian#gmail.com +``` + ## License Luban is licensed under the [MIT](LICENSE.TXT) license. diff --git a/docs/data_excel.md b/docs/data_excel.md index b058ca8..5f6b494 100644 --- a/docs/data_excel.md +++ b/docs/data_excel.md @@ -78,11 +78,11 @@ - 之前用 bean 来定义结构，我们引入的新的 tag “enum” 来定义 枚举。 - enum 的 name 属性表示 枚举名。 - 如果生成 c#代码的话，会生成 cfg.item.Equality 类。 -- ``` ``` 为检举项。 +- `` 为检举项。 - 其中 name 为必填项，不可为空，也不能重复。 - alias 是可选项，枚举项别名。 - value 是枚举值，主要给程序使用。 -- [完整用法](images/adv/def_10.png) +- [完整用法](images/adv/def_10.png) ``` @@ -106,8 +106,17 @@ - 有时候希望一个字段是复合类型。 - 比如，我们想用一个字段 level_range 来表示道具可以使用的等级范围，它包含两个字段，最小等级和最大等级。 -- 此时，可以通过定义 bean 来解决。 - ![如图](images/adv/def_12.png) +- 此时，可以通过定义 bean 来解决。 + [定义](images/adv/def_12.png) + ``` + + + + + + + + ``` - 之前的字段都在一个单元格内填写，现在这个字段是 bean 类型，有两个值，该怎么填写呢？ 如果也像 list,int 那样把两个数写在一个单元格里(如下图)，会发现工具报错了: “10,20” 不是合法的整数值。 ![如图](images/adv/def_13.png) @@ -116,8 +125,17 @@ 让 level_range 标题头占据两列，这样就能在两个单元格里分别填写最小最大等级了。 ![如图](images/adv/def_14.png) 2. 使用 sep 分割单元格 - 字段定义中指定 sep 属性，用某些字符分割单元格，这样就能识别为两个整数了。 - ![如图](images/adv/def_15.png) + 字段定义中指定 sep 属性，用某些字符分割单元格，这样就能识别为两个整数了。 + [定义](images/adv/def_15.png) + ``` + + + + + + + + ``` 如果想用 分号; 或者 竖号 | 分割，只要 sep=”;” 或者 sep=”|“ 即可。 ![如图](images/adv/def_16.png) @@ -125,23 +143,66 @@ - 有些时候，我们需要一个 结构列表字段。 比如说 道具不同等级会增加不同的血量。我们定义一个 ItemLevelAttr 结构。 - ![如图](images/adv/def_17.png) -- 对应的 excel 配置如下。 + [定义](images/adv/def_17.png) + + ``` + + + + + + + + + + + + ``` + + 配置: ![如图](images/adv/def_18.png) + - 对于多个值构成的字段，填写方式为 在标题头(level_attrs)对应的列范围内，按顺序填值。不需要跟策划的标题头名有对应关系。空白单元格会被忽略。也就是如下填法也是可以的： ![如图](images/adv/def_19.png) - 这种填法的缺点是占据在太多的列。如果想如下填，该怎么办呢？ ![如图](images/adv/def_20.png) - 有两种办法。 1. bean ItemLevelAttr 增加属性 sep=”,” - ![如图](images/adv/def_21.png) + [定义](images/adv/def_21.png) + ``` + + + + + ``` 如果不想用逗号”,” ，想用;来分割单元格内的数据，只要将 sep=”;” 即可。 2. 字段 level_attrs 增加属性 sep=”,”，即 - ![如图](images/adv/def_22.png) + [定义](images/adv/def_22.png) + ``` + + + + + + + + ``` 如果想所有数据都在一个单元格内填写，又该怎么办呢？ ![如图](images/adv/def_23.png) - 想用 | 来分割不同 ItemLevelAttr ,用 , 来分割每个记录的数据。只需要 字段 level_attrs 的 sep=”,|” 即可。 - ![如图](images/adv/def_24.png) + 想用 | 来分割不同 ItemLevelAttr ,用 , 来分割每个记录的数据。只需要 字段 level_attrs 的 sep=”,|” 即可。 + [定义](images/adv/def_24.png) + ``` + + + + + + + + ``` ## 多态 bean @@ -151,12 +212,40 @@ - 假设 item 有一个形状 Shape 类型的字段。Shape 有两种 Circle 和 Rectangle. Cicle 有 2 个字段 int id; float radius; Rectangle 有 3 个字段 int id; float width; float height; - ![如图](images/adv/def_25.png) + [定义](images/adv/def_25.png) + ``` + + + + + + + + + + + + + + ``` + 配置: ![如图](images/adv/def_26.png) - 注意到，多态 bean 与普通 bean 填写区别在于，多态 bean 需要一个类型名。这也好理解，如果没有类型名，如何知道使用哪个 bean 呢。 -- 有时间策划不太习惯填写英文，或者说类型名有时候会调整，不希望调整类型名后配置也跟着改变，因为，多态 bean 支持别名的概念。 - ![如图](images/adv/def_27.png) -- 这时，可以这样填数据： +- 有时间策划不太习惯填写英文，或者说类型名有时候会调整，不希望调整类型名后配置也跟着改变，因为，多态 bean 支持别名的概念。 + [定义](images/adv/def_27.png) + ``` + + + + + + + + + + + ``` +- 配置 ![如图](images/adv/def_28.png) - 使用类型名和别名来标识多态都是支持的，可以混合使用。 diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..6310ce7 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,9 @@ +[//]: # (Author: bug) +[//]: # (Date: 2020-11-15 23:59:21) + + +## 为什么要使用"客户端/服务器"模式 + * 配置文件需要反复生成与测试 + * 文件数量上升后，配置生成不可避免地变慢 + * 再快的技术，也挡不住大量数据的处理 + * 效率就是生命 \ No newline at end of file