高级功能

文本替换(别名/宏)

为了便于理解,我们支持配置一组别名的表。在 MacroSource 中,主配置为文件名,次配置为表明,补充配置为Key-Value的开始行号和列号。比如:

字段

简介

主配置

次配置

补充配置

说明

MacroSource

文本宏数据源(文件路径,表名)

资源转换示例.xlsx

macro

2,1

次配置为表名,补充配置为数据起始位置(行号, 列号)

这时候我们会认为在文件 资源转换示例.xlsxmacro 表中。从第 2 行开始,第 1 列为别名的Key,第 2 列为别名的Value。

这样我们在执行转表的读取数据时候,会尝试去这里查找是否又它的别名,如果有,则直接转换成Value。

比如 xresloader sampleupgrade_10001 表的 CostType 这一列是整数类型,但是我们可以配置成 游戏币 。就是因为我们在 macro 表中配置了。

游戏币

10001

多表数据合并

如果Excel的多个表的结构相同(列对应的字段相同)。则我们可以通过配置多个 DataSource 来让 xresloader 对多个表进行数据合并。这样我们可以把数据按类型分布在几个表中并在转换的时候最后合并。

详见 xresloader sample资源转换示例.xlsxscheme_upgradeupgrade_10001upgrade_10002 表。

数据验证器

xresloader 提供了一个基于协议描述得高级功能- 数据验证器 。用于限制输入数据的范围。 数据验证器 的使用方法是在Excel的字段名后面跟 @ 符号,然后输入协议名称或者数字范围 A-B ,多个验证器可以用 | 隔开。 这样在数据转出的时候转表工具会检查数据的合法性。比如:

角色ID

等级

货币类别

消耗值

Id

Level

CostType

CostValue@0-1000|2000-3000

10001

1

10001

2

10001

50

上面这个表,如果 消耗值 这一列出现了[0, 1000]和[2000-3000]以外的值,转表工具会转表不通过并予以提示。

还有一个特殊的用法是,比如我们有技能要对单位的属性加成。然后我们定义单位属性的proto如下:

message unit_attribute {
    int32 hp           = 1;
    int32 mp           = 2;
    int32 power        = 3;
}

message skill_effect {
    int32 id           = 1;
    int32 level        = 2;
    int32 func_type    = 3;
    int32 attr_type    = 4;
    int32 value        = 5;
}

然后我们可以定义技能功能表如下:

技能ID

等级

功能类别

属性

id

level

func_type

attr_type@unit_attribute

value

20001

1

hp

100

20001

2

1001

hp

200

使用 skill_effect 转出如上的表, 属性 这个字段的验证器设为了 unit_attributeattr_type 的类型是int32。 这时在转出数据的时候,转出的数据是 unit_attribute.hp 的字段编号 1

Protobuf 插件支持

项目中可以导入 xresloader header extensions 目录, 然后通过导入 xresloader header extensions v2xresloader header extensions v3 中的相应proto文件,就可以获得额外的插件扩展支持。

> 注意: 使用插件功能时 生成pb的时候也要导入插件的proto文件和protobuf官方include目录里的 google/protobuf/descriptor.proto 文件。

Protobuf插件 - Message插件

插件名称

类型

插件功能

org.xresloader.msg_description

string

消息体描述信息,会写入输出的header中和代码中

org.xresloader.ue.helper

string

生成UE Utility代码的类名后缀

org.xresloader.ue.not_data_table

bool

生成UE Utility代码时,不生产加载代码,这用于带name字段的依赖类型

比如 xresloader sample proto_v3 kind.proto 里, arr_in_arr_cfg 配置了相关字段,会影响到一些输出。

Protobuf插件 - Field插件

插件名称

类型

插件功能

org.xresloader.field_description

string

字段描述信息,会写入输出的header中和代码中

org.xresloader.verifier

string

字段描述信息,会写入输出的header中和代码中

org.xresloader.field_alias

string

字段别名,可用于验证器和Excel中直接填别名

org.xresloader.field_ratio

int32

数值放大倍数,转出数值=Excel内数值*field_ratio。比如设为1000时,如果Excel里填的是1.05,转出的数据是 1050

org.xresloader.ue.key_tag

int32

生成UE代码时,如果需要支持多个Key组合成一个Name,用这个字段指定系数(必须大于0)

org.xresloader.ue.ue_type_name

string

生成UE代码时,如果指定了这个字段,那么生成的字段类型将是 `TSoftObjectPtr<ue_type_name>` , 并且支持蓝图中直接引用

org.xresloader.ue.ue_type_is_class

bool

生成UE代码时,如果这个字段为true,那么生成的字段类型将是 `TSoftClassPtr<ue_type_name>` , 并且支持蓝图中直接引用

比如我们定义单位属性的proto如下:

import "xresloader.proto";

message unit_attribute {
    int32 hp           = 1 [(org.xresloader.field_alias) = "生命"];
    int32 mp           = 2 [(org.xresloader.field_alias) = "魔力"];
    int32 power        = 3 [(org.xresloader.field_alias) = "力量"];
}

message skill_effect {
    int32 id           = 1;
    int32 level        = 2;
    int32 func_type    = 3;
    int32 attr_type    = 4;
    int32 value        = 5;
}

然后我们可以在Excel表中使用别名:

技能ID

等级

功能类别

属性

id

level

func_type

attr_type@unit_attribute

value

20001

1

生命

100

20001

2

1001

生命

200

Protobuf插件 - EnumValue插件

插件名称

类型

插件功能

org.xresloader.enumv_description

string

枚举值描述信息,会写入输出的header中和代码中

org.xresloader.enum_alias

string

枚举值别名,可用于验证器和Excel中直接填别名

比如 xresloader sample proto_v3 kind.proto 里, role_upgrade_cfg 内的 CostType 这一列配置验证器引射到协议的 cost_type 和 协议描述字段。

syntax = "proto3";

import "xresloader.proto";

enum cost_type {
  EN_CT_UNKNOWN = 0;
  EN_CT_MONEY   = 10001 [(org.xresloader.enum_alias) = "金币"];
  EN_CT_DIAMOND = 10101 [(org.xresloader.enum_alias) = "钻石"];
}

message role_upgrade_cfg {
  uint32 Id = 1;
  uint32 Level = 2;
  uint32 CostType = 3 [
    (org.xresloader.verifier) = "cost_type", // 这里等同于在Excel中使用 @cost_type 标识
    (org.xresloader.field_description) = "Refer to cost_type"
  ];
  int32 CostValue = 4;
  int32 ScoreAdd = 5;
}

然后,我们就可以按如下方式配消耗类型:

角色ID

等级

货币类别

消耗值

Id

Level

CostType

CostValue@0-1000|2000-3000

10001

1

EN_CT_MONEY

10

10001

2

金币

50

仅导出部分字段

如果我们需要给客户端和服务器读取同一张Excel表里的不同字段的数据,只要proto不一样即可。对于proto中不存在的字段,我们在转换的时候会忽略掉。 即,我们可能会有一个 role_serverrole_client 。这两个数据结构不一样,但指向同一个数据源。

批量转表的include标签

公式支持

xresloader 支持公式功能,但是不建议使用跨文件公式。是因为有些平台里,文件的引用可能会使用绝对路径,这时候如果改变一个文件中的值会影响另一个文件。 而另一个文件计算公式的时候读取失败,则会用之前的数据缓存(Excel中对所有公式的计算结果有缓存)。这时候数据可能滞后,但是是没有提示的。可能会引起困惑。

定长数组

详见 数据类型说明-定长数组 章节。