Skip to main content
Multiplayer

Not translated yet — showing English.

Game Server Hosting

Your game server runs the match; PlayServ lists its rooms, hands out seats and checks who may come in. The server registers each room it hosts and keeps it alive with a heartbeat. Players get a ticket from PlayServ and bring it to the server, which checks it before letting them in. This page covers the Unity Dedicated Server; servers written in C# are in C# Game Servers.


Two kinds of game server

Unity Dedicated ServerC# game server
What it isA Unity build with the Dedicated Server target and the com.playserv.game-server packageA .NET process built on PlayServ's C# SDK
Game loop and netcodeYours: Unity, plus Netcode for GameObjects, Mirror or any otherPlayServ's room tick and simulation, over PlayServ's game connection
Runs onA PlayServ machine pool, or your own machinesPlayServ (Cloud Run), a machine pool, or your own machines
GuideThis pageC# Game Servers

Where each runs is set up in Servers.


What PlayServ owns

The room type's room settings are authoritative: capacity, reservation TTL, room lifetime, idle timeout and max rooms. The server reads them and gets changes on its next heartbeat, with no restart. Lowering the capacity doesn't remove anyone.

Room settings come first

Until the game server has room settings, it can connect, but every room it tries to register is refused, and players get RoomTypeNotFound.


Set up a Unity Dedicated Server

Install the package

Install the com.playserv.game-server companion package in Tools ▸ PlayServ ▸ Settings, the same SDK version as the game.

Build for the server

Build with the Dedicated Server target. In an ordinary client build, every PlayServGameServer call is refused.

Configure it

Call Configure once, on the main thread, before anything else:

using Playserv.GameServer;

PlayServGameServer.Configure(new PlayServGameServerOptions
{
    ExecutorSlug = "sky-arena",
    ServerKeyProvider = new PlayServDelegateServerKeyProvider(ct => secrets.GetServerKeyAsync(ct)),
});

A server PlayServ starts on a machine pool gets its credentials automatically. StartRoomAsync connects the server to PlayServ by itself. A server you run yourself needs a server key; load it from your secret store, and never put it in a scene, asset or config file under source control.


Register a room

StartRoomAsync registers a room, then keeps it alive with a heartbeat every 5 seconds:

var room = await PlayServGameServer.StartRoomAsync(new PlayServStartRoomRequest(
    "sky-arena",
    new PlayServGameRoomSnapshot("canyon-1", players: 0, capacity: 8,
        state: "lobby", attributes: new { map = "canyon" },
        connect: new PlayServGameRoomConnect(publicHost, 7777, "udp"), region: "eu")), ct);
Snapshot fieldWhat it is
roomNameThe name players join.
players · capacity · openSeats taken, seats in total, and whether it takes players.
state · attributesFree text and values players can filter on when they browse.
connect · regionWhere players connect, and where the room runs. Without connect, players don't know where to go.

Call room.Update(snapshot) when something changes, such as the state going from lobby to playing. A room that stops sending heartbeats is marked stale after 15 seconds and then removed.

room.StateMeaning
ActiveRegistered and beating.
DegradedA heartbeat failed for a network reason; the SDK keeps retrying.
Draining · ClosedClosing, or closed.
TerminatedRefused for good, for example a bad key. Terminated fires with the error.

LifetimeClosed fires when the room's lifetime ends and PlayServ closes it.


Rooms players ask for

When a player calls HostRoomAsync, PlayServ asks one of your servers to open a room. Set a RoomFactory to answer:

RoomFactory = (request, ct) =>
{
    var wish = request.Attributes as IDictionary<string, object>;
    var map = wish != null && wish.TryGetValue("map", out var m) ? m as string : "canyon";
    if (map != "canyon" && map != "orbit")
        return Task.FromResult(PlayServRoomCreateDecision.Refuse(PlayServRoomCreateRefusal.ContentRefused, "Unknown map"));

    return Task.FromResult(PlayServRoomCreateDecision.Accept(new PlayServGameRoomSnapshot(
        request.RoomName, 0, request.Configuration.Capacity, attributes: new { map },
        connect: new PlayServGameRoomConnect(publicHost, 7777, "udp"))));
},

Keep the room name PlayServ gave. The attributes the player asked for are only a wish: the room gets the ones you return. Refuse with RoomNameConflict, InstanceDraining, RoomQuotaExceeded, RoomCreateFailed or ContentRefused; only InstanceDraining stops PlayServ from offering this server new rooms. The factory has 5 seconds.


Admit players

A player connects with the reservation ticket from their join. Check it in your netcode's connection approval, before the player is in:

room.Admission.AdmissionRejected += rejected => network.Disconnect(rejected.AdmissionId);

var admission = room.Admission.TryAdmit(reservationToken);   // synchronous
if (!admission.Ok) return false;                              // refuse the connection
network.Accept(connectionId, admission.PlayerId, admission.AdmissionId);

TryAdmit also tells PlayServ the player joined. Take the player's ID from the result, never from what the client sent. Subscribe to AdmissionRejected before you accept any connection: PlayServ can still reject an admission shortly after, and you then disconnect that exact connection.

Before a ticket is even issued, the TicketOfferHandler option can accept or refuse the player, within 3 seconds, for example to keep a private room private. The Params the player sent with their join are in the offer.

Reconnects. room.CreateConnectionTracker() keeps a dropped player's seat for 30 seconds by default. Call tracker.TryAdmit(connectionId, token) instead of Admission.TryAdmit, tracker.ReportDisconnected(connectionId) when a connection drops, and handle ConnectionRemoved when the seat is freed. A returning player brings a new ticket and a new connection.


Remove players and close rooms

CallWhat it does
room.ReportLeave(playerId) · room.Kick(playerId)Tells PlayServ the player is out. Close their connection yourself: the SDK never closes your sockets.
tracker.RemovePlayer(playerId)Removes a player without waiting for the reconnect grace.
room.CloseAsync()Closes the room. Its unused tickets stop working.

Backoffice actions don't reach a Unity server yet

Delete room and Remove from room in Game Rooms don't stop a Unity Dedicated Server's room or disconnect the player: the room stays in Session closing while the server keeps it, and the removed player only can't rejoin. Close rooms and remove players from your server.


Answer RPC calls

Players call your server with PlayServRpc.InvokeAsync. Register the methods before Configure:

var round = new PlayServServerRpcParameter<int>("Round");   // matches the client's field name, case included
var registry = new PlayServServerRpcRegistry();
registry.Register<RoundPreview>("round.preview", new[] { round },
    (caller, args, ct) => Task.FromResult(BuildPreview(caller.PlayerId, args.Get(round))));

options.RpcRegistry = registry;

caller.PlayerId is checked by PlayServ. Calls run one at a time on the main thread; each must finish within HttpTimeout, 10 seconds by default.


Send events and shut down

PlayServGameServer.Events.PublishAsync(group, eventType, payload) sends an event to everyone in a group.

Before the process exits, await PlayServGameServer.ShutdownAsync(): it stops taking new rooms, closes its rooms and disconnects. Dispose alone is only a best effort.


Where it runs

WhereHow
A PlayServ machine poolBuild and push a linux/amd64 image from the Editor (Deployment ▸ Server Images) or with playserv image push, then set the pool up on the server's Hosting tab in Servers.
Your own machinesDeclare the game server with playserv functions declare <slug> --kind game_server, see Deploying with the CLI.

Rolling out a new image closes rooms

Rolling a pool onto a new image restarts its machines, and the rooms on them close. Roll out between matches.

With Max rooms reached, a new room is refused, and a player who hosts gets RoomQuotaExceeded. In process-per-room mode, a player who hosts while the pool is full waits up to 90 seconds, then gets RoomUnreachable; HostRoomAsync stops waiting after 45 seconds unless you raise its Timeout.

A server PlayServ starts for one room. In process-per-room mode, PlayServ starts a process for the room a player asked for. Register exactly that room: PlayServServerLaunch.GetRoomName() returns its name, and PlayServServerLaunch.ResolveConnect(listenPort) the public address players connect to.


Next steps

Last updated on 22 Oct 2026