Pular para o conteúdo principal
Multiplayer

Esta página ainda não foi traduzida: mostrando a versão em inglês.

Hospedagem de game servers

O seu game server executa a partida; o PlayServ lista as Rooms dele, distribui as vagas e confere quem pode entrar. O servidor registra cada Room que hospeda e a mantém viva com um heartbeat. Os Players recebem um ticket do PlayServ e o levam ao servidor, que o confere antes de deixá-los entrar. Esta página trata do Unity Dedicated Server; servidores escritos em C# estão em Game servers em C#.


Dois tipos de game server

Unity Dedicated ServerGame server em C#
O que éUma build da Unity com o target Dedicated Server e o pacote com.playserv.game-serverUm processo .NET construído sobre o SDK C# do PlayServ
Game loop e netcodeSão seus: Unity, mais Netcode for GameObjects, Mirror ou qualquer outroO tick de Room e a simulação do PlayServ, sobre a conexão de jogo do PlayServ
Onde rodaUm pool de máquinas do PlayServ ou as suas próprias máquinasPlayServ (Cloud Run), um pool de máquinas ou as suas próprias máquinas
GuiaEsta páginaGame servers em C#

Onde cada um roda é configurado em Servers.


O que fica com o PlayServ

As Room settings do tipo de Room são a fonte da verdade: capacidade, TTL da reserva, tempo de vida da Room, timeout de inatividade e número máximo de Rooms. O servidor lê esses valores e recebe as mudanças no heartbeat seguinte, sem reiniciar. Reduzir a capacidade não remove ninguém.

Primeiro as Room settings

Enquanto o game server não tiver Room settings, ele consegue conectar, mas toda Room que tentar registrar é recusada, e os Players recebem RoomTypeNotFound.


Configurar um Unity Dedicated Server

Instale o pacote

Instale o pacote complementar com.playserv.game-server em Tools ▸ PlayServ ▸ Settings, na mesma versão do SDK usada pelo jogo.

Faça a build para o servidor

Faça a build com o target Dedicated Server. Em uma build comum de cliente, toda chamada a PlayServGameServer é recusada.

Configure o servidor

Chame Configure uma única vez, na main thread, antes de qualquer outra coisa:

using Playserv.GameServer;

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

Um servidor que o PlayServ inicia em um pool de máquinas recebe as credenciais automaticamente. StartRoomAsync conecta o servidor ao PlayServ por conta própria. Um servidor que você mesmo executa precisa de uma server key; carregue-a do seu cofre de segredos e nunca a coloque em uma cena, asset ou arquivo de configuração versionado.


Registrar uma Room

StartRoomAsync registra uma Room e depois a mantém viva com um heartbeat a cada 5 segundos:

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);
Campo do snapshotO que é
roomNameO nome em que os Players entram.
players · capacity · openVagas ocupadas, total de vagas e se a Room aceita Players.
state · attributesTexto livre e valores que os Players podem usar como filtro ao listar Rooms.
connect · regionOnde os Players conectam e onde a Room roda. Sem connect, os Players não sabem para onde ir.

Chame room.Update(snapshot) quando algo mudar, como o estado passar de lobby para playing. Uma Room que para de enviar heartbeats é marcada como stale depois de 15 segundos e então removida.

room.StateSignificado
ActiveRegistrada e enviando batimentos.
DegradedUm heartbeat falhou por motivo de rede; o SDK continua tentando.
Draining · ClosedFechando, ou fechada.
TerminatedRecusada em definitivo, por exemplo por uma key inválida. Terminated dispara com o erro.

LifetimeClosed dispara quando o tempo de vida da Room acaba e o PlayServ a fecha.


Rooms pedidas pelos Players

Quando um Player chama HostRoomAsync, o PlayServ pede a um dos seus servidores que abra uma Room. Defina uma RoomFactory para responder:

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"))));
},

Mantenha o nome de Room que o PlayServ definiu. Os atributos que o Player pediu são só um pedido: a Room fica com os que você retornar. Recuse com RoomNameConflict, InstanceDraining, RoomQuotaExceeded, RoomCreateFailed ou ContentRefused; só InstanceDraining impede o PlayServ de oferecer novas Rooms a este servidor. A factory tem 5 segundos para responder.


Admitir Players

Um Player conecta com o ticket de reserva que recebeu ao entrar. Confira o ticket na aprovação de conexão do seu netcode, antes de o Player entrar:

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 também avisa o PlayServ de que o Player entrou. Pegue o ID do Player do resultado, nunca do que o cliente enviou. Assine AdmissionRejected antes de aceitar qualquer conexão: o PlayServ ainda pode rejeitar uma admissão logo depois, e aí você desconecta exatamente aquela conexão.

Antes mesmo de o ticket ser emitido, a opção TicketOfferHandler pode aceitar ou recusar o Player, em até 3 segundos, por exemplo para manter uma Room privada. Os Params que o Player enviou ao entrar vêm na oferta.

Reconexões. room.CreateConnectionTracker() guarda a vaga de um Player que caiu por 30 segundos, por padrão. Chame tracker.TryAdmit(connectionId, token) em vez de Admission.TryAdmit, tracker.ReportDisconnected(connectionId) quando uma conexão cair, e trate ConnectionRemoved quando a vaga for liberada. Um Player que volta traz um ticket novo e uma conexão nova.


Remover Players e fechar Rooms

ChamadaO que faz
room.ReportLeave(playerId) · room.Kick(playerId)Avisa o PlayServ de que o Player saiu. Feche a conexão dele você mesmo: o SDK nunca fecha os seus sockets.
tracker.RemovePlayer(playerId)Remove um Player sem esperar o período de tolerância de reconexão.
room.CloseAsync()Fecha a Room. Os tickets não usados dela deixam de funcionar.

Ações do Backoffice ainda não chegam a um servidor Unity

Delete room e Remove from room em Game Rooms não encerram a Room de um Unity Dedicated Server nem desconectam o Player: a Room fica em Session closing enquanto o servidor a mantiver, e o Player removido apenas não consegue voltar. Feche Rooms e remova Players a partir do seu servidor.


Responder chamadas RPC

Os Players chamam o seu servidor com PlayServRpc.InvokeAsync. Registre os métodos antes de 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 é verificado pelo PlayServ. As chamadas rodam uma de cada vez na main thread; cada uma precisa terminar dentro de HttpTimeout, 10 segundos por padrão.


Enviar Events e encerrar

PlayServGameServer.Events.PublishAsync(group, eventType, payload) envia um Event para todos em um Group.

Antes de o processo terminar, aguarde PlayServGameServer.ShutdownAsync(): ele para de aceitar novas Rooms, fecha as suas Rooms e desconecta. Dispose sozinho é só uma tentativa, sem garantia.


Onde o servidor roda

OndeComo
Um pool de máquinas do PlayServFaça a build e publique uma imagem linux/amd64 pelo Editor (Deployment ▸ Server Images) ou com playserv image push, depois configure o pool na aba Hosting do servidor em Servers.
As suas próprias máquinasDeclare o game server com playserv functions declare <slug> --kind game_server, veja Deploying with the CLI.

Publicar uma imagem nova fecha Rooms

Passar um pool para uma imagem nova reinicia as máquinas dele, e as Rooms que estão nelas fecham. Faça o rollout entre partidas.

Com Max rooms atingido, uma Room nova é recusada, e um Player que tenta hospedar recebe RoomQuotaExceeded. No modo de um processo por Room, um Player que hospeda enquanto o pool está cheio espera até 90 segundos e então recebe RoomUnreachable; HostRoomAsync para de esperar depois de 45 segundos, a menos que você aumente o Timeout dele.

Um servidor que o PlayServ inicia para uma única Room. No modo de um processo por Room, o PlayServ inicia um processo para a Room que um Player pediu. Registre exatamente essa Room: PlayServServerLaunch.GetRoomName() retorna o nome dela, e PlayServServerLaunch.ResolveConnect(listenPort), o endereço público ao qual os Players conectam.


Próximos passos

Atualizado em 22 de out. de 2026