Uso de vales de reposición de servidor - Multiplayer SDK

Los juegos hospedados en un servidor a veces necesitan buscar jugadores adicionales. Lo más habitual es que esto ocurra cuando uno o varios jugadores se desconectan mientras la partida está en curso. Los vales de reposición de servidor permiten a un servidor de juego buscar jugadores adicionales que encajen en la partida que se está jugando actualmente. Los vales de reposición de servidor difieren de los vales de emparejamiento normales de varias maneras:

Coincidencia
- Los vales de reposición no pueden coincidir entre sí.
- Los vales de reposición tienen prioridad durante la búsqueda, lo que reduce la fragmentación de la base de jugadores.
Contrato
- Los vales de reposición se pueden crear con un campo ServerDetails. Esto permite al servidor indicar cómo deben conectarse a él los jugadores emparejados.
- Los vales de reposición se pueden crear con asignaciones de equipo. Esto permite que los juegos con equipos mantengan su información de equipo.
Propiedades de la cola
- Los vales de reposición no desencadenan la asignación de Multiplayer Server.
- Los vales de reposición no se reflejan en las estadísticas de cola, ya que sus jugadores ya están jugando una partida y sesgarían de forma imprecisa el tiempo de espera.
Propiedad
- Los vales de reposición pertenecen a un servidor de juego, no a un usuario. Los usuarios no pueden ver los vales de reposición ni interactuar con ellos de ninguna manera.

Requisitos previos

Familiaridad básica con el Multiplayer SDK de PlayFab. Para obtener más información, consulte el Inicio rápido del SDK de emparejamiento.
Defina PFMULTIPLAYER_INCLUDE_SERVER_APIS antes de incluir el encabezado de emparejamiento. Por ejemplo:

#define PFMULTIPLAYER_INCLUDE_SERVER_APIS
#include <PFMatchmaking.h>

Configurar un vale de reposición de servidor

Cree y rellene una estructura PFMatchmakingServerBackfillTicketConfiguration con los detalles necesarios:

timeoutInSeconds: Cuánto tiempo se intentará rellenar el vale, en segundos.
queueName: El nombre de una cola de partidas.
memberCount: El número de miembros que hay actualmente en la partida.
members: Los miembros PFMatchmakingMatchMember que hay actualmente en la partida.
serverDetails (opcional): Rellene PFMultiplayerServerDetails con información sobre su servidor (FQDN, dirección IP, puertos, región) que se proporciona a los clientes.

El campo PFMultiplayerServerDetails::ipv4Address no se valida y puede usarse para proporcionar información arbitraria de cadena de conexión a los clientes.

// Define the server port configuration.
PFMultiplayerPort serverPorts[] = {
    { "portname", 12345, PFMultiplayerProtocolType::Udp }
};

// Populate the server details.
PFMultiplayerServerDetails serverDetails = {};
serverDetails.fqdn = "your.server.fqdn.com";
serverDetails.ipv4Address = "123.234.123.234";
serverDetails.ports = serverPorts;
serverDetails.portCount = sizeof(serverPorts) / sizeof(serverPorts[0]);
serverDetails.region = "EastUS";

// Set up the backfill ticket configuration.
PFMatchmakingServerBackfillTicketConfiguration backfillConfig = {};
backfillConfig.timeoutInSeconds = 60;                 // Try for 60 seconds
backfillConfig.queueName = "YourQueueName";
backfillConfig.memberCount = currentMatchMemberCount; // e.g., 4
backfillConfig.members = currentMatchMembers;         // Pointer to an array of PFMatchmakingMatchMember
backfillConfig.serverDetails = &serverDetails;        // Optional; can be nullptr if not needed

Creación de un vale de reposición de servidor

Al usar PFMultiplayerCreateServerBackfillTicket para crear un vale de reposición de servidor, es necesario pasar la entidad de nuestro servidor de juego (como una PFEntityKey) junto con la configuración de reposición que creamos en el paso anterior.

PFMatchmakingTicketHandle backfillTicket = nullptr;
HRESULT hr = PFMultiplayerCreateServerBackfillTicket(
    multiplayerHandle,            // The handle of the PFMultiplayer API instance.
    &serverEntity,                // PFEntityKey for your game server entity
    &backfillConfig,              // The backfill ticket configuration.
    nullptr,                      // Optional async context
    &backfillTicket               // The resulting ticket object.
);

if (FAILED(hr))
{
    // handle ticket creation failure
}

Comprobar el estado del vale de emparejamiento

Debe comprobar si hay actualizaciones del vale llamando a PFMultiplayerStartProcessingMatchmakingStateChanges para recibir los cambios de estado y llamando después a PFMultiplayerFinishProcessingMatchmakingStateChanges cuando termine de procesar esos cambios de estado. El SDK devuelve un cambio de estado TicketStatusChanged cada vez que cambia el estado del vale y un cambio de estado TicketCompleted cuando el emparejamiento se ha completado.

HRESULT hrTicketError = S_OK;

uint32_t stateChangeCount;
const PFMatchmakingStateChange * const * stateChanges;
HRESULT hr = PFMultiplayerStartProcessingMatchmakingStateChanges(g_pfmHandle, &stateChangeCount, &stateChanges);
if (FAILED(hr))  
{  
    return;  
}  

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);
if (FAILED(hr))  
{  
    return;  
}  

// Now that we've returned the state change(s), bail out if we detected ticket failure.
if (FAILED(hrTicketError))  
{  
    return;  
}  

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 contienen el identificador de la partida, los usuarios que se han emparejado juntos, la región preferida para la partida y una cadena de organización para el lobby asociado a la partida. Una vez que recupere toda la información que necesite de la estructura PFMatchmakingMatchDetails, el vale debe destruirse con PFMultiplayerDestroyMatchmakingTicket.

const PFMatchmakingMatchDetails* match;
HREULT hr = PFMatchmakingTicketGetMatch(ticket, &match);
if (FAILED(hr))  
{  
    return;  
}  

std::string matchId = match->matchId;
std::string lobbyArrangementString = match->lobbyArrangementString;

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);

Cancelación de un vale

Si desea cancelar el proceso de emparejamiento antes del tiempo de espera establecido en PFMatchmakingServerBackfillTicketConfiguration, llame a PFMatchmakingTicketCancel con el identificador del vale. Llamar a esta API no garantiza que el vale se cancele. El vale podría completarse antes de que la cancelación pueda procesarse, o la solicitud de cancelación puede producir un error debido a errores de red o del servicio. Puede seguir procesando los cambios de estado de emparejamiento para obtener el resultado del vale si desea confirmar que la cancelación del vale se ha completado antes de continuar. De lo contrario, puede llamar inmediatamente a PFMultiplayerDestroyMatchmakingTicket.

HRESULT hr = PFMatchmakingTicketCancel(ticket);

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);

​Requisitos previos

​Configurar un vale de reposición de servidor

​Creación de un vale de reposición de servidor

​Comprobar el estado del vale de emparejamiento

​Obtener la partida

​Cancelación de un vale

Requisitos previos

Configurar un vale de reposición de servidor

Creación de un vale de reposición de servidor

Comprobar el estado del vale de emparejamiento

Obtener la partida

Cancelación de un vale