GFNetworkContractMessage¶
API Reference / Network / 类索引
- 路径：
addons/gf/extensions/network/contracts/gf_network_contract_message.gd - 模块：
Network - 继承：
Resource - API：
public - 类别：资源定义 (
resource_definition) - 首次版本：
3.17.0
网络契约中的单个消息定义。 消息定义描述 message_type、默认通道和 payload 字段集合，可用于构造、 校验和生成强类型辅助函数。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 属性 | message_type |
var message_type: StringName = &"" |
| 属性 | display_name |
var display_name: String = "" |
| 属性 | channel_id |
var channel_id: StringName = &"" |
| 属性 | fields |
var fields: Array[GFNetworkContractField] = [] |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | get_message_type |
func get_message_type() -> StringName: |
| 方法 | get_display_name |
func get_display_name() -> String: |
| 方法 | get_field |
func get_field(target_field_name: StringName) -> GFNetworkContractField: |
| 方法 | build_payload |
func build_payload(values: Dictionary = {}, options: Dictionary = {}) -> Dictionary: |
| 方法 | make_message |
func make_message(values: Dictionary = {}, options: Dictionary = {}) -> GFNetworkMessage: |
| 方法 | validate_definition |
func validate_definition() -> Dictionary: |
| 方法 | validate_payload |
func validate_payload(payload: Dictionary) -> Dictionary: |
| 方法 | validate_message |
func validate_message(message: GFNetworkMessage) -> Dictionary: |
| 方法 | describe |
func describe() -> Dictionary: |
属性¶
message_type¶
- API：
public
消息类型标识。
display_name¶
- API：
public
编辑器展示名称。
channel_id¶
- API：
public
默认逻辑通道。为空时发送时不强制通道。
fields¶
- API：
public
payload 字段定义。
结构：
fields: Array[GFNetworkContractField]，按声明顺序保存 payload 字段定义。
metadata¶
- API：
public
项目自定义元数据。框架不解释该字段。
结构：
metadata: Dictionary，保存项目自定义消息元数据。
方法¶
get_message_type¶
- API：
public
获取消息类型。
返回：消息类型。
get_display_name¶
- API：
public
获取展示名称。
返回：展示名称。
get_field¶
- API：
public
查找字段定义。
参数：
| 名称 | 说明 |
|---|---|
target_field_name |
字段名称。 |
返回：字段定义；不存在时返回 null。
build_payload¶
- API：
public
构建 payload 字典。
参数：
| 名称 | 说明 |
|---|---|
values |
字段值字典，可使用 StringName 或 String 作为键。 |
options |
可选项，支持 include_defaults。 |
返回：payload 字典。
结构：
values: Dictionary[StringName|String, Variant]，字段名到字段值的映射。options: Dictionary，支持 include_defaults。return: Dictionary[StringName, Variant]，按字段契约归一化后的 payload。
make_message¶
- API：
public
构建 GFNetworkMessage。
参数：
| 名称 | 说明 |
|---|---|
values |
字段值字典。 |
options |
可选元信息，支持 sequence、tick、sender_id、channel_id。 |
返回：网络消息。
结构：
values: Dictionary[StringName|String, Variant]，字段名到字段值的映射。options: Dictionary，支持 include_defaults、sequence、tick、sender_id、channel_id。
validate_definition¶
- API：
public
校验消息定义是否完整。
返回：校验报告字典。
结构：
return: Dictionary，GFValidationReportDictionary 格式，包含 ok、issues、issue_count 和 next_actions。
validate_payload¶
- API：
public
校验 payload 是否符合字段契约。
参数：
| 名称 | 说明 |
|---|---|
payload |
payload 字典。 |
返回：校验报告字典。
结构：
payload: Dictionary[StringName|String, Variant]，待校验 payload 字段值。return: Dictionary，GFValidationReportDictionary 格式，包含 ok、issues、issue_count 和 next_actions。
validate_message¶
- API：
public
校验 GFNetworkMessage 是否匹配该消息契约。
参数：
| 名称 | 说明 |
|---|---|
message |
网络消息。 |
返回：校验报告字典。
结构：
return: Dictionary，GFValidationReportDictionary 格式，包含 ok、issues、issue_count 和 next_actions。
describe¶
- API：
public
描述消息契约。
返回：描述字典。
结构：
return: Dictionary，包含 message_type、display_name、channel_id、field_count、fields、metadata。