Pular para o conteúdo principal
Multiplayer

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
PlacementStateopen, full, self_closed, draining ou session_closing.
RegionAté 32 caracteres.
AttributesAté 4 correspondências exatas nos atributos da Room.
Limit · CursorDe 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 é
RoomNameO nome usado para entrar.
Players · CapacityVagas ocupadas e total de vagas. Players pode passar de Capacity depois que a capacidade foi reduzida.
State · AttributesO que o seu servidor informa, como "lobby" ou o mapa.
PlacementState · RegionSe a Room aceita Players e onde ela roda.
ConnectOnde 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",
});
DetalheO que acontece
Nome da RoomO PlayServ gera o nome; leia-o em result.Reservation.RoomName.
AtributosUm 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.
ReservaJá é a do host. Não entre na Room de novo.
Timeout45 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

PlayServMatchReservationO que é
RoomNameA Room.
ReservationTokenO ticket que o servidor confere. É um segredo: não o registre em log.
ConnectHost, Port, Transport e ConnectString. Pode ser null se o servidor ainda não informou.
Region · AttributesOnde a Room roda e os atributos dela.
RemainingLifetimePor 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 inteira45 s
ConnectTimeout — espera por Connect30 s
MaxUnreachableRetries — novas tentativas de entrada quando o servidor não responde3

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.

DetalheO que faz
StateIdle, Entering, Ready, Reconnecting, Failed ou Closed; StateChanged dispara a cada mudança.
MensagensSendTextAsync e o evento MessageReceived.
RecuperaçãoAté 3 reentradas em 120 segundos. A hospedagem nunca é repetida.
SaídaLeaveAsync 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.

RoomFailureCodeQuando
RoomNotFoundNão existe Room com esse nome.
RoomFullNão há vaga livre.
RoomClosedA Room está fechada ou em drenagem.
RoomRefusedO seu servidor recusou o Player ou a Room.
RoomUnreachableO servidor não respondeu a tempo. Tente de novo depois de RetryAfter.
RoomTypeNotFoundO tipo de Room não tem Room settings.
RoomQuotaExceededHospedagem: o tipo de Room já está no seu Max rooms.
RoomHostUnavailable · RoomHostCapacityExhaustedHospedagem: nenhum servidor pode abrir uma Room agora.
RegionUnavailableHospedagem: não há servidor nessa região.
UnknownQualquer 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

Atualizado em 22 de out. de 2026