UPNP in Godot – Complete Guide

Welcome to a world where games and applications seamlessly communicate with the vast network that is the internet, breaking free from the constraints of local play. Today, we’re venturing into the realms of network programming within Godot Engine, specifically focusing on the Universal Plug and Play (UPnP) features newly introduced in Godot 4. Whether you’re an aspiring game developer or a seasoned coder, understanding UPnP in Godot can be a game-changer for your projects. Prepare to equip yourself with the knowledge to bridge local content to the global stage.

What is UPnP?

UPnP stands for Universal Plug and Play, a set of networking protocols that permits networked devices, such as PCs and printers, to effortlessly discover each other’s presence on the network and establish functional network services. UPnP’s magic lies in its ability to manage network configurations, facilitating activities like port forwarding, essential for multiplayer games and services that require external network access.

What is it for in Godot?

Within the context of Godot Engine, UPnP plays a critical role in simplifying the creation of network connections for multiplayer functionality. It allows your Godot project to dynamically configure a network router, paving the way for other players to connect to a game hosted on a local network – all without the pesky need for manual router configuration.

Why should I learn it?

Learning about UPnP is pivotal for any budding or experienced developer aiming to create games or applications with online connectivity. Here’s why:

– **Streamlined Networking**: UPnP automates the technical aspects of network communication, making it easier to connect players from different networks.
– **Accessibility**: It empowers your applications to be accessible by players worldwide, without them needing to fiddle with their router settings.
– **Security and Control**: By managing port forwarding programmatically, you are in control of network security, ensuring that only the necessary ports are open and used when needed.

CTA Small Image

Initializing UPnP in Your Godot Project

To start using UPnP in Godot, you’ll first need to initialize the UPnP instance. It’s a simple setup process that enables your game to communicate with network devices using UPnP protocols.

var upnp = UPNP.new()

func _ready():
    # Initialize UPnP with our desired settings
    if upnp.get_gateway():
        print("UPnP Gateway found: ", upnp.get_gateway().get_description())

This basic initialization script will search for UPnP-capable gateways on your network and, if available, print the gateway’s description to the console.

Setting up Port Forwarding

Once you have UPnP initialized, the next step is to set up port forwarding. This is crucial for allowing external connections to access your game server. You will specify which local port to forward and the desired external port that external users will connect to.

# Forward port 7777 to the external port 7777
func _ready():
    upnp.add_port_mapping(7777, 7777, "UDP")

    # Ensure to check if port mapping is added successfully
    if upnp.is_mapping_ok():
        print("Port forwarding is setup successfully!")
        print("Failed to setup port forwarding.")

In this example, we forward local port 7777 to the same external port number for UDP traffic. Always verify if the port mapping is successful with `is_mapping_ok()`.

Removing a Port Mapping

For the sake of security and clean network configurations, it’s essential to remove port mappings when they are no longer needed. This can be done simply with Godot’s UPnP implementation.

# Remove the previously added port mapping
func _exit_tree():
    upnp.delete_port_mapping(7777, "UDP")
    print("Port forwarding removed.")

It’s good practice to remove port mappings when a game server shuts down or when a player disconnects.

Handling Dynamic IP Addresses

Not every user has a static IP address, and you might need to update port mappings if an IP address changes. Here’s how you can handle dynamic IP checks and updates within Godot’s UPnP.

func _process(delta):
    # Check for IP change every few seconds
    if OS.get_ticks_msec() % 10000 == 0:
        var new_ip = upnp.discover()
        if new_ip != current_ip:
            upnp.delete_port_mapping(7777, "UDP")
            upnp.add_port_mapping(7777, 7777, "UDP")
            print("IP has changed, port mapping updated.")

In this snippet, we have a process loop that periodically checks for an IP address change every 10 seconds and updates the port mapping accordingly.

Remember: UPnP settings and capabilities can vary between different devices and networks, so functionality isn’t always guaranteed. It’s a good idea to build fallback mechanisms for scenarios where UPnP may not be available or fails to configure correctly. Stay tuned for the next part of our series where we’ll dive into more complex UPnP configurations and troubleshooting common issues.As you dive deeper into the functionality of UPnP in Godot, it becomes apparent how this tool can elevate your networked games. Let’s explore further into the world of Godot’s UPnP with more advanced coding examples and critical information.

When working with UPnP, one of the elements you might want to handle is the lease duration for your port mappings. This specifies how long the port remains open without needing to be refreshed. In Godot, you can set the lease duration in seconds as shown below:

# Set a lease duration of 3600 seconds (1 hour) for port forwarding
func _ready():
    upnp.add_port_mapping(7777, 7777, "UDP", 3600)
    if upnp.is_mapping_ok():
        print("Port forwarding with lease duration is setup successfully!")

Always remember to check if UPnP is available and if port forwarding is successfully set with `is_mapping_ok()`. If the mapping fails, it is important to inform the user or attempt an alternative networking setup.

Additionally, you can retrieve a list of existing port mappings to keep track of which ports have been forwarded. This can be particularly useful for debugging purposes or for managing multiple port mappings dynamically:

var mappings = upnp.get_port_mapping_list()
for mapping in mappings:
    print("External Port: ", mapping.external_port, " Protocol: ", mapping.protocol)

Sometimes, you’ll need to differentiate between internal clients that are part of your local network and external clients connecting over the internet. To facilitate this, you can use the UPnP instance to get the local IP address of the host machine:

var local_ip = upnp.get_local_ip()
print("Local IP Address: ", local_ip)

This IP address can be used when you’re setting up your game server, making sure that local clients can directly connect without going through the external internet.

Furthermore, you might want to determine the external IP address that UPnP has registered with the port mapping. This is relevant for external clients to know where to connect:

var external_ip = upnp.query_external_address()
if external_ip != "":
    print("External IP Address: ", external_ip)
    print("Could not retrieve external IP address.")

In case you are running a game that should not be interrupted (like a long tournament), it’s essential to keep renewing the port mappings as per the lease time. Consider setting up a recurring method that renews port mapping leases:

func renew_port_mappings():
    upnp.delete_port_mapping(7777, "UDP")  # First remove the old mapping
    upnp.add_port_mapping(7777, 7777, "UDP", 3600)  # Then add it anew with a fresh lease

    # Setup a timer to run this method again just before the lease expires
    var timer = Timer.new()
    timer.set_wait_time(3500)  # Slightly less than the lease duration
    timer.connect("timeout", self, "renew_port_mappings")

Creating the timer within the function, connecting it to a timeout signal, and starting it ensures that your mapping will try to renew before the current lease ends. It’s a way to keep your game server accessible as long as it’s needed.

Finally, interacting with UPnP requires network communication, which might not be instantaneous. Consider running these potentially longer tasks in separate threads, especially in a production environment, to avoid stalling your main game loop:

func _ready():
    var thread = Thread.new()
    thread.start(self, "_threaded_upnp_setup")
    # ...rest of your game setup code...

func _threaded_upnp_setup():
    if upnp.add_port_mapping(7777, 7777, "UDP", 3600) and upnp.is_mapping_ok():
        print("Port mapping added successfully in a separate thread.")

Working with UPnP in Godot can at times feel like a collection of simple steps, yet it has profound effects on the multiplayer experience you can offer. Mastering these techniques not only sharpens your network programming skills but also massively enhances the accessibility and professionalism of your multiplayer projects. Continue experimenting, refining, and remember to always keep an eye on your networking performance and security considerations.UPnP integration in Godot is an essential skill for developing games with seamless multiplayer experiences. As we delve into the details, remember that practical implementation is as important as understanding the concepts.

Sometimes you may need to test whether UPnP services are enabled and functional on the network. You can perform a simple check using the following code, which can help decide how to proceed with networking setup:

func is_upnp_enabled():
    return upnp.get_gateway() != null

if is_upnp_enabled():
    print("UPnP is enabled. Proceed with port forwarding.")
    print("UPnP is not enabled. Consider alternative networking solutions.")

If UPnP is disabled on the network, your game should be able to handle this gracefully, preferably by providing the users with informative feedback or alternative connection options.

In cases where multiple port mappings are needed, such as running separate UDP and TCP services, you can easily set up both mappings in Godot:

func setup_multiple_port_mappings():
    upnp.add_port_mapping(7777, 7777, "UDP")
    upnp.add_port_mapping(8888, 8888, "TCP")

    if upnp.is_mapping_ok():
        print("Both UDP and TCP port mappings are set up successfully.")

While mapping common ports such as 7777 for UDP or 8888 for TCP can sometimes lead to conflicts, especially if other services on the network use these ports, you can implement a method to find and map an available port dynamically:

func setup_dynamic_port_mapping():
    var local_port = 7777
    while local_port < 8000:
        upnp.add_port_mapping(local_port, local_port, "UDP")
        if upnp.is_mapping_ok():
            print("Dynamically found and mapped an available port: ", local_port)
        local_port += 1
    print("No available port found within the range.")

To ensure optimal functionalities, and before fully committing to using UPnP, it’s a good idea to create a cleanup function that removes all port mappings made during the session. This function can be called when the game session ends:

func cleanup_upnp():
    # Assuming we have a list or array of opened ports stored
    for port in opened_ports:
        upnp.delete_port_mapping(port, "UDP")
    print("Cleaned up all UPnP port mappings.")

Keeping track of the opened ports in a session variable (`opened_ports`) allows for efficient cleanup operations.

Another useful aspect of UPnP you might need is the ability to update an existing port mapping. This can become necessary if your game session changes the port it’s operating on, or if you need to adjust mappings on-the-fly:

func update_port_mapping(old_port, new_port):
    upnp.delete_port_mapping(old_port, "UDP")  # Remove the old mapping first
    upnp.add_port_mapping(new_port, new_port, "UDP")  # Then create a new mapping

    if upnp.is_mapping_ok():
        print("Updated port mapping from ", old_port, " to ", new_port)

Always remember to check that your updated port mapping has been successful, ensuring a smooth multiplayer experience.

And finally, for developers implementing lobbies or server lists, it’s often desirable to return the port back to its default state to enable the next game session to configure its own necessities:

func reset_to_default_port_mapping(default_port):
    upnp.delete_port_mapping(current_port, "UDP")  # Clear the current setting
    upnp.add_port_mapping(default_port, default_port, "UDP")  # Reset to default port

    if upnp.is_mapping_ok():
        print("Successfully reset to the default port: ", default_port)

This ensures that the network environment is left in a manageable state for future sessions or other applications requiring UPnP services.

These examples provide a more comprehensive view of UPnP’s integration into Godot, giving you the tools to better manage network configurations for robust multiplayer functionality. As you continue your journey in game development with Godot, you’ll find these techniques invaluable for optimizing player connectivity and satisfaction.

Continuing Your Godot Journey

Delving into the world of Godot and its UPnP capabilities is just the beginning of what you can achieve. As you continue to explore and master game development, we encourage you to further your journey and keep building on the knowledge you’ve acquired. Our Godot Game Development Mini-Degree is the perfect next step for those looking to expand their skills with Godot.

With our comprehensive courses, you can delve into a variety of topics, from perfecting 2D and 3D game mechanics to mastering UI systems and exploring different genres like RPGs, RTS games, and platformers. Godot’s open-source nature, combined with our project-based courses, provides a rich learning experience that can open doors to new opportunities in the game development industry.

Don’t stop at UPnP— broaden your Godot expertise with Zenva’s flexible learning options and hands-on challenges. And if you seek to widen your horizons even further, our complete collection of Godot courses is available to support you at any stage of your learning path. Whether you’re just starting or looking to specialize, our curriculum has something for everyone. Join us at Zenva and take your game development career to the next level!


In closing, integrating UPnP in your Godot projects may seem like a small step, but it’s a giant leap in enhancing the multiplayer capabilities of your games. You’ve unlocked the potential to connect players from around the globe with ease, pushing the boundaries of what’s possible in indie and professional game development alike. And remember, this is only a fraction of the power that Godot and your creativity can unleash.

Continue to learn, experiment, and build with us at Zenva. Our Godot Game Development Mini-Degree is designed to support you through every line of code and every new challenge. With Zenva, you’re not just learning to code – you’re learning to create. Let’s make games that resonate, engage, and surprise. Indulge your passion for game development, and let’s craft unforgettable experiences together.

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.