Pular para o conteúdo principal

Início rápido da API REST de Matchmaking

É altamente recomendável considerar o uso dos Multiplayer SDKs, pois eles incluem suporte a mensagens em tempo real que reduz a necessidade de sondagem. Isso melhorará a experiência de matchmaking e reduzirá os atrasos. Início rápido - SDK do cliente
Este guia de início rápido orienta você por todo o processo de integração do recurso de matchmaking. Todos os exemplos de código deste início rápido são para o Unity; no entanto, os conceitos e o fluxo se aplicam (em geral) a outras plataformas também. Dependendo do design do seu jogo, considere a seção de matchmaking de usuário único ou de vários usuários. Este tutorial ilustra como enviar um tíquete para uma fila específica a fim de encontrar uma partida. Uma fila provavelmente corresponde a um modo de jogo ou a vários modos de jogo (por exemplo, um modo de captura de bandeira e um modo rei da colina na mesma fila). O serviço de matchmaking se encarrega de encontrar uma partida entre os tíquetes de uma fila. Quando uma partida é encontrada, seu título deve se encarregar de conectar os jogadores para a jogabilidade.

Configurar uma fila de matchmaking no Game Manager

Este início rápido pressupõe que você tenha configurado suas filas no Game Manager. Para obter detalhes sobre como configurar uma, confira Configurando filas de matchmaking.

Matchmaking de tíquete de usuário único

Se o seu jogo tiver um modo 1v1 ou permitir que um único usuário entre sozinho no matchmaking, considere o matchmaking de usuário único. O matchmaking de usuário único segue o padrão ilustrado abaixo. Fluxo de matchmaking

Criar um tíquete de matchmaking

Um usuário cria um tíquete de matchmaking usando CreateMatchmakingTicket. Quando a criação do tíquete é bem-sucedida, o serviço retorna um TicketId. A criação do tíquete exige que você especifique o Creator (a identidade e os atributos do usuário), GiveUpAfterSeconds (o tempo, em segundos, antes de o serviço desistir de combinar o tíquete) e o QueueName no qual encontrar uma partida. O campo Creator deve conter os atributos de usuário exigidos pela configuração da fila correspondente ao QueueName. Um bom valor para GiveUpAfterSeconds é 120 segundos, para evitar que os usuários desistam por conta própria.

Verificar o status do tíquete de matchmaking

Você deve sondar o serviço pelo TicketId para acessar o Status do tíquete no matchmaking. Para isso, faça com que seu título chame GetMatchmakingTicket. Você pode sondar até 10 vezes por minuto. Por exemplo, sonde o status do tíquete a cada 6 segundos. A sondagem pode aumentar os atrasos ao recuperar o status do seu tíquete. É por esse motivo que recomendamos fortemente considerar o uso do método do Multiplayer SDK descrito aqui: Início rápido - SDK do cliente. Ele evita a necessidade de sondagem usando a funcionalidade de mensagens em tempo real. Quando o status do tíquete mudar para Matched, seu cliente poderá parar de sondar o tíquete. A partir desse ponto, o tíquete incluirá o MatchId.

Obter a partida

No seu cliente, chame GetMatch com o MatchId fornecido na resposta de GetMatchmakingTicket. Essa partida contém a lista de usuários que foram combinados.

Cancelando um tíquete de matchmaking

Se, por algum motivo, seu cliente quiser cancelar o processo de matchmaking antes que GiveUpAfterSeconds seja atingido, chame CancelMatchmakingTicket com o TicketId. Se uma partida ainda não tiver sido encontrada, o tíquete será retirado do processo de matchmaking e seu status mudará para Canceled.

Matchmaking de tíquete de vários usuários

Se o seu jogo permitir que grupos de jogadores entrem juntos em uma fila de matchmaking, há mais algumas coisas que precisam ser feitas para entrar no matchmaking. Recomendamos que seu título designe um líder de grupo (o criador) para evitar chamadas desnecessárias. O líder cria o tíquete, mas todos os membros do grupo devem concordar em ingressar nele.

Criar um tíquete de matchmaking (vários usuários)

O grupo deve eleger um criador de tíquete no seu título. O criador cria um tíquete de matchmaking usando CreateMatchmakingTicket, que retorna um TicketId em caso de êxito. A criação do tíquete exige que você especifique o Creator (a identidade e os atributos do usuário), GiveUpAfterSeconds (o tempo, em segundos, antes de o serviço desistir de combinar o tíquete), MembersToMatchWith (as identidades dos outros membros do grupo) e o QueueName no qual encontrar uma partida. O campo Creator deve conter os atributos de usuário exigidos pela configuração da fila correspondente ao QueueName. Um bom valor para GiveUpAfterSeconds é 120 segundos, para evitar que os usuários desistam por conta própria.

Os membros do grupo ingressam no tíquete de partida

Depois que o tíquete de partida for criado, os outros membros do grupo precisarão ingressar nele para dar continuidade ao processo de matchmaking. Nesse momento, o tíquete está no status WaitingForPlayers. Ele não começará a ser combinado com outros tíquetes até que todos os MembersToMatchWith tenham ingressado no tíquete. Para que os membros ingressem, o Creator deve compartilhar o TicketId com os outros membros por meio do seu título. Cada membro então chama JoinMatchmakingTicket, fornecendo os próprios atributos necessários. Depois que todos os membros tiverem ingressado no tíquete, o status do tíquete passará a ser WaitingForMatch.
O restante do processo é igual ao do matchmaking de tíquete de usuário único

Conectando seus jogadores

Depois que seus jogadores forem combinados, você vai querer que eles se conectem uns aos outros, seja por meio de um servidor ou de conexões ponto a ponto. Se você estiver usando um servidor dedicado, poderá contar com a ID da partida para identificar de forma exclusiva o grupo de jogadores em que eles devem estar. Se você estiver usando os servidores multijogador do PlayFab, GetMatch fornecerá um servidor e uma porta para seus jogadores se conectarem. Para obter mais informações, confira Integração com o PlayFab Multiplayer Servers. Nesta versão, a conexão ponto a ponto ainda não tem suporte oficial no matchmaking. Se for necessária uma conexão ponto a ponto, considere usar o PlayFab Party ou uma solução alternativa provisória. Entre em contato conosco para obter mais suporte sobre isso.

Conclusão

Com este início rápido, você já deve ter um fluxo de matchmaking funcionando no seu jogo. Além disso, considere o seguinte:
  • Como seu título lida com a formação de grupos.
  • O que seu título exibe enquanto os usuários aguardam uma partida.
  • Como lidar com falhas e novas tentativas.
Última modificação em 8 de outubro de 2026