【更新】更新文档

2021-11-30 15:08:15 +08:00 · 2021-11-30 15:08:15 +08:00 · d686f82ba8
parent d571638970
commit d686f82ba8
3 changed files with 46 additions and 101 deletions
--- a/README.md
+++ b/README.md
@ -23,7 +23,7 @@
 luban相较于常规的excel导表工具有以下核心优势：
 - 增强了excel格式。可以比较简洁地excel配置**任意复杂**的数据，像子结构、结构列表，以及更复杂的深层次的嵌套结构都能直接解析处理。
 - 完备的类型系统和多原始数据支持（excel、xml、json、lua、yaml），可以轻松表达和解析**任意复杂**的数据。意味着传统excel导表工具无法处理的技能、行为树、副本等等复杂配置，luban也能够统一处理了，彻底将程序从复杂的配置解析中解放出来。
- 支持binary、protobuf（同时可以生成相应的pb定义）、json、lua等多种导出数据格式。
+- 支持binary、**protobuf**（同时可以生成相应的pb定义）、**msgpack**、**flatbuffers**、json、lua等多种导出数据格式。
 - 完善的工作流支持。如id的外键引用检查;资源合法性检查;灵活的数据源定义（拆表或者多表合一）;灵活的分组导出机制；多种本地化支持;生成极快（日常迭代300ms以内）；[Excel2TextDiff](https://github.com/focus-creative-games/Excel2TextDiff)工具方便diff查看excel文件的版本间差异；
 - **LubanAssistant Excel插件**。支持把json、lua、xml等文本格式的配置数据加载到excel中，批量编辑处理，最后再保存回原文件，较好地解决大型项目中多人合作数据编辑冲突合并的问题，较好解决在编辑器中制作的配置难以在excel中批量修改的问题。
 - 支持自定义代码与数据模板。强大的数据表达能力使得绝大多数项目的配置格式往往是luban的子集，因而有较低的项目迁移成本，利用模板重新适配代码和数据生成后，即使是研发已久或者上线项目也能从luban强大的数据处理能力中受益。
@ -78,6 +78,7 @@ luban相较于常规的excel导表工具有以下核心优势：
   - python (3.0+)
   - erlang (18+)
   - rust (1.5+)
+   - 其他protobuf、msgpack、flatbuffers支持的语言
 - 支持主流引擎和平台
   - unity + c#
   - unity + [tolua](https://github.com/topameng/tolua)、[xlua](https://github.com/Tencent/xLua)
@ -221,11 +222,15 @@ array与list类型都能表示列表，它们区别在于array生成的代码为
 ```
 或者在 \_\_beans__.xlsx 里定义

-|##|full_name|sep|comment|*fields_name| *fields.type | ...|
-| - | - | - | - | - | - | - |
-|| Reward|||item_id|int||
-|||||count|int||
-|||||desc|string||
+
+<table border="1">
+<tr align="center"><td>##</td><td>full_name</td><td >sep</td><td>comment</td><td colspan="5">fields</td>  </tr>
+<tr align="center"><td>##+</td><td></td><td/><td/><td>name</td><td>type</td><td>group</td><td>comment</td><td>tags</td></tr>
+<tr><td></td><td>Reward</td><td/><td/><td>item_id</td><td>int</td><td></td><td>道具id</td><td/></tr>
+<tr><td></td><td></td><td/><td/><td>count</td><td>int</td><td></td><td>个数</td><td/></tr>
+<tr><td></td><td></td><td/><td/><td>desc</td><td>string</td><td></td><td>描述</td><td/></tr>
+</table>
+

 数据表如下

@ -243,7 +248,7 @@ array与list类型都能表示列表，它们区别在于array生成的代码为
 <tr align="center">
 <td>##</td>
 <td>id</td>
-<td>item id</td><td>count</td><td>desc</td>
+<td>道具id</td><td>个数</td><td>描述</td>
 </tr>
 <tr align="center">
 <td/>
@ -420,9 +425,7 @@ xml中定义如下
 </table>

 ### 引用检查
-游戏配置中经常要填写诸如道具id之类的外键数据，这些数据必须是合法的id值，luban支持生成时检查id的合法性，如果有误，则打出警告。
-
-只要字段定义中添加 ref="表全名" 即可。不只是表顶层字段，列表及嵌套结构的子字段也支持完整的引用检查。
+游戏配置中经常要填写诸如道具id之类的外键数据，这些数据必须是合法的id值，luban支持生成时检查id的合法性，如果有误，则打出警告。不只是表顶层字段，列表及嵌套结构的子字段也支持完整的引用检查。

 ```xml
 <bean name="Reward">
@ -703,6 +706,9 @@ xml中定义如下
 ### 多种导出数据格式
 支持以下几种导出数据格式
 - binary
+- protobuf
+- msgpack
+- flatbuffers
 - json
 - lua
 - erlang
@ -748,74 +754,11 @@ binary格式占空间最小，lua其次，json最大。
 id为1的记录对应的内容如下
 ```json
 {
-  "x4": 1,
-  "x1": true,
-  "x5": 100,
-  "x6": 1.20000005,
-  "s1": "hq",
-  "s2": {
-    "key": "/asfa",
-    "text": "aabbcc"
-  },
-  "v2": {
-    "x": 1,
-    "y": 2
-  },
-  "v3": {
-    "x": 1.10000002,
-    "y": 2.20000005,
-    "z": 3.4000001
-  },
-  "v4": {
-    "x": 10.1000004,
-    "y": 11.1999998,
-    "z": 12.3000002,
-    "w": 13.3999996
-  },
-  "t1": "1990-1-1 00:00:00",
-  "x12": {
-    "x1": 10
-  },
-  "x13": "A",
-  "x14": {
-    "__type__": "DemoD2",
-    "x1": 1,
-    "x2": 2
-  },
-  "k1": [
-    12
-  ],
-  "k8": [
-    [
-      2,
-      2
-    ],
-    [
-      4,
-      10
-    ]
-  ],
-  "k9": [
-    {
-      "y1": 1,
-      "y2": true
-    },
-    {
-      "y1": 2,
-      "y2": false
-    }
-  ],
-  "k15": [
-    {
-      "__type__": "DemoD2",
-      "x1": 1,
-      "x2": 2
-    },
-    {
-      "__type__": "DemoD2",
-      "x1": 2,
-      "x2": 3
-    }
+  "id":1,
+  "x":5,
+  "items":[
+    {"x":1, "y":true, "z":"abcd", "a":{"x":10, "y":100}, "b":[1,3,5]},
+    {"x":2, "y":false, "z":"abcd", "a":{"x":22, "y":33}, "b":[4,5]}
  ]
 }
 ```
@ -892,12 +835,12 @@ println(tables.TbItem.Get(12).Name)

 ## 开发环境架设

- 安装 [VS2019 社区版](https://visualstudio.microsoft.com/zh-hans/vs/)
+- 安装 [VS2022 社区版](https://visualstudio.microsoft.com/zh-hans/vs/)
 - 安装 [.dotnet core sdk 6.0](https://dotnet.microsoft.com/download/dotnet/6.0)

 ## 安装与使用

-参见 [client&server安装与使用说明](docs/luban_install_manual.md)
+参见 [client&server安装与使用说明](docs/luban_command_tools.md)

 ## 如何贡献

--- a/docs/luban_command_tools.md
+++ b/docs/luban_command_tools.md
@ -32,7 +32,7 @@ Luban工具有两种部属方式。

  Client与Server在同个进程内运行，不需要单独部属Luban.Server。

-  将运行脚本中%LUBAN_CLIENT%变量由 Luban.Client/Luban.Client 改为 Luban.ClientServer/Luban.ClientServer，同时删除 -h (--host ) 选项及其参数。
+  将运行脚本中%LUBAN_CLIENT%变量由 Luban.Client/Luban.Client 改为 Luban.ClientServer/Luban.ClientServer，同时**删除 -h (--host ) 选项及其参数**。

  Luban.ClientServer是Luban.Client的功能超集，可以完全替代Luban.Client。

@ -50,6 +50,7 @@ Luban工具有两种部属方式。
    -p, --port <port>               可选参数。 监听端口 <port>，默认为8899。
    -l, --loglevel <log level>      可选参数。 日志级别。默认为INFO。 有效值有: TRACE,DEBUG,INFO,WARN,ERROR,FATAL,OFF
    -t, --template_search_path      可选参数。模板的额外搜索路径。优先从此路径，再从Templates目录搜索模板文件。
+    --i10n:default_timezone  <timezone>       可选参数。 datetime数据转换为UTC时间默认使用的时区。

 ## luban-client 使用介绍

@ -77,7 +78,7 @@ Luban工具有两种部属方式。
    --input_convert_dir <dir>               可选参数。 执行json、lua、xlsx之类数据格式转换时，提供的数据源，覆盖table中默认的input参数。
    -c,--output_code_dir <output code dir>  可选参数。 生成代码文件的目录。
    -s,--service                            必选参数。生成分组目标。一般来说，会定义client,server,editor等好几个目标，不同目标的生成内容不同。
-    --gen_types <type1,type2,,,>            必选参数。生成任务类型。既可以是生成代码也可以是生成数据或者其他。目前支持的有 code_cs_bin,code_cs_json,code_cs_unity_json,code_lua_bin,code_java_bin,code_go_bin,code_go_json,code_cpp_bin,code_python27_json,code_python3_json，code_typescript_bin,code_typescript_json,data_bin,data_lua,data_json,data_json_monolithic,data_template,convert_json,convert_lua,convert_xlsx
+    --gen_types <type1,type2,,,>            必选参数。生成任务类型。既可以是生成代码也可以是生成数据或者其他。目前支持的有 code_cs_bin,code_cs_json,code_cs_unity_json,code_lua_bin,code_java_bin,code_go_bin,code_go_json,code_cpp_bin,code_python27_json,code_python3_json，code_typescript_bin,code_typescript_json,code_rust_json,code_protobuf,data_bin,data_lua,data_json,data_json_monolithic,data_template,data_protobuf,convert_json,convert_lua,convert_xlsx
    --output_data_dir <output data dir>     可选参数。 导出的数据文件的目录。只生成代码时可不指定。
    --output_compact_json                   可选参数。默认导出的json格式为对齐后的优雅格式，使用此参数后导出紧凑的不带空格和换行的格式。
    --validate_root_dir <path validate root dir>. 可选参数。 配置path检查的根目录。
@ -90,13 +91,17 @@ Luban工具有两种部属方式。
    --naming_convention_enum_member <convention>    可选参数。生成代码中enum类型名的命名约定，可用值为 language_recommend,none,camelCase,PascalCase,under_scores。 默认为language_recommend。此选项目前未生效。
    --access_bean_member <access mode>  可选参数。 bean属性的访问方式。可用值为language_recommend,variable,getter_setter,property。默认为 language_recommend。此字段目前未生效。

-    -t,--l10n_timezone <timezone>           可选参数。 指定所在时区。影响datetime类型转换为utc时间。 默认为中国北京时间。
-    --input_l10n_text_files <file1,file2..> 可选参数。 本地化的文本映射表。可以有多个。
-    --l10n_text_field_name <field name>     可选参数。 文本映射表中，目标映射列的列名，默认为text
-    --output_l10n_not_translated_text_file <file> 可选参数。 未被本地化映射的text key和value的输出文件。不提供该参数则不生成
-    --patch <patch name>                  可选参数。当前需要生成的分支名称。
-    --patch_input_data_dir <patch data root dir> 可选参数。分支数据的根目录。
+    --l10n:timezone <timezone>           可选参数。 指定所在时区。影响datetime类型转换为utc时间。 默认为中国北京时间。
+    --l10n:input_text_files <file1,file2..> 可选参数。 本地化的文本映射表。可以有多个。
+    --l10n:text_field_name <field name>     可选参数。 文本映射表中，目标映射列的列名，默认为text
+    --l10n:output_not_translated_text_file <file> 可选参数。 未被本地化映射的text key和value的输出文件。不提供该参数则不生成
+    --l10n:patch <patch name>                  可选参数。当前需要生成的分支名称。
+    --l10n:patch_input_data_dir <patch data root dir> 可选参数。分支数据的根目录。

+    --typescript:bright_require_path <path>     可选参数。生成typescript代码引用的bright模块的路径
+    --typescript:bright_package_name <packet>   可选参数。生成typescript代码以包形式引用bright库的路径
+    --typescript:use_puerts_bytebuf             可选参数。生成typescript代码中使用puerts中导入的c# Bytebuf类。
+    --cs:use_unity_vector                   可选参数。生成c#代码中，使用UnityEngine.Vector{2,3,4}作为Vector数据类型。

 ## 示例

@ -135,8 +140,7 @@ Luban工具有两种部属方式。
        --output_code_dir d:\client\Assets\Gen ^
        --output_data_dir d:\client\Assets\StreamingAssets\GameData ^
        --gen_types code_cs_bin,data_bin ^
-        --service client ^
-        --export_test_data 
+        --service client

    linux bash命令同理。

@ -144,7 +148,7 @@ Luban工具有两种部属方式。

    你要为客户端生成代码和数据。
    你期望使用json格式导出数据类型。
-    你不期望导出数据中包含测试数据
+    你不期望导出数据中包含dev和test标签的数据
        
    则win下命令为:

@ -158,7 +162,8 @@ Luban工具有两种部属方式。
        --output_code_dir d:\client\Assets\Gen ^
        --output_data_dir d:\client\Assets\StreamingAssets\GameData ^
        --gen_types code_cs_unity_json,data_json ^
-        --service client
+        --service client ^
+        --export_exclude_tags dev,test

 案例3：
    
@ -180,8 +185,7 @@ Luban工具有两种部属方式。
        --output_code_dir d:\server\src\Gen ^
        --output_data_dir d:\server\GameData ^
        --gen_types code_cs_json,data_json ^
-        --service server ^
-        --export_test_data
+        --service server
 案例4：

    luban-server 被你部属在 192.168.1.10这台机器上，端口为1111。其他的如案例3。
@ -198,8 +202,7 @@ Luban工具有两种部属方式。
        --output_code_dir d:\server\src\Gen ^
        --output_data_dir d:\server\GameData ^
        --gen_types code_cs_json,data_json ^
-        --service server ^
-        --export_test_data
+        --service server

 案例5：
    
@ -222,8 +225,7 @@ Luban工具有两种部属方式。
        --output_code_dir d:\server\src\Gen ^
        --output_data_dir d:\server\GameData ^
        --gen_types code_cs_json,data_json ^
-        --service server ^
-        --export_test_data    
+        --service server   



--- a/src/Luban.Job.Cfg/Source/GenArgs.cs
+++ b/src/Luban.Job.Cfg/Source/GenArgs.cs
@ -23,7 +23,7 @@ namespace Luban.Job.Cfg
        [Option("output_data_json_monolithic_file", Required = false, HelpText = "output monolithic json file")]
        public string OutputDataJsonMonolithicFile { get; set; }

-        [Option("gen_types", Required = true, HelpText = "code_cs_bin,code_cs_json,code_cs_unity_json,code_lua_bin,code_java_bin,code_java_json,code_go_bin,code_go_json,code_cpp_bin,code_python3_json,code_typescript_bin,code_typescript_json,code_rust_json,data_bin,data_lua,data_json,data_json2,data_json_monolithic,data_resources,data_template,convert_json,convert_lua,convert_xlsx . can be multi")]
+        [Option("gen_types", Required = true, HelpText = "code_cs_bin,code_cs_json,code_cs_unity_json,code_lua_bin,code_java_bin,code_java_json,code_go_bin,code_go_json,code_cpp_bin,code_python3_json,code_typescript_bin,code_typescript_json,code_rust_json,code_protobuf,data_bin,data_lua,data_json,data_json2,data_json_monolithic,data_resources,data_template,data_protobuf,convert_json,convert_lua,convert_xlsx . can be multi")]
        public string GenType { get; set; }

        [Option("template_name", Required = false, HelpText = "template name. use with gen_types=data_template")]
@ -53,10 +53,10 @@ namespace Luban.Job.Cfg
        [Option("l10n:output_not_translated_text_file", Required = false, HelpText = "the file save not translated l10n texts.")]
        public string L10nOutputNotTranslatedTextFile { get; set; }

-        [Option("10n:patch", Required = false, HelpText = "patch name")]
+        [Option("l10n:patch", Required = false, HelpText = "patch name")]
        public string L10nPatchName { get; set; }

-        [Option("10n:patch_input_data_dir", Required = false, HelpText = "patch input data root dir")]
+        [Option("l10n:patch_input_data_dir", Required = false, HelpText = "patch input data root dir")]
        public string L10nPatchInputDataDir { get; set; }
    }
 }