Struct PacketPeerUdp

pub struct PacketPeerUdp { /* private fields */ }

Expand description

Godot class PacketPeerUDP.

Inherits PacketPeer.

Related symbols:

packet_peer_udp: sidecar module with related enum/flag types
IPacketPeerUdp: virtual methods

§Construction

This class is reference-counted. You can create a new instance using PacketPeerUdp::new_gd().

§Godot docs

UDP packet peer. Can be used to send and receive raw UDP packets as well as Variants.

Example: Send a packet:

var peer = PacketPeerUDP.new()

# Optionally, you can select the local port used to send the packet.
peer.bind(4444)

peer.set_dest_address("1.1.1.1", 4433)
peer.put_packet("hello".to_utf8_buffer())

Example: Listen for packets:

var peer

func _ready():
	peer = PacketPeerUDP.new()
	peer.bind(4433)


func _process(_delta):
	if peer.get_available_packet_count() > 0:
		var array_bytes = peer.get_packet()
		var packet_string = array_bytes.get_string_from_ascii()
		print("Received message: ", packet_string)

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Implementations§

§

impl PacketPeerUdp

pub fn bind(&mut self, port: i32) -> Error

To set the default parameters, use bind_ex and its builder methods. See the book for detailed usage instructions. Binds this PacketPeerUDP to the specified port and bind_address with a buffer size recv_buf_size, allowing it to receive incoming packets.

If bind_address is set to "*" (default), the peer will be bound on all available addresses (both IPv4 and IPv6).

If bind_address is set to "0.0.0.0" (for IPv4) or "::" (for IPv6), the peer will be bound to all available addresses matching that IP type.

If bind_address is set to any valid address (e.g. "192.168.1.101", "::1", etc.), the peer will only be bound to the interface with that address (or fail if no interface with the given address exists).

pub fn bind_ex<'ex>(&'ex mut self, port: i32) -> ExBind<'ex>

Binds this PacketPeerUDP to the specified port and bind_address with a buffer size recv_buf_size, allowing it to receive incoming packets.

If bind_address is set to "*" (default), the peer will be bound on all available addresses (both IPv4 and IPv6).

If bind_address is set to "0.0.0.0" (for IPv4) or "::" (for IPv6), the peer will be bound to all available addresses matching that IP type.

If bind_address is set to any valid address (e.g. "192.168.1.101", "::1", etc.), the peer will only be bound to the interface with that address (or fail if no interface with the given address exists).

pub fn close(&mut self)

Closes the PacketPeerUDP’s underlying UDP socket.

pub fn wait(&mut self) -> Error

Waits for a packet to arrive on the bound address. See bind.

Note: wait can’t be interrupted once it has been called. This can be worked around by allowing the other party to send a specific “death pill” packet like this:

socket = PacketPeerUDP.new()
# Server
socket.set_dest_address("127.0.0.1", 789)
socket.put_packet("Time to stop".to_ascii_buffer())

# Client
while socket.wait() == OK:
	var data = socket.get_packet().get_string_from_ascii()
	if data == "Time to stop":
		return

pub fn is_bound(&self) -> bool

Returns whether this PacketPeerUDP is bound to an address and can receive packets.

pub fn connect_to_host(&mut self, host: impl AsArg<GString>, port: i32) -> Error

Calling this method connects this UDP peer to the given host/port pair. UDP is in reality connectionless, so this option only means that incoming packets from different addresses are automatically discarded, and that outgoing packets are always sent to the connected address (future calls to set_dest_address are not allowed). This method does not send any data to the remote peer, to do that, use put_var or put_packet as usual. See also UDPServer.

Note: Connecting to the remote peer does not help to protect from malicious attacks like IP spoofing, etc. Think about using an encryption technique like TLS or DTLS if you feel like your application is transferring sensitive information.

pub fn is_socket_connected(&self) -> bool

Returns true if the UDP socket is open and has been connected to a remote address. See connect_to_host.

pub fn get_packet_ip(&self) -> GString

Returns the IP of the remote peer that sent the last packet(that was received with get_packet or get_var).

pub fn get_packet_port(&self) -> i32

Returns the port of the remote peer that sent the last packet(that was received with get_packet or get_var).

pub fn get_local_port(&self) -> i32

Returns the local port to which this peer is bound.

pub fn set_dest_address( &mut self, host: impl AsArg<GString>, port: i32, ) -> Error

Sets the destination address and port for sending packets and variables. A hostname will be resolved using DNS if needed.

Note: set_broadcast_enabled must be enabled before sending packets to a broadcast address (e.g. 255.255.255.255).

pub fn set_broadcast_enabled(&mut self, enabled: bool)

Enable or disable sending of broadcast packets (e.g. set_dest_address("255.255.255.255", 4343). This option is disabled by default.

Note: Some Android devices might require the CHANGE_WIFI_MULTICAST_STATE permission and this option to be enabled to receive broadcast packets too.

pub fn join_multicast_group( &mut self, multicast_address: impl AsArg<GString>, interface_name: impl AsArg<GString>, ) -> Error

Joins the multicast group specified by multicast_address using the interface identified by interface_name.

You can join the same multicast group with multiple interfaces. Use get_local_interfaces to know which are available.

Note: Some Android devices might require the CHANGE_WIFI_MULTICAST_STATE permission for multicast to work.

pub fn leave_multicast_group( &mut self, multicast_address: impl AsArg<GString>, interface_name: impl AsArg<GString>, ) -> Error

Removes the interface identified by interface_name from the multicast group specified by multicast_address.

Methods from Deref<Target = PacketPeer>§

pub fn get_var(&mut self) -> Variant

To set the default parameters, use get_var_ex and its builder methods. See the book for detailed usage instructions. Gets a Variant. If allow_objects is true, decoding objects is allowed.

Internally, this uses the same decoding mechanism as the bytes_to_var method.

Warning: Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.

pub fn get_var_ex<'ex>(&'ex mut self) -> ExGetVar<'ex>

Gets a Variant. If allow_objects is true, decoding objects is allowed.

Internally, this uses the same decoding mechanism as the bytes_to_var method.

Warning: Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution.

pub fn put_var(&mut self, var: &Variant) -> Error

To set the default parameters, use put_var_ex and its builder methods. See the book for detailed usage instructions. Sends a Variant as a packet. If full_objects is true, encoding objects is allowed (and can potentially include code).

Internally, this uses the same encoding mechanism as the var_to_bytes method.

pub fn put_var_ex<'ex>(&'ex mut self, var: &'ex Variant) -> ExPutVar<'ex>

Sends a Variant as a packet. If full_objects is true, encoding objects is allowed (and can potentially include code).

Internally, this uses the same encoding mechanism as the var_to_bytes method.

pub fn get_packet(&mut self) -> PackedArray<u8>

Gets a raw packet.

pub fn put_packet(&mut self, buffer: &PackedArray<u8>) -> Error

Sends a raw packet.

pub fn get_packet_error(&self) -> Error

Returns the error state of the last packet received (via get_packet and get_var).

pub fn get_available_packet_count(&self) -> i32

Returns the number of packets currently available in the ring-buffer.

pub fn get_encode_buffer_max_size(&self) -> i32

pub fn set_encode_buffer_max_size(&mut self, max_size: i32)

Methods from Deref<Target = RefCounted>§

pub fn get_reference_count(&self) -> i32

Returns the current reference count.

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

Returns the object’s built-in class name, as a String. See also is_class.

Note: This method ignores class_name declarations. If this object’s script has defined a class_name, the base, built-in class name is returned instead.

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

Returns true if the object inherits from the given class. See also get_class.

var sprite2d = Sprite2D.new()
sprite2d.is_class("Sprite2D") # Returns true
sprite2d.is_class("Node")     # Returns true
sprite2d.is_class("Node3D")   # Returns false

Note: This method ignores class_name declarations in the object’s script.

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

Assigns value to the given property. If the property does not exist or the given value’s type doesn’t match, nothing happens.

var node = Node2D.new()
node.set("global_scale", Vector2(8, 2.5))
print(node.global_scale) # Prints (8.0, 2.5)

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

Returns the Variant value of the given property. If the property does not exist, this method returns null.

var node = Node2D.new()
node.rotation = 1.5
var a = node.get("rotation") # a is 1.5

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

Assigns a new value to the property identified by the property_path. The path should be a NodePath relative to this object, and can use the colon character (:) to access nested properties.

var node = Node2D.new()
node.set_indexed("position", Vector2(42, 0))
node.set_indexed("position:y", -10)
print(node.position) # Prints (42.0, -10.0)

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

Gets the object’s property indexed by the given property_path. The path should be a NodePath relative to the current object and can use the colon character (:) to access nested properties.

Examples: "position:x" or "material:next_pass:blend_mode".

var node = Node2D.new()
node.position = Vector2(5, -10)
var a = node.get_indexed("position")   # a is Vector2(5, -10)
var b = node.get_indexed("position:y") # b is -10

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

Note: This method does not support actual paths to nodes in the SceneTree, only sub-property paths. In the context of nodes, use get_node_and_resource instead.

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns the object’s property list as an Array of dictionaries. Each Dictionary contains the following entries:

name is the property’s name, as a String;
class_name is an empty StringName, unless the property is VariantType::OBJECT and it inherits from a class;
type is the property’s type, as an int (see [enum Variant.Type]);
hint is how the property is meant to be edited (see [enum PropertyHint]);
hint_string depends on the hint (see [enum PropertyHint]);
usage is a combination of [enum PropertyUsageFlags].

Note: In GDScript, all class members are treated as properties. In C# and GDExtension, it may be necessary to explicitly mark class members as Godot properties using decorators or attributes.

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns this object’s methods and their signatures as an Array of dictionaries. Each Dictionary contains the following entries:

name is the name of the method, as a String;
args is an Array of dictionaries representing the arguments;
default_args is the default arguments as an Array of variants;
flags is a combination of [enum MethodFlags];
id is the method’s internal identifier int;
return is the returned value, as a Dictionary;

Note: The dictionaries of args and return are formatted identically to the results of get_property_list, although not all entries are used.

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

Returns true if the given property has a custom default value. Use property_get_revert to get the property’s default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns false.

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

Returns the custom default value of the given property. Use property_can_revert to check if the property has a custom default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns null.

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

Adds or changes the entry name inside the object’s metadata. The metadata value can be any Variant, although some types cannot be serialized correctly.

If value is null, the entry is removed. This is the equivalent of using remove_meta. See also has_meta and get_meta.

Note: A metadata’s name must be a valid identifier as per is_valid_identifier method.