SocketIOClient

Inherits: Object

Socket.IO v5 protocol client for real-time bidirectional communication.

Description

SocketIOClient is a singleton that provides full Socket.IO v5 protocol client functionality. It manages WebSocket connections, namespaces, and handles the Socket.IO packet encoding/decoding automatically.

Socket.IO enables real-time, bidirectional communication between clients and servers. It's commonly used for chat applications, live updates, real-time games, and any application requiring instant data synchronization.

The client supports:

  • Multiple namespaces (multiplexing)

  • Event-based communication

  • Acknowledgments with timeout

  • Binary data transmission

  • Automatic reconnection handling

  • TLS/SSL secure connections (wss://)

Important: You must call poll() regularly (e.g., in _process) to process incoming messages and maintain the connection.

# Connect to server
var socketio = SocketIOClient.get_singleton()
socketio.connect_to_url("ws://localhost:3000")

# Get main namespace and set up event handlers
var main_ns = socketio.get_namespace("/")
main_ns.on("welcome", func(data): print("Welcome: ", data))
main_ns.on("message", func(data): handle_message(data))

# Emit events
main_ns.emit("chat_message", ["Hello, server!"])

# Use acknowledgments
main_ns.emit_with_ack("get_user_data", [123], func(response):
    print("User data: ", response)
)

# Poll in _process
func _process(delta):
    socketio.poll()

For more information about the Socket.IO protocol, see: https://socket.io/docs/v4/socket-io-protocol/

Tutorials

Methods

void

close()

Error

connect_to_url(url: String, auth: Dictionary = {}, tls_options: TLSOptions = null)

SocketIONamespace

create_namespace(namespace: String)

ConnectionState

get_connection_state() const

String

get_connection_url() const

String

get_engine_io_session_id() const

SocketIONamespace

get_namespace(namespace: String = "/")

bool

has_namespace(namespace: String) const

bool

is_socket_connected() const

void

poll()

Signals

connect_error(error: Dictionary) 🔗

Emitted when a connection error occurs. The error dictionary contains error information from the server, typically including a "message" field.

connected(session_id: String) 🔗

Emitted when successfully connected to the server's main namespace ("/"). The session_id is the Socket.IO session identifier.

disconnected(reason: String) 🔗

Emitted when disconnected from the server. The reason describes why the disconnection occurred (e.g., "client disconnect", "server disconnect", connection error message).

namespace_connected(namespace_path: String) 🔗

Emitted when a namespace successfully connects. Use this to know when custom namespaces are ready to use.

namespace_disconnected(namespace_path: String) 🔗

Emitted when a namespace is disconnected.

Enumerations

enum ConnectionState: 🔗

ConnectionState STATE_DISCONNECTED = 0

The client is not connected to any server.

ConnectionState STATE_CONNECTING = 1

The client is attempting to connect to the server.

ConnectionState STATE_CONNECTED = 2

The client is connected to the server.

Method Descriptions

void close() 🔗

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

Error connect_to_url(url: String, auth: Dictionary = {}, tls_options: TLSOptions = null) 🔗

Connects to a Socket.IO server at the given url. Returns @GlobalScope.OK on success, or an error code on failure.

The url should be in the format ws://host:port or wss://host:port for secure connections. The /socket.io/ path and Engine.IO parameters are automatically appended.

The auth dictionary can contain authentication data that will be sent with the initial connection to the main namespace.

The tls_options parameter allows you to configure TLS/SSL settings for secure connections. Use TLSOptions.client() for standard secure connections.

After connecting, the main namespace ("/") is automatically created and will attempt to connect. Listen for the connected signal to know when the connection is established.

Note: You must call poll() regularly for the connection to work.

SocketIONamespace create_namespace(namespace: String) 🔗

Creates and returns a new SocketIONamespace for the given namespace path. If the namespace already exists, returns the existing one.

The namespace must start with a forward slash (e.g., "/admin", "/chat").

After creating a namespace, you must call SocketIONamespace.connect_to_namespace() to actually connect to it on the server.

var admin_ns = socketio.create_namespace("/admin")
admin_ns.connect_to_namespace({"token": "secret123"})
admin_ns.on("admin_event", func(data): process_admin(data))

ConnectionState get_connection_state() const 🔗

Returns the current connection state as a ConnectionState value.

String get_connection_url() const 🔗

Returns the URL that was used to connect to the server.

String get_engine_io_session_id() const 🔗

Returns the Engine.IO session ID received from the server. This is different from the Socket.IO session ID (which is per-namespace).

Returns an empty string if not connected.

SocketIONamespace get_namespace(namespace: String = "/") 🔗

Returns the SocketIONamespace for the given namespace path, or null if it doesn't exist.

The main namespace "/" is created automatically when connecting.

bool has_namespace(namespace: String) const 🔗

Returns true if a namespace with the given path exists.

bool is_socket_connected() const 🔗

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

void poll() 🔗

Processes incoming and outgoing Socket.IO messages. This method must be called regularly (typically in _process) for the client to function.

This method handles:

  • WebSocket message processing

  • Packet encoding/decoding

  • Event dispatching to namespaces

  • Acknowledgment timeout checking

  • Connection state updates