跳到主要内容
版本:classic

代码与数据生成

支持的平台、引擎和语言

  • 跨平台
    • 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格式。
  • 其他格式。很容易扩展支持。
提示

同一种格式,为不同语言生成的数据是完全相同的

不同语言支持的格式如下:

languagebinaryjsonlua
c#✔️✔️
java✔️✔️
go✔️✔️
c++✔️
go✔️✔️
python✔️✔️
typescript✔️✔️
rust✔️
lua✔️✔️
erlangerlang
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#代码时,可以(当前也只有这个选择)选择这个。

调生成的数据文件的后缀

数据格式的默认文件后缀如下

dataextension
data_binbin
data_jsonjson
data_json2json
data_lualua
data_xmlxml
data_yamlyml
data_protobufbp

可以通过命令行选项"--data_file_extension xxx"手动指定输出文件的后缀。

不同导出格式的性能测试结果

硬件:

Intel(R) Core i7-10700 @ 2.9G 16核

32G 内存

数据集

500个excel表 每个表有1000行比较大的记录 每个表文件大小 132k

测试结果:

格式首次耗时累积耗时单个输出文件大小输出文件总大小
bin15.652 s797 ms164 K59.5 M
json17.746 s796 ms1.11 M555 M
lua17.323 s739 ms433 K212 M

binary与json格式加载性能对比

以luban_examples的DataTables配置为测试数据,以Projects下的csharp_Unity_bin和csharp_Unity_json项目为测试对比, 加载100遍cfg.Table。

binary格式耗时28ms,json格式耗时112ms。

加载性能大约为 4:1。