> ## 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.
# Inicio rápido del SDK de Matchmaking
> Tutorial de inicio rápido del flujo de cliente de emparejamiento del SDK multijugador de PlayFab: inicializar la biblioteca, enviar un ticket y recibir los resultados de la partida.
Esta guía de inicio rápido le acompaña por todo el proceso para agregar el emparejamiento a su juego mediante el SDK multijugador de PlayFab.
Este tutorial ilustra cómo enviar un ticket a una cola específica para encontrar una partida. Una cola probablemente se corresponda con un modo de juego o con varios modos de juego (por ejemplo, un modo de capturar la bandera y un modo rey de la colina en la misma cola).
El servicio de emparejamiento se encarga de encontrar una partida entre los tickets de una cola. Cuando se encuentra una partida, el título debe encargarse de conectar a los jugadores entre sí para jugar.
El SDK multijugador de PlayFab también proporciona API para las salas (Lobbies) de PlayFab. \* Para obtener más información sobre las API de C++, consulte el [Inicio rápido del SDK de Lobby](/services/playfab/multiplayer/lobby/lobby-getting-started) \* Para obtener más información sobre las API de Unity, consulte el [Inicio rápido para Unity](/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-sdk-getting-started) \* Para obtener más información sobre las API de Unreal, consulte el [Inicio rápido para Unreal](/services/playfab/multiplayer/networking/party-unreal-engine-oss-quickstart)
## Requisitos previos
Necesita una [cuenta de PlayFab](https://developer.playfab.com) para usar PlayFab Matchmaking. Para obtener instrucciones sobre cómo crear una cuenta, consulte [Inicio rápido: Game Manager](/services/playfab/live-service-management/gamemanager/quickstart).
## Configurar una cola de emparejamiento en Game Manager
La biblioteca empareja a los usuarios que crean tickets para las colas configuradas en Game Manager. Para obtener detalles sobre cómo configurar una, consulte [Configuración de colas de emparejamiento](/services/playfab/multiplayer/matchmaking/config-queues).
## Descargar y configurar el SDK multijugador de PlayFab
Descargue el [SDK de C/C++](/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks) para su plataforma e integre los archivos de encabezado y biblioteca proporcionados en su compilación.
Este inicio rápido se centra en el uso del SDK de C/C++. Para las interfaces de Unity y Unreal, consulte los siguientes artículos: \* [Inicio rápido para Unity](/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-sdk-getting-started) \* [Inicio rápido para Unreal](/services/playfab/multiplayer/networking/party-unreal-engine-oss-quickstart)
## Iniciar sesión con una entidad de PlayFab
Para usar el SDK de Lobby de PlayFab, debe autenticar su cliente mediante claves de entidad y tokens de entidad de PlayFab. Adquiera un par de clave de entidad y token de PlayFab iniciando sesión con la API REST [LoginWithCustomId](https://learn.microsoft.com/en-us/rest/api/playfab/client/authentication/login-with-custom-id). Esta API también está disponible como proyección de C/C++ a través del [SDK de REST de PlayFab](/services/playfab/sdks/playfab-sdk-intro).
LoginWithCustomId es una forma rápida de empezar a usar las características de PlayFab, pero no está pensada como el mecanismo de inicio de sesión que incluirá en su versión final. Para obtener orientación sobre el inicio de sesión, consulte [Conceptos básicos y procedimientos recomendados de inicio de sesión](/services/playfab/identity/player-identity/login/login-basics-best-practices).
## Inicializar el SDK multijugador de PlayFab
Inicialice el SDK multijugador de PlayFab siguiendo estos pasos básicos:
1. Inicialice el SDK llamando a [PFMultiplayerInitialize](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/functions/pfmultiplayerinitialize)
2. Establezca la clave de entidad y el token que usa la biblioteca en nombre de los jugadores llamando a [PFMultiplayerSetEntityToken](/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
}
```
## Crear un ticket de emparejamiento
Un ticket de emparejamiento se crea mediante [PFMultiplayerCreateMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayercreatematchmakingticket), en el que se especifican todos los usuarios locales que deben formar parte de la partida y los atributos que desee asociar a esos usuarios.
Esta función también toma una estructura [PFMatchmakingTicketConfiguration](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/structs/pfmatchmakingticketconfiguration) donde se especifica a qué cola pertenece el ticket, un tiempo de espera para el ticket y los usuarios remotos que desee emparejar en este ticket.
### Emparejamiento con un único usuario local
Puede iniciar el emparejamiento para un único usuario local con una llamada 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);
```
### Emparejamiento con un grupo de usuarios remotos
Para iniciar el emparejamiento en grupo con usuarios remotos, resulta útil considerar a un cliente como el líder. Haga que el líder cree el ticket mediante **PFMultiplayerCreateMatchmakingTicket**, especificando los demás usuarios del grupo a través del parámetro **configuration**. Una vez creado el ticket, llame a **GetTicketId** para obtener el identificador del ticket. Envíe este identificador a cada uno de los demás usuarios a través de un mecanismo externo, como una malla de red o una sala compartida de PlayFab, y haga que cada cliente llame a **PFMultiplayerJoinMatchmakingTicketFromId** con el identificador del ticket para unirse al ticket de emparejamiento. El estado del ticket será **PFMatchmakingTicketStatus::WaitingForPlayers** mientras espera a que se unan los jugadores especificados y cambiará a **PFMatchmakingTicketStatus::WaitingForMatch** una vez que todos los jugadores se hayan unido al ticket.
```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);
```
### Emparejamiento con varios usuarios locales
Al emparejar con varios usuarios locales, en lugar de pasar una sola **PFEntityKey** a las funciones **PFMultiplayerCreateMatchmakingTicket** o **PFMultiplayerJoinMatchmakingTicketFromId**, debe pasar una lista de claves. De forma similar, deberá pasar una lista de atributos para cada usuario. Las posiciones de las entradas de cada lista deben corresponderse entre sí. Es decir, la primera entrada de la lista de atributos debe contener los atributos del primer jugador de la 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);
```
## Comprobar el estado del ticket de emparejamiento
Debe comprobar las actualizaciones del ticket llamando a [PFMultiplayerStartProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerstartprocessingmatchmakingstatechanges) para recibir los cambios de estado y, después, llamando a [PFMultiplayerFinishProcessingMatchmakingStateChanges](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerfinishprocessingmatchmakingstatechanges) cuando haya terminado de procesar esos cambios de estado.
El SDK devolverá un cambio de estado **TicketStatusChanged** cada vez que cambie el estado del ticket y un cambio de estado **TicketCompleted** cuando el emparejamiento haya finalizado.
### Ejemplo con el 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);
```
## Obtener la partida
Después de recibir el cambio de estado **PFMatchmakingStateChangeType::TicketCompleted**, llame a [PFMatchmakingTicketGetMatch](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketgetmatch) para obtener los detalles de la partida. Estos detalles contendrán el identificador de la partida, los usuarios que se han emparejado, la región preferida para la partida y una cadena de organización (arrangement string) para la sala asociada a la partida.
Una vez que haya recuperado la información que necesite de la estructura **PFMatchmakingMatchDetails**, el ticket debe destruirse con [PFMultiplayerDestroyMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket).
### Ejemplo con el 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);
```
## Cancelación de un ticket de emparejamiento
Si por algún motivo su cliente desea cancelar el proceso de emparejamiento antes del tiempo de espera establecido en `PFMatchmakingTicketConfiguration`, llame a [PFMatchmakingTicketCancel](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmatchmakingticketcancel) con el identificador del ticket.
Llamar a esta API no garantiza que el ticket se cancele. El ticket todavía podría completarse antes de que se procese la cancelación, o la solicitud de cancelación podría fallar debido a errores de red o del servicio. Puede seguir procesando los cambios de estado del emparejamiento para obtener el resultado del ticket si desea confirmar que la cancelación del ticket se ha completado antes de continuar. De lo contrario, puede llamar inmediatamente a [PFMultiplayerDestroyMatchmakingTicket](/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmatchmaking/functions/pfmultiplayerdestroymatchmakingticket).
### Ejemplo con el SDK de cliente de Matchmaking
```cpp theme={null}
HRESULT hr = PFMatchmakingTicketCancel(ticket);
PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);
```
## (Opcional) Conectar a los jugadores en una sala
Después de que los jugadores se hayan emparejado, pueden unirse en una sala (lobby). La estructura **PFMatchmakingMatchDetails** del ticket emparejado contiene un campo **lobbyArrangementString**, que puede usarse para unir a los usuarios en la misma sala.
Para obtener más información sobre cómo interactúan Lobby y Matchmaking, consulte [Uso conjunto de sala y emparejamiento](/services/playfab/multiplayer/lobby/lobby-and-matchmaking).
Para obtener más información sobre las salas de PlayFab, consulte la [Información general de Lobby de PlayFab](/services/playfab/multiplayer/lobby).
### Ejemplo con el 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));
```
## Conclusión
Con este inicio rápido, ahora debería tener un flujo de emparejamiento funcional en su juego. Además, debería tener en cuenta lo siguiente:
* Cómo controla el título la formación de grupos.
* Qué muestra el título mientras los usuarios esperan una partida.
* Cómo controlar los errores y los reintentos.
## Consulte también
* [SDK de Lobby](/services/playfab/multiplayer/lobby/lobby-getting-started)
## Related topics
- [Inicio rápido del SDK de Lobby](/es/services/playfab/multiplayer/lobby/lobby-getting-started.md)
- [SDK de PlayFab Lobby y Matchmaking](/es/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/lobby-matchmaking-sdks.md)
- [Inicio rápido de Matchmaking](/es/services/playfab/multiplayer/matchmaking/quickstart.md)
- [Inicio rápido del complemento de Unity de Multiplayer](/es/services/playfab/multiplayer/lobby/lobby-matchmaking-sdks/multiplayer-unity-plugin-quickstart.md)
- [Inicio rápido de datos del jugador](/es/services/playfab/player-progression/player-data/quickstart.md)