> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Início rápido do SDK de Matchmaking > Passo a passo de início rápido do fluxo de cliente de matchmaking do PlayFab Multiplayer SDK: inicializar a biblioteca, enviar um tíquete e receber os resultados da partida. Este guia de início rápido orienta você por todo o processo de adicionar o matchmaking ao seu jogo usando o PlayFab Multiplayer SDK. 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. O PlayFab Multiplayer SDK também fornece APIs para os PlayFab Lobbies. \* Para obter mais informações sobre as APIs C++, confira o [Início rápido do SDK de Lobby](/pt-BR/services/playfab/multiplayer/lobby/lobby-getting-started) \* Para obter mais informações sobre as APIs do Unity, confira o [Início rápido para Unity](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-sdk-getting-started) \* Para obter mais informações sobre as APIs do Unreal, confira o [Início rápido para Unreal](/pt-BR/services/playfab/multiplayer/networking/party-unreal-engine-oss-quickstart) ## Pré-requisitos Você precisa de uma [conta do PlayFab](https://developer.playfab.com) para usar o PlayFab Matchmaking. Para obter instruções sobre como criar uma conta, confira [Início rápido: Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager/quickstart). ## Configurar uma fila de matchmaking no Game Manager A biblioteca combina usuários que criam tíquetes para filas configuradas no Game Manager. Para obter detalhes sobre como configurar uma, confira [Configurando filas de matchmaking](/pt-BR/services/playfab/multiplayer/matchmaking/config-queues). ## Baixar e configurar o PlayFab Multiplayer SDK Baixe o [SDK C/C++](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks) para sua plataforma e integre os arquivos de cabeçalho e de biblioteca do provedor ao seu build. Este início rápido se concentra no uso do SDK C/C++. Para as interfaces do Unity e do Unreal, confira os seguintes artigos: \* [Início rápido para Unity](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-sdk-getting-started) \* [Início rápido para Unreal](/pt-BR/services/playfab/multiplayer/networking/party-unreal-engine-oss-quickstart) ## Fazer login de uma entidade do PlayFab Para usar o PlayFab Lobby SDK, você precisa autenticar seu cliente usando chaves de entidade e tokens de entidade do PlayFab. Obtenha um par de chave e token de entidade do PlayFab fazendo login com a API REST [LoginWithCustomId](https://learn.microsoft.com/en-us/rest/api/playfab/client/authentication/login-with-custom-id). Essa API também está disponível como uma projeção C/C++ por meio do [PlayFab REST SDK](/pt-BR/services/playfab/sdks/playfab-sdk-intro). LoginWithCustomId é uma forma rápida de começar a usar os recursos do PlayFab, mas não se destina a ser o mecanismo de login com o qual você lança o jogo. Para obter orientações sobre login, confira [Noções básicas e práticas recomendadas de login](/pt-BR/services/playfab/identity/player-identity/login/login-basics-best-practices). ## Inicializar o PlayFab Multiplayer SDK Inicialize o PlayFab Multiplayer SDK seguindo estas etapas básicas: 1. Inicialize o SDK chamando [PFMultiplayerInitialize](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayerinitialize) 2. Defina a chave e o token de entidade usados pela biblioteca em nome dos seus jogadores chamando [PFMultiplayerSetEntityToken](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayersetentitytoken). ```cpp theme={null} static PFMultiplayerHandle g_pfmHandle = nullptr; ... ... HRESULT hr = S_OK; // Initialize the PFMultiplayer library. hr = PFMultiplayerInitialize(titleId, &g_pfmHandle); if (FAILED(hr)) { // handle initialize failure } // Set an entity token for a local user. The token is used to authenticate PlayFab operations on behalf of this user. // Tokens can expire, and this API token should be called again when this token is refreshed. hr = PFMultiplayerSetEntityToken(g_pfmHandle, localUserEntity, entityToken); if (FAILED(hr)) { // handle set entity token failure } ``` ## Criar um tíquete de matchmaking Você cria um tíquete de matchmaking usando [PFMultiplayerCreateMatchmakingTicket](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreatematchmakingticket), no qual você especifica todos os usuários locais que devem fazer parte da partida e quaisquer atributos que deseja associar a esses usuários. Essa função também recebe um [PFMatchmakingTicketConfiguration](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketconfiguration), no qual você especifica a qual fila o tíquete se destina, um tempo limite para o tíquete e quaisquer usuários remotos que você deseja incluir neste tíquete. ### Matchmaking com um único usuário local Você pode iniciar o matchmaking para um único usuário local com uma chamada a **PFMultiplayerCreateMatchmakingTicket**. ```cpp theme={null} const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager. PFMatchmakingTicketConfiguration configuration{}; configuration.timeoutInSeconds = 120; configuration.queueName = yourQueueName; const char* attributes = "\"{\"color\":\"blue\", \"role\":\"tank\"}\""; const PFMatchmakingTicket* ticket; HRESULT hr = PFMultiplayerCreateMatchmakingTicket( g_pfmHandle, 1, // number of local users localUserEntity, &attributes, &configuration, nullptr, // optional asyncContext &ticket); RETURN_IF_FAILED(hr); ``` ### Matchmaking com um grupo de usuários remotos Para iniciar o matchmaking em grupo com usuários remotos, é útil considerar um cliente como o líder. Peça ao líder que crie o tíquete usando **PFMultiplayerCreateMatchmakingTicket**, especificando os outros usuários do grupo por meio do parâmetro **configuration**. Depois que o tíquete for criado, chame **GetTicketId** para obter a ID do tíquete. Envie essa ID para cada um dos outros usuários por meio de um mecanismo externo, como uma malha de rede ou um PlayFab Lobby compartilhado, e peça a cada cliente que chame **PFMultiplayerJoinMatchmakingTicketFromId** com a ID do tíquete para ingressar no tíquete de matchmaking. O status do tíquete será **PFMatchmakingTicketStatus::WaitingForPlayers** enquanto aguarda o ingresso dos jogadores especificados e mudará para **PFMatchmakingTicketStatus::WaitingForMatch** quando todos os jogadores tiverem ingressado no tíquete. ```cpp theme={null} // Creating the ticket on the leader's client const char* remoteMemberEntityId1 = ...; const char* remoteMemberEntityId2 = ...; std::vector remoteMatchMemberEntityKeys; remoteMatchMemberEntityKeys.push_back({ remoteMemberEntityId1, "title_player_account" }); remoteMatchMemberEntityKeys.push_back({ remoteMemberEntityId2, "title_player_account" }); const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager. PFMatchmakingTicketConfiguration configuration{}; configuration.timeoutInSeconds = 120; configuration.queueName = yourQueueName; configuration.membersToMatchWithCount = 2; // number of remote members to match with configuration.membersToMatchWith = remoteMatchMemberEntityKeys.data(); const char* attributes = "\"{\"color\":\"blue\", \"role\":\"tank\"}\""; const PFMatchmakingTicket* ticket; HRESULT hr = PFMultiplayerCreateMatchmakingTicket( g_pfmHandle, 1, // number of local users localUserEntity, &attributes, &configuration, nullptr, // optional asyncContext &ticket); RETURN_IF_FAILED(hr); // Getting the ticket ID PCSTR ticketId; hr = PFMatchmakingTicketGetTicketId(ticket, &ticketId); RETURN_IF_FAILED(hr); ``` ```cpp theme={null} // Joining the ticket on the other players' clients const char* attributes = "\"{\"color\":\"blue\", \"role\":\"healer\"}\""; const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager. const PFMatchmakingTicket* ticket; HRESULT hr = PFMultiplayerJoinMatchmakingTicketFromId( g_pfmHandle, 1, // number of local users localUserEntity, &attributes, ticketId, yourQueueName, nullptr, // optional asyncContext &ticket); ``` ### Matchmaking com vários usuários locais Ao fazer matchmaking com vários usuários locais, em vez de passar um único **PFEntityKey** para as funções **PFMultiplayerCreateMatchmakingTicket** ou **PFMultiplayerJoinMatchmakingTicketFromId**, você precisa passar uma lista de chaves. Da mesma forma, você precisará passar uma lista de atributos para cada usuário. As posições das entradas de cada lista devem corresponder entre si. Ou seja, a primeira entrada da lista de atributos deve conter os atributos do primeiro jogador da lista de **PFEntityKey**. ```cpp theme={null} const char* yourQueueName = ...; // This is the name of the queue you configured in Game Manager. PFMatchmakingTicketConfiguration configuration{}; configuration.timeoutInSeconds = 120; configuration.queueName = queueName; std::vector localMatchMemberEntityKeys{ ... }; std::vector localMatchMemberAttributes{ ... }; const PFMatchmakingTicket* ticket; HRESULT hr = PFMultiplayerCreateMatchmakingTicket( g_pfmHandle, static_cast(localMatchMemberEntityKeys.size()) localMatchMemberEntityKeys.data(), localMatchMemberAttributes.data(), &configuration, nullptr, // optional asyncContext &ticket); RETURN_IF_FAILED(hr); ``` ## Verificar o status do tíquete de matchmaking Você deve verificar se há atualizações no tíquete chamando [PFMultiplayerStartProcessingMatchmakingStateChanges](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges) para receber as alterações de estado e, em seguida, chamando [PFMultiplayerFinishProcessingMatchmakingStateChanges](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges) quando terminar de processar essas alterações de estado. O SDK retornará uma alteração de estado **TicketStatusChanged** sempre que o status do tíquete mudar e uma alteração de estado **TicketCompleted** quando o matchmaking for concluído. ### Exemplo usando o SDK de cliente de Matchmaking ```cpp theme={null} HRESULT hrTicketError = S_OK; uint32_t stateChangeCount; const PFMatchmakingStateChange * const * stateChanges; hr = PFMultiplayerStartProcessingMatchmakingStateChanges(g_pfmHandle, &stateChangeCount, &stateChanges); RETURN_IF_FAILED(hr); for (uint32_t i = 0; i < stateChangeCount; ++i) { const PFMatchmakingStateChange& stateChange = *stateChanges[i]; switch (stateChange.stateChangeType) { case PFMatchmakingStateChangeType::TicketStatusChanged: { const auto& ticketStatusChanged = static_cast(stateChange); PFMatchmakingTicketStatus status; if (SUCCEEDED(PFMatchmakingTicketGetStatus(ticketStatusChanged.ticket, &status))) { printf("Ticket status is now: %i.\n", status); } break; } case PFMatchmakingStateChangeType::TicketCompleted: { const auto& ticketCompleted = static_cast(stateChange); printf("PFMatchmaking completed with Result 0x%08x.\n", ticketCompleted.result); if (FAILED(ticketCompleted.result)) { // On failure, we must record the HRESULT so we can return the state change(s) and then bail // out of this function. hrTicketError = ticketCompleted.result; } break; } } } hr = PFMultiplayerFinishProcessingMatchmakingStateChanges(g_pfmHandle, stateChangeCount, stateChanges); RETURN_IF_FAILED(hr); // Now that we've returned the state change(s), bail out if we detected ticket failure. RETURN_IF_FAILED(hrTicketError); ``` ## Obter a partida Depois de receber a alteração de estado **PFMatchmakingStateChangeType::TicketCompleted**, chame [PFMatchmakingTicketGetMatch](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch) para obter os detalhes da partida. Esses detalhes conterão a ID da partida, os usuários que foram combinados, a região preferencial da partida e uma cadeia de caracteres de organização do lobby associado à partida. Depois de recuperar todas as informações necessárias da struct **PFMatchmakingMatchDetails**, o tíquete deve ser destruído com [PFMultiplayerDestroyMatchmakingTicket](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket). ### Exemplo usando o SDK de cliente de Matchmaking ```cpp theme={null} const PFMatchmakingMatchDetails* match; HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match); RETURN_IF_FAILED(hr); std::string matchId = match->matchId; std::string lobbyArrangementString = match->lobbyArrangementString; PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket); ``` ## Cancelando um tíquete de matchmaking Se, por algum motivo, seu cliente quiser cancelar o processo de matchmaking antes do tempo limite definido em `PFMatchmakingTicketConfiguration`, chame [PFMatchmakingTicketCancel](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketcancel) com o identificador do tíquete. Chamar essa API não garante que o tíquete será cancelado. O tíquete ainda pode ser concluído antes que o cancelamento possa ser processado, ou a solicitação de cancelamento pode falhar devido a erros de rede ou do serviço. Você ainda pode processar as alterações de estado de matchmaking para obter o resultado do tíquete, caso queira confirmar que o cancelamento do tíquete foi concluído antes de prosseguir. Caso contrário, você pode chamar imediatamente [PFMultiplayerDestroyMatchmakingTicket](/pt-BR/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket). ### Exemplo usando o SDK de cliente de Matchmaking ```cpp theme={null} HRESULT hr = PFMatchmakingTicketCancel(ticket); PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket); ``` ## (Opcional) Conectando seus jogadores em um Lobby Depois que seus jogadores forem combinados, eles poderão se reunir em um lobby. O **PFMatchmakingMatchDetails** do tíquete combinado contém um campo **lobbyArrangementString**, que pode ser usado para colocar os usuários no mesmo Lobby. Para obter mais informações sobre como o Lobby e o Matchmaking interagem, confira [Usar o lobby e o matchmaking juntos](/pt-BR/services/playfab/multiplayer/lobby/lobby-and-matchmaking). Para obter mais informações sobre os PlayFab Lobbies, confira a [Visão geral do PlayFab Lobby](/pt-BR/services/playfab/multiplayer/lobby). ### Exemplo usando o SDK de cliente de Matchmaking ```cpp theme={null} const PFMatchmakingMatchDetails* match; HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match); RETURN_IF_FAILED(hr); std::string matchId = match->matchId; std::string lobbyArrangementString = match->lobbyArrangementString; PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket); PFLobbyHandle lobby; RETURN_IF_FAILED_HR(PFMultiplayerJoinArrangedLobby( m_pfmHandle, &joiningUser, lobbyArrangementString, &joinConfig, nullptr, // optional asyncContext &lobby)); ``` ## 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. ## Confira também * [Lobby SDK](/pt-BR/services/playfab/multiplayer/lobby/lobby-getting-started) ## Related topics - [Início rápido do SDK do Lobby](/pt-BR/services/playfab/multiplayer/lobby/lobby-getting-started.md) - [SDKs de Lobby e Matchmaking do PlayFab](/pt-BR/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks.md) - [Início rápido de matchmaking](/pt-BR/services/playfab/multiplayer/matchmaking/quickstart.md) - [Início rápido do Unity](/pt-BR/services/playfab/sdks/unity3d/quickstart.md) - [Início rápido do SDK Generator](/pt-BR/services/playfab/sdks/sdkgenerator/quickstart.md)