Skip to main content
Multiplayer

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
PlacementStateopen, full, self_closed, draining or session_closing.
RegionUp to 32 characters.
AttributesUp to 4 exact matches on the room's attributes.
Limit · Cursor1–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
RoomNameThe name to join.
Players · CapacitySeats taken and seats in total. Players can be over Capacity after the capacity was lowered.
State · AttributesWhat your server reports, such as "lobby" or the map.
PlacementState · RegionWhether the room takes players, and where it runs.
ConnectWhere 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",
});
DetailWhat happens
Room namePlayServ makes it up; read it from result.Reservation.RoomName.
AttributesA 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.
ReservationAlready for the host. Don't join the room again.
Timeout45 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

PlayServMatchReservationWhat it is
RoomNameThe room.
ReservationTokenThe ticket the server checks. A secret: don't log it.
ConnectHost, Port, Transport and ConnectString. Can be null if the server hasn't reported it yet.
Region · AttributesWhere the room runs, and its attributes.
RemainingLifetimeHow 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 call45 s
ConnectTimeout — waiting for Connect30 s
MaxUnreachableRetries — joins retried when the server doesn't answer3

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.

DetailWhat it does
StateIdle, Entering, Ready, Reconnecting, Failed or Closed; StateChanged fires on each change.
MessagesSendTextAsync and the MessageReceived event.
RecoveryUp to 3 rejoins within 120 seconds. Hosting is never repeated.
LeavingLeaveAsync, 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.

RoomFailureCodeWhen
RoomNotFoundNo room with that name.
RoomFullNo free seat.
RoomClosedThe room is closed, or draining.
RoomRefusedYour server refused the player or the room.
RoomUnreachableThe server didn't answer in time. Retry after RetryAfter.
RoomTypeNotFoundThe room type has no room settings.
RoomQuotaExceededHosting: the room type already runs its Max rooms.
RoomHostUnavailable · RoomHostCapacityExhaustedHosting: no server can open a room now.
RegionUnavailableHosting: no server in that region.
UnknownAnything 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

Last updated on 22 Oct 2026