代码与数据生成
支持的平台、引擎和语言
- 跨平台
- Win
- Mac
- Linux (包括WSL)
- 支持主流的游戏开发语言
- c++ (11+)
- c# (.net framework 4+. dotnet core 3+)
- java (1.6+)
- go (1.10+)
- lua (5.1+)
- js 和 typescript (3.0+)
- python (3.0+)
- erlang (18+)
- rust (1.5+)
- 其他protobuf支持语言
- 支持主流的引擎
- unity
- unreal
- cocos2d-x
- 微信小游戏平台
- 其他家支持js的小游戏平台
- 支持主流的热更新方案
- xlua
- tolua
- slua
- ILRuntime
- sluaunreal
- puerts
- XIL
- 支持主流的开源框架
- skynet
- ET
- GameFramework
- xlua-framework
支持的数据格式
- binary 格式。 格式紧凑,加载高效,但基本不具体可读性。推荐只用于正式发布。
- json 格式。 可读性佳。支持优雅对齐格式,也支持紧凑格式。 推荐用于服务器端,以及用于客户端开发期。
- protobuf 格式。适用于熟悉pb的开发者。
- msgpack 格式。
- lua 格式。 可读性佳。 推荐仅用于客户端脚本语言为lua的情形。
- xml 格式。
- erlang格式。 仅用于 erlang语言。
- yaml格式。
- 其他格式。很容易扩展支持。
同一种格式,为不同语言生成的数据是完全相同的
不同语言支持的格式如下:
language | binary | json | lua |
---|---|---|---|
c# | ✔️ | ✔️ | |
java | ✔️ | ✔️ | |
go | ✔️ | ✔️ | |
c++ | ✔️ | ❌ | |
go | ✔️ | ✔️ | |
python | ✔️ | ✔️ | |
typescript | ✔️ | ✔️ | |
rust | ❌ | ✔️ | |
lua | ✔️ | ❌ | ✔️ |
erlang | erlang | ||
protobuf | ✔️ | ✔️ |
生成代码和数据
代码生成相关的工具有三个,都在luban_examples/Tools目录下。
- Luban.Client。 Luban工具客户端
- Luban.Server。 Luban工具服务器端
- Luban.ClientServer。 Luban工具前后端一体。
对于新手简单起见,我们介绍Luban.ClientServer的用法,命令如下:
dotnet %LUBAN_CLIENT_SERVER_DLL% -j cfg -- ^
-d %ROOT_FILE% ^
--input_data_dir %INPUT_DATA_DIR% ^
--output_code_dir %OUTPUT_CODE_DIR%
--output_data_dir %OUTPUT_DIR% ^
--gen_types %GEN_TYPE% ^
-s %GROUP%
其中:
- LUBAN_CLIENT_SERVER_DLL为 Luban.ClientServer.dll的路径, 可以指向 luban_examples/Tools/Luban.ClientServer/Luban.ClientServer.dll
- ROOT_FILE 为根定义文件,指向 MyConfigs/Define/__root__.xml
- INPUT_DATA_DIR 为配置数据的根目录,指向 MyConfigs/Datas
- OUTPUT_CODE_DIR 为生成代码的目录
- GEN_TYPE 为生成类型。 如果你使用unity,想生成c#代码,导出json数据,则使用 "code_cs_unity_json,data_json"
- GROUP 为导出分组。客户端则取client,服务器取server,所有则取all
更多项目类型,参见 示例项目
为unity项目生成c#代码并导出json数据
对于命令行的介绍参见 上面。 你的生成命令大略如下
dotnet %LUBAN_CLIENT_SERVER_DLL% -j cfg -- ^
-d %ROOT_FILE% ^
--input_data_dir %INPUT_DATA_DIR% ^
--output_code_dir %OUTPUT_CODE_DIR%
--output_data_dir %OUTPUT_DIR% ^
--gen_types "code_cs_unity_json,data_json" ^
-s client
也即 --gen_types参数取 "code_cs_unity_json,data_json", -s 参数取 client
具体项目,可参见 Csharp_Unity_Json
更多项目类型,参见 示例项目
为 unity + puerts 项目生成 ts代码,并生成json数据
--gen_types 参数取 "code_typescript_json,data_json",-s 参数取 client
具体项目,可参见 Typescript_Unity_Puerts_Json
为 UE4项目,生成c++代码(非蓝图)和binary数据
基准的参考项目为 Cpp_Unreal_bin。
由于生成的代码依赖于一些头文件,你需要先从该项目 拷备Source\Cpp_Unreal\Private\bright 到你们项目合适的位置。必须保证bright目录在include目录路径内,如生成的代码中 #include "bright/serialization/ByteBuf.h" 可以找到这个文件。
接着命令行参数取 --gen_types "code_cpp_bin,data_bin"
其他类型项目类型,如何生成代码和数据
不同项目之间,仅仅是 --gen_types 不一样, 请从示例项目中找到与你项目匹配的项目,参考相应目录下的 gen_code.bat 即可。
生成protobuf的定义文件及protobuf数据格式
目前支持proto2和proto3语法
protobuf2
只支持bin格式导出。
取 --gen_types code_protobuf2,data_protobuf_bin 即可,参见 Protobuf2_bin。 每个导出的数据文件对应Table类序列化后的内容,加载即可,以item.TbItem表为例。
var tbItem = ItemTbItem.Parser.ParseFrom(File.OpenRead("pb_datas/item_tbitem.bytes"));
protobuf3
既支持bin格式,也支持json格式导出。
- binary格式导出。 --gen_types code_protobuf3,data_protobuf_bin
- json格式导出。 --gen_types code_protobuf3,data_protobuf_json
生成msgpack的数据
取 --gen_types data_msgpack 即可。 参见 MsgPack_bin
生成flatbuffers的定义文件及flatbuffers数据格式
取 --gen_types code_flatbuffers,data_flatbuffers_json 即可,参见 Flatbuffers_json。
由于binary格式过于复杂,现在只支持导出json格式,但是使用者可以使用flatc工具将数据转成binary!特地生成了 convert_json_2_binary.bat 和convert_json_2_binary.sh这两个批处理文件,方便自动一键转换。
目前由于flat_buffers不支持容器的元素类型为union,因此略微有一些兼容性问题,但在项目中可以通过使用一个bean来包含这个union字段来迂回解决。
data_flatbuffers_json 和 data_json的输出格式有一些区别
- data_flatbuffers_json 顶层为 包含data_list字段的 table,而 data_json顶层直接对应 data_list的内容
- flatbuffers不支持本地化。 所以它的text类型导出格式为string,而data_json为 {"key":"xxx", "text":"text}
- data_flatbuffers_json序列化bean类型字段时,如果遇到多态类型,会多序列化一个string类型的xxx_type字段,用于指示union的类型。也正是如此 data_flatbuffers_json不支持容器中出现union
- data_flatbuffers_json 输出的数据中,如果包含容器类型数据,并且元素类型为union,则无法被正确解析。
只生成代码或者数据
以 Csharp_Unity_Json 为例。
- --gen_types code_cs_unity_json 则只生成代码
- --gen_types data_json 则只生成数据
配置中有些string字段是资源地址,统一导出这些资源地址
首先定义类型时,添加上'#res=xxx' 这种标签,xxx可以取任意值。如下所示。
<bean name="TestRes">
<var name="icon" type="string#res=item"/>
</bean>
取 '--gen_types data_resources',并且新增参数'--output:data:resource_list_file resources.txt'。 运行即可将所有带res标签的数据导出到resources.text文件中。
假设配置表中包含icon="/ui/icon1.jpg" 和 icon="/ui/icon1/jpg" 这两个数据,则导出的资源列表内容为
item,/ui/icon1.jpg
item,/ui/icon2.jpg
参见示例 GenerateDatas/gen_resource_list.bat 文件。
生成的c#代码中,vector的类型由System.Numerics.Vector{2,3,4},改成 UnityEngine.Vector{2,3,4}
命令行参数中添加 --cs:use_unity_vector 选项即可。 参见示例 Csharp_Unity_bin
自定义代码命名风格
可以。 添加选项 --naming_convention_bean_member none 即可。使生成的代码中的字段名与定义名相同。
支持以下代码命名风格:
- none。 无命名风格,生成的字段名和定义的名称一样
- language_recommend。即根据生成的语言不同,自动设置该语言推荐的风格。比如c#为PascalCase,java为 camelCase,python为under_scores。
- camelCalse。 即驼峰形式,生成 xxxYyyy这种风格的字段名。
- PascalCase。 即Pascal形式。生成XxxYyy这种风格的字段名。
- under_scores。 下划线形式。即生成xxx_yyy这种风格的字段名。
默认使用 language_recommend。
gen_types中 code_cs_json和code_cs_unity_json的区别
code_cs_json生成代码中使用了 System.Text.Json库,这个只有.net core 3以后的版本才有,unity目前的.net版本不支持,所以这是给基于.net coer的服务器项目使用的。 code_cs_unity_json使用了第三方的SimpleJson库,兼容unity的.net版本,给unity生成加载json数据的c#代码时,可以(当前也只有这个选择)选择这个。
调生成的数据文件的后缀
数据格式的默认文件后缀如下
data | extension |
---|---|
data_bin | bin |
data_json | json |
data_json2 | json |
data_lua | lua |
data_xml | xml |
data_yaml | yml |
data_protobuf | bp |
可以通过命令行选项"--data_file_extension xxx"手动指定输出文件的后缀。
不同导出格式的性能测试结果
硬件:
Intel(R) Core i7-10700 @ 2.9G 16核
32G 内存
数据集
500个excel表 每个表有1000行比较大的记录 每个表文件大小 132k
测试结果:
格式 | 首次耗时 | 累积耗时 | 单个输出文件大小 | 输出文件总大小 |
---|---|---|---|---|
bin | 15.652 s | 797 ms | 164 K | 59.5 M |
json | 17.746 s | 796 ms | 1.11 M | 555 M |
lua | 17.323 s | 739 ms | 433 K | 212 M |
binary与json格式加载性能对比
以luban_examples的DataTables配置为测试数据,以Projects下的csharp_Unity_bin和csharp_Unity_json项目为测试对比, 加载100遍cfg.Table。
binary格式耗时28ms,json格式耗时112ms。
加载性能大约为 4:1。