GFNetworkSnapshot

API Reference / Network / 类索引

• 路径：addons/gf/extensions/network/snapshot/gf_network_snapshot.gd
• 模块：Network
• 继承：RefCounted
• API：public
• 类别：值对象 (value_object)
• 首次版本：3.17.0

通用网络状态快照。 保存 tick、peer_id、纯字典状态和元数据，可用于同步、回放、插值或项目自定义差量流程。

成员概览

类型	名称	签名
属性	tick	var tick: int = 0
属性	peer_id	var peer_id: int = -1
属性	state	var state: Dictionary = {}
属性	metadata	var metadata: Dictionary = {}
方法	to_dict	func to_dict() -> Dictionary:
方法	from_dict	func from_dict(data: Dictionary) -> void:
方法	duplicate_snapshot	func duplicate_snapshot() -> GFNetworkSnapshot:
方法	has_value	func has_value(key: StringName) -> bool:
方法	get_value	func get_value(key: StringName, default_value: Variant = null) -> Variant:
方法	set_value	func set_value(key: StringName, value: Variant) -> void:
方法	erase_value	func erase_value(key: StringName) -> void:
方法	make_delta_to	func make_delta_to(target: GFNetworkSnapshot) -> Dictionary:
方法	apply_delta	func apply_delta(delta: Dictionary) -> GFNetworkSnapshot:
方法	make_patch_to	func make_patch_to(target: GFNetworkSnapshot, options: Dictionary = {}) -> Dictionary:
方法	apply_patch	func apply_patch(patch: Dictionary) -> GFNetworkSnapshot:
方法	make_message	func make_message(message_type: StringName = &"snapshot", channel_id: StringName = &"") -> GFNetworkMessage:

属性

tick

• API：public

var tick: int = 0

快照所属 tick。

peer_id

• API：public

var peer_id: int = -1

快照来源 peer；-1 表示未指定。

state

• API：public

var state: Dictionary = {}

快照状态字典。

结构：

• state: Dictionary[StringName|String, Variant]，保存项目自定义同步状态。

metadata

• API：public

var metadata: Dictionary = {}

项目自定义元数据。

结构：

• metadata: Dictionary，保存项目自定义快照元数据。

方法

to_dict

• API：public

func to_dict() -> Dictionary:

转为字典。

返回：快照字典。

结构：

• return: Dictionary，包含 tick、peer_id、state、metadata。

from_dict

• API：public

func from_dict(data: Dictionary) -> void:

从字典恢复。

参数：

名称	说明
data	快照字典。

结构：

• data: Dictionary，包含 tick、peer_id、state、metadata。

duplicate_snapshot

• API：public

func duplicate_snapshot() -> GFNetworkSnapshot:

复制快照。

返回：新快照。

has_value

• API：public

func has_value(key: StringName) -> bool:

检查状态字段是否存在。

参数：

名称	说明
key	字段名。

返回：存在返回 true。

get_value

• API：public

func get_value(key: StringName, default_value: Variant = null) -> Variant:

读取状态字段。

参数：

名称	说明
key	字段名。
default_value	缺失时返回的默认值。

返回：字段值。

结构：

• default_value: Variant，状态字段缺失时返回的默认值。
• return: Variant，字段值或 default_value。

set_value

• API：public

func set_value(key: StringName, value: Variant) -> void:

设置状态字段。

参数：

名称	说明
key	字段名。
value	字段值。

结构：

• value: Variant，字段值，会通过 GFVariantData.duplicate_variant() 复制后保存。

erase_value

• API：public

func erase_value(key: StringName) -> void:

删除状态字段。

参数：

名称	说明
key	字段名。

make_delta_to

• API：public

func make_delta_to(target: GFNetworkSnapshot) -> Dictionary:

生成当前快照到目标快照的浅层差量。

参数：

名称	说明
target	目标快照。

返回：差量字典。

结构：

• return: Dictionary，成功时包含 ok、from_tick、to_tick、peer_id、set、erase、metadata；失败时包含 ok、error。

apply_delta

• API：public

func apply_delta(delta: Dictionary) -> GFNetworkSnapshot:

应用浅层差量并返回新快照。

参数：

名称	说明
delta	make_delta_to() 生成的差量字典。

返回：新快照。

结构：

• delta: Dictionary，make_delta_to() 返回的差量结构。

make_patch_to

• API：public

func make_patch_to(target: GFNetworkSnapshot, options: Dictionary = {}) -> Dictionary:

生成当前快照到目标快照的路径级 patch。

参数：

名称	说明
target	目标快照。
options	生成选项。

返回：patch 字典。

结构：

• options: Dictionary，可选 recursive: bool = true，max_depth: int = 8。
• return: Dictionary，成功时包含 ok、format、version、from_tick、to_tick、peer_id、set、erase、metadata；失败时包含 ok、error。

apply_patch

• API：public

func apply_patch(patch: Dictionary) -> GFNetworkSnapshot:

应用路径级 patch 并返回新快照。

参数：

名称	说明
patch	make_patch_to() 生成的 patch 字典。

返回：新快照。

结构：

• patch: Dictionary，make_patch_to() 返回的 patch 结构。

make_message

• API：public

func make_message(message_type: StringName = &"snapshot", channel_id: StringName = &"") -> GFNetworkMessage:

打包为网络消息。

参数：

名称	说明
message_type	消息类型。
channel_id	逻辑通道标识。

返回：网络消息。