Connection Lifecycle & Reconnection

Handle the various states of a room connection.

Leaving a Room

Disconnect from the room. Use consented: true (default) for intentional leaves, or false to simulate an unexpected disconnect.

client.ts

// consented leave
room.leave();
 
// force unconsented leave
room.leave(false);

Client.cs

// consented leave
room.Leave();
 
// unconsented leave
room.Leave(false);

client.lua

-- consented leave
room:leave()
 
-- unconsented leave
room:leave(false)

client.hx

// consented leave
room.leave();
 
// unconsented leave
room.leave(false);

client.gd

# consented leave
room.leave()

client.dart

// consented leave
await room.leave();

Backend: Use Room → On Leave to handle client disconnection.

Listening for the leave event:

client.ts

room.onLeave((code) => {
  console.log("client left the room");
});

Client.cs

room.OnLeave += (code) => {
  Debug.Log ("client left the room");
}

client.lua

room:on("leave", function()
  print("client left the room")
end)

client.hx

room.onLeave += function () {
  trace("client left the room");
};

client.gd

room.left.connect(_on_room_left)
 
func _on_room_left(code: int, reason: String):
    print("client left the room: ", reason)

client.dart

room.onLeave.listen((code) {
  print('client left the room');
});

Possible closing codes and their meaning:

1000 - Regular socket shutdown
Between 1001 and 1015 - Abnormal socket shutdown
Between 4000 and 4010 - Reserved by the framework (CONSENTED, SERVER_SHUTDOWN, FAILED_TO_RECONNECT, …)
Between 4011 and 4999 - Custom application close code (See more details)

Automatic Reconnection

The SDK automatically attempts to reconnect when the connection is unexpectedly dropped.

⚠️

Automatic reconnection only triggers if the room has been connected for at least minUptime milliseconds. This threshold prevents reconnection loops for rooms that fail immediately after joining.

On Drop Event

Triggered when the connection is unexpectedly dropped. The SDK will automatically attempt to reconnect.

client.ts

room.onDrop((code, reason) => {
  console.log("connection dropped, attempting to reconnect...");
  console.log("code:", code, "reason:", reason);
});

Client.cs

room.OnDrop += (code, reason) => {
  Debug.Log("connection dropped, attempting to reconnect...");
  Debug.Log("code: " + code + " reason: " + reason);
};

client.lua

room:on("drop", function(code, reason)
  print("connection dropped, attempting to reconnect...")
  print("code:", code, "reason:", reason)
end)

client.hx

room.onDrop += function(code, reason) {
  trace("connection dropped, attempting to reconnect...");
  trace("code: " + code + " reason: " + reason);
};

client.gd

# The Godot SDK handles reconnection automatically
# Use the error signal to detect connection issues
room.error.connect(func(code: int, message: String):
    print("connection error: ", message))

client.dart

room.onDrop.listen((error) {
  print('connection dropped, attempting to reconnect...');
  print('code: ${error.code} reason: ${error.message}');
});

The onDrop event is different from onLeave. While onLeave is triggered when the client intentionally leaves or the connection is permanently closed, onDrop indicates a temporary disconnection where reconnection will be attempted.

Close codes that trigger onDrop:

1005 - No status received
1006 - Abnormal closure
1001 - Going away
4010 - May try reconnect

On Reconnect Event

Triggered when the client successfully reconnects after a connection drop. While disconnected, your room.send() calls will be queued and sent to the server when the client reconnects. The maximum number of queued messages is configurable using room.reconnection.maxEnqueuedMessages.

client.ts

room.onReconnect(() => {
  console.log("successfully reconnected to the room!");
});

Client.cs

room.OnReconnect += () => {
  Debug.Log("successfully reconnected to the room!");
};

client.lua

room:on("reconnect", function()
  print("successfully reconnected to the room!")
end)

client.hx

room.onReconnect += function() {
  trace("successfully reconnected to the room!");
};

client.gd

# The Godot SDK handles reconnection automatically
# The joined signal will fire again after successful reconnection
room.joined.connect(func():
    print("connected/reconnected to the room!"))

client.dart

room.onReconnect.listen((_) {
  print('successfully reconnected to the room!');
});

Reconnection Options

You may configure the reconnection behavior using room.reconnection.

Reconnection config options

Option	Default	Description
`enabled`	`true`	Set to `false` to disable automatic reconnection entirely
`maxRetries`	`15`	Maximum reconnection attempts
`minDelay`	`100`	Minimum delay between attempts (ms)
`maxDelay`	`5000`	Maximum delay between attempts (ms)
`minUptime`	`5000`	Minimum room uptime before reconnection is allowed (ms)
`delay`	`100`	Initial delay between attempts (ms)
`maxEnqueuedMessages`	`10`	Maximum buffered messages during reconnection
`backoff`	exponential	Delay calculation function

Status properties (read-only)

Property	Type	Description
`isReconnecting`	boolean	Whether currently reconnecting
`retryCount`	number	Current reconnection attempt count
`enqueuedMessages`	array	Messages buffered while disconnected (count: `.length`)

Customizing reconnection behavior:

client.ts

const room = await client.joinOrCreate("battle");
 
// Customize reconnection options
room.reconnection.maxRetries = 10;
room.reconnection.maxDelay = 10000; // 10 seconds max delay
room.reconnection.minUptime = 3000; // Allow reconnection after 3 seconds

Client.cs

Colyseus.Room<YourStateClass> room = await client.JoinOrCreate<YourStateClass>("battle");
 
// Customize reconnection options
room.Reconnection.MaxRetries = 10;
room.Reconnection.MaxDelay = 10000; // 10 seconds max delay
room.Reconnection.MinUptime = 3000; // Allow reconnection after 3 seconds

client.lua

client:join_or_create("battle", {}, function(err, room)
  -- Customize reconnection options
  room.reconnection.max_retries = 10
  room.reconnection.max_delay = 10000 -- 10 seconds max delay
  room.reconnection.min_uptime = 3000 -- Allow reconnection after 3 seconds
end)

client.hx

client.joinOrCreate("battle", [], YourStateClass, function(err, room) {
  // Customize reconnection options
  room.reconnection.maxRetries = 10;
  room.reconnection.maxDelay = 10000; // 10 seconds max delay
  room.reconnection.minUptime = 3000; // Allow reconnection after 3 seconds
});

client.gd

# Reconnection is handled automatically by the Godot SDK
# Configuration options may vary - check the SDK documentation

client.dart

final room = await client.joinOrCreate('battle');
 
// Customize reconnection options
room.setReconnectionOptions(
  maxRetries: 10,
  maxDelayMs: 10000, // 10 seconds max delay
  minUptimeMs: 3000, // Allow reconnection after 3 seconds
);

Custom backoff function:

client.ts

room.reconnection.backoff = (attempt: number, delay: number) => {
  return Math.floor(Math.pow(2, attempt) * delay);
};

Client.cs

room.Reconnection.Backoff = (attempt, delay) => {
  return (int)Math.Floor(Math.Pow(2, attempt) * delay);
};

client.lua

room.reconnection.backoff = function(attempt, delay)
  return math.floor(math.pow(2, attempt) * delay)
end

client.hx

room.reconnection.backoff = function(attempt:Int, delay:Int):Int {
  return Math.floor(Math.pow(2, attempt) * delay);
};

client.gd

# Custom backoff functions are not currently exposed in the Godot SDK
# The SDK uses a default exponential backoff strategy

client.dart

// Custom backoff functions are not exposed in the Flutter SDK.
// The native core uses a default exponential backoff strategy.

Manual Reconnection

For more control, you can manually reconnect using a cached reconnection token. Because this method returns a new room instance on the client, you must reattach all event listeners to the room after reconnecting.

You must store/cache the room.reconnectionToken from an active room connection.
The server needs to call .allowReconnection() for that client.

client.ts

try {
  const room = await client.reconnect(cachedReconnectionToken);
  console.log("joined successfully", room);
 
} catch (e) {
  console.error("join error", e);
}

Client.cs

try {
  Colyseus.Room<YourStateClass> room = await client.Reconnect<YourStateClass>(cachedReconnectionToken);
  Debug.Log("joined successfully");
 
} catch (ex) {
  Debug.Log("join error");
  Debug.Log(ex.Message);
}

client.lua

client:reconnect(cached_reconnection_token, function(err, room)
  if (err ~= nil) then
    print("join error: " .. err)
    return
  end
 
  print("joined successfully")
end)

client.hx

client.reconnect(cachedReconnectionToken, YourStateClass, function(err, room) {
  if (err != null) {
    trace("join error: " + err);
    return;
  }
 
  trace("joined successfully");
});

client.gd

var room: Colyseus.Room = client.reconnect(cached_reconnection_token)
 
room.joined.connect(func():
    print("reconnected successfully"))
 
room.error.connect(func(code: int, message: String):
    printerr("reconnect error: ", message))

client.dart

try {
  final room = await client.reconnect(cachedReconnectionToken);
  print('joined successfully');
 
} catch (e) {
  print('join error: $e');
}

Error Handling

Listen for errors that occur in the room.

client.ts

room.onError((code, message) => {
  console.log("oops, error occurred:");
  console.log(message);
});

Client.cs

room.OnError += (code, message) => {
  Debug.Log ("oops, error occurred:");
  Debug.Log(message);
}

client.lua

room:on("error", function(code, message)
  print("oops, error occurred:")
  print(message)
end)

client.hx

room.onError += function(code, message) {
  trace("oops, error occurred:");
  trace(message);
};

client.gd

room.error.connect(_on_room_error)
 
func _on_room_error(code: int, message: String):
    printerr("oops, error occurred: ", message)

client.dart

room.onError.listen((error) {
  print('oops, error occurred:');
  print('${error.code}: ${error.message}');
});

Removing Listeners

Remove all event listeners from the room (onJoin, onStateChange, onError, onLeave, onReconnect, onDrop, registered message handlers, and schema callbacks):

client.ts

room.removeAllListeners();

The SDK calls removeAllListeners() automatically when the room is left. You only need it to detach early, e.g. when tearing down a UI screen while staying connected.

Sending & Receiving Messages Matchmaking