Démarrage rapide de Party - XBOX Game Development Documentation

Ce démarrage rapide décrit les fonctionnalités principales de PlayFab Party, accompagnées d’extraits de code. PlayFab Party a été conçu dès le départ pour être multiplateforme. Nous avons structuré ces démarrages rapides de la même manière : la plupart des informations s’appliquent à toutes les plateformes, et les prérequis et étapes propres à chaque plateforme sont décrits dans les documents liés. Pour une compréhension plus approfondie, consultez la documentation de référence et la documentation conceptuelle liées, ainsi que les exemples d’applications propres à chaque plateforme.

Ce guide de démarrage rapide couvre l’utilisation du SDK Party C++ * Pour les utilisateurs de Unity, consultez le Démarrage rapide pour Unity * Pour les utilisateurs d’Unreal Engine qui souhaitent utiliser PlayFab Online Subsystem pour Unreal Engine, consultez le Démarrage rapide pour Unreal.

Prérequis

Vous avez besoin d’un compte PlayFab, et vous devez activer la fonctionnalité Party pour commencer à utiliser Party.

Créez votre compte PlayFab ou connectez-vous à celui-ci. Pour obtenir des instructions, consultez Démarrage rapide : Game Manager.
Activez la fonctionnalité Party via Game Manager depuis votre compte PlayFab.

Prérequis de la plateforme

Avant de commencer ce démarrage rapide, effectuez la configuration propre à la plateforme nécessaire, comme indiqué dans les rubriques suivantes :

<!—3. Nintendo Switch prerequisites—>

Prérequis Linux

Une fois les étapes propres à la plateforme terminées, poursuivez avec les autres étapes de cette rubrique pour configurer PlayFab Party.

Télécharger et configurer le SDK Party

Il existe des SDK Party pour différentes plateformes et différents moteurs de jeu. Sélectionnez et téléchargez celui dont vous avez besoin. Pour les liens de téléchargement, consultez SDK Party. Après avoir installé le SDK, vous pouvez exécuter un exemple pour voir comment Party fonctionne avant de commencer à écrire du code. Pour télécharger un exemple, accédez à Exemples Party. Si vous utilisez Party dans des titres XBOX et PC, nous vous recommandons d’utiliser la bibliothèque d’assistance XBOX Live pour Party pour garantir un fonctionnement et un comportement cohérents. Cette bibliothèque aide votre titre à respecter les exigences XBOX Live. Pour en savoir plus, consultez Exigences XBOX.

Se connecter à votre titre PlayFab et obtenir un jeton d’entité et un ID d’entité

Pour initialiser et utiliser Party, vous devez vous connecter à PlayFab. Vous pouvez utiliser PlayFabClientAPI::LoginWithCustomID ou une méthode de connexion propre à la plateforme. Une fois la connexion effectuée, PlayFab renvoie un ID d’entité et un jeton d’entité dans le LoginResult. Ces deux informations clés sont utilisées pour initialiser une instance d’utilisateur local pour PlayFab Party. Un exemple de connexion avec un ID personnalisé, tel qu’implémenté dans PlayFabManager.cpp, est présenté dans cet extrait de code :

PlayFabClientAPI::LoginWithCustomID(
    loginRequest,
    [this, callback, userId](const LoginResult& loginResult, void*)
    {
        // Sign in was successful.
        DEBUGLOG("PlayFab::signin -- Login with custom id callback\n");

        // Save the PlayFab id and entity data for Party authentication.
        m_playfabId = loginResult.PlayFabId;
        if (loginResult.EntityToken.notNull() && loginResult.EntityToken->Entity.notNull())
        {
            m_entityKey = loginResult.EntityToken->Entity;
            m_entityToken = loginResult.EntityToken->EntityToken;
        }

Après avoir obtenu avec succès l’ID d’entité et le jeton d’entité auprès de PlayFab, vous pouvez procéder à l’activation, puis à l’initialisation de Party.

Si vous utilisez XBOX Live, vous pouvez également utiliser la bibliothèque d’assistance XBOX Live pour Party pour vous connecter.

Initialiser PlayFab Party

Globalement, l’initialisation de Party comprend les étapes suivantes :

Obtenir une référence singleton au PartyManager et l’initialiser.
Il s’agit de la classe de gestion principale pour interagir avec la bibliothèque Party.

    auto& partyManager = PartyManager::GetSingleton();
    PartyError err;

    //Only initialize the party manager once.
    if (m_partyInitialized == false)
    {
        // Initialize PlayFab Party
        err = partyManager.Initialize(titleId);
        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Initialize failed: %s\n", GetErrorMessage(err));
            return;
        }

        m_partyInitialized = true;
    }

Créer un objet utilisateur local.
Cet objet utilisateur local sert à représenter un utilisateur local sur l’appareil (PC, console, téléphone, etc.) lors des opérations de mise en réseau et de chat. L’objet utilisateur local est initialisé avec l’ID d’entité PlayFab.

    //Only create a local user object if it doesn't exist.
    if (m_localUser == nullptr)
    {
        PartyString entityId = Managers::Get<PlayFabManager>()->EntityId().c_str();
        PartyString entityToken = Managers::Get<PlayFabManager>()->EntityToken().c_str();

        // Create a local user object
        err = partyManager.CreateLocalUser(
            entityId,                                   // User id
            entityToken,                                // User entity token
            &m_localUser                                // OUT local user object
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("CreateLocalUser failed: %s\n", GetErrorMessage(err));
            return;
        }
    }

Créer un contrôle de chat et définir le canal d’entrée et de sortie audio sur lequel Party recevra ou transmettra des données.
L’objet contrôle de chat gère les opérations de chat de l’utilisateur sur l’appareil spécifique.

    // Only create local chat controls if they don't exist.
    if (m_localChatControl == nullptr)
    {
        PartyLocalDevice* localDevice = nullptr;

        // Retrieve the local device
        err = partyManager.GetLocalDevice(&localDevice);

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("GetLocalDevice failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Create a chat control for the local user on the local device
        err = localDevice->CreateChatControl(
            m_localUser,                                // Local user object
            m_languageCode,                             // Language id
            nullptr,                                    // Async identifier
            &m_localChatControl                         // OUT local chat control
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("CreateChatControl failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Use system default settings for the audio input device
        err = m_localChatControl->SetAudioInput(
            PartyAudioDeviceSelectionType::SystemDefault,   // Selection type
            nullptr,                                        // Device id
            nullptr                                         // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetAudioInput failed: %s\n", GetErrorMessage(err));
            return;
        }

        // Use system default settings for the audio output device
        err = m_localChatControl->SetAudioOutput(
            PartyAudioDeviceSelectionType::SystemDefault,   // Selection type
            nullptr,                                        // Device id
            nullptr                                         // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetAudioOutput failed: %s\n", GetErrorMessage(err));
        }

Définir les options de transcription et de traduction.
La transcription et la traduction sont des fonctionnalités de chat facultatives qui peuvent considérablement améliorer l’accessibilité de votre jeu. Vous trouverez plus d’informations sur ces fonctionnalités dans la Vue d’ensemble du chat.

        // Get the available list of text to speech profiles
        err = m_localChatControl->PopulateAvailableTextToSpeechProfiles(nullptr);

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Populating available TextToSpeechProfiles failed: %s \n", GetErrorMessage(err));
        }

        // Set transcription options for transcribing other users regardless of language, and ourselves.
        PartyVoiceChatTranscriptionOptions transcriptionOptions =
            PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithMatchingLanguages |
            PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithNonMatchingLanguages |
            PartyVoiceChatTranscriptionOptions::TranslateToLocalLanguage |
            PartyVoiceChatTranscriptionOptions::TranscribeSelf;

        // Set the transcription options on our chat control.
        err = m_localChatControl->SetTranscriptionOptions(
            transcriptionOptions,                       // Transcription options
            nullptr                                     // Async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("SetTranscriptionOptions failed: %s\n", GetErrorMessage(err));
        }

        // Enable translation to local language in chat controls.
        err = m_localChatControl->SetTextChatOptions(
            PartyTextChatOptions::TranslateToLocalLanguage,
            nullptr
        );

À ce stade, PlayFab Party est initialisé dans votre application ou votre jeu. Consultez le code NetworkManager::Initialize() dans NetworkManager.cpp dans l’application de démonstration pour un exemple complet. L’étape suivante consiste à créer un réseau Party et à s’y connecter.

Créer un réseau Party

Un réseau Party est un ensemble sécurisé d’un ou de plusieurs appareils et de leurs utilisateurs autorisés, créé par le jeu pour échanger des communications de chat ou de données. Un réseau Party correspond généralement au concept de session multijoueur ou de « lobby » de chat d’un jeu. Vous ne pouvez envoyer des messages qu’aux joueurs de votre propre réseau. L’extrait de code suivant montre comment créer un réseau Party.

    // Set the maximum number of devices allowed in a network to 16 devices
    constexpr uint8_t c_maxSampleNetworkDeviceCount = 16;
    static_assert(c_maxSampleNetworkDeviceCount <= c_maxNetworkConfigurationMaxDeviceCount, "Must be less than or equal to c_maxNetworkConfigurationMaxDeviceCount.");

    // Initialize network configuration for Party Network.
    PartyNetworkConfiguration cfg = {};
    cfg.maxDeviceCount = c_maxSampleNetworkDeviceCount;
    cfg.maxUserCount = c_maxSampleNetworkDeviceCount;
    ...
    
    // Initialize an empty network descriptor to hold the result of the following call.
    PartyNetworkDescriptor networkDescriptor = {};

    // Create a new network descriptor
    err = PartyManager::GetSingleton().CreateNewNetwork(
        m_localUser,                                // Local User
        &cfg,                                       // Network Config
        0,                                          // Region List Count
        nullptr,                                    // Region List
        &invitationConfiguration,                   // Invitation configuration
        nullptr,                                    // Async Identifier
        &networkDescriptor,                         // OUT network descriptor
        nullptr                                     // applied initialinvitationidentifier.
    );

Une fois l’appel à la fonction CreateNewNetwork() réussi, un objet descripteur de réseau PartyNetworkDescriptor est renvoyé ou renseigné. Le descripteur contient les données nécessaires aux autres joueurs pour se connecter à un réseau. Consultez la documentation de référence de l’API pour obtenir des informations sur les autres paramètres de la fonction. Une fois un réseau Party créé, des invitations permettent de contrôler quels utilisateurs peuvent le rejoindre. PlayFab Matchmaking, PlayFab Lobby, les invitations de la plateforme ou des services de jeu personnalisés peuvent être utilisés pour partager les détails de connexion avec d’autres joueurs. Le type d’invitation le plus simple est une invitation ouverte constituée d’un descripteur de réseau. Pour obtenir des informations détaillées sur tous les types d’invitations et sur le modèle de sécurité, consultez Invitations et modèle de sécurité.

Partager le descripteur de réseau Party

À ce stade, vous disposez d’un descripteur de réseau Party et êtes prêt à le partager avec d’autres joueurs. Il existe de nombreux mécanismes de synchronisation que vous pouvez utiliser pour partager ces informations ; toutefois, à des fins de test rapide, vous pouvez copier-coller manuellement le descripteur de réseau Party de la session Party hôte vers la session Party invitée. Nous vous recommandons d’utiliser PlayFab Lobby pour partager le descripteur de réseau dans votre jeu multijoueur, mais vous pouvez également utiliser votre propre service de lobby, vos propres invitations ou d’autres mécanismes de partage selon les besoins de votre jeu.

Partager manuellement le descripteur de réseau Party

Depuis la session hôte, utilisez PartyManager::SerializeNetworkDescriptor() pour sérialiser le descripteur de réseau en chaîne et l’afficher dans la console.
Copiez-collez la chaîne du descripteur de réseau dans un autre jeu, en local ou à distance.
Dans la session invitée, utilisez PartyManager::DeserializeNetworkDescriptor() pour désérialiser le descripteur de réseau à partir de la chaîne du descripteur de réseau.
Connectez-vous au réseau Party.

Utiliser PlayFab Lobby pour partager le descripteur de réseau Party

PlayFab Lobby peut être utilisé pour regrouper temporairement des joueurs lorsqu’ils entrent dans des parties et en sortent, et pour synchroniser le descripteur de réseau afin que les joueurs puissent rejoindre le même réseau. PlayFab Lobby est hautement personnalisable pour répondre à une grande variété de besoins de jeu sur toutes les plateformes prises en charge et entre plateformes. Consultez le Démarrage rapide du SDK Multiplayer pour plus de détails sur l’utilisation de PlayFab Lobby avec les messages en temps réel. Pour plus de détails sur l’utilisation conjointe de PlayFab Lobby et de PlayFab Party, consultez Créer un lobby avec le SDK PlayFab Multiplayer.

Activer les réseaux évolutifs

Les réseaux PlayFab Party peuvent évoluer pour prendre en charge de 2 à 128 appareils. Le service choisit une configuration de relais optimisée pour votre scénario ; il est donc important de configurer le maxDeviceCount dans PartyNetworkConfiguration pour qu’il corresponde au nombre maximal d’appareils attendu dans votre réseau. Pour une description des réseaux évolutifs, consultez Réseaux évolutifs.

Se connecter à un réseau Party

Suivez les étapes ci-dessous pour rejoindre le réseau Party après avoir obtenu le descripteur de réseau Party :

Utilisez PartyManager::DeserializeNetworkDescriptor() pour désérialiser le descripteur de réseau à partir de la chaîne du descripteur de réseau.
Connectez-vous au réseau Party.
Authentifiez l’utilisateur local pour le réseau.
Connectez le contrôle de chat local au réseau afin de pouvoir utiliser la VOIP.
Établissez un point de terminaison de réseau Party pour le trafic des messages de jeu.

    PartyNetworkDescriptor networkDescriptor = {};

    // Deserialize the remote network's descriptor
    PartyError err = PartyManager::DeserializeNetworkDescriptor(descriptor, &networkDescriptor);

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed to deserialize descriptor: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return;
    }

    // This portion of connecting to the network is the same for
    // both creating a new and joining an existing network.

    PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
        &descriptor,                                // Network descriptor
        nullptr,                                    // Async identifier
        &m_network                                  // OUT network
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Authenticate the local user on the network so we can participate in it
    err = m_network->AuthenticateLocalUser(
        m_localUser,                                // Local user
        networkId,                                  // Invitation Id
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Connect the local user chat control to the network so we can use VOIP
    err = m_network->ConnectChatControl(
        m_localChatControl,                         // Local chat control
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Establish a network endoint for game message traffic
    err = m_network->CreateEndpoint(
        m_localUser,                                // Local user
        0,                                          // Property Count
        nullptr,                                    // Property name keys
        nullptr,                                    // Property Values
        nullptr,                                    // Async identifier
        &m_localEndpoint                            // OUT local endpoint
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

Envoyer un message à un autre appareil ou point de terminaison du réseau

Une fois connecté au réseau Party, vous pouvez envoyer un message à l’aide de l’objet point de terminaison local.

    if (m_localEndpoint && m_state == NetworkManagerState::NetworkConnected)
    {
        auto packet = message.Serialize();

        // Form the data packet into a data buffer structure
        PartyDataBuffer data[] = {
            {
                static_cast<const void*>(packet.data()),
                static_cast<uint32_t>(packet.size())
            },
        };

        // Set delivery options for guaranteed and sequential delivery.
        PartySendMessageOptions deliveryOptions =
            PartySendMessageOptions::GuaranteedDelivery |
            PartySendMessageOptions::SequentialDelivery;

        // Send out the message to all other peers
        PartyError err = m_localEndpoint->SendMessage(
            0,                                      // endpoint count; 0 = broadcast
            nullptr,                                // endpoint list
            deliveryOptions,                        // send message options
            nullptr,                                // configuration
            1,                                      // buffer count
            data,                                   // buffer
            nullptr                                 // async identifier
        );

        if (PARTY_FAILED(err))
        {
            DEBUGLOG("Failed to SendMessage: %s\n", GetErrorMessage(err));
        }
    }

Le code complet est disponible dans NetworkManager.cpp.

Recevoir un message et le restituer sur l’appareil local

La dernière étape consiste à recevoir les messages envoyés par les membres Party distants et à les restituer (les lire) sur votre appareil.

Lors de la création du contrôle de chat dans l’une des étapes précédentes, vous avez déjà configuré les périphériques d’entrée et de sortie audio utilisés par Party pour envoyer, recevoir et restituer les données audio. Pour recevoir les messages audio, vous devez également définir l’autorisation de chat appropriée entre chaque contrôle de chat si vous souhaitez que l’audio circule. Par défaut, les autorisations de chat sont définies sur NONE. Pour plus d’informations, consultez l’article Autorisations de chat.

Le traitement des autres messages provenant de la couche Party s’effectue au mieux dans un thread de mise à jour dédié ou dans une boucle de jeu à haute fréquence. La boucle de jeu doit être configurée pour s’exécuter à chaque image et recevoir les messages du gestionnaire Party via la fonction StartProcessingStateChanges(). Pour une description complète de tous les changements d’état, consultez la documentation de référence de Party. Vous pouvez également consulter NetworkManager.cpp pour un exemple de traitement de chaque changement d’état.

Gestion de la suspension du titre

Certaines plateformes prennent en charge la suspension temporaire de l’exécution de votre titre : iOS, Switch et GDK. Lorsque votre titre est suspendu, la pile réseau est invalidée et PlayFab Party ne peut pas maintenir la connexion au réseau PlayFab Party. Une attention particulière est nécessaire pour gérer la suspension et la reprise de l’exécution de votre titre lors de l’utilisation de PlayFab Party.

iOS

Sur iOS, vous devez quitter le réseau PlayFab Party puis vous y reconnecter Pour quitter le réseau Party, appelez LeaveNetwork(). Une fois le réseau réactivé, appelez ConnectToNetwork() avec le descripteur de réseau Party précédent.

Switch et GDK

Sur Nintendo Switch et Microsoft GDK, vous devez nettoyer PlayFab Party et attendre la reprise de l’exécution du titre avant de réinitialiser PlayFab Party et de vous reconnecter à votre réseau. Pour arrêter Party, appelez Cleanup().

L’appel de Cleanup() récupère toutes les ressources de la bibliothèque et détruit tous les objets de la bibliothèque. Après la réinitialisation de Party, vous devez recréer tous les objets de la bibliothèque, comme les utilisateurs locaux et les contrôles de chat, et rétablir tout état réseau antérieur en réauthentifiant les utilisateurs locaux, en reconnectant les contrôles de chat et en recréant les points de terminaison.

Une fois le réseau réactivé, appelez Initialize(). Une fois Party correctement initialisé, les étapes suivantes sont nécessaires pour rejoindre de nouveau un réseau PlayFab Party précédent :

Connectez-vous au réseau Party avec le descripteur de réseau Party précédent.
Recréez tous les objets utilisateur local et réauthentifiez ces utilisateurs locaux dans le réseau.
Recréez tous les contrôles de chat locaux et reconnectez-les au réseau pour activer la VOIP
Recréez tous les points de terminaison de réseau Party pour le trafic des messages de jeu.

    PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
        &descriptor,                                // Network descriptor
        nullptr,                                    // Async identifier
        &m_network                                  // OUT network
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Authenticate the local user on the network so we can participate in it
    err = m_network->AuthenticateLocalUser(
        m_localUser,                                // Local user
        networkId,                                  // Invitation Id
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Connect the local user chat control to the network so we can use VOIP
    err = m_network->ConnectChatControl(
        m_localChatControl,                         // Local chat control
        nullptr                                     // Async identifier
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

    // Establish a network endoint for game message traffic
    err = m_network->CreateEndpoint(
        m_localUser,                                // Local user
        0,                                          // Property Count
        nullptr,                                    // Property name keys
        nullptr,                                    // Property Values
        nullptr,                                    // Async identifier
        &m_localEndpoint                            // OUT local endpoint
    );

    if (PARTY_FAILED(err))
    {
        DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
        errorCallback(err);
        return false;
    }

Si la reconnexion aboutit, la Party peut de nouveau communiquer avec les autres pairs ; en revanche, si le réseau précédent n’existe plus, la reconnexion échoue. Dans ce cas, vous devez gérer l’erreur de connexion appropriée.

Étapes suivantes

Découvrez-en plus sur les objets PlayFab Party et leurs relations et consultez la documentation de référence de l’API Party afin que votre jeu puisse tirer le meilleur parti de ces capacités. Pour des conseils plus spécifiques à XBOX, consultez tôt et souvent les exigences XBOX.

Voir aussi

Fonctionnalités de Party
SDK Party
Exemples Party
Services multijoueurs
Objets Party et leurs relations
Principes de base du chat Party
Invitations Party et modèle de sécurité
Interaction de Party avec vos flux de découverte
Documentation de référence de l’API Party
Recommandations d’expérience utilisateur Party pour la synthèse vocale et la conversion de la parole en texte

​Prérequis

​Prérequis de la plateforme

​Télécharger et configurer le SDK Party

​Se connecter à votre titre PlayFab et obtenir un jeton d’entité et un ID d’entité

​Initialiser PlayFab Party

​Créer un réseau Party

​Partager le descripteur de réseau Party

​Partager manuellement le descripteur de réseau Party

​Utiliser PlayFab Lobby pour partager le descripteur de réseau Party

​Activer les réseaux évolutifs

​Se connecter à un réseau Party

​Envoyer un message à un autre appareil ou point de terminaison du réseau

​Recevoir un message et le restituer sur l’appareil local

​Gestion de la suspension du titre

​iOS

​Switch et GDK

​Étapes suivantes

​Voir aussi

Prérequis

Prérequis de la plateforme

Télécharger et configurer le SDK Party

Se connecter à votre titre PlayFab et obtenir un jeton d’entité et un ID d’entité

Initialiser PlayFab Party

Créer un réseau Party

Partager le descripteur de réseau Party

Partager manuellement le descripteur de réseau Party

Utiliser PlayFab Lobby pour partager le descripteur de réseau Party

Activer les réseaux évolutifs

Se connecter à un réseau Party

Envoyer un message à un autre appareil ou point de terminaison du réseau

Recevoir un message et le restituer sur l’appareil local

Gestion de la suspension du titre

iOS

Switch et GDK

Étapes suivantes

Voir aussi