Tâches multijoueurs

• S’abonner aux notifications de modification de session Multiplayer Session Directory (MPSD)
• Créer une session MPSD
• Définir un arbitre pour une session MPSD
• Gérer l’activation du titre
• Rendre l’utilisateur joignable
• Envoyer des invitations de jeu
• Rejoindre une session de jeu à partir d’une session de lobby
• Rejoindre une session MPSD à partir d’une activation de titre
• Définir l’activité actuelle de l’utilisateur
• Mettre à jour une session MPSD
• Quitter une session MPSD
• Remplir les emplacements de session libres pendant le matchmaking
• Créer un ticket de match
• Obtenir l’état d’un ticket de match

​

S’abonner aux notifications de modification de session Multiplayer Session Directory (MPSD)

1. Utilisez le même objet XblContextHandle pour tous les appels d’un même utilisateur. Les abonnements sont liés à la durée de vie de cet objet. S’il y a plusieurs utilisateurs locaux, utilisez un objet XblContextHandle distinct pour chaque utilisateur.
2. Implémentez des gestionnaires d’événements pour XblMultiplayerAddSessionChangedHandler et XblMultiplayerSessionSubscriptionLostHandler.
3. Si vous vous abonnez aux modifications pour plusieurs utilisateurs, ajoutez du code à votre gestionnaire d’événements XblMultiplayerAddSessionChangedHandler pour éviter un travail inutile. Utilisez la propriété XblMultiplayerSessionChangeEventArgs::Branch et la propriété XblMultiplayerSessionChangeEventArgs::ChangeNumber. Ces propriétés vous permettent de suivre la dernière modification vue et d’ignorer les modifications plus anciennes.
4. Appelez XblMultiplayerSetSubscriptionsEnabled pour autoriser les abonnements.
5. Créez un objet de session local, puis rejoignez cette session en tant que membre actif.
6. Appelez XblMultiplayerAddSessionChangedHandler pour chaque utilisateur, en transmettant le type de modification de session pour lequel vous souhaitez être notifié.
7. Écrivez la session dans MPSD comme décrit dans la section Mettre à jour une session MPSD de cette rubrique.

​

Analyse des notifications de modification de session en double

• Stocker la dernière valeur de la propriété ChangeNumber pour chaque valeur de la propriété Branch évaluée.
• Si un shoulder tap a une valeur de propriété ChangeNumber supérieure à la dernière valeur stockée pour cette valeur de propriété Branch, traiter le shoulder tap, puis mettre à jour la dernière valeur de la propriété ChangeNumber.
• Si un shoulder tap n’a pas de valeur de propriété ChangeNumber supérieure pour cette valeur de propriété Branch, ignorer le traitement du shoulder tap. Cette modification de session a déjà été traitée.

​

Créer une session MPSD

1. Créez un nouvel objet XblContextHandle. Votre titre crée cet objet une seule fois, l’stocke et le réutilise selon les besoins dans tout le code source. Il est nécessaire d’utiliser exactement le même contexte, en particulier lorsque vous travaillez avec des abonnements de session.
2. Créez un nouveau XblMultiplayerSessionHandle avec XblMultiplayerSessionCreateHandle pour préparer toutes les données de session dont MPSD a besoin pour créer une nouvelle session.
3. Apportez les modifications requises avant d’écrire la session dans MPSD. Par exemple, lors de la jonction d’un membre à la session avec un appel à XblMultiplayerSessionJoin, le client ajoute des données de requête locales masquées qui indiquent à MPSD d’effectuer la jonction lors de l’appel de mise à jour de la session.
4. Lorsque vous avez terminé d’apporter des modifications locales, écrivez-les dans MPSD comme décrit dans la section Mettre à jour une session MPSD de cette rubrique.
5. Recevez de MPSD le nouvel objet XblMultiplayerSessionHandle, dont de nombreux champs sont renseignés.
6. Utilisez maintenant le nouvel objet de session. Supprimez l’ancienne copie, qui contient une requête masquée de création d’une nouvelle session.

​

Exemple

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.

    XblMultiplayerSessionHandle sessionHandle;
    HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
    if (SUCCEEDED(hr))
    {
        // Process multiplayer session handle.
    }
    else
    {
        // Handle failure.
    }
};

XblMultiplayerSessionReference ref;
pal::strcpy(ref.Scid, sizeof(ref.Scid), SCID);
pal::strcpy(ref.SessionTemplateName, sizeof(ref.SessionTemplateName), SESSION_TEMPLATE_NAME);
pal::strcpy(ref.SessionName, sizeof(ref.SessionName), SESSION_NAME);

XblMultiplayerSessionInitArgs args = {};

XblMultiplayerSessionHandle sessionHandle = XblMultiplayerSessionCreateHandle(XUID, &ref, &args);

auto hr = XblMultiplayerSessionJoin(
    sessionHandle,
    memberCustomConstantsJson.c_str(),
    initializeRequested,
    joinWithActiveStatus);
    
 hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::CreateNew, asyncBlock.get());
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

• XAsyncBlock
• XblMultiplayerSessionCreateHandle
• XblMultiplayerSessionInitArgs
• XblMultiplayerSessionReference
• XblMultiplayerSessionWriteMode
• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionResult

​

Définir un arbitre pour une session MPSD

1. Récupérez auprès de MPSD les jetons d’appareil des candidats hôtes en appelant XblMultiplayerSessionMembers.

   [!NOTE] Si la session a été créée par le matchmaking SmartMatch, vos clients peuvent utiliser les candidats hôtes disponibles auprès de MPSD en appelant XblMultiplayerSessionHostCandidates.

2. Sélectionnez l’hôte souhaité dans la liste des candidats hôtes.
3. Appelez XblMultiplayerSessionSetHostDeviceToken pour définir le jeton d’appareil dans le cache local de MPSD. Si l’appel de définition du jeton d’appareil hôte réussit, le jeton d’appareil local remplace le jeton de l’hôte.
4. Si un code d’état HTTP/412 est reçu lors de la tentative de définition du jeton d’appareil hôte, interrogez les données de session. Vérifiez si le jeton d’appareil hôte correspond à la console locale. Si ce n’est pas le cas, une autre console a été désignée comme arbitre.

   [!NOTE] Votre client doit gérer le code d’état HTTP/412 séparément des autres codes HTTP, car HTTP/412 n’indique pas un échec standard. Pour plus d’informations sur ce code d’état, consultez Codes d’état des sessions multijoueurs.

5. Mettez à jour la session dans MPSD comme décrit dans la section Mettre à jour une session MPSD de cette rubrique.

   [!NOTE] Si vous ne disposez pas d’un meilleur algorithme, le client peut implémenter un algorithme glouton dans lequel chaque candidat hôte tente de se définir comme hôte si personne d’autre ne l’a encore fait. Pour plus d’informations, consultez la section Arbitre de session de la rubrique Rubriques avancées sur les sessions multijoueurs.

​

Gérer l’activation du titre

1. Configurez un gestionnaire d’événements pour l’événement CoreApplicationView.Activated. Ce gestionnaire se déclenche à chaque activation par protocole, même si le titre est déjà en cours d’exécution.
2. Lors de l’activation du titre, démarrez une session et abonnez-vous aux notifications de modification de session. Pour plus d’informations, consultez S’abonner aux notifications de modification de session MPSD dans cette rubrique.
3. Faites rejoindre la session à l’utilisateur en tant que membre actif. Pour plus d’informations, consultez Rejoindre une session MPSD à partir d’une activation de titre dans cette rubrique.
4. Définissez la session de lobby comme session d’activité exposée au moyen de l’interface utilisateur du profil. Pour plus d’informations, consultez Définir l’activité actuelle de l’utilisateur dans cette rubrique.
5. Faites rejoindre la session de jeu à l’utilisateur en tant que membre actif. L’utilisateur peut maintenant se connecter aux pairs et entrer dans le jeu ou dans le lobby.

​

Rendre l’utilisateur joignable

1. Créez un objet de session, puis modifiez les attributs selon les besoins.
2. Faites rejoindre la session à l’utilisateur en tant que membre actif. Pour plus d’informations, consultez Rejoindre une session MPSD à partir d’une activation de titre dans cette rubrique.
3. Déterminez si l’utilisateur a été désigné comme arbitre de la session.
4. Si l’utilisateur n’est pas l’arbitre, passez à l’étape 7.
5. Si l’utilisateur est l’arbitre, appelez XblMultiplayerSessionSetHostDeviceToken.
6. Tentez d’écrire la session en appelant XblMultiplayerWriteSessionAsync.
7. Définissez la session comme session active. Pour plus d’informations, consultez Définir l’activité actuelle de l’utilisateur dans cette rubrique.

​

Envoyer des invitations de jeu

• Envoyer les invitations pour la session de lobby.
• Envoyer les invitations à l’aide de l’interface utilisateur d’invitation générique de la plateforme XBOX, avec la référence de la session de jeu.

1. Rendre la partie du joueur qui invite joignable. Pour plus d’informations, consultez Rendre l’utilisateur joignable dans cette rubrique.
2. Déterminer si les invitations doivent être envoyées au moyen de la session de lobby ou à l’aide de l’interface utilisateur d’invitation.
3. Si la session de lobby est utilisée, envoyer les invitations en appelant XblMultiplayerSendInvitesAsync. Cette méthode peut nécessiter la création d’une liste de joueurs dans l’interface du jeu en appelant XGameUiShowPlayerPickerAsync.
4. Si l’interface utilisateur d’invitation est utilisée, appeler XGameUiShowSendGameInviteAsync pour afficher l’interface utilisateur d’invitation.
5. Gérer XblMultiplayerAddSessionChangedHandler pour le joueur local une fois que le joueur distant a rejoint la session.
6. Pour le joueur distant, implémenter un code d’activation de titre. Pour plus d’informations, consultez Gérer l’activation du titre dans cette rubrique.

​

Rejoindre une session de jeu à partir d’une session de lobby

1. Lorsque vous créez la session de jeu, utilisez l’API XblMultiplayerSetTransferHandleAsync pour créer un handle de transfert qui lie la session de lobby et la session de jeu.
2. Stockez le GUID du handle de transfert dans la session de lobby au lieu de la référence de la session de jeu.
3. Lorsque le titre souhaite déplacer des membres de la session de lobby vers la session de jeu, chaque client utilise le handle de transfert de la session de lobby pour rejoindre la session de jeu à l’aide de l’API XblMultiplayerWriteSessionByHandleAsync.
4. MPSD consulte la session de lobby pour vérifier que les membres qui tentent de rejoindre la session de jeu à l’aide du handle de transfert se trouvent également dans la session de lobby.
5. Si les membres se trouvent dans la session de lobby, ils peuvent accéder à la session de jeu.

​

Rejoindre une session MPSD à partir d’une activation de titre

1. Implémentez un gestionnaire d’événements pour l’événement CoreApplicationView.Activated. Il signale les activations du titre.
2. Lorsque le gestionnaire se déclenche, examinez la propriété IActivatedEventArgs.Kind. Si elle est définie sur Protocol, effectuez un cast des arguments de l’événement vers la classe ProtocolActivatedEventArgs.
3. Examinez l’objet ProtocolActivatedEventArgs. Si l’URI indiqué dans la propriété ProtocolActivatedEventArgs.Uri correspond à inviteHandleAccept (invitation acceptée) ou à activityHandleJoin (jonction au moyen de l’interface utilisateur du shell), analysez la chaîne de requête de l’URI. Elle est mise en forme comme une chaîne de requête d’URI normale avec des paires clé/valeur; extrayez les champs suivants.
   • Pour une invitation acceptée :
     1. handle
     2. invitedXuid
     3. senderXuid
   • Pour une jonction :
     1. handle
     2. joinerXuid
     3. joineeXuid
4. Démarrez le code multijoueur du titre, qui doit inclure un appel à XblMultiplayerSetSubscriptionsEnabled.
5. Créez un objet XblMultiplayerSessionHandle local en appelant XblMultiplayerSessionCreateHandle.
6. Appelez XblMultiplayerSessionJoin pour rejoindre la session. Utilisez les paramètres suivants afin que la jonction soit définie comme active.
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. Appelez XblMultiplayerSessionSetSessionChangeSubscription pour recevoir un shoulder tap lorsque la session change après la jonction.
8. Appelez XblMultiplayerWriteSessionByHandleAsync en utilisant le handle obtenu comme décrit à l’étape 3. L’utilisateur est maintenant membre de la session et peut utiliser les données de la session pour se connecter au jeu.

​

Définir l’activité actuelle de l’utilisateur

​

Mettre à jour une session MPSD

1. Apportez les modifications requises à la session actuelle, par exemple en appelant XblMultiplayerSessionLeave.
2. Une fois toutes les modifications apportées, écrivez les modifications locales dans MPSD à l’aide de l’une de ces méthodes.
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   Définissez le mode d’écriture sur XblMultiplayerSessionWriteMode::SynchronizedUpdate si vous écrivez dans une partie partagée que d’autres titres peuvent également modifier. Pour plus d’informations, consultez la section Synchronisation des mises à jour de session de la rubrique Vue d’ensemble de Multiplayer Session Directory. La méthode d’écriture écrit la jonction sur le serveur et obtient la dernière session, à partir de laquelle découvrir les autres membres de la session et les adresses d’appareil sécurisées (SDA) de leurs consoles. Pour plus d’informations sur l’établissement d’une connexion réseau entre ces consoles, consultez Introduction to Winsock on XBOX One.
3. Supprimez l’ancien objet de session local. Utilisez l’objet de session nouvellement récupéré afin que les actions futures reposent sur le dernier état connu de la session.

​

Quitter une session MPSD

1. Appelez XblMultiplayerSessionLeave pour la session de jeu.
2. Mettez à jour la session de jeu dans MPSD comme décrit dans la section Mettre à jour une session MPSD de cette rubrique.
3. Si nécessaire, appelez la méthode XblMultiplayerSessionLeave pour la session de lobby, puis mettez à jour cette session.
4. Si nécessaire pour la session de lobby, arrêtez l’API multijoueur en vous désinscrivant à l’aide d’appels à XblMultiplayerRemoveSubscriptionLostHandler et à XblMultiplayerRemoveSessionChangedHandler.

​

Remplir les emplacements de session libres pendant le matchmaking

1. Accédez au dernier état de session de la session de ticket créée pendant le matchmaking.
2. Ajoutez les joueurs disponibles pour jouer à partir de la session de lobby.
3. Déterminez si la session de ticket est pleine.
4. Si la session est pleine, poursuivez la partie.
5. Si la session n’est pas encore pleine, créez le ticket de match comme décrit dans Créer un ticket de match dans cette rubrique. Assurez-vous de créer le ticket avec le paramètre preserveSession défini sur Always.
6. Poursuivez le matchmaking. Pour plus d’informations, consultez Vue d’ensemble du matchmaking.

​

Créer un ticket de match

1. Appelez XblMatchmakingCreateMatchTicketAsync en transmettant une référence à la session de ticket. La méthode lit la session de ticket dans MPSD et démarre le matchmaking pour les utilisateurs de la session. En interne, la méthode appelle POST (/serviceconfigs/{scid}/hoppers/{hoppername}).
2. Définissez le paramètre preserveSession sur Never si le service de matchmaking doit associer les membres de la session dans une nouvelle session ou dans une autre session existante. Définissez le paramètre preserveSession sur Always pour permettre au titre de réutiliser une session de jeu existante comme session de ticket afin de poursuivre la partie. Le service de matchmaking peut alors garantir que la session soumise est conservée et que les joueurs associés sont ajoutés à cette session.
3. Utilisez XblCreateMatchTicketResponse::EstimatedWaitTime, retourné dans l’objet CreateMatchTicketResponse, pour informer les utilisateurs de la durée attendue du matchmaking.
4. Utilisez XblCreateMatchTicketResponse::MatchTicketId, retourné dans l’objet de réponse, pour annuler le matchmaking de la session si nécessaire, en supprimant le ticket. La suppression du ticket utilise XblMatchmakingDeleteMatchTicketAsync.

​

Obtenir l’état d’un ticket de match

1. Obtenez l’objet XblMultiplayerSessionHandle de la session de ticket.
2. Appelez XblMultiplayerSessionMatchmakingServer pour accéder à l’objet XblMultiplayerMatchmakingServer utilisé lors du matchmaking.
3. Vérifiez l’objet XblMultiplayerMatchmakingServer pour déterminer l’état du processus de matchmaking, le temps d’attente habituel pour la session et la référence de la session cible, si un match a été trouvé.