StreamPeerTCP in Godot – Complete Guide

StreamPeerTCP is an essential part of Godot 4’s networking capabilities, allowing developers to manage TCP connections effectively within their games or applications. With the massive multiplayer online gaming industry and cloud-based applications on the rise, understanding technologies like StreamPeerTCP becomes ever more relevant.

What is StreamPeerTCP?

StreamPeerTCP is a class in the Godot Engine that encapsulates the functionality needed for TCP (Transmission Control Protocol) networking. TCP is a standard that defines how to establish and maintain a network conversation through which application programs can exchange data. Whether it is for a multiplayer game or a data-intensive application, TCP ensures reliable, ordered, and error-checked delivery of a stream of bytes between applications running on hosts communicating over an IP network.

What is it for?

This class is specialized for handling TCP connections. It provides developers with a high-level way to create networked experiences without delving into the low-level details of network programming. StreamPeerTCP can be used to connect to servers, send and receive data, and manage the state of the connection. It is an invaluable tool for creating multiplayer games, client-server applications, and any other project that requires network communication.

Why should I learn it?

Understanding StreamPeerTCP unlocks the potential to create connected experiences that are essential in today’s digital landscape. Here are a few reasons to learn about this powerhouse:

– Networking Knowledge: A solid grasp of TCP and networking principles will broaden your capabilities as a developer.
– Multiplayer Games: To develop real-time multiplayer games, you need to learn about network management, where StreamPeerTCP plays a vital role.
– Scalability: Knowledge of TCP connections is crucial when scaling applications to handle more users or data.
– Career Advantage: Many companies look for developers with networking skills, making this knowledge highly marketable.

Grasping the concepts behind StreamPeerTCP will open doors to exciting projects and opportunities in the realm of game development and beyond.

CTA Small Image

Creating a TCP Connection with StreamPeerTCP

To start using StreamPeerTCP, you need to establish a connection to a server. Here’s a basic example of how to connect to a server listening on IP “” at port 8080.

var tcp_connection =

func _ready():
    var error = tcp_connection.connect_to_host("", 8080)
    if error == OK:
        print("Connected successfully!")
        print("Failed to connect.")

This code will connect to a local server on your machine. The `connect_to_host` function initiates a connection, and returns `OK` if successful.

Sending Data Through TCP Connection

Once a connection is established, sending data is straightforward. In Godot, you need to have your data in form of a `PoolByteArray` to send it through the connection.

func send_message(message : String):
    var data = message.to_utf8()

This function converts a string into UTF-8 byte array and sends it through the open TCP connection. This is a basic way to send data, which is text in this case.

Receiving Data From TCP Connection

Receiving data is just a matter of reading from the connection. The `get_available_bytes()` method lets you know how much data there is to read.

func receive_message():
    var received_data = PoolByteArray()
    if tcp_connection.get_available_bytes() > 0:
        received_data = tcp_connection.get_data(tcp_connection.get_available_bytes())
        print("Received message: ", received_data.get_string_from_utf8())

In this snippet, we’re checking if there are any bytes available to read from the connection. If there are, we read all the available data and print the message to the console after converting it back to a string.

Handling Disconnections

It’s important to properly handle disconnections to prevent any unwanted exceptions or errors. In the following code, we check the connection status before attempting to read or write data.

func check_connection():
    if tcp_connection.is_connected_to_host():
        print("Connection is still open.")
        print("Connection is closed.")
        # Perform necessary cleanup, such as re-establishing the connection or shutting down.

This function assesses whether the connection is still live and will print a message accordingly. Proper disconnection handling is essential when working with network connections to maintain a robust application behavior.When working with StreamPeerTCP in Godot 4, it’s essential to handle network events properly. The engine’s main loop runs network operations asynchronously, so we must ensure we’re reacting to data as it becomes available.

Let’s explore handling server responses and various operations you might perform with a TCP connection.

Listening for Incoming Data
To process incoming data, you usually want to check for it in the `_process` function, which is called every frame.

func _process(delta):
    if tcp_connection.get_status() == StreamPeerTCP.STATUS_CONNECTED:
        if tcp_connection.get_available_bytes() > 0:
            var data = tcp_connection.get_data(tcp_connection.get_available_bytes())
            print("Received data: ", data.get_string_from_ascii())

In this example, we’re continuously checking if there’s incoming data as long as the connection is up. If there’s data available, we read and print it.

Sending Data Periodically
In some applications, you might want to send data at regular intervals, such as a heartbeat packet to keep the connection alive.

var heartbeat_timer = 0.0

func _process(delta):
    heartbeat_timer += delta
    if heartbeat_timer >= 5.0:
        heartbeat_timer = 0.0

func send_heartbeat():
    var heartbeat_msg = "ping"
    print("Sent heartbeat")

This block sends a “ping” message every 5 seconds. Adjusting this timer is essential, depending on the needs of your application.

Handling Disconnects Gracefully
Detecting when the other side has closed the connection allows you to shut down your end cleanly.

func _process(delta):
    if tcp_connection.get_status() != StreamPeerTCP.STATUS_CONNECTED:

func handle_disconnect():
    print("Disconnected from the server")

This code checks if the connection status is not connected, which indicates that the other side has probably disconnected.

Writing Structured Data
Sending plain text is fine for simple applications, but for more complex data, you’ll want to serialize your data into a structured format.

func send_player_position(x, y):
    var position = {
        "x": x,
        "y": y
    var position_json = to_json(position)

In this snippet, we’re sending a player’s position as JSON. This allows us to send more complex data structures across the network.

Synchronous Operations
While Godot handles TCP communication asynchronously by default, you might need to perform synchronous read or write under particular conditions.

func synchronous_send(data):
    var bytes_to_send = data.length()
    while bytes_to_send > 0:
        var sent_bytes = tcp_connection.put_data(data)
        if sent_bytes > 0:
            data = data.subarray(sent_bytes, data.length() - 1)
            bytes_to_send -= sent_bytes
            print("Failed to send data or the connection was closed")

This code continues to attempt to send data until it has all been sent, or an error occurs. Note, however, that locking up the main thread with synchronous operations can lead to a poor user experience, so this should be used sparingly.

Receiving Large Data Blocks
When expecting larger blocks of data, consider reading in chunks to avoid overloading your application.

func receive_large_data():
    var received_data = PoolByteArray()
    var chunk_size = 1024  # read 1024 bytes at a time
    while tcp_connection.get_available_bytes() > 0:
        var chunk = tcp_connection.get_partial_data(chunk_size)
    // Process the received data after completely reading it

In the code above, we’re reading the incoming data in 1024-byte chunks. This method is typically used when you know the size of incoming data or want to impose a limit to manage memory efficiently.

Understanding and properly utilizing these snippets will significantly enhance your ability to manage TCP connections in Godot 4, leading to more robust and interactive networked applications. With practice, you’ll be able to handle complex scenarios and create seamless online experiences.Effective management of network traffic and error handling are crucial for any networked application. Let’s delve further into some advanced use cases and examples where handling exceptions and optimizing data transmission can play a significant role in creating a stable networking environment in Godot 4 using StreamPeerTCP.

Checking for Errors during Data Transmission
When sending or receiving data over a TCP connection, it’s possible for various errors to occur. Properly managing these can prevent crashes and other problematic behaviors.

func send_safe_data(data):
    var error = tcp_connection.put_data(data)
    if error != OK:
        print("Failed to send data, error code: ", error)

This function sends data and checks the return value for errors, allowing for proper error handling and perhaps a retry mechanism.

Efficiently Handling Multiple Connections
While StreamPeerTCP handles one connection, you might have a server that needs to manage multiple clients concurrently.

var clients = []

func _process(delta):
    for client in clients:
        if client.get_status() != StreamPeerTCP.STATUS_CONNECTED:
            # Remove the disconnected client from the list
            print("Client disconnected.")
            # Perform routine checks or send updates to connected clients
            # ...

In this example, we have a list of client connections that we iterate over every frame, removing any clients that have disconnected.

Segmenting Data to Ensure Message Integrity
In some cases, you might send data that’s too large to be sent in one piece, or you want to ensure that messages are received as whole chunks.

func send_data_in_chunks(data, chunk_size):
    var total_sent = 0
    while total_sent < data.length():
        var end = min(data.length(), total_sent + chunk_size)
        var chunk = data.subarray(total_sent, end)
        var error = tcp_connection.put_data(chunk)
        if error == OK:
            total_sent += chunk_size
            print("Error sending data chunk: ", error)

This sends data in defined chunk sizes, assuming that `data` is a `PoolByteArray`. This can be critical for ensuring that large data sets are sent completely and correctly.

Reassembling Data Chunks
Just as important as sending data in chunks is the ability to reassemble these on the receiving end.

var buffered_data = PoolByteArray()

func receive_and_assemble_data():
    var bytes_to_read = tcp_connection.get_available_bytes()
    while bytes_to_read > 0:
        var chunk = tcp_connection.get_partial_data(min(chunk_size, bytes_to_read))
        bytes_to_read -= chunk_size

Here, we append each received chunk to a buffer, which allows for reassembly of the original message before processing it further.

Discarding Excess Data
Sometimes, you may need to discard data that is no longer relevant or is flooding your buffer.

func discard_incoming_data():
    var error = tcp_connection.get_available_bytes()
    if error > 0:
        tcp_connection.get_data(error)  # This reads and discards all available data

This example reads and ignores all available data, essentially flushing the buffer which can be useful when the received data is no longer needed, or you need to synchronize communication anew.

Timing Out Inactive Connections
To prevent dead or inactive connections from lingering indefinitely, it’s good practice to implement a timeout.

var connection_timeout_limit = 10.0
var connection_timer = 0.0

func _process(delta):
    connection_timer += delta
    if connection_timer > connection_timeout_limit:
        print("Connection timed out.")

This snippet adds a timeout that disconnects the TCP connection if it remains inactive for more than a given amount of time.

By incorporating these additional pieces of logic into your networked applications, you can ensure that data transfers are not only stable and reliable, but can also handle unexpected situations gracefully. It’s this level of detail and control that can ultimately make or break the networked experience of your game or application in Godot 4.

Where to Go Next?

Embarking on a journey to learn game development with Godot can be thrilling and challenging. If you’re eager to continue exploring and mastering the world of game creation, our Godot Game Development Mini-Degree is a fantastic resource to deepen your skills. This program is meticulously crafted to transition you from a beginner to a confident developer capable of building your own games.

Our Mini-Degree covers critical areas such as GDScript, 2D and 3D gameplay, control flow, player mechanics, and game systems spanning genres like RPGs and platformers. The beauty of Godot—and our courses—is the learner-friendly approach, ensuring you can progress at your own pace. Plus, the Godot engine is both free and open-source, providing an accessible and powerful platform for your creative projects.

For a broader selection of topics and to further expand your toolkit, make sure to explore our full range of Godot courses. With over 250 courses available, Zenva is ready to assist you in taking your game development aspirations to the next level, hone your craft, and open doors to new opportunities in the ever-growing field of game development.


In the ever-evolving landscape of game development, technologies like StreamPeerTCP in Godot 4 provide the backbone for creating interactive and connected experiences that captivate players around the globe. From multiplayer games that bring people together to robust network applications, mastering the skills taught in our Godot Game Development Mini-Degree will give you the expertise to breathe life into your innovative ideas.

At Zenva, we’re committed to empowering you with the knowledge to turn your dreams into reality. Whether you’re building your first game or looking to refine your existing skills, our courses are designed to support you every step of the way. Embrace the journey, expand your horizons, and join a community of learners who share your passion for game creation. Together, let’s unlock the full potential of your creative vision.

Python Blog Image

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