Esta página ainda não foi traduzida: mostrando a versão em inglês.
Listar, hospedar e entrar em Rooms
PlayServMatchmaking encontra uma Room para o Player e lhe entrega uma reserva: um ticket de curta duração para uma vaga. O jogo lista as Rooms que os seus servidores executam e entra em uma pelo nome, ou pede uma Room nova. Com a reserva, ele conecta ao servidor da Room. Esta página é a referência; o fluxo completo está em Conectar-se a um jogo.
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;
Toda chamada exige uma client key e um Player logado; sem isso, ela lança InvalidOperationException antes de enviar qualquer coisa. O primeiro argumento é o tipo de Room: o slug do seu game server, como sky-arena. Ele precisa ter Room settings, ou toda chamada falha com RoomTypeNotFound.
Listar Rooms
BrowseRoomsAsync(roomType, query) retorna uma página com as Rooms que os seus servidores registraram.
Filtro (PlayServRoomBrowseQuery) | Valores |
|---|---|
PlacementState | open, full, self_closed, draining ou session_closing. |
Region | Até 32 caracteres. |
Attributes | Até 4 correspondências exatas nos atributos da Room. |
Limit · Cursor | De 1 a 200 Rooms por página, 50 por padrão; passe page.CursorNext para obter a próxima página. HasMore diz se ela existe. |
Cada Room (PlayServRoomListing) | O que é |
|---|---|
RoomName | O nome usado para entrar. |
Players · Capacity | Vagas ocupadas e total de vagas. Players pode passar de Capacity depois que a capacidade foi reduzida. |
State · Attributes | O que o seu servidor informa, como "lobby" ou o mapa. |
PlacementState · Region | Se a Room aceita Players e onde ela roda. |
Connect | Onde conectar. Fica null até o servidor informar. |
A lista pode incluir Rooms em session_closing, nas quais não é possível entrar.
Entrar em uma Room pelo nome
JoinRoomAsync(roomType, roomName) pede uma vaga nessa Room. Para passar dados à verificação de admissão do servidor, como um time, use a forma com request:
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
});
A resposta é uma reserva ou uma exceção: uma recusa lança PlayServMatchmakingException, veja Erros. Pedir de novo enquanto a sua reserva para essa Room ainda é válida devolve a mesma reserva. Um Player que já está na Room volta a entrar mesmo que ela esteja cheia ou em drenagem.
Hospedar uma Room nova
HostRoomAsync(request) pede a um dos seus servidores que abra uma Room e dá ao Player uma reserva nela.
var result = await PlayServMatchmaking.HostRoomAsync(new PlayServHostRoomRequest
{
FunctionSlug = "sky-arena",
Attributes = new Dictionary<string, object> { ["map"] = "canyon" },
Region = "eu",
});
| Detalhe | O que acontece |
|---|---|
| Nome da Room | O PlayServ gera o nome; leia-o em result.Reservation.RoomName. |
| Atributos | Um objeto plano, de até 2048 bytes em JSON. É só um pedido: o servidor pode alterá-lo ou recusá-lo. Valem os atributos que vêm na reserva. |
| Reserva | Já é a do host. Não entre na Room de novo. |
| Timeout | 45 segundos por padrão. |
Hospedar de novo pode criar uma segunda Room
Se HostRoomAsync estourar o tempo, a Room pode ter sido criada mesmo assim. Chamar de novo pode abrir outra; procure a primeira na lista antes de tentar outra vez.
A reserva
PlayServMatchReservation | O que é |
|---|---|
RoomName | A Room. |
ReservationToken | O ticket que o servidor confere. É um segredo: não o registre em log. |
Connect | Host, Port, Transport e ConnectString. Pode ser null se o servidor ainda não informou. |
Region · Attributes | Onde a Room roda e os atributos dela. |
RemainingLifetime | Por quanto tempo o ticket ainda vale. |
Uma reserva vale pelo Reservation TTL do tipo de Room, de 1 a 60 segundos, e só pode ser usada uma vez. Conecte imediatamente, sem tela de confirmação no meio. Use RemainingLifetime, não ExpiresAt: ExpiresAt segue o relógio da plataforma, que pode diferir do relógio do dispositivo. Quando uma Room fecha, as reservas não usadas dela deixam de funcionar.
Entrar e conectar em uma chamada
JoinRoomAndConnectAsync(request, options, connector) entra na Room, espera até a reserva ter um Connect utilizável, executa o seu connector com ele e retorna a reserva.
var reservation = await PlayServMatchmaking.JoinRoomAndConnectAsync(
new PlayServJoinRoomRequest { FunctionSlug = "sky-arena", RoomName = roomName },
connector: (r, ct) => myTransport.ConnectAsync(r.Connect, r.ReservationToken, ct));
Opção (PlayServRoomJoinOptions) | Padrão |
|---|---|
Timeout — a chamada inteira | 45 s |
ConnectTimeout — espera por Connect | 30 s |
MaxUnreachableRetries — novas tentativas de entrada quando o servidor não responde | 3 |
Com um connector, chame o método a partir da main thread da Unity; o connector também roda nela. Um connector que falha não é repetido. Se o tempo acabar, a chamada lança PlayServMatchmakingException com room_join_timeout.
Room sessions
Para um servidor que usa a conexão de jogo do próprio PlayServ, CreateRoomSession(protocolFactory) mantém o Player na Room: ela entra com HostAsync, JoinAsync ou ConnectAsync e, se a conexão cair, volta a entrar com uma reserva nova.
| Detalhe | O que faz |
|---|---|
State | Idle, Entering, Ready, Reconnecting, Failed ou Closed; StateChanged dispara a cada mudança. |
| Mensagens | SendTextAsync e o evento MessageReceived. |
| Recuperação | Até 3 reentradas em 120 segundos. A hospedagem nunca é repetida. |
| Saída | LeaveAsync e depois Dispose. |
O seu IPlayServRoomProtocol confirma que o servidor admitiu o Player antes de EnterAsync terminar. CreateGameConnection() oferece a mesma conexão, sem a lógica de reentrada.
Erros
Recusas lançam PlayServMatchmakingException. Decida pelo RoomFailureCode; RetryAfter diz quando tentar de novo.
RoomFailureCode | Quando |
|---|---|
RoomNotFound | Não existe Room com esse nome. |
RoomFull | Não há vaga livre. |
RoomClosed | A Room está fechada ou em drenagem. |
RoomRefused | O seu servidor recusou o Player ou a Room. |
RoomUnreachable | O servidor não respondeu a tempo. Tente de novo depois de RetryAfter. |
RoomTypeNotFound | O tipo de Room não tem Room settings. |
RoomQuotaExceeded | Hospedagem: o tipo de Room já está no seu Max rooms. |
RoomHostUnavailable · RoomHostCapacityExhausted | Hospedagem: nenhum servidor pode abrir uma Room agora. |
RegionUnavailable | Hospedagem: não há servidor nessa região. |
Unknown | Qualquer outro caso. Um Player removido da Room por um operador recebe Unknown com UnifiedError.SourceCode removed_from_room. |
Matchmaking automático
Em breve
O matchmaking automático, em que o PlayServ escolhe uma Room para o Player, ainda não está disponível. Até lá, os Players listam Rooms e entram pelo nome, ou hospedam uma.
Próximos passos
- Conectar-se a um jogo — o fluxo completo, do login à partida
- Hospedagem de game servers — o lado do servidor: registrar Rooms e admitir Players
- Game Rooms — acompanhar e gerenciar Rooms ao vivo no Backoffice
Atualizado em 22 de out. de 2026