StreamPeerTLS in Godot – Complete Guide

Secure connections are fundamental in an interconnected, digital world. Whether you’re creating a multiplayer game, a chat app, or any other project that involves communicating data over the internet, ensuring that this information is sent securely and privately is paramount. In this tutorial, we’re going to delve deep into StreamPeerTLS, a class in Godot 4 that is pertinent for achieving secure network communication through TLS (Transport Layer Security).

Knowing how to implement StreamPeerTLS in your Godot projects is not just about adding a layer of security; it’s also about deeply understanding the mechanics of secure network connections, which you can leverage to build professional and reliable software. As you ease into the topic, you’ll find that the complexities of network encryption become manageable and engaging as we explore the practical aspects of using StreamPeerTLS through examples and explanations.

What is StreamPeerTLS?

StreamPeerTLS is a class in the Godot Engine that provides TLS functionality for network connections. Essentially, TLS is the successor to SSL (Secure Sockets Layer), which is widely used to secure transmissions over the internet. When you access a website with HTTPS, that’s TLS in action – it’s encrypting your communication with the site to prevent eavesdropping or tampering.

In Godot, the StreamPeerTLS class wraps around a regular StreamPeer to encrypt the incoming and outgoing bytes using TLS. It’s an essential tool for Godot developers who want to ensure their network communications remain confidential and authenticated.

What is it for?

StreamPeerTLS is used for creating secure connections between a Godot app and a server, or between a Godot server and a client. This could be vital in:

– Securing transmissions in a multiplayer game.
– Encrypting data sent to and from an API.
– Ensuring the privacy of chat messages in a networking app.

By using StreamPeerTLS, you are effectively preventing unauthorized access to data in transit, establishing trust in your application, and complying with modern security standards.

Why Should I Learn It?

Understanding how to implement StreamPeerTLS can elevate your Godot skills, making you capable of developing not only fun and interactive experiences but also secure and trustworthy applications. Here are some compelling reasons why learning StreamPeerTLS is valuable:

– **Security**: As cyber threats continue to evolve, a fundamental understanding of network security is indispensable.
– **Professional Development**: Knowledge of secure network communication is a sought-after skill in the game development industry.
– **Trust**: Users are increasingly conscious about their data privacy. Implementing TLS can help build users’ trust in your applications.

As we progress through this tutorial, be prepared to engage with realistic examples that give life to these concepts, and remember, grasping TLS will be a substantial addition to your toolkit as a budding Godot developer.

CTA Small Image

Basic Setup of StreamPeerTLS in Godot

To begin using StreamPeerTLS, you need to establish a StreamPeer connection. Let’s start by creating a basic connection without the TLS layer, which we will later secure.

var connection =
if connection.connect_to_host("", 443) == OK:
    print("Connected to the host successfully!")
    print("Failed to connect to the host.")

In this snippet, you create a `StreamPeerTCP` object and attempt to connect to “” on port 443, which is the default port for HTTPS connections. This is a non-secured connection as of now.

Upgrading to a Secure Connection

Now, let’s upgrade our connection to use TLS. First, you’ll need to instantiate a `StreamPeerTLS` object and start the handshake process to establish the secure connection.

var tls_connection =
if tls_connection.start_handshake(connection, true) == OK:
    print("TLS handshake was successful!")
    print("TLS handshake failed.")

This code initializes the TLS handshake on the previously established `StreamPeerTCP` connection. The `true` argument stands for whether the handshake is for a server (`false`) or a client (`true`).

Sending and Receiving Secure Data

With a TLS connection established, sending and receiving data is now secure. Here’s an example of sending a HTTP GET request over our secured connection:

var request = "GET / HTTP/1.1\r\nHost:\r\n\r\n"

Listening for a response is similar to an unsecured stream, but it’s encrypted transparently by the `StreamPeerTLS` class:

var response = PoolByteArray()
while tls_connection.get_status() == StreamPeerTLS.STATUS_CONNECTED:

In this snippet, we listen for incoming data as long as the connection is active and append it to our response array. We then print the response as a UTF-8 string.

Error Handling with StreamPeerTLS

Error handling is key when working with network protocols. With StreamPeerTLS, you’ll likely need to handle errors such as failed handshakes or disconnected peers. Here’s a basic approach to error handling:

var result = tls_connection.start_handshake(connection, true)
match result:
        print("TLS handshake was successful!")
        print("Can't connect to the host.")
        print("Certificate could not be found.")
        print("An unknown error occurred: ", result)

This code checks the result of the handshake and responds accordingly, using Godot’s built-in error constants for more readable code.

Throughout these snippets, we’ve covered the basic steps of setting up a StreamPeerTLS connection, performing a handshake, and handling errors. In the following sections, we’ll continue to build upon these foundations and explore more advanced features of using StreamPeerTLS in your Godot projects. Stay tuned as we delve deeper into making the most out of secure connections in Godot.Handling a Disconnected Peer is another essential aspect. When working with network connections, peers may disconnect unexpectedly. Below is an example of how you might handle such an event:

func _process(delta):
    if tls_connection.get_status() == StreamPeerTLS.STATUS_DISCONNECTED:
        print("The peer has disconnected.")
        # Perform any necessary cleanup here

In this example, we are checking the connection status during the game loop (assuming this code is inside a node with an active process callback) and printing a message when the peer has disconnected.

Next, let’s consider the case where we want to verify the server’s SSL certificate to ensure we’re connecting to the correct server. Doing so is crucial for preventing Man-in-the-Middle (MitM) attacks:

var cert =
if cert.load("path/to/your/certificate.crt") == OK:
    print("Certificate loaded and verification mode set.")
    print("Failed to load certificate.")

In the above snippet, we load an X509 certificate from a given path and configure the `StreamPeerTLS` to verify the peer against this certificate.

Now, consider you want to gracefully close the TLS connection:

func disconnect_from_host():
    print("Disconnected from host.")

This function triggers a disconnection from the host, which is especially important for cleanly ending the session and freeing up resources.

What if you need to handle binary data? Godot’s `StreamPeer` classes, including `StreamPeerTLS`, can handle binary data transmission:

var data_to_send = PoolByteArray([1, 2, 3, 4, 5])  # Some binary data
print("Binary data sent.")

In this code snippet, we form a `PoolByteArray` with arbitrary binary data and send it over the TLS connection.

When receiving binary data, you might want to wait until a certain amount of data is available:

func get_data(size):
    var received_data = PoolByteArray()
    while received_data.size()  0:
            received_data.append_array(tls_connection.get_partial_data(size - received_data.size()))
    return received_data

# Usage
var size_expected = 1024  # The size of the data we expect to receive
var data = get_data(size_expected)
print("Received data of expected size.")

In the `get_data` function, we loop until we have received the size of data we expect. The `get_partial_data` method fetches only the data that’s currently available up to the desired size.

Managing time-out is another important aspect of dealing with network communications:

var start_time = OS.get_ticks_msec()

while tls_connection.get_status() == StreamPeerTLS.STATUS_CONNECTED and OS.get_ticks_msec() - start_time = 5000:
    print("Connection timed out.")

This example uses `get_ticks_msec` method from the OS singleton to determine the time passed. If the connection is still active but no data has been received or sent in 5 seconds, we consider the connection to have timed out.

These sections of code demonstrate a few scenarios in which you might use `StreamPeerTLS` in your projects, elaborating on both sending and receiving data, handling disconnections, managing certificates, and dealing with binary data and timeouts. Familiarizing yourself with these operations will significantly aid your ability to build secure and robust networked applications with Godot. Remember, each connection is unique and might require different handling based on the network conditions and the specifics of your application.Continuing on our journey with `StreamPeerTLS`, let’s explore handling more data-intensive operations. This can be particularly relevant when developing applications that require the transmission of large volumes of data over secure connections, such as file transfers or continuous data streams in a multiplayer game.

Firstly, you might want to implement a function that continues to read until it has received a specified amount of data. This is useful for scenarios where the data size is known in advance, such as when dealing with fixed-format messages or chunks of a larger data transfer:

func read_exactly(tls_stream, amount):
    var buffer = PoolByteArray()
    while buffer.size() < amount:
        var chunk = tls_stream.get_partial_data(amount - buffer.size())
        if chunk.size() == 0:
            break  # No more data available at the moment
    return buffer

# Usage
var expected_size = 4096
var data = read_exactly(tls_connection, expected_size)
if data.size() == expected_size:
    print("Received all the expected data.")
    print("Did not receive all the expected data.")

In the example above, we define a function `read_exactly()` that attempts to read the exact amount of data expected from the `tls_stream`. This loop continues asking for data until either the required amount is received or no more data is available at the current time.

When working with JSON data, which is common for many applications, you’ll want to securely send and receive JSON objects:

var json_data = { "name": "Zenva", "course": "Godot Security" }
var json_string = to_json(json_data)

# Later, when receiving
var received_json_data = JSON.parse(tls_connection.get_string_from_utf8())
if received_json_data.error == OK:
    print("Received JSON data: ", received_json_data.result)
    print("Failed to parse JSON data.")

By encoding the JSON data as a UTF-8 string before sending, and parsing the received UTF-8 string back into JSON, we ensure that the structure of data is preserved over the TLS connection.

To efficiently manage multiple incoming connections or requests, you may want to implement a non-blocking or asynchronous pattern. This can be achieved using Godot’s `yield` functionality in combination with signals:

func _ready():
    var peer_accepted = yield(tls_connection, "peer_connected")
    print("New peer connected: ", peer_accepted)

# Elsewhere in the code, after the `peer_connected` signal is emitted
func handle_new_peer(tls_stream):
    var data = tls_stream.get_some_data()  # Your function to handle peer data
    print("Data received from new peer: ", data)

The `yield` waits for the “peer_connected” signal before continuing, allowing your code to react to new connections without continual polling, which can make the code cleaner and more efficient.

Sometimes you need to ensure that the data has been fully sent before continuing, especially when sending a sequence of messages or commands:

func send_and_flush(tls_stream, data):
    print("Data sent and flushed.")

# Example usage
var command = "PAUSE GAME"
send_and_flush(tls_connection, command.to_utf8())

Here, `put_flush()` ensures that all data previously sent to the stream is flushed through to the receiving end, providing a guarantee that the data is on its way before you carry on with the next steps in your code.

Let’s now consider a situation where you expect to receive messages that are delimited in some way, for example by a newline character, which is typical of line-based protocols:

func get_line_from_stream(tls_stream):
    var line = PoolByteArray()
    var byte_array = PoolByteArray([ord('\n')])
    while true:
        var byte = tls_stream.get_partial_data(1)
        if byte.size() == 0 or byte[0] == byte_array[0]:
            break  # We've reached the end of a line or no data is available
    return line.get_string_from_utf8()

# Usage
while tls_connection.get_status() == StreamPeerTLS.STATUS_CONNECTED:
    var line = get_line_from_stream(tls_connection)
    if line != "":
        print("Received line: ", line)

In this function `get_line_from_stream`, we read from the stream one byte at a time until we encounter the newline character. This approach is useful when protocols rely on these kinds of terminators to denote the end of a message or command.

The examples provided give you a flavor of the various types of I/O operations you may encounter when developing networked applications with Godot’s StreamPeerTLS. Practical understanding and implementation of these patterns can significantly contribute to making your application robust and user-friendly. Remember to always test your networked features thoroughly to ensure that they can handle the unpredictable nature of real-world networking conditions.

Next Steps in Your Game Development Journey

Embarking on the path of secure networking in Godot is just a starting point. As you continue honing your Godot skills, consider taking them to the next level with our comprehensive Godot Game Development Mini-Degree. This curated series of courses empowers you to build cross-platform games from scratch. You’ll learn about crafting engaging gameplay, utilizing both 2D and 3D assets, scripting with GDScript, and much more. It’s perfect for reinforcing the basics if you’re just starting out, or for enhancing your existing development prowess with deeper insights into Godot 4’s powerful capabilities.

Our Mini-Degree is designed with flexibility in mind, featuring a mix of live coding lessons, quizzes, and interactive learning experiences. By working through real projects, you’ll build a personal portfolio that showcases your ability to create diverse games, such as RPGs, RTSs, survival games, and platformers. Godot’s expansive, open-source community support will be at your disposal, buoying you towards potential opportunities in the burgeoning game market.

For an even broader spectrum of learning materials, our full range of Godot courses will ensure that all your learning needs are met, regardless of where you are on your game development journey. With over 250 courses available, Zenva has the resources you need to advance your career, master coding, and excel in game creation. Begin today, and watch as your game development dreams turn into reality.


Delving into the nuances of secure network programming with Godot’s StreamPeerTLS is just the tip of the iceberg in your game development adventure. By mastering secure communication, you’re not only upgrading your technical repertoire, but you’re also committing to the privacy and security of your users – a step that can set your projects apart in today’s security-conscious environment. We hope this guide empowers you to confidently implement TLS in your forthcoming Godot projects and ignites a passion for going even further in your game development journey with us.

Tackling new challenges, such as secure networking, is only one facet of what you’ll experience through our Godot Game Development Mini-Degree. Each step forward with Zenva is a stride towards expertise, opening new pathways to turn your most ambitious game concepts into tangible, playable realities. So why wait? Continue your ascent to game development mastery and forge the path to creating the games you’ve always imagined. Your story as a celebrated game developer starts here – with Zenva, where learning never ends and every skill you acquire becomes a part of your success.

Python Blog Image

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