PacketPeerStream in Godot – Complete Guide

Navigating the waters of game development can be challenging, but mastering the nuances of network communication is a powerful step towards creating multiplayer experiences and more connected games. In Godot 4, understanding the PacketPeerStream class is crucial for managing data exchange over networks effectively. This tutorial series will shed light on PacketPeerStream, demonstrating its use and features with practical examples. Prepare to amplify your Godot coding toolkit and embrace the exciting possibilities of networked gameplay!

What Is PacketPeerStream?


is a class in the Godot 4 engine. It acts as a wrapper that allows you to use PacketPeer over a StreamPeer, providing the tools to send and receive data in packet form via streams. This abstraction is particularly useful when dealing with TCP or UDP protocols where data is typically handled in chunks, or “packets”.

What Is It For?
The PacketPeerStream class enables developers to write packet-based code that can interact with streams. This is highly beneficial when creating networked applications or multiplayer game features, as it simplifies the process of sending and receiving discrete chunks of data.

Why Should I Learn It?
Learning how to use PacketPeerStream can make the difference between a game that plays locally and one that connects players across the globe. By wrapping your head around this concept, you’ll be able to create more robust and responsive online game experiences, opening up a world of gaming that is dynamic and interactive.

Continue on this journey to expand your Godot skills and venture into the realm of networked game development with confidence and curiosity. Let’s dive into the world of PacketPeerStream together!

CTA Small Image

Setting Up PacketPeerStream

Before we delve into code examples, it’s crucial to understand how to set up PacketPeerStream. We’ll start by creating a PacketPeerStream instance and pair it with a StreamPeerTCP instance for TCP communication.

// Create a StreamPeerTCP instance
var tcp =

// Create a PacketPeerStream instance
var pps =

// Set the StreamPeerTCP instance as the base for the PacketPeerStream
pps.stream_peer = tcp

With these lines of code, we’ve prepared a networked environment within Godot where we can send and receive packets of data over TCP.

Connecting to a Server

To initiate communication, the client needs to connect to a server. Here’s how to use StreamPeerTCP to connect to a server at a specified IP and port.

// Connect to a server at IP "" and port 8080
var error = tcp.connect_to_host("", 8080)

if error != OK:
    print("Failed to connect to host:", error)
    print("Successfully connected to host")

This example checks for any connection errors and prints the status to the console. Replace “” and “8080” with the appropriate server IP address and port you want to connect to.

Sending Data to the Server

Once connected, you may want to send data to the server. PacketPeerStream.put_packet() makes this simple.

// Assume we are connected and tcp is the connected StreamPeerTCP's instance
var message = "Hello, Server!"
// Convert string message to raw data
var raw_data = message.to_utf8()

// Use put_packet() to send the raw data

This code snippet converts a string message to UTF-8 byte array and sends it as a packet to the connected server.

Receiving Data from the Server

In a networked environment, receiving data is just as important as sending it. This code snippet demonstrates receiving a packet from the server:

// Call this method in _process or when you expect data
func receive_data_from_server():
    // Check if a packet is available
    if pps.get_available_packet_count() > 0:
        # Get the packet as raw data
        var raw_data = pps.get_packet()
        # Convert the raw data to string
        var message = raw_data.get_string_from_utf8()
        print("Received message from server: ", message)

This function checks for available packets and, if present, processes one and prints the message to the console.

Closing the Connection

Properly closing the connection is essential for clean network communication. When finished, ensure you close the StreamPeerTCP connection:

// Close the TCP connection when no longer needed

Closing the connection helps to avoid unnecessary use of server resources and potential memory leaks.

These examples cover the basics of setting up PacketPeerStream, connecting to a server, sending and receiving data, and properly closing the connection. They are the foundational blocks for creating networked interactions using Godot 4. In the next part, we’ll explore more advanced use cases and build upon these concepts.

Moving deeper into the functionalities of the PacketPeerStream, let’s explore how we can manage more complex data structures, handle errors, and create a listening server.

Handling Complex Data Structures

Games usually require the transfer of complex data structures like dictionaries or arrays. To facilitate this, Godot provides the methods put_var and get_var.

// Sending a dictionary to the server
var player_data = {"name": "Player1", "score": 5000}

// Receiving a dictionary or any variable data from the server
func receive_variable_data_from_server():
    if pps.get_available_packet_count() > 0:
        var received_var = pps.get_var()
        if received_var is Dictionary:
            print("Received Dictionary:", received_var)

This pair of methods takes care of serializing and deserializing complex data types, so they can be sent and received over the network.

Error Handling during Data Transmission

Error handling is crucial when working with network communication to ensure reliability and robustness. Here’s an example for error checking when sending data:

var status = pps.put_packet(raw_data)
if status != OK:
    print("Failed to send packet:", status)
    print("Packet sent successfully")

This code snippet checks for errors after attempting to send a packet and responds accordingly. A similar approach should be taken for error handling when receiving packets.

Creating a Listening Server

Up till now, we’ve focused on the client-side. Let’s switch gears and set up a basic server to listen for connections using Godot’s StreamPeerTCP.listen() method:

// Assuming tcp is a StreamPeerTCP instance

func start_server(port):
    var error = tcp.listen(port)
    if error != OK:
        print("Failed to start server:", error)
        print("Server is listening on port", port)

In this snippet, we attempt to listen to a port and handle potential errors. This is the first step in establishing a server that clients can connect to.

To accept connections, we can poll for them in _process:

func _process(delta):
    if tcp.is_listening() and tcp.is_connection_available():
        var new_connection = tcp.take_connection()
        print("New client connected")

This code checks if a new connection is available and, if so, accepts it.

Reading and Writing to Connected Clients

A server that can’t communicate with its clients isn’t very useful. Here’s how you can read and write to clients:

// Write to a connected client
func send_data_to_client(conn):
    var message = "Welcome to the server!"
    var error = conn.put_packet(message.to_utf8())
    if error != OK:
        print("Failed to send data to client:", error)

// Read data from a connected client
func read_data_from_client(conn):
    if conn.get_available_packet_count() > 0:
        var packet = conn.get_packet()
        var message = packet.get_string_from_utf8()
        print("Received from client:", message)

These examples use a StreamPeerTCP instance representing a connected client (conn) to send and receive packets of data.

Utilizing these techniques, you can create not just clients but also servers within the Godot environment, effectively allowing you to build the infrastructure for multiplayer games or other networked applications. As your understanding of PacketPeerStream grows, you’ll be perfectly positioned to explore more intricate network operations and gameplay logic.

As you grow more comfortable with setting up clients and servers, it’s time to explore advanced functionalities such as broadcasting messages, gracefully handling client disconnections, and ensuring secure data transmission.

Broadcasting messages to all connected clients is a common requirement for games, especially in multiplayer lobbies. Let’s create a basic framework to manage clients and send broadcasts.

var clients = []

# Function to add a newly connected client to the clients array
func add_client(new_client):

# Function to broadcast a message to all connected clients
func broadcast_message(message):
    var raw_data = message.to_utf8()
    for client in clients:
        var error = client.put_packet(raw_data)
        if error != OK:
            print("Failed to send message to client:", error)

It’s equally important to handle client disconnections properly to avoid sending data to non-existent recipients.

# Function to remove a disconnected client from the clients array
func remove_client(disconnected_client):

Now, let’s make sure we’re efficiently cleaning up and removing any clients that have disconnected.

func _process(delta):
    for client in clients:
        if client.get_status() == StreamPeerTCP.STATUS_NONE:
            print("Client disconnected")

When data security is a concern, especially with sensitive information like player credentials, encryption comes into play. Godot’s PacketPeerStream doesn’t provide encryption out of the box, but you can implement it at the application level.

Here’s a simplistic example of applying a basic XOR cipher to the data before sending it over the network:

# Function to apply XOR cipher to a pool byte array
func xor_cipher(data, key):
    var crypted_data = PoolByteArray()
    for i in range(0, data.size()):
        crypted_data.append(data[i] ^ key)
    return crypted_data

# Encrypting a message before sending
func send_encrypted_message(client, message, key):
    var raw_data = message.to_utf8()
    raw_data = xor_cipher(raw_data, key)

# Decrypting a message upon reception
func receive_encrypted_message(client, key):
    if client.get_available_packet_count() > 0:
        var crypted_data = client.get_packet()
        var raw_data = xor_cipher(crypted_data, key)
        var message = raw_data.get_string_from_utf8()
        print("Received encrypted message:", message)

Please note that this XOR example is purely educational and should not be used in production. For real-world applications, look into robust encryption methods such as TLS, which are outside the scope of this introduction.

Advanced networking also demands proper synchronization of game state across clients. For this, we can timestamp packets and use an authoritative server model to ensure everyone has the most up-to-date information.

# Function to send a timestamped game state to clients
func send_game_state(game_state):
    var timestamp = OS.get_unix_time()
    var packet = {"timestamp": timestamp, "state": game_state}

Finally, as your multiplayer game or application becomes more complex, it’s a good practice to implement a protocol to manage the different packet types and data structures you’re sending and receiving.

# Use an Enum to define different packet types

# Add a type field to your packets
func send_typed_message(client, message, type):
    var packet = {"type": type, "data": message}

By now, you should have a solid grasp of using PacketPeerStream in Godot 4 for network communication. Remember, these examples serve as stepping stones for building more sophisticated systems tailored to your specific game or application needs. With practice and innovation, you can leverage these fundamental building blocks to create an exciting and feature-rich multiplayer experience.

Continue Your Game Development Journey with Zenva

Exploring the intricacies of the PacketPeerStream class in Godot 4 is just the beginning of your game development adventure. If this tutorial sparked your curiosity and you’re eager to dive deeper into the world of Godot and game creation, our Godot Game Development Mini-Degree is an excellent next step to continue honing your skills.

This comprehensive course collection will guide you through a variety of topics, from GDScript essentials to creating engaging gameplay mechanics across a spectrum of game genres. You’ll gain hands-on experience by working on projects that can enhance your portfolio, all while learning at your own pace. Our curriculum is designed for both beginners and seasoned developers, ensuring that you can build a solid foundation or expand on your existing knowledge.

Ready to broaden your expertise? Explore our full range of Godot courses, where you’ll find content that will help you become a well-rounded developer, capable of bringing your unique game ideas to life. Check out our entire catalog of Godot tutorials and take another step towards mastering game development. At Zenva, we’re proud to help you grow from a beginner to a professional, providing over 250 courses tailored to boost your career in technology.


The journey of mastering network communication in Godot 4 with PacketPeerStream is one filled with opportunities to create dynamic and connected gaming experiences. As we’ve seen, understanding how to send and receive data across the network is a potent skill in the ever-evolving world of game development. By applying the principles and code examples from this tutorial, you’re well on your way to developing engaging multiplayer games and networked applications that could captivate a global audience.

And this is just the tip of the iceberg. When you’re ready to elevate your expertise, Zenva’s Godot Game Development Mini-Degree awaits to take you through a vast landscape of coding, design, and game mechanics. Enhance your knowledge, create your dream project, and join the ranks of successful game developers with the tools and support from our comprehensive courses. The future of gaming is bright, and with Zenva, you’re always one step closer to reaching your game development zenith.

Python Blog Image

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