diff --git a/README.md b/README.md index 56a84e3..8de4405 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ luban基于 **meta定义 + 数据源** 的设计，实现了**完备的类型系 Luban适合有以下需求的开发者： - 希望找一个功能完备经受过上线项目检验的满足**中大型**游戏项目配置需求的游戏配置解决方案 +- 希望有较完善的工作流，有效提高策划与程序的开发效率 - 希望针对项目需求方便地定制配置、消息等生成，满足更严苛的内存和性能的要求 - 希望做其他自定义生成或者缓存 @@ -54,13 +55,13 @@ Luban适合有以下需求的开发者： - **强大完备的类型系统**。**可以优雅表达任意复杂的数据结构**。支持所有常见原生类型、datetime类型、容器类型list,set,map、枚举和结构、**多态结构**以及**可空类型**。 - 支持增强的excel格式。可以在excel里比较简洁填写出非常复杂的数据（比如顶层字段包含"list,A"类型字段， 而A是结构并且其中又包含"list,B"类型字段，B也是结构并且包含"list,C"这样的字段...）。 - 生成代码清晰易读、良好模块化。特地支持运行时原子性热更新配置。 -- 使用云生成模式。生成极快，MMORPG这样大型项目也能秒内生成。日常增量生成基本在300ms以内。节省迭代时间。支持watch监测模式，数据目录变化立即重新生成。 +- 生成极快。支持常规的本地缓存增量生成模式，也支持云生成模式。MMORPG这样大型项目也能秒内生成。日常增量生成基本在300ms以内，项目后期极大节省了迭代时间。另外支持**watch监测模式**，数据目录变化立即重新生成。 - 灵活的数据源定义。一个表可以来自多个文件或者一个文件内定义多个表或者一个目录下所有文件甚至来自云表格，以及以上的组合 - 支持表与字段级别分组。可以选择性地导出客户端或者服务器所用的表及字段 - 多种导出数据格式支持。支持binary、json、lua、xml、erlang 等导出数据格式 -- **====>强大灵活的定制能力<====** - - **支持代码模板，可以用自定义模板定制生成的代码格式** - - **支持数据模板，可以用模板文件定制导出格式**。意味着可以在不改动现有程序代码的情况下，把luban当作**配置处理前端**，生成自定义格式的数据与自己项目的配置加载代码配合工作。开发已久的项目或者已经上线的老项目，也能从luban强大的数据处理工作流中获益 +- 强大灵活的定制能力 + - 支持代码模板，可以用自定义模板定制生成的代码格式 + - **支持数据模板**，可以用模板文件定制导出格式。意味着可以在不改动现有程序代码的情况下，把luban当作**配置处理前端**，生成自定义格式的数据与自己项目的配置加载代码配合工作。开发已久的项目或者已经上线的老项目，也能从luban强大的数据处理工作流中获益 - 支持数据标签。 可以选择导出符合要求的数据，发布正式数据时策划不必手动注释掉那些测试数据了 - 强大的数据校验能力。支持内建数据格式检查；支持ref表引用检查（策划不用担心填错id）;支持path资源检查（策划不用担心填错资源路径）;支持range检查 - 支持常量别名。策划不必再为诸如 升级丹 这样的道具手写具体道具id了 @@ -140,60 +141,59 @@ Luban适合有以下需求的开发者： 这儿只简略展示lua、c#、typescript、go语言在开发中的用法，更多语言以及更详细的使用范例和代码见[示例项目](https://github.com/focus-creative-games/luban_examples)。 -- Lua 使用示例 - - ```Lua - -- 访问一个单例表 - print(require("TbGlobal").name) - -- 访问普通的 key-value 表 - print(require("TbItem")[12].x1) - ``` - C# 使用示例 - ```C# - // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 - var tables = new cfg.Tables(file => return new ByteBuf(File.ReadAllBytes(gameConfDir + "/" + file))); - // 访问一个单例表 - Console.WriteLine(tables.TbGlobal.Name); - // 访问普通的 key-value 表 - Console.WriteLine(tables.TbItem.Get(12).X1); - // 支持 operator []用法 - Console.WriteLine(tables.TbMail[1001].X2); - ``` +```C# +// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 +var tables = new cfg.Tables(file => return new ByteBuf(File.ReadAllBytes(gameConfDir + "/" + file))); +// 访问一个单例表 +Console.WriteLine(tables.TbGlobal.Name); +// 访问普通的 key-value 表 +Console.WriteLine(tables.TbItem.Get(12).X1); +// 支持 operator []用法 +Console.WriteLine(tables.TbMail[1001].X2); +``` - typescript 使用示例 - ```typescript - // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 - let tables = new cfg.Tables(f => JsHelpers.LoadFromFile(gameConfDir, f)) - // 访问一个单例表 - console.log(tables.TbGlobal.name) - // 访问普通的 key-value 表 - console.log(tables.TbItem.get(12).x1) - ``` +```typescript +// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 +let tables = new cfg.Tables(f => JsHelpers.LoadFromFile(gameConfDir, f)) +// 访问一个单例表 +console.log(tables.TbGlobal.name) +// 访问普通的 key-value 表 +console.log(tables.TbItem.get(12).x1) +``` - go 使用示例 - ```go - // 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 - if tables , err := cfg.NewTables(loader) ; err != nil { - println(err.Error()) - return - } - // 访问一个单例表 - println(tables.TbGlobal.Name) - // 访问普通的 key-value 表 - println(tables.TbItem.Get(12).X1) +```go +// 一行代码可以加载所有配置。 cfg.Tables 包含所有表的一个实例字段。 +if tables , err := cfg.NewTables(loader) ; err != nil { + println(err.Error()) + return +} +// 访问一个单例表 +println(tables.TbGlobal.Name) +// 访问普通的 key-value 表 +println(tables.TbItem.Get(12).X1) - ``` +``` + +- Lua 使用示例 + +```Lua +-- 访问一个单例表 +print(require("TbGlobal").name) +-- 访问普通的 key-value 表 +print(require("TbItem")[12].x1) +``` ------ ## 配置快速预览 -**luban兼容传统的excel导表工具，可以在excel定义完整的数据表**。与常见的专注于excel的导表工具不同，luban传统做法为定义与数据分离，使用单独的xml定义 **表和结构**，数据文件只包含数据。 - -下面展示完普通兼容例子后，剩余例子都是**定义与数据分离**的传统风格。使用者自己选择是定义与数据混合的方式还是定义与数据分离的方式或者混用两种方式。目前luban_examples项目中大多数示例使用定义与数据分离的方式。 +**luban兼容传统的excel导表工具，可以在excel定义完整的数据表**。与常见的专注于excel的导表工具不同，luban推荐做法为定义与数据分离，使用单独的xml定义 **表和结构**，数据文件只包含数据。 ### 传统兼容横表 @@ -232,7 +232,7 @@ Luban适合有以下需求的开发者：
-### 常规的原生数据 （从本示例起为定义与数据分离的模式） +### 常规的原生数据 （虽然示例中这些表都在xml中定义，实际上它们可以完全只在excel定义） 以下是一个包含所有常见简单原生数据的表。 diff --git a/docs/images/install/install_04.png b/docs/images/install/install_04.png index a965d5c..3b5758b 100644 Binary files a/docs/images/install/install_04.png and b/docs/images/install/install_04.png differ diff --git a/docs/images/install/install_10.png b/docs/images/install/install_10.png new file mode 100644 index 0000000..8a1fe3d Binary files /dev/null and b/docs/images/install/install_10.png differ diff --git a/docs/install.md b/docs/install.md index d2aed4a..12e5a4a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -7,49 +7,44 @@ 下载项目 [luban_examples](https://github.com/focus-creative-games/luban_examples)。 项目中包含测试配置、最新的luban_client&luban_server工作以及大量的示例项目。为方便起见，后续提及到的文件，默认都指这个项目中的文件。 -1. 部属 luban-server - - 基于 docker - - docker run -d --rm --name luban-server -p 8899:8899 focuscreativegames/luban-server:latest - - - 基于 .net 5 runtime （推荐win平台使用，可跨平台，不需要重新编译） - - 从[示例项目](https://github.com/focus-creative-games/luban_examples/tree/main/Tools/Luban.Server)拷贝 Luban.Server（**可跨平台，即使在linux、mac平台也不需要重新编译**） - - 在Luban.Server目录下运行 dotnet Luban.Server.dll - -1. 使用 luban-client - - 基于 docker (推荐 linux、mac平台使用) - - docker run --rm -v $PWD/.cache.meta:/bin/.cache.meta focuscreativegames/luban-client <参数> - - 提醒！ .cache.meta这个文件用于保存本地生成或者提交到远程的文件md5缓存，**强烈推荐** 添加-v 映射，不然每次重新计算所有涉及文件的md5,这可能在项目后期会造成多达几秒的延迟。 - - 基于 .net 5 runtime （推荐win平台使用，可跨平台，不需要重新编译） - - 从[示例项目](https://github.com/focus-creative-games/luban_examples/tree/main/Tools/Luban.Client)拷贝 Luban.Client（**可跨平台，即使在linux、mac平台也不需要重新编译**） - - 在Luban.Client目录下运行 dotnet Luban.Client.dll <参数> - -1. 设置全局环境变量 - - set_global_envs.bat 脚本文件，它会设置全局环境变量 LUBAN_SERVER_IP 为 127.0.0.1。如果你在其他机器上部属luban-server，请将LUBAN_SERVER_IP改为相应地址。 ## 创建游戏配置 1. 创建目录结构 config 为根目录，下面创建两个子目录 Datas 和 Defines，分别用于 存放策划 excel 及各种配置数据 以及 配置定义。 ![如图](images/install/install_01.png) 2. 在 Defines 目录下创建 \_\_root__.xml 根定义文件 - ![如图](images/install/install_02.png) - 可以直接从 [示例配置](https://github.com/focus-creative-games/luban_examples/tree/main/DesignerConfigs/Defines) 拷贝这个文件。 - 这个 root 文件描述了： +```xml + - - 生成代码的默认顶层命名空间为 cfg - - 有 3 个分组 c,s,e 对应 client，server，editor 分组。 分组用于配置选择性导出。后面再介绍。 - - import name=”.” 表明从当前目录导入所有子模块定义文件。我们会把所有子模块定义文件也放到 Defines 目录下。 - - server 表示最终输出的目标。当前定义了 4 个目标。service 的 group 属性指明了这个目标会包含哪些分组。例如： server 目标就只包含 s 分组，而 all 目标包含了所有分组。我们先不细究这些定义的含义。 + -7. 创建第一个配置表 物品表 + + + + -8. 添加物品表 excel 文件 - 我们可以直接在 Datas 目录下添加 物品表.xlsx 文件，不过如果所有表都放到 Datas 目录下，查找起来很不方便。 - 为了方便，我们按模块组织配置文件，在 Datas 目录下新建一个 item 目录，目录下创建一个 “物品表.xlsx” 文件。 + client + server + editor + + + + 补充table表声明。文件相对data目录 + 补充enum定义。相对data目录 + 补充bean定义。相对data目录 + + + + + +``` + +可以直接从 [示例配置](https://github.com/focus-creative-games/luban_examples/tree/main/DesignerConfigs/Defines) 拷贝这个文件。 + + +4. 添加物品表 excel 文件 + 在 Datas 目录下新建一个 item 目录，目录下创建一个 “物品表.xlsx” 文件。 ![如图](images/install/install_03.png) @@ -57,121 +52,87 @@ ![配置](images/install/install_04.png) - - 第 1 行是 meta 行。有一些关于 excel 文件的元描述，默认全空，使用默认默认值即可。 + - 第 1 行是 meta 行，包含关于excel文件的元描述，title_rows:4表示除了meta行外，有4行标题头。 单元格 A1 必须是 ##。表示这是一个有效数据表。 - 第 2 行是程序字段名行。 - - 第 3 行是标题头行。策划自行填写，可留空。 - - 第 4 行是描述行。策划可以填写字段的补充描述。可留空。 - - 从第 5 开始为实际的数据行。如果某个数据行整行为空，则会被跳过。 + - 第3行是属性行。格式为 type&属性1=值1&属性2=值2 ... + - 第 4 行是标题头行。策划自行填写，可留空。 + - 第 5 行是描述行。策划可以填写字段的补充描述。可留空。 + - 从第 6 开始为实际的数据行。如果某个数据行整行为空，则会被跳过。 - 我们定义一个简单的物品表，有 4 个字段。 +然后再在 Datas 目录下的tables.xlsx（请从 DesignerConfigs/Datas目录拷贝过来）添加表声明。如下图： - - id 道具 id - - name 道具名 - - desc 道具描述 - - price 道具购买价格 +![添加声明](images/install/install_10.png) -9. 创建定义 - 我们已经填好了第一个配置表，此时应该会有疑问： - - 1. 字段类型呢？字段类型怎么没有定义啊？ - 2. 生成的代码中相关的类名又在哪儿获得呢？ - 3. 如何导出？最终导出的数据在哪个文件？ 导出文件又是啥格式？ - - --- - 我们正式开始： - - 每个配置表都需要在某个子模块定义文件中添加一个相应的定义描述，每个模块可以包含多个表定义。 - - 我们在 Defines 目录创建 item.xml，item.xml 是一个子模块定义文件，用于包含物品模块的所有结构，枚举及配表定义。接着在 item.xml 里添加物品表相关定义。 - - 文件内容如下： - - ![定义](images/install/install_05.png) - - - 简略介绍一下定义: - - table 是表定义，每个表都有一个对应的表定义。 - - name 表名。推荐采取 TbXXXX 这种名字约定。 - - value 记录的类型。即配置表里每行记录的类型。 - - index 以 value 的哪个字段为主键。这里用 Item 结构里的 id 字段做主键。可为空，默认为第一个字段。 - - input 数据源。这个表的数据文件来源，相对 Datas 目录。可以是多个，以英文分号 ; 分割。 - - bean 用于定义公用结构，同时也用于定义表记录结构。 - - name 类型名。 这儿取 Item，最终生成的 c#代码会使用 cfg.item.Item 这样的类名。 - - var 用于定义字段。 - - name 字段名。推荐统一 xx_yy_zz 这种风格。 - - type 字段类型。 可以是 bool,int,float,string 等等，完整的类型参见链接。 10. 至此,物品表的创建工作大功告成! ## 生成代码和数据以及在程序中使用 -- 根据前后端以及引擎和平台类型以及所用语言，介绍常见组合下，如何生成代码和数据。 - 1. 项目准备。 - 拷贝示例项目中 Csharp_DotNetCore_bin\Core 目录到项目中，可以自由组织位置。 - 此时尝试编译项目，理论上应该能成功编译。 - 2. 运行生成命令 +1. 项目准备。 + +拷贝示例项目中 Csharp_DotNetCore_bin\Core 目录到项目中，可以自由组织位置。 此时尝试编译项目，理论上应该能成功编译。 + +2. 运行生成命令 - - ```bat - - -h 127.0.0.1 ^ - -p 8899 ^ +```bat + dotnet -j cfg ^ --^ --define_file ^ --input_data_dir <配置数据根目录(Datas)的路径>^ - --output_code_dir <输出的代码文件的路径>^ + --output_code_dir <生成的代码文件的路径>^ --output_data_dir <导出的数据文件的路径>^ - --service server^ + --service all^ --export_test_data^ --gen_types "code_cs_bin,data_bin" - ``` + ``` - **============提醒=============** +其中 - **如果你们项目使用json导出格式，需要将 --gen_types的参数改为 "code_cs_json,data_json"** +- 指向 Tools/Luban.ClientServer/Luban.ClientServer.dll +- 指向 Define/__root__.xml - **如果你们项目使用typescript并且json导出格式，需要将 --gen_types的参数改为 "code_typescript_json, data_json"** - 更多语言或者导出类型的组合，请参考 [luban_examples](https://github.com/focus-creative-games/luban_examples) +详细的命令文档请看 [install_manual](./luban_install_manual.md)。 - **=============================** +更多语言或者导出类型的组合，请参考 [luban_examples](https://github.com/focus-creative-games/luban_examples) - 如果一切正常，会产生一系列日志，最终一行是 == succ == 。 - ![类似这样](images/install/install_07.png) - 如果遇到 类似这样的错误，说明服务器未启动。 启动 luban-server 即可。 +如果一切正常，会产生一系列日志，最终一行是 == succ == 。 + +![类似这样](images/install/install_07.png) + + +如果一切顺利。生成的代码文件会在 –output_code_dir 参数指定的 目录中，生成的配置数据会在 –output_data_dir 参数指定的目录中。 +把 –output_code_dir 加入到 项目中，编译。此时应该能编译成功。 + +3. 加载配置 - ![错误例子](images/install/install_08.png) +只需一行代码既可完成所有配置表的加载工具 - 如果一切顺利。生成的代码文件会在 –output_code_dir 参数指定的 目录中，生成的配置数据会在 –output_data_dir 参数指定的目录中。 - 把 –output_code_dir 加入到 项目中，编译。此时应该能编译成功。 +```c# + var tables = new cfg.Tables(file => + new Bright.Serialization.ByteBuf( + System.IO.File.ReadAllBytes( + "/" + file))); +``` - 3. 加载配置 - 只需一行代码既可完成所有配置表的加载工具 +![代码](images/install/install_09.png) - ```c# - var tables = new cfg.Tables(file => - new Bright.Serialization.ByteBuf( - System.IO.File.ReadAllBytes( + "/" + file))); - ``` +4. 使用加载后的配置表 + cfg.Tables 里包含所有配置表的一个实例字段。 + 加载完 cfg.Tables 后，只需要用 tables.<表名> 就能获得那个表实例，接着可以做各种操作。 + 例如我们要访问 id = 1 的那个记录。代码如下 - ![代码](images/install/install_09.png) - 4. 使用加载后的配置表 - cfg.Tables 里包含所有配置表的一个实例字段。 - 加载完 cfg.Tables 后，只需要用 tables.<表名> 就能获得那个表实例，接着可以做各种操作。 - 例如我们要访问 id = 1 的那个记录。代码如下 +```c# + cfg.item.Item itemInfo = tables.TbItem.Get(1); + Console.WriteLine(“{0} {1} {2} {3}”, + itemInfo.Id, itemInfo.X1, itemInfo.X2,itemInfo.X3) +``` - ```c# - cfg.item.Item itemInfo = tables.TbItem.Get(1); - Console.WriteLine(“{0} {1} {2} {3}”, - itemInfo.Id, itemInfo.Name, itemInfo.Desc,itemInfo.Price) - ``` - 可能你会注意到，item.xml 里定义 Item 时，字段名 id,name,desc,price 首字母被大写了。 - 工具会根据输出的语言，自动作相应代码风格的字段名转换，也即 boo_bar 会被转换为 BooBar 这样的名字。 - 这也是为什么推荐 配置字段定义时统一使用 xx_yy_zz 的风格。 +可能你会注意到，item.xml 里定义 Item 时，字段名 id,x1,x2,x3 首字母被大写了。工具会根据输出的语言，自动作相应代码风格的字段名转换，也即 boo_bar 会被转换为 BooBar 这样的名字。这也是为什么推荐 配置字段定义时统一使用 xx_yy_zz 的风格。 5. 至此完成 配置加载与使用! diff --git a/docs/luban_install_manual.md b/docs/luban_install_manual.md index 2d40520..71998b0 100644 --- a/docs/luban_install_manual.md +++ b/docs/luban_install_manual.md @@ -1,7 +1,11 @@ ## 部属 -### 部属 luban-server +Luban工具有两种部属方式。 + +### 方法1： Luban.Client与Luban.Server独立部属，云生成模式 + +#### 部属 luban-server - 基于 docker (强烈推荐以这种方式在服务器上部属luban-server，因为可以充分利用缓存机制大幅缩短生成时间) @@ -10,9 +14,9 @@ - 基于 .net 5 runtime （可跨平台，不需要重新编译） - 自行安装 .net 5 runtime. - 从[示例项目](https://github.com/focus-creative-games/luban_examples/tree/main/Tools/Luban.Server)拷贝 Luban.Server（**可跨平台，即使在linux、mac平台也不需要重新编译**） - - 在Luban.Server目录下运行 dotnet Luban.Server.dll (Win平台可以直接运行 Luban.Server.exe) + - 在Luban.Server目录下运行 dotnet Luban.Server.dll (提示：Win平台可以直接运行 Luban.Server.exe) -### 安装 luban-client +#### 安装 luban-client - 基于 docker (只推荐与jenkins之类devops工具配合使用，因为docker容器启动会增加一定的延迟) docker run --rm -v $PWD/.cache.meta:/bin/.cache.meta focuscreativegames/luban-client <参数> @@ -23,6 +27,16 @@ - 从[示例项目](https://github.com/focus-creative-games/luban_examples/tree/main/Tools/Luban.Client)拷贝 Luban.Client（**可跨平台，即使在linux、mac平台也不需要重新编译**） + +### 方法2： Client与Server一体模式 + + Client与Server在同个进程内运行，不需要单独部属Luban.Server。 + + 将运行脚本中%LUBAN_CLIENT%变量由 Luban.Client/Luban.Client 改为 Luban.ClientServer/Luban.ClientServer，同时删除 -h (--host ) 选项及其参数（如果指定了-h选项，则不启动内嵌Luban.Server，使用云生成）。 + + Luban.ClientServer是Luban.Client的功能超集，可以完全替代Luban.Client。 + + ----- ## 使用