SocketIONamespace

Represents a Socket.IO namespace for event-based communication.

Description

SocketIONamespace represents a Socket.IO namespace, which provides isolated communication channels within a single WebSocket connection (multiplexing).

Namespaces allow you to organize your Socket.IO communication into separate logical channels. For example, you might have a /chat namespace for chat messages and a /notifications namespace for system notifications.

Each namespace has its own:

Connection state
Event handlers
Session ID

The main namespace "/" is created automatically when connecting to a server via SocketIOClient.

# Get or create namespace
var chat_ns = SocketIOClient.get_singleton().create_namespace("/chat")

# Connect with authentication
chat_ns.connect_to_namespace({"token": "user_token_here"})

# Listen for events
chat_ns.on("message", func(data):
    print("Received message: ", data[0])
)

chat_ns.on("user_joined", func(data):
    print("User joined: ", data[0]["username"])
)

# Emit events
chat_ns.emit("send_message", ["Hello everyone!"])

# Request-response pattern with acknowledgments
chat_ns.emit_with_ack("get_history", [100], func(messages):
    for msg in messages[0]:
        display_message(msg)
)

Tutorials

Socket.IO Developer Examples

Methods

Error	connect_to_namespace(auth: Dictionary = {})
void	disconnect_from_namespace()
void	emit(event: String, data: Array = [])
void	emit_with_ack(event: String, data: Array, callback: Callable, timeout: float = 5.0)
ConnectionState	get_connection_state() const
String	get_namespace_path() const
String	get_session_id() const
bool	is_namespace_connected() const
void	off(event: String, callback: Callable)
void	on(event: String, callback: Callable)

Signals

connected(session_id: String) 🔗

Emitted when this namespace successfully connects to the server. The session_id is the Socket.IO session identifier for this namespace.

disconnected(reason: String) 🔗

Emitted when this namespace is disconnected. The reason describes why the disconnection occurred.

event_received(event_name: String, data: Array) 🔗

Emitted for every event received from the server, regardless of whether specific listeners are registered. This is useful as a catch-all event handler.

The event_name is the name of the event, and data contains the event arguments.

Enumerations

enum ConnectionState: 🔗

ConnectionState STATE_DISCONNECTED = 0

The namespace is not connected.

ConnectionState STATE_CONNECTING = 1

The namespace is attempting to connect.

ConnectionState STATE_CONNECTED = 2

The namespace is connected and ready to send/receive events.

Method Descriptions

Error connect_to_namespace(auth: Dictionary = {}) 🔗

Connects to this namespace on the server. Returns @GlobalScope.OK on success.

The auth dictionary can contain authentication/authorization data that will be sent to the server. The server can use this to validate access to the namespace.

Note: The main namespace "/" connects automatically. You only need to call this for custom namespaces.

Wait for the connected signal before emitting events.

void disconnect_from_namespace() 🔗

Disconnects from this namespace. The WebSocket connection remains open for other namespaces.

The disconnected signal will be emitted.

void emit(event: String, data: Array = []) 🔗

Emits an event to the server with the given event name and data array.

The data array can contain any JSON-serializable types (strings, numbers, booleans, dictionaries, arrays) and binary data (PackedByteArray).

Binary data is automatically extracted and sent as separate attachments per the Socket.IO v5 protocol.

# Simple event
namespace.emit("hello", [])

# Event with data
namespace.emit("chat_message", ["Hello!", {"timestamp": Time.get_unix_time_from_system()}])

# Event with binary data
var image_data = load_image_as_bytes()
namespace.emit("upload_avatar", [image_data, "avatar.png"])

void emit_with_ack(event: String, data: Array, callback: Callable, timeout: float = 5.0) 🔗

Emits an event and expects an acknowledgment response from the server. The callback will be called when the server responds, or when the timeout (in seconds) is reached.

The callback receives an array containing the server's response data. If the timeout is reached, the callback receives ["timeout"].

This is useful for request-response patterns where you need confirmation or data back from the server.

# Request user profile with 10 second timeout
namespace.emit_with_ack("get_profile", [user_id], func(response):
    if response[0] == "timeout":
        print("Request timed out")
    else:
        var profile = response[0]
        display_profile(profile)
, 10.0)

ConnectionState get_connection_state() const 🔗

Returns the current connection state of this namespace as a ConnectionState value.

String get_namespace_path() const 🔗

Returns the namespace path (e.g., "/", "/admin", "/chat").

String get_session_id() const 🔗

Returns the Socket.IO session ID for this namespace. Returns an empty string if not connected.

This is different from the Engine.IO session ID and is specific to each namespace.

bool is_namespace_connected() const 🔗

There is currently no description for this method. Please help us by contributing one!

void off(event: String, callback: Callable) 🔗

Removes an event listener. The callback must be the same Callable that was registered with on().

var message_handler = func(data): print(data)
namespace.on("message", message_handler)
# Later...
namespace.off("message", message_handler)

void on(event: String, callback: Callable) 🔗

Registers an event listener for the given event name. When the server emits this event, the callback will be called with an array containing the event data.

Multiple callbacks can be registered for the same event. They will all be called in the order they were registered.

namespace.on("player_moved", func(data):
    var player_id = data[0]
    var position = data[1]
    update_player_position(player_id, position)
)