Struct Upnp

pub struct Upnp { /* private fields */ }

Expand description

Godot class UPNP.

Inherits RefCounted.

Related symbols:

upnp: sidecar module with related enum/flag types
IUpnp: virtual methods

§Construction

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

§Godot docs

This class can be used to discover compatible UPNPDevices on the local network and execute commands on them, like managing port mappings (for port forwarding/NAT traversal) and querying the local and remote network IP address. Note that methods on this class are synchronous and block the calling thread.

To forward a specific port (here 7777, note both discover and add_port_mapping can return errors that should be checked):

var upnp = UPNP.new()
upnp.discover()
upnp.add_port_mapping(7777)

To close a specific port (e.g. after you have finished using it):

upnp.delete_port_mapping(port)

Note: UPnP discovery blocks the current thread. To perform discovery without blocking the main thread, use Threads like this:

# Emitted when UPnP port mapping setup is completed (regardless of success or failure).
signal upnp_completed(error)

# Replace this with your own server port number between 1024 and 65535.
const SERVER_PORT = 3928
var thread = null

func _upnp_setup(server_port):
	# UPNP queries take some time.
	var upnp = UPNP.new()
	var err = upnp.discover()

	if err != OK:
		push_error(str(err))
		upnp_completed.emit(err)
		return

	if upnp.get_gateway() and upnp.get_gateway().is_valid_gateway():
		upnp.add_port_mapping(server_port, server_port, ProjectSettings.get_setting("application/config/name"), "UDP")
		upnp.add_port_mapping(server_port, server_port, ProjectSettings.get_setting("application/config/name"), "TCP")
		upnp_completed.emit(OK)

func _ready():
	thread = Thread.new()
	thread.start(_upnp_setup.bind(SERVER_PORT))

func _exit_tree():
	# Wait for thread finish here to handle game exit while the thread is running.
	thread.wait_to_finish()

Terminology: In the context of UPnP networking, “gateway” (or “internet gateway device”, short IGD) refers to network devices that allow computers in the local network to access the internet (“wide area network”, WAN). These gateways are often also called “routers”.

Pitfalls:

As explained above, these calls are blocking and shouldn’t be run on the main thread, especially as they can block for multiple seconds at a time. Use threading!
Networking is physical and messy. Packets get lost in transit or get filtered, addresses, free ports and assigned mappings change, and devices may leave or join the network at any time. Be mindful of this, be diligent when checking and handling errors, and handle these gracefully if you can: add clear error UI, timeouts and re-try handling.
Port mappings may change (and be removed) at any time, and the remote/external IP address of the gateway can change likewise. You should consider re-querying the external IP and try to update/refresh the port mapping periodically (for example, every 5 minutes and on networking failures).
Not all devices support UPnP, and some users disable UPnP support. You need to handle this (e.g. documenting and requiring the user to manually forward ports, or adding alternative methods of NAT traversal, like a relay/mirror server, or NAT hole punching, STUN/TURN, etc.).
Consider what happens on mapping conflicts. Maybe multiple users on the same network would like to play your game at the same time, or maybe another application uses the same port. Make the port configurable, and optimally choose a port automatically (re-trying with a different port on failure).

Further reading: If you want to know more about UPnP (and the Internet Gateway Device (IGD) and Port Control Protocol (PCP) specifically), Wikipedia is a good first stop, the specification can be found at the Open Connectivity Foundation and Godot’s implementation is based on the MiniUPnP client.

Implementations§

§

impl Upnp

pub fn get_device_count(&self) -> i32

Returns the number of discovered UPNPDevices.

pub fn get_device(&self, index: i32) -> Option<Gd<UpnpDevice>>

Returns the UPNPDevice at the given index.

pub fn add_device(&mut self, device: impl AsArg<Option<Gd<UpnpDevice>>>)

Adds the given UPNPDevice to the list of discovered devices.

pub fn set_device( &mut self, index: i32, device: impl AsArg<Option<Gd<UpnpDevice>>>, )

Sets the device at index from the list of discovered devices to device.

pub fn remove_device(&mut self, index: i32)

Removes the device at index from the list of discovered devices.

pub fn clear_devices(&mut self)

Clears the list of discovered devices.

pub fn get_gateway(&self) -> Option<Gd<UpnpDevice>>

Returns the default gateway. That is the first discovered UPNPDevice that is also a valid IGD (InternetGatewayDevice).

pub fn discover(&mut self) -> i32

To set the default parameters, use discover_ex and its builder methods. See the book for detailed usage instructions. Discovers local UPNPDevices. Clears the list of previously discovered devices.

Filters for IGD (InternetGatewayDevice) type devices by default, as those manage port forwarding. timeout is the time to wait for responses in milliseconds. ttl is the time-to-live; only touch this if you know what you’re doing.

See [enum UPNPResult] for possible return values.

pub fn discover_ex<'ex>(&'ex mut self) -> ExDiscover<'ex>

Discovers local UPNPDevices. Clears the list of previously discovered devices.

Filters for IGD (InternetGatewayDevice) type devices by default, as those manage port forwarding. timeout is the time to wait for responses in milliseconds. ttl is the time-to-live; only touch this if you know what you’re doing.

See [enum UPNPResult] for possible return values.

pub fn query_external_address(&self) -> GString

Returns the external IP address of the default gateway (see get_gateway) as string. Returns an empty string on error.

pub fn add_port_mapping(&self, port: i32) -> i32

To set the default parameters, use add_port_mapping_ex and its builder methods. See the book for detailed usage instructions. Adds a mapping to forward the external port (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see get_gateway) to the port_internal on the local machine for the given protocol proto (either "TCP" or "UDP", with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with get_gateway and call add_port_mapping on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device.

Depending on the gateway device, if a mapping for that port already exists, it will either be updated or it will refuse this command due to that conflict, especially if the existing mapping for that port wasn’t created via UPnP or points to a different network address (or device) than this one.

If port_internal is 0 (the default), the same port number is used for both the external and the internal port (the port value).

The description (desc) is shown in some routers management UIs and can be used to point out which application added the mapping.

The mapping’s lease duration can be limited by specifying a duration in seconds. The default of 0 means no duration, i.e. a permanent lease and notably some devices only support these permanent leases. Note that whether permanent or not, this is only a request and the gateway may still decide at any point to remove the mapping (which usually happens on a reboot of the gateway, when its external IP address changes, or on some models when it detects a port mapping has become inactive, i.e. had no traffic for multiple minutes). If not 0 (permanent), the allowed range according to spec is between 120 (2 minutes) and 86400 seconds (24 hours).

See [enum UPNPResult] for possible return values.

pub fn add_port_mapping_ex<'ex>(&'ex self, port: i32) -> ExAddPortMapping<'ex>

Adds a mapping to forward the external port (between 1 and 65535, although recommended to use port 1024 or above) on the default gateway (see get_gateway) to the port_internal on the local machine for the given protocol proto (either "TCP" or "UDP", with UDP being the default). If a port mapping for the given port and protocol combination already exists on that gateway device, this method tries to overwrite it. If that is not desired, you can retrieve the gateway manually with get_gateway and call add_port_mapping on it, if any. Note that forwarding a well-known port (below 1024) with UPnP may fail depending on the device.

Depending on the gateway device, if a mapping for that port already exists, it will either be updated or it will refuse this command due to that conflict, especially if the existing mapping for that port wasn’t created via UPnP or points to a different network address (or device) than this one.

If port_internal is 0 (the default), the same port number is used for both the external and the internal port (the port value).

The description (desc) is shown in some routers management UIs and can be used to point out which application added the mapping.

The mapping’s lease duration can be limited by specifying a duration in seconds. The default of 0 means no duration, i.e. a permanent lease and notably some devices only support these permanent leases. Note that whether permanent or not, this is only a request and the gateway may still decide at any point to remove the mapping (which usually happens on a reboot of the gateway, when its external IP address changes, or on some models when it detects a port mapping has become inactive, i.e. had no traffic for multiple minutes). If not 0 (permanent), the allowed range according to spec is between 120 (2 minutes) and 86400 seconds (24 hours).

See [enum UPNPResult] for possible return values.

pub fn delete_port_mapping(&self, port: i32) -> i32

To set the default parameters, use delete_port_mapping_ex and its builder methods. See the book for detailed usage instructions. Deletes the port mapping for the given port and protocol combination on the default gateway (see get_gateway) if one exists. port must be a valid port between 1 and 65535, proto can be either "TCP" or "UDP". May be refused for mappings pointing to addresses other than this one, for well-known ports (below 1024), or for mappings not added via UPnP. See [enum UPNPResult] for possible return values.

pub fn delete_port_mapping_ex<'ex>( &'ex self, port: i32, ) -> ExDeletePortMapping<'ex>

Deletes the port mapping for the given port and protocol combination on the default gateway (see get_gateway) if one exists. port must be a valid port between 1 and 65535, proto can be either "TCP" or "UDP". May be refused for mappings pointing to addresses other than this one, for well-known ports (below 1024), or for mappings not added via UPnP. See [enum UPNPResult] for possible return values.

pub fn set_discover_multicast_if(&mut self, m_if: impl AsArg<GString>)

pub fn get_discover_multicast_if(&self) -> GString

pub fn set_discover_local_port(&mut self, port: i32)

pub fn get_discover_local_port(&self) -> i32

pub fn set_discover_ipv6(&mut self, ipv6: bool)

pub fn is_discover_ipv6(&self) -> bool

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.