GFNetworkUtility

API Reference / Network / 类索引

• 路径：addons/gf/extensions/network/runtime/gf_network_utility.gd
• 模块：Network
• 继承：GFUtility
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

可插拔网络后端运行时。 负责把通用 GFNetworkMessage 编码后交给后端发送，并将后端收到的 bytes 解码为消息信号。

成员概览

类型	名称	签名
信号	message_received	signal message_received(peer_id: int, message: GFNetworkMessage)
信号	message_rejected	signal message_rejected(peer_id: int, reason: String, details: Dictionary)
信号	connected	signal connected
信号	disconnected	signal disconnected(reason: String)
信号	peer_connected	signal peer_connected(peer_id: int)
信号	peer_disconnected	signal peer_disconnected(peer_id: int)
属性	backend	var backend: GFNetworkBackend
属性	serializer	var serializer: GFNetworkSerializer = GFNetworkSerializer.new()
属性	validator	var validator: GFNetworkMessageValidator = GFNetworkMessageValidator.new()
属性	session	var session: GFNetworkSession = GFNetworkSession.new()
方法	ready	func ready() -> void:
方法	tick	func tick(delta: float) -> void:
方法	dispose	func dispose() -> void:
方法	set_backend	func set_backend(next_backend: GFNetworkBackend) -> void:
方法	register_channel	func register_channel(channel: GFNetworkChannel) -> void:
方法	unregister_channel	func unregister_channel(channel_id: StringName) -> void:
方法	get_channel	func get_channel(channel_id: StringName) -> GFNetworkChannel:
方法	get_channel_ids	func get_channel_ids() -> PackedStringArray:
方法	clear_channels	func clear_channels() -> void:
方法	host	func host(options: Dictionary = {}) -> Error:
方法	connect_to_endpoint	func connect_to_endpoint(endpoint: String, options: Dictionary = {}) -> Error:
方法	disconnect_network	func disconnect_network() -> void:
方法	send_message	func send_message(peer_id: int, message: GFNetworkMessage, options: Dictionary = {}) -> Error:
方法	send_message_on_channel	func send_message_on_channel( peer_id: int, message: GFNetworkMessage, channel_id: StringName, options: Dictionary = {} ) -> Error:
方法	get_debug_snapshot	func get_debug_snapshot() -> Dictionary:

信号

message_received

• API：public

signal message_received(peer_id: int, message: GFNetworkMessage)

收到消息后发出。

参数：

名称	说明
peer_id	发送方 peer 标识。
message	解码后的网络消息。

message_rejected

• API：public

signal message_rejected(peer_id: int, reason: String, details: Dictionary)

消息校验失败后发出。

参数：

名称	说明
peer_id	关联 peer 标识。
reason	拒绝原因。
details	校验或解码详情。

结构：

• details: Dictionary，包含 ok、errors 或 error/data 等诊断字段。

connected

• API：public

signal connected

后端连接成功后发出。

disconnected

• API：public

signal disconnected(reason: String)

后端断开后发出。

参数：

名称	说明
reason	断开原因。

peer_connected

• API：public

signal peer_connected(peer_id: int)

远端节点连接后发出。

参数：

名称	说明
peer_id	远端 peer 标识。

peer_disconnected

• API：public

signal peer_disconnected(peer_id: int)

远端节点断开后发出。

参数：

名称	说明
peer_id	远端 peer 标识。

属性

backend

• API：public

var backend: GFNetworkBackend

当前网络后端。

serializer

• API：public

var serializer: GFNetworkSerializer = GFNetworkSerializer.new()

消息编码器。

validator

• API：public

var validator: GFNetworkMessageValidator = GFNetworkMessageValidator.new()

消息校验器。

session

• API：public

var session: GFNetworkSession = GFNetworkSession.new()

当前会话状态。

方法

ready

• API：public

func ready() -> void:

注册网络诊断快照贡献。

tick

• API：public

func tick(delta: float) -> void:

推进运行时逻辑。

参数：

名称	说明
delta	本帧时间增量（秒）。

dispose

• API：public

func dispose() -> void:

释放后端、通道和诊断贡献。

set_backend

• API：public

func set_backend(next_backend: GFNetworkBackend) -> void:

设置网络后端。

参数：

名称	说明
next_backend	新后端。

register_channel

• API：public

func register_channel(channel: GFNetworkChannel) -> void:

注册网络通道。

参数：

名称	说明
channel	通道资源。

unregister_channel

• API：public

func unregister_channel(channel_id: StringName) -> void:

注销网络通道。

参数：

名称	说明
channel_id	通道标识。

get_channel

• API：public

func get_channel(channel_id: StringName) -> GFNetworkChannel:

获取网络通道。

参数：

名称	说明
channel_id	通道标识。

返回：通道资源。

get_channel_ids

• API：public

func get_channel_ids() -> PackedStringArray:

获取已注册通道标识。

返回：排序后的通道标识。

clear_channels

• API：public

func clear_channels() -> void:

清空网络通道。

host

• API：public

func host(options: Dictionary = {}) -> Error:

启动主机。

参数：

名称	说明
options	后端选项。

返回：Godot 错误码。

结构：

• options: Dictionary，传给 session.start_host() 和 backend.host() 的后端选项。

connect_to_endpoint

• API：public

func connect_to_endpoint(endpoint: String, options: Dictionary = {}) -> Error:

连接远端。

参数：

名称	说明
endpoint	远端地址。
options	后端选项。

返回：Godot 错误码。

结构：

• options: Dictionary，传给 session.start_client() 和 backend.connect_to_endpoint() 的后端选项。

disconnect_network

• API：public

func disconnect_network() -> void:

断开连接。

send_message

• API：public

func send_message(peer_id: int, message: GFNetworkMessage, options: Dictionary = {}) -> Error:

发送消息。

参数：

名称	说明
peer_id	目标 peer；后端可约定 -1 表示广播。
message	消息载体。
options	后端发送选项。

返回：Godot 错误码。

结构：

• options: Dictionary，传给 backend.send_bytes() 的发送选项。

send_message_on_channel

• API：public

func send_message_on_channel( peer_id: int, message: GFNetworkMessage, channel_id: StringName, options: Dictionary = {} ) -> Error:

通过指定通道发送消息。

参数：

名称	说明
peer_id	目标 peer；后端可约定 -1 表示广播。
message	消息载体。
channel_id	通道标识。
options	后端发送选项覆盖。

返回：Godot 错误码。

结构：

• options: Dictionary，覆盖 GFNetworkChannel.build_send_options() 的发送选项。

get_debug_snapshot

• API：public

func get_debug_snapshot() -> Dictionary:

获取网络工具调试快照。

返回：调试信息字典。

结构：

• return: Dictionary，包含 backend_configured、serializer_configured、validator_configured、backend、session、channels、validator。