Not translated yet — showing English.
Browse, Host & Join Rooms
PlayServMatchmaking finds a room for the player and gives them a reservation: a short-lived ticket for one seat. The game browses the rooms your servers run and joins one by name, or asks for a new room. With the reservation, it connects to the room's server. This page is the reference; the whole flow is in Connecting to a Game.
using System.Collections.Generic;
using Playserv.Matchmaking;
using Playserv.Wrapper;
PlayServRoomBrowsePage page = await PlayServMatchmaking.BrowseRoomsAsync(
"sky-arena", new PlayServRoomBrowseQuery { PlacementState = "open", Region = "eu" });
PlayServMatchResult result = await PlayServMatchmaking.JoinRoomAsync("sky-arena", page.Rooms[0].RoomName);
PlayServMatchReservation reservation = result.Reservation;
Every call needs a client key and a signed-in player; otherwise it throws InvalidOperationException before anything is sent. The first argument is the room type: the slug of your game server, such as sky-arena. It must have room settings, or every call fails with RoomTypeNotFound.
Browse rooms
BrowseRoomsAsync(roomType, query) returns a page of the rooms your servers have registered.
Filter (PlayServRoomBrowseQuery) | Values |
|---|---|
PlacementState | open, full, self_closed, draining or session_closing. |
Region | Up to 32 characters. |
Attributes | Up to 4 exact matches on the room's attributes. |
Limit · Cursor | 1–200 rooms per page, 50 by default; pass page.CursorNext for the next page. HasMore says whether there is one. |
Each room (PlayServRoomListing) | What it is |
|---|---|
RoomName | The name to join. |
Players · Capacity | Seats taken and seats in total. Players can be over Capacity after the capacity was lowered. |
State · Attributes | What your server reports, such as "lobby" or the map. |
PlacementState · Region | Whether the room takes players, and where it runs. |
Connect | Where to connect. null until the server reports it. |
The list can include rooms in session_closing, which can't be joined.
Join a room by name
JoinRoomAsync(roomType, roomName) asks for a seat in that room. To pass data to the server's admission check, such as a team, use the request form:
var result = await PlayServMatchmaking.JoinRoomAsync(new PlayServJoinRoomRequest
{
FunctionSlug = "sky-arena",
RoomName = roomName,
Params = new { team = "red" }, // sent as JSON; the server sees it when it admits the player
});
The answer is a reservation, or an exception: a refusal throws PlayServMatchmakingException, see Errors. Asking again while your reservation for that room is still valid returns the same one. A player who is already in the room gets back in even if it's full or draining.
Host a new room
HostRoomAsync(request) asks one of your servers to open a room, and gives the player a reservation in it.
var result = await PlayServMatchmaking.HostRoomAsync(new PlayServHostRoomRequest
{
FunctionSlug = "sky-arena",
Attributes = new Dictionary<string, object> { ["map"] = "canyon" },
Region = "eu",
});
| Detail | What happens |
|---|---|
| Room name | PlayServ makes it up; read it from result.Reservation.RoomName. |
| Attributes | A flat object, up to 2048 bytes as JSON. A wish: the server may change or refuse it. The attributes in the reservation are the ones that count. |
| Reservation | Already for the host. Don't join the room again. |
| Timeout | 45 seconds by default. |
Hosting again can create a second room
If HostRoomAsync times out, the room may still have been created. Calling it again can open another one; browse for the first before you retry.
The reservation
PlayServMatchReservation | What it is |
|---|---|
RoomName | The room. |
ReservationToken | The ticket the server checks. A secret: don't log it. |
Connect | Host, Port, Transport and ConnectString. Can be null if the server hasn't reported it yet. |
Region · Attributes | Where the room runs, and its attributes. |
RemainingLifetime | How long the ticket is still valid. |
A reservation is valid for the room type's Reservation TTL, 1–60 seconds, and can be used once. Connect right away, with no confirmation screen in between. Use RemainingLifetime, not ExpiresAt: ExpiresAt is the platform's clock, which can differ from the device's. When a room closes, its unused reservations stop working.
Join and connect in one call
JoinRoomAndConnectAsync(request, options, connector) joins, waits until the reservation has a usable Connect, then runs your connector with it, and returns the reservation.
var reservation = await PlayServMatchmaking.JoinRoomAndConnectAsync(
new PlayServJoinRoomRequest { FunctionSlug = "sky-arena", RoomName = roomName },
connector: (r, ct) => myTransport.ConnectAsync(r.Connect, r.ReservationToken, ct));
Option (PlayServRoomJoinOptions) | Default |
|---|---|
Timeout — the whole call | 45 s |
ConnectTimeout — waiting for Connect | 30 s |
MaxUnreachableRetries — joins retried when the server doesn't answer | 3 |
With a connector, call it from Unity's main thread; the connector runs there too. A failing connector isn't retried. If the time runs out, it throws PlayServMatchmakingException with room_join_timeout.
Room sessions
For a server that uses PlayServ's own game connection, CreateRoomSession(protocolFactory) keeps the player in the room: it enters with HostAsync, JoinAsync or ConnectAsync, and if the connection drops, it rejoins with a fresh reservation.
| Detail | What it does |
|---|---|
State | Idle, Entering, Ready, Reconnecting, Failed or Closed; StateChanged fires on each change. |
| Messages | SendTextAsync and the MessageReceived event. |
| Recovery | Up to 3 rejoins within 120 seconds. Hosting is never repeated. |
| Leaving | LeaveAsync, then Dispose. |
Your IPlayServRoomProtocol checks that the server let the player in before EnterAsync completes. CreateGameConnection() gives the same connection without the rejoin logic.
Errors
Refusals throw PlayServMatchmakingException. Switch on RoomFailureCode; RetryAfter says when to try again.
RoomFailureCode | When |
|---|---|
RoomNotFound | No room with that name. |
RoomFull | No free seat. |
RoomClosed | The room is closed, or draining. |
RoomRefused | Your server refused the player or the room. |
RoomUnreachable | The server didn't answer in time. Retry after RetryAfter. |
RoomTypeNotFound | The room type has no room settings. |
RoomQuotaExceeded | Hosting: the room type already runs its Max rooms. |
RoomHostUnavailable · RoomHostCapacityExhausted | Hosting: no server can open a room now. |
RegionUnavailable | Hosting: no server in that region. |
Unknown | Anything else. A player removed from the room by an operator gets Unknown with UnifiedError.SourceCode removed_from_room. |
Automatic matchmaking
Coming soon
Automatic matchmaking, where PlayServ picks a room for the player, isn't available yet. Until then, players browse and join rooms by name, or host one.
Next steps
- Connecting to a Game — the whole flow, from sign-in to playing
- Game Server Hosting — the server side: registering rooms and admitting players
- Game Rooms — watch and manage live rooms in the Backoffice
Last updated on 22 Oct 2026