Client SDK

The Client SDK provides everything you need to connect to a Colyseus server from your game or application.

Client Setup

The Client instance is your entry point to connect to the server.

client.ts

import { Client } from "@colyseus/sdk";
const client = new Client("http://localhost:2567");
 
// ... with full-stack type safety (optional)
import type { server } from "../../server/src/app.config.ts";
const client = new Client<typeof server>("http://localhost:2567");

Client.cs

using Colyseus;
 
Client client = new Client("http://localhost:2567");

client.lua

local Colyseus = require("colyseus.sdk")
 
local client = Colyseus.Client("http://localhost:2567");

client.hx

import io.colyseus.Client;
 
var client = new Client("http://localhost:2567");

client.gd

var client = Colyseus.Client.new("ws://localhost:2567")

client.dart

import 'package:colyseus/colyseus.dart';
 
final client = ColyseusClient('ws://localhost:2567');

Joining Rooms

Once you have a client, you can join rooms. Choose the method that best fits your matchmaking needs.

Join or Create (Recommended)

The most common way to connect. Joins an existing room if available, or creates a new one.

client.ts

try {
  const room = await client.joinOrCreate("battle", {/* options */});
  console.log("joined successfully", room);
 
} catch (e) {
  console.error("join error", e);
}

Client.cs

try {
  Colyseus.Room<YourStateClass> room = await client.JoinOrCreate<YourStateClass>("battle", /* Dictionary of options */);
  Debug.Log("joined successfully");
 
} catch (ex) {
  Debug.Log("join error");
  Debug.Log(ex.Message);
}

client.lua

client:join_or_create("battle", {--[[options]]}, function(err, room)
  if (err ~= nil) then
    print("join error: " .. err)
    return
  end
 
  print("joined successfully")
end)

client.hx

client.joinOrCreate("battle", [/* options */], YourStateClass, function(err, room) {
  if (err != null) {
    trace("join error: " + err);
    return;
  }
 
  trace("joined successfully");
});

client.gd

var room: Colyseus.Room = client.join_or_create("battle")
 
room.joined.connect(func():
    print("joined successfully"))
 
room.error.connect(func(code: int, message: String):
    printerr("join error: ", message))

client.dart

try {
  final room = await client.joinOrCreate('battle',
      options: {/* options */}, stateType: MyRoomState.new);
  print('joined successfully');
 
} catch (e) {
  print('join error: $e');
}

Locked or private rooms are ignored by this method.

Other Join Methods

These methods use the same pattern as joinOrCreate. Replace the method name accordingly.

Method	Signature	Description
`create`	`client.create(roomName, options)`	Always creates a new room, even if others exist.
`join`	`client.join(roomName, options)`	Joins an existing room. Fails if none available. Locked/private rooms are ignored.
`joinById`	`client.joinById(roomId, options)`	Joins a specific room by its unique ID. Private rooms can be joined by ID. Useful for invite links.
`consumeSeatReservation`	`client.consumeSeatReservation(reservation)`	Joins using a pre-reserved seat from the server. See Matchmaker → Reserve Seat For.

You may disallow the client from creating rooms. See Matchmaker → Restricting the frontend from creating rooms

Example: Creating an invite link with joinById

client.ts

// Share the room ID with other players
const inviteLink = `https://mygame.com/join?roomId=${room.roomId}`;
 
// On the receiving end, parse the room ID and join
const params = new URLSearchParams(window.location.search);
const room = await client.joinById(params.get("roomId"));

Send and Receive Messages

Once connected to a room, you can send and receive messages in real-time.

Sending Messages

Send messages to the room. Messages are encoded with MsgPack and can hold any JSON-serializable data.

client.ts

//
// sending message with string type
//
room.send("move", { direction: "left"});
 
//
// sending message with number type
//
room.send(0, { direction: "left"});

Client.cs

//
// sending message with string type
//
await room.Send("move", new { direction = "left" });
 
//
// sending message with number type
//
await room.Send(0, new { direction = "left" });

client.lua

--
-- sending message with string type
--
room:send("move", { direction = "left" })
 
--
-- sending message with number type
--
room:send(0, { direction = "left" })

client.hx

//
// sending message with string type
//
room.send("move", { direction: "left" });
 
//
// sending message with number type
//
room.send(0, { direction: "left" });

client.gd

# sending message with string type
room.send_message("move", {"direction": "left"})
 
# sending message with number type
room.send_message(0, {"direction": "left"})

client.dart

//
// sending message with string type
//
room.send('move', {'direction': 'left'});
 
//
// sending message with number type
//
room.sendInt(0, {'direction': 'left'});

Backend: See Room → Message Handling for detailed documentation on receiving messages from the client.

Send Raw Bytes

For custom encoding, send a Uint8Array of raw bytes.

client.js

//
// sending message with number type
//
room.sendBytes(0, new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));
 
//
// sending message with string type
//
room.sendBytes("some-bytes", new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));

⚠️

The payload must be a Uint8Array. A plain number[] array silently sends an empty message, since the SDK reads .byteLength from the payload.

Receiving Messages

Listen for messages sent from the server.

client.ts

room.onMessage("powerup", (message) => {
  console.log("message received from server");
  console.log(message);
});

Client.cs

class PowerUpMessage {
  string kind;
}
 
room.OnMessage<PowerUpMessage>("powerup", (message) => {
  Debug.Log ("message received from server");
  Debug.Log(message);
});

client.lua

room:on_message("powerup", function(message)
  print("message received from server")
  print(message)
end)

client.hx

room.onMessage("powerup", function(message) {
  trace("message received from server");
  trace(Std.string(message));
});

client.gd

room.message_received.connect(_on_message_received)
 
func _on_message_received(type: Variant, message: Variant):
    print("message received from server")
    print(message)

client.dart

room.onMessage('powerup').listen((message) {
  print('message received from server');
  print(message);
});

Backend: To send a message from the server to a client, use client.send() or room.broadcast().

Request/Response

Send a message and await the server’s reply. The server answers by returning a value from its matching message handler.

client.ts

//
// Promise form: room.request(type, payload)
//
const profile = await room.request("get-profile", { userId: 42 });
 
//
// Override the default timeout (10s) per request
//
const result = await room.request("slow-task", { id }, { timeout: 30_000 });
 
//
// Callback form: pass a 3rd argument to room.send()
//
room.send("get-profile", { userId: 42 }, (profile, error) => {
    if (error) { return console.error(error); }
    console.log(profile);
});

The promise rejects (or the callback receives an error) when the handler throws or no handler is registered for that type. Rejection also happens when the connection closes first, or when no reply arrives within the timeout. The default timeout is Room.defaultRequestTimeout (10000 ms), overridable per request via the timeout option.

The server may also deliberately reject a request via ctx.reject(reason): a business-logic “no”, distinct from an error. The rejection arrives as an Error with name: "rejected", and the server’s raw reason on its .reason property:

client.ts

try {
    await room.request("join-team", { team: "red" });
} catch (e: any) {
    if (e.name === "rejected") {
        console.log(e.reason); // => { code: "TEAM_FULL", team: "red" }
    }
}

Pass mode: "unreliable" in the options to send the request over the unreliable channel, when the transport has one. A genuine packet drop is then surfaced by the timeout.

Request/response is currently available in the JavaScript/TypeScript SDK.

Sending Input (Netcode)

For prediction-ready rooms (rooms that call defineInput() on the server), room.input() returns a typed input channel: stage fields on input.data, then input.send() once per fixed step.

client.ts

const input = room.input();   // input schema arrives from the server's defineInput()
 
input.data.moveX = 1;
input.data.jump = true;
input.send();

Inputs are buffered and acknowledged, and power client-side prediction and lag compensation. See room.input(options) for the full reference: reliability modes, redundancy, and the InputHandle surface.

The netcode APIs (room.input(), room.clock, Predict) are available in Colyseus 0.18+ across the official SDKs. See Client Prediction.

State Synchronization

The room state is automatically synchronized from the server to all connected clients. The room.state property always contains the latest state.

State Sync Callbacks (Recommended)

Use Callbacks to listen for specific property changes with fine-grained control.

client.ts

import { Callbacks } from "@colyseus/sdk";
 
const callbacks = Callbacks.get(room);
 
callbacks.listen("currentTurn", (currentValue, previousValue) => {
    console.log("Turn changed:", previousValue, "->", currentValue);
});
 
callbacks.onAdd("players", (player, sessionId) => {
    console.log("Player joined:", sessionId);
 
    callbacks.listen(player, "hp", (currentHp, previousHp) => {
        console.log("Player", sessionId, "hp:", currentHp);
    });
});
 
callbacks.onRemove("players", (player, sessionId) => {
    console.log("Player left:", sessionId);
});

client.cs

var callbacks = Colyseus.Schema.Callbacks.Get(room);
 
callbacks.Listen(state => state.currentTurn, (currentValue, previousValue) => {
    Debug.Log($"Turn changed: {previousValue} -> {currentValue}");
});
 
callbacks.OnAdd(state => state.players, (sessionId, player) => {
    Debug.Log($"Player joined: {sessionId}");
 
    callbacks.Listen(player, p => p.hp, (currentHp, previousHp) => {
        Debug.Log($"Player {sessionId} hp: {currentHp}");
    });
});
 
callbacks.OnRemove(state => state.players, (sessionId, player) => {
    Debug.Log($"Player left: {sessionId}");
});

client.lua

local callbacks = ColyseusSDK.callbacks(room)
 
callbacks:listen("currentTurn", function(currentValue, previousValue)
    print("Turn changed: " .. tostring(previousValue) .. " -> " .. tostring(currentValue))
end)
 
callbacks:on_add("players", function(player, sessionId)
    print("Player joined: " .. sessionId)
 
    callbacks:listen(player, "hp", function(currentHp, previousHp)
        print("Player " .. sessionId .. " hp: " .. tostring(currentHp))
    end)
end)
 
callbacks:on_remove("players", function(player, sessionId)
    print("Player left: " .. sessionId)
end)

client.hx

import io.colyseus.serializer.schema.Callbacks;
 
var callbacks = Callbacks.get(room);
 
callbacks.listen("currentTurn", function(currentValue, previousValue) {
    trace("Turn changed: " + previousValue + " -> " + currentValue);
});
 
callbacks.onAdd("players", function(player, sessionId) {
    trace("Player joined: " + sessionId);
 
    callbacks.listen(player, "hp", function(currentHp, previousHp) {
        trace("Player " + sessionId + " hp: " + currentHp);
    });
});
 
callbacks.onRemove("players", function(player, sessionId) {
    trace("Player left: " + sessionId);
});

client.gd

var callbacks = Colyseus.Callbacks.of(room)
 
callbacks.listen("currentTurn", _on_turn_change)
callbacks.on_add("players", _on_player_add)
callbacks.on_remove("players", _on_player_remove)
 
func _on_turn_change(current_value, previous_value):
    print("Turn changed: ", previous_value, " -> ", current_value)
 
func _on_player_add(player: Dictionary, key: String):
    callbacks.listen(player, "hp", func(current_hp, previous_hp):
        print("Player ", key, " hp: ", current_hp))
 
func _on_player_remove(player: Dictionary, key: String):
    print("Player left: ", key)

client.dart

final callbacks = Callbacks.get(room);
final state = room.state!;   // joined with stateType: MyRoomState.new
 
callbacks.listen(state, 'currentTurn', (String value, String? previous) {
  print('Turn changed: $previous -> $value');
});
 
callbacks.onAdd(state.players, (sessionId, player) {
  print('Player joined: $sessionId');
 
  callbacks.listen(player, 'hp', (double hp, double? previous) {
    print('Player $sessionId hp: $hp');
  });
});
 
callbacks.onRemove(state.players, (sessionId, player) {
  print('Player left: $sessionId');
});

See the full State Sync Callbacks documentation for all available methods including listen, onAdd, onRemove, and more.

On State Change

The onStateChange event fires whenever the server synchronizes state updates. Use this when you need to know something changed, without tracking individual properties.

room.onStateChange((state) => {
    console.log("the room state has been updated:", state);
});

Connection Lifecycle

Leaving a room, automatic and manual reconnection, error handling, and removing listeners. See Connection Lifecycle & Reconnection for the full reference.

Latency & Server Selection

Measure network latency and choose optimal servers for your players.

Measuring Latency

Before Joining

Create a temporary connection to measure latency before joining a room.

Parameters

options.pingCount: Number of pings to send (default: 1). Returns the average latency when greater than 1.

client.ts

const latency = await client.getLatency();
console.log("Latency:", latency, "ms");
 
// With multiple pings for a more accurate average
const avgLatency = await client.getLatency({ pingCount: 5 });
console.log("Average Latency:", avgLatency, "ms");

Client.cs

float latency = await client.GetLatency();
Debug.Log("Latency: " + latency + " ms");
 
// With multiple pings for a more accurate average
float avgLatency = await client.GetLatency(new LatencyOptions { PingCount = 5 });
Debug.Log("Average Latency: " + avgLatency + " ms");

client.lua

client:get_latency(function(err, latency)
  print("Latency: " .. latency .. " ms")
end)
 
-- With multiple pings for a more accurate average
client:get_latency({ ping_count = 5 }, function(err, avg_latency)
  print("Average Latency: " .. avg_latency .. " ms")
end)

client.hx

client.getLatency(function(err, latency) {
  trace("Latency: " + latency + " ms");
});
 
// With multiple pings for a more accurate average
client.getLatency({ pingCount: 5 }, function(err, avgLatency) {
  trace("Average Latency: " + avgLatency + " ms");
});

client.gd

# Latency measurement API may vary in the Godot SDK
# Check the SDK documentation for available methods

client.dart

// Not available in the Flutter SDK.
// Measure round-trip time on a live connection with room.ping() instead.

During a Room Connection

Measure round-trip time on an existing connection.

client.ts

room.ping((latency) => {
  console.log("Latency:", latency, "ms");
});

Client.cs

room.Ping((latency) => {
  Debug.Log("Latency: " + latency + " ms");
});

client.lua

room:ping(function(latency)
  print("Latency: " .. latency .. " ms")
end)

client.hx

room.ping(function(latency) {
  trace("Latency: " + latency + " ms");
});

client.gd

# Ping API may vary in the Godot SDK
# Check the SDK documentation for available methods

client.dart

final latency = await room.ping();
print('Latency: $latency ms');

If the connection is not open, calling ping() has no effect.

Multi-Region Server Selection

Automatically connect to the server with the lowest latency from a list of endpoints.

Parameters

endpoints: Array of server endpoints (URLs or endpoint settings objects).
options: Optional client options to pass to each client instance.
latencyOptions.pingCount: Number of pings to send per endpoint (default: 1).

client.ts

import { Client } from "@colyseus/sdk";
 
// Select the best server from multiple regions
const client = await Client.selectByLatency([
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com",
]);
 
// Now use the client with the lowest latency
const room = await client.joinOrCreate("game");

Client.cs

using Colyseus;
 
// Select the best server from multiple regions
Colyseus.Client client = await Colyseus.Client.SelectByLatency(new string[] {
    "https://us-east.gameserver.com",
    "https://eu-west.gameserver.com",
    "https://asia.gameserver.com"
});
 
// Now use the client with the lowest latency
Room<YourStateClass> room = await client.joinOrCreate<YourStateClass>("game");

client.lua

local Colyseus = require("colyseus.sdk")
 
-- Select the best server from multiple regions
Colyseus.Client.select_by_latency({
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com"
}, function(err, client)
  -- Now use the client with the lowest latency
  client:join_or_create("game", {}, function(err, room)
    print("joined successfully")
  end)
end)

client.hx

import io.colyseus.Client;
 
// Select the best server from multiple regions
Client.selectByLatency([
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com"
], function(err, client) {
  // Now use the client with the lowest latency
  client.joinOrCreate("game", [], YourStateClass, function(err, room) {
    trace("joined successfully");
  });
});

client.gd

# Multi-region server selection may vary in the Godot SDK
# You can manually test latency to multiple endpoints:
var endpoints = [
    "wss://us-east.gameserver.com",
    "wss://eu-west.gameserver.com",
    "wss://asia.gameserver.com"
]
 
# Select endpoint with lowest latency and create client
var client = Colyseus.Client.new(endpoints[0])  # Set your preferred endpoint

client.dart

// Multi-region selection is not available in the Flutter SDK.
// Pick an endpoint yourself and create the client for it:
final client = ColyseusClient('wss://us-east.gameserver.com');

The method logs the latency for each endpoint to the console for debugging purposes. If all endpoints fail to respond, an error is thrown.

HTTP Requests

The client.http utility performs HTTP requests to your server endpoint. The client.auth.token is sent automatically as an Authorization header.

// GET
const response = await client.http.get("/profile");
 
// POST
const response = await client.http.post("/profile", { body: { name: "Jake" } });
 
// PUT
const response = await client.http.put("/profile", { body: { name: "Jake" } });
 
// DELETE
const response = await client.http.delete("/profile");

See Server → HTTP Routes for setting up HTTP endpoints on your server, and Authentication → HTTP Middleware for securing them.

Room Reference

Quick reference for room properties.

Property	Type	Description
`state`	`any`	The synchronized room state from the server
`sessionId`	`string`	Unique identifier for the current client connection
`roomId`	`string`	Unique room ID (shareable for direct joins)
`name`	`string`	Name of the room type (e.g., `"battle"`)
`reconnectionToken`	`string`	Token for manual reconnection
`reconnection`	`ReconnectionOptions`	Automatic reconnection configuration
`clock`	`RoomClock`	Server time & latency estimates (`serverNow()`, `rtt()`). See `room.clock`

Next Steps

State Sync Callbacks - Listen for state changes on the client
Netcode - Predict local input and reconcile to server state
Room API - Server-side room implementation
Authentication - Secure your room connections
Tutorials - Step-by-step game implementations

Advanced Schema Usage Connection Lifecycle