Inicio rápido del SDK de Matchmaking - XBOX Game Development Documentation

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 * Para obtener más información sobre las API de Unity, consulte el Inicio rápido para Unity * Para obtener más información sobre las API de Unreal, consulte el Inicio rápido para Unreal

Requisitos previos

Necesita una cuenta de PlayFab para usar PlayFab Matchmaking. Para obtener instrucciones sobre cómo crear una cuenta, consulte Inicio rápido: Game Manager.

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.

Descargar y configurar el SDK multijugador de PlayFab

Descargue el SDK de C/C++ 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 * Inicio rápido para Unreal

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. Esta API también está disponible como proyección de C/C++ a través del SDK de REST de PlayFab.

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.

Inicializar el SDK multijugador de PlayFab

Inicialice el SDK multijugador de PlayFab siguiendo estos pasos básicos:

Inicialice el SDK llamando a PFMultiplayerInitialize
Establezca la clave de entidad y el token que usa la biblioteca en nombre de los jugadores llamando a PFMultiplayerSetEntityToken.

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, 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 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.

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.

// Creating the ticket on the leader's client

const char* remoteMemberEntityId1 = ...;
const char* remoteMemberEntityId2 = ...;

std::vector<PFEntityKey> 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);

// 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.

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<PFEntityKey> localMatchMemberEntityKeys{ ... };
std::vector<PCSTR> localMatchMemberAttributes{ ... };

const PFMatchmakingTicket* ticket;
HRESULT hr = PFMultiplayerCreateMatchmakingTicket(
    g_pfmHandle,
    static_cast<uint32_t>(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 para recibir los cambios de estado y, después, llamando a 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

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<const PFMatchmakingTicketStatusChangedStateChange&>(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<const PFMatchmakingTicketCompletedStateChange&>(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 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.

Ejemplo con el SDK de cliente de Matchmaking

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 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.

Ejemplo con el SDK de cliente de Matchmaking

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. Para obtener más información sobre las salas de PlayFab, consulte la Información general de Lobby de PlayFab.

Ejemplo con el SDK de cliente de Matchmaking

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

​Requisitos previos

​Configurar una cola de emparejamiento en Game Manager

​Descargar y configurar el SDK multijugador de PlayFab

​Iniciar sesión con una entidad de PlayFab

​Inicializar el SDK multijugador de PlayFab

​Crear un ticket de emparejamiento

​Emparejamiento con un único usuario local

​Emparejamiento con un grupo de usuarios remotos

​Emparejamiento con varios usuarios locales

​Comprobar el estado del ticket de emparejamiento

​Ejemplo con el SDK de cliente de Matchmaking

​Obtener la partida

​Ejemplo con el SDK de cliente de Matchmaking

​Cancelación de un ticket de emparejamiento

​Ejemplo con el SDK de cliente de Matchmaking

​(Opcional) Conectar a los jugadores en una sala

​Ejemplo con el SDK de cliente de Matchmaking

​Conclusión

​Consulte también

Requisitos previos

Configurar una cola de emparejamiento en Game Manager

Descargar y configurar el SDK multijugador de PlayFab

Iniciar sesión con una entidad de PlayFab

Inicializar el SDK multijugador de PlayFab

Crear un ticket de emparejamiento

Emparejamiento con un único usuario local

Emparejamiento con un grupo de usuarios remotos

Emparejamiento con varios usuarios locales

Comprobar el estado del ticket de emparejamiento

Ejemplo con el SDK de cliente de Matchmaking

Obtener la partida

Ejemplo con el SDK de cliente de Matchmaking

Cancelación de un ticket de emparejamiento

Ejemplo con el SDK de cliente de Matchmaking

(Opcional) Conectar a los jugadores en una sala

Ejemplo con el SDK de cliente de Matchmaking

Conclusión

Consulte también