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 Server | Game server em C# | |
|---|---|---|
| O que é | Uma build da Unity com o target Dedicated Server e o pacote com.playserv.game-server | Um processo .NET construído sobre o SDK C# do PlayServ |
| Game loop e netcode | São seus: Unity, mais Netcode for GameObjects, Mirror ou qualquer outro | O tick de Room e a simulação do PlayServ, sobre a conexão de jogo do PlayServ |
| Onde roda | Um pool de máquinas do PlayServ ou as suas próprias máquinas | PlayServ (Cloud Run), um pool de máquinas ou as suas próprias máquinas |
| Guia | Esta página | Game 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 snapshot | O que é |
|---|---|
roomName | O nome em que os Players entram. |
players · capacity · open | Vagas ocupadas, total de vagas e se a Room aceita Players. |
state · attributes | Texto livre e valores que os Players podem usar como filtro ao listar Rooms. |
connect · region | Onde 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.State | Significado |
|---|---|
Active | Registrada e enviando batimentos. |
Degraded | Um heartbeat falhou por motivo de rede; o SDK continua tentando. |
Draining · Closed | Fechando, ou fechada. |
Terminated | Recusada 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
| Chamada | O 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
| Onde | Como |
|---|---|
| Um pool de máquinas do PlayServ | Faç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áquinas | Declare 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
- Conectar-se a um jogo — o lado do Player no fluxo
- Servers — frotas, Room settings e pools de máquinas
- Game Rooms — as Rooms que o seu servidor registra, ao vivo no Backoffice
Atualizado em 22 de out. de 2026