Utilisation des tickets de backfill de serveur - SDK Multiplayer

Les jeux hébergés sur un serveur doivent parfois rechercher des joueurs supplémentaires. Cela se produit le plus souvent lorsqu’un ou plusieurs joueurs se déconnectent pendant la partie. Les tickets de backfill de serveur permettent à un serveur de jeu de rechercher des joueurs supplémentaires qui s’intègrent dans la partie en cours. Les tickets de backfill de serveur diffèrent des tickets de matchmaking ordinaires de plusieurs façons :

Mise en correspondance
- Les tickets de backfill ne peuvent pas être mis en correspondance entre eux.
- Les tickets de backfill sont prioritaires lors de la recherche, ce qui réduit la fragmentation de la base de joueurs.
Contrat
- Les tickets de backfill peuvent être créés avec un champ ServerDetails. Cela permet au serveur d’indiquer comment les joueurs mis en correspondance doivent s’y connecter.
- Les tickets de backfill peuvent être créés avec des affectations d’équipe. Cela permet aux jeux comportant des équipes de conserver leurs informations d’équipe.
Propriétés de la file d’attente
- Les tickets de backfill ne déclenchent pas l’allocation de Multiplayer Server.
- Les tickets de backfill ne sont pas pris en compte dans les statistiques de file d’attente, car leurs joueurs sont déjà en train de jouer et fausseraient le temps d’attente.
Propriété
- Les tickets de backfill appartiennent à un serveur de jeu, et non à un utilisateur. Les utilisateurs ne peuvent ni consulter les tickets de backfill ni interagir avec eux de quelque façon que ce soit.

Prérequis

Une connaissance de base du SDK PlayFab Multiplayer. Pour plus d’informations, consultez le Démarrage rapide du SDK Matchmaking.
Définissez PFMULTIPLAYER_INCLUDE_SERVER_APIS avant d’inclure l’en-tête de matchmaking. Par exemple :

#define PFMULTIPLAYER_INCLUDE_SERVER_APIS
#include <PFMatchmaking.h>

Configurer un ticket de backfill de serveur

Créez et renseignez une structure PFMatchmakingServerBackfillTicketConfiguration avec les détails nécessaires :

timeoutInSeconds : durée, en secondes, pendant laquelle tenter de remplir le ticket.
queueName : le nom d’une file d’attente de correspondance.
memberCount : le nombre de membres actuellement dans la correspondance.
members : les membres PFMatchmakingMatchMember actuellement dans la correspondance.
serverDetails (facultatif) : renseignez PFMultiplayerServerDetails avec des informations sur votre serveur (FQDN, adresse IP, ports, région) qui sont fournies aux clients.

Le champ PFMultiplayerServerDetails::ipv4Address n’est pas validé et peut être utilisé pour fournir des informations de chaîne de connexion arbitraires aux clients.

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

Création d’un ticket de backfill de serveur

Pour créer un ticket de backfill de serveur avec PFMultiplayerCreateServerBackfillTicket, nous devons transmettre l’entité de notre serveur de jeu (sous forme de PFEntityKey) ainsi que la configuration de backfill créée à l’étape précédente.

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
}

Vérifier l’état du ticket de matchmaking

Vous devez vérifier les mises à jour du ticket en appelant PFMultiplayerStartProcessingMatchmakingStateChanges pour recevoir les changements d’état, puis en appelant PFMultiplayerFinishProcessingMatchmakingStateChanges lorsque vous avez terminé de traiter ces changements d’état. Le SDK retourne un changement d’état TicketStatusChanged chaque fois que l’état du ticket change, et un changement d’état TicketCompleted lorsque le matchmaking est terminé.

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;  
}  

Obtenir la correspondance

Après avoir reçu le changement d’état PFMatchmakingStateChangeType::TicketCompleted, appelez PFMatchmakingTicketGetMatch pour obtenir les détails de la correspondance. Ces détails contiennent l’ID de la correspondance, les utilisateurs qui ont été mis en correspondance, la région préférée pour la correspondance et une chaîne d’arrangement pour le lobby associé à la correspondance. Une fois que vous avez récupéré les informations dont vous avez besoin dans la structure PFMatchmakingMatchDetails, le ticket doit être détruit avec 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);

Annulation d’un ticket

Si vous souhaitez annuler le processus de matchmaking avant l’expiration du délai défini dans PFMatchmakingServerBackfillTicketConfiguration, appelez PFMatchmakingTicketCancel avec le handle du ticket. L’appel de cette API ne garantit pas l’annulation du ticket. Le ticket peut encore se terminer avant que l’annulation puisse être traitée, ou la demande d’annulation peut échouer en raison d’erreurs réseau ou de service. Vous pouvez toujours traiter les changements d’état du matchmaking pour obtenir le résultat du ticket si vous souhaitez confirmer que l’annulation du ticket est terminée avant de continuer. Sinon, vous pouvez appeler immédiatement PFMultiplayerDestroyMatchmakingTicket.

HRESULT hr = PFMatchmakingTicketCancel(ticket);

PFMultiplayerDestroyMatchmakingTicket(g_pfmHandle, ticket);

​Prérequis

​Configurer un ticket de backfill de serveur

​Création d’un ticket de backfill de serveur

​Vérifier l’état du ticket de matchmaking

​Obtenir la correspondance

​Annulation d’un ticket

Prérequis

Configurer un ticket de backfill de serveur

Création d’un ticket de backfill de serveur

Vérifier l’état du ticket de matchmaking

Obtenir la correspondance

Annulation d’un ticket