Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

ENetConnection

继承: RefCounted < Object

ENetHost 的包装类。

描述

ENet 的目的是在 UDP(用户数据报协议)之上,提供一个相对轻便、简单和健壮的网络通信层。

教程

方法

void

bandwidth_limit(in_bandwidth: int = 0, out_bandwidth: int = 0)

void

broadcast(channel: int, packet: PackedByteArray, flags: int)

void

channel_limit(limit: int)

void

compress(mode: CompressionMode)

ENetPacketPeer

connect_to_host(address: String, port: int, channels: int = 0, data: int = 0)

Error

create_host(max_peers: int = 32, max_channels: int = 0, in_bandwidth: int = 0, out_bandwidth: int = 0)

Error

create_host_bound(bind_address: String, bind_port: int, max_peers: int = 32, max_channels: int = 0, in_bandwidth: int = 0, out_bandwidth: int = 0)

void

destroy()

Error

dtls_client_setup(hostname: String, client_options: TLSOptions = null)

Error

dtls_server_setup(server_options: TLSOptions)

void

flush()

int

get_local_port() const

int

get_max_channels() const

Array[ENetPacketPeer]

get_peers()

float

pop_statistic(statistic: HostStatistic)

void

refuse_new_connections(refuse: bool)

Array

service(timeout: int = 0)

void

socket_send(destination_address: String, destination_port: int, packet: PackedByteArray)


枚举

enum CompressionMode: 🔗

CompressionMode COMPRESS_NONE = 0

无压缩。这使用最多的带宽,但具有占用最少 CPU 资源的好处。这个选项可以用于 Wireshark 等工具使用,更容易进行网络调试。

CompressionMode COMPRESS_RANGE_CODER = 1

ENet 的内置范围编码。适用于小数据包,但对于大于 4 KB 的数据包不是最有效的算法。

CompressionMode COMPRESS_FASTLZ = 2

FastLZ 压缩。与 COMPRESS_ZLIB 相比,此选项使用的 CPU 资源更少,代价是使用更多的带宽。

CompressionMode COMPRESS_ZLIB = 3

Zlib 压缩。与 COMPRESS_FASTLZ 相比,此选项使用的带宽更少,代价是使用更多的 CPU 资源。

CompressionMode COMPRESS_ZSTD = 4

Zstandard 压缩。请注意,此算法对小于 4 KB 的数据包效率不高。因此,建议在大多数情况下使用其他压缩算法。


enum EventType: 🔗

EventType EVENT_ERROR = -1

service 期间发生错误。你可能需要 destroy 主机并重新创建。

EventType EVENT_NONE = 0

在指定的时间限制内没有事件发生。

EventType EVENT_CONNECT = 1

由 enet_host_connect 发起的连接请求已完成。该数组将包含成功连接的对等体。

EventType EVENT_DISCONNECT = 2

对等体已断开连接。如果对等体超时,或者由 connect_to_host 初始化的连接请求超时,则在由 ENetPacketPeer.peer_disconnect 发起的断开连接成功完成时,生成该事件。该数组将包含断开连接的对等体。数据字段包含用户提供的描述断开连接的数据,如果没有可用的数据,则为 0。

EventType EVENT_RECEIVE = 3

已从对等体接收到一个数据包。该数组将包含发送数据包的对等体和接收数据包的通道号。接收到的数据包将被排队到关联的 ENetPacketPeer


enum HostStatistic: 🔗

HostStatistic HOST_TOTAL_SENT_DATA = 0

发送数据的总数。

HostStatistic HOST_TOTAL_SENT_PACKETS = 1

发送 UDP 数据包的总数。

HostStatistic HOST_TOTAL_RECEIVED_DATA = 2

接收数据的总数。

HostStatistic HOST_TOTAL_RECEIVED_PACKETS = 3

接收 UDP 数据包的总数。


方法说明

void bandwidth_limit(in_bandwidth: int = 0, out_bandwidth: int = 0) 🔗

调整主机的带宽限制。


void broadcast(channel: int, packet: PackedByteArray, flags: int) 🔗

将一个 packet 加入队列,以便将其通过指定的 channel 发送到与主机关联的所有对等体。请参阅 ENetPacketPeer 中的 FLAG_* 常量以了解可用的数据包标志。


void channel_limit(limit: int) 🔗

限制未来传入连接的最大允许通道数。


void compress(mode: CompressionMode) 🔗

设置用于网络数据包的压缩方法。这些在压缩速度与带宽之间有不同的权衡,如果需要使用压缩,可能需要测试哪一种最适合你的用例。

注意:大多数游戏的网络设计,都涉及频繁发送许多小数据包(每个小于 4 KB)。如果有疑问,建议保留默认压缩算法,因为它最适合这些小数据包。

注意:压缩模式必须在服务器及其所有客户端上设置为相同的值。如果客户端上设置的压缩模式与服务器上设置的不同,则客户端将无法连接。


ENetPacketPeer connect_to_host(address: String, port: int, channels: int = 0, data: int = 0) 🔗

使用指定的端口 port 并分配所需的通道 channels,向外部地址 address 建立连接。可以在连接期间可以传递数据 data ,形式为 32 位整数。

注意:在调用此方法之前,必须先调用 create_hostcreate_host_bound


Error create_host(max_peers: int = 32, max_channels: int = 0, in_bandwidth: int = 0, out_bandwidth: int = 0) 🔗

创建一个 ENetHost,最多允许 max_peers 个连接的对等体,每个连接最多分配 max_channels 个通道,可选择将带宽限制为 in_bandwidthout_bandwidth


Error create_host_bound(bind_address: String, bind_port: int, max_peers: int = 32, max_channels: int = 0, in_bandwidth: int = 0, out_bandwidth: int = 0) 🔗

创建一个类似 create_host 的 ENetHost,它还被绑定到给定的 bind_addressbind_port


void destroy() 🔗

销毁主机和与其关联的所有资源。


Error dtls_client_setup(hostname: String, client_options: TLSOptions = null) 🔗

配置此 ENetHost 以使用允许对 ENet 客户端进行 DTLS 加密的自定义 Godot 扩展。在 connect_to_host 之前调用它,让 ENet 连接使用 DTLS 根据 hostname 验证服务器证书。可以通过可选的 client_options 参数来自定义受信任的证书颁发机构,或禁用通用名称验证。见 TLSOptions.clientTLSOptions.client_unsafe


Error dtls_server_setup(server_options: TLSOptions) 🔗

配置该 ENetHost 以使用允许对 ENet 服务器进行 DTLS 加密的自定义 Godot 扩展。在 create_host_bound 之后立即调用该方法,以让 ENet 期望对等体使用 DTLS 进行连接。请参阅 TLSOptions.server


void flush() 🔗

将指定主机上所有被队列的数据包发送到其指定的对等体。


int get_local_port() const 🔗

返回该对等体绑定到的本地端口。


int get_max_channels() const 🔗

返回连接的对等体所允许的最大通道数。


Array[ENetPacketPeer] get_peers() 🔗

返回与该主机关联的对等体列表。

注意:该列表可能包含一些未完全连接或仍在断开连接的对等体。


float pop_statistic(statistic: HostStatistic) 🔗

返回并重置主机统计信息。详情见 HostStatistic


void refuse_new_connections(refuse: bool) 🔗

将 DTLS 服务器配置为自动断开新连接。

注意:这个方法只有在调用了 dtls_server_setup 后才有用。


Array service(timeout: int = 0) 🔗

等待指定主机上的事件,并在主机与其对等体之间传送数据包。返回的 Array 将有 4 个元素。EventType、生成事件的 ENetPacketPeer、事件关联的数据(如果有)、事件关联的通道(如果有)。如果生成的事件是 EVENT_RECEIVE,则接收到的数据包,将被队列到关联的 ENetPacketPeer

定期调用该函数来处理连接、断开连接和接收新数据包。


void socket_send(destination_address: String, destination_port: int, packet: PackedByteArray) 🔗

Sends a packet toward a destination from the address and port currently bound by this ENetConnection instance.

This is useful as it serves to establish entries in NAT routing tables on all devices between this bound instance and the public facing internet, allowing a prospective client's connection packets to be routed backward through the NAT device(s) between the public internet and this host.

This requires forward knowledge of a prospective client's address and communication port as seen by the public internet - after any NAT devices have handled their connection request. This information can be obtained by a STUN service, and must be handed off to your host by an entity that is not the prospective client. This will never work for a client behind a Symmetric NAT due to the nature of the Symmetric NAT routing algorithm, as their IP and Port cannot be known beforehand.