Exemples de code pour Multiplayer Activity

Cette rubrique est conçue comme un guide de démarrage rapide pour l’utilisation de base des API clientes Multiplayer Activity. Elle traite de la gestion des activités, de l’envoi d’invitations et de l’ajout de joueurs à la liste des joueurs récents. Activités Invitations Joueurs récents

Activités

Définition d’une activité

Chaque fois qu’un titre démarre ou rejoint une expérience multijoueur, il doit créer une activité. Cela permet à l’interpréteur de commandes, ainsi qu’aux autres joueurs de votre titre, de voir l’activité du joueur, et permet éventuellement à d’autres joueurs de rejoindre la partie en cours. Si un joueur souhaite rejoindre une activité de votre titre alors que celui-ci n’est pas en cours d’exécution, le titre est activé et la chaîne de connexion lui est transmise. Les titres doivent mettre à jour l’activité à mesure que des joueurs la rejoignent ou la quittent. Cela offre aux autres joueurs une vue plus complète de l’activité et les informe si celle-ci est complète. Pour plus d’informations sur les champs d’activité, consultez Contenu des activités. Voici un exemple de code permettant de définir une activité. Il s’applique aussi bien à la création d’une activité qu’à la mise à jour d’une activité existante.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

XblMultiplayerActivityInfo info{};
info.connectionString = "dummyConnectionString";
info.joinRestriction = XblMultiplayerActivityJoinRestriction::Followed;
info.maxPlayers = 10;
info.currentPlayers = 1;
info.groupId = "dummyGroupId";

HRESULT hr = XblMultiplayerActivitySetActivityAsync(
    xblContext,
    &info,
    false,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Obtention d’activités

Les titres peuvent souhaiter connaître les activités d’autres joueurs. Par exemple, un titre peut souhaiter afficher dans le jeu une interface présentant les amis d’un joueur dans le titre ainsi que leurs activités. Voici un exemple de code permettant de récupérer une activité.

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

    size_t resultSize{};
    HRESULT hr = XblMultiplayerActivityGetActivityResultSize(async, &resultSize);
    if (SUCCEEDED(hr))
    {
        std::vector<uint8_t> buffer(resultSize);
        XblMultiplayerActivityInfo* activityInfo{};
        size_t resultCount{};
        hr = XblMultiplayerActivityGetActivityResult(async, buffer.size(), buffer.data(), &activityInfo, &resultCount, nullptr);
        if (SUCCEEDED(hr))
        {
            // ...
        }
    }
};

HRESULT hr = XblMultiplayerActivityGetActivityAsync(
    xblContext,
    &xuid,
    1,
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Suppression d’une activité

Lorsqu’un joueur met fin à une activité multijoueur ou la quitte, le titre doit supprimer l’activité à l’aide du code suivant.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityDeleteActivityAsync(xblContext, async.get());

if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Invitations

Envoi d’invitations sans interface utilisateur

Les joueurs peuvent souhaiter envoyer des invitations directement à un ou plusieurs autres joueurs. Avant d’envoyer une invitation, le titre doit s’assurer qu’une activité est définie. Cela garantit la continuité entre l’interpréteur de commandes et votre titre, car l’interpréteur de commandes envoie les invitations en fonction de l’activité actuelle. Pour envoyer une invitation sans interface utilisateur, une fois une activité définie à l’aide de XblMultiplayerActivitySetActivityAsync (voir l’exemple ci-dessus), le titre doit appeler l’API XblMultiplayerActivitySendInvitesAsync en lui transmettant un tableau de joueurs à inviter et la même chaîne de connexion que celle utilisée dans votre activité actuelle. Pour plus d’informations sur le contenu d’une invitation, consultez Envoyer à un autre joueur une demande pour rejoindre une expérience multijoueur. Voici un exemple de code permettant d’envoyer des invitations sans interface utilisateur.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivitySendInvitesAsync(
    xblContext,
    &xuid,
    1,
    true, // Setting false will send the invite to only players on the sender's platform.
    "dummyConnectionString",
    async.get()
);

if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Envoi d’invitations avec interface utilisateur

Les joueurs peuvent souhaiter envoyer des invitations directement à un ou plusieurs autres joueurs. Avant d’envoyer une invitation, le titre doit s’assurer qu’une activité est définie. Cela garantit la continuité entre l’interpréteur de commandes et votre titre, car l’interpréteur de commandes envoie les invitations en fonction de l’activité actuelle. Pour envoyer une invitation avec interface utilisateur, une fois une activité définie à l’aide de XblMultiplayerActivitySetActivityAsync (voir l’exemple ci-dessus), le titre doit appeler l’API XGameUiShowMultiplayerActivityGameInviteAsync en lui transmettant l’utilisateur demandeur. Elle utilise l’activité actuelle du titre et invite des joueurs à l’aide de sa chaîne de connexion et de ses paramètres. Pour plus d’informations sur le contenu d’une invitation, consultez Envoyer à un autre joueur une demande pour rejoindre une expérience multijoueur. Voici un exemple de code permettant d’envoyer des invitations avec interface utilisateur.

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XGameUiShowMultiplayerActivityGameInviteResult(async);
    if (hrAsync == S_OK) 
    { 
        // Handle success 
    } 
    else 
    { 
        // Likely will only happen during development - usually indicates 
        // an invalid user was passed in or that there is no multiplayer activity set
    }     
};

HRESULT hr = XGameUiShowMultiplayerActivityGameInviteAsync(
    async.get()
    requestingUser
);

if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Réception d’invitations

Pour être avertis lorsqu’un joueur a accepté une invitation, les titres peuvent s’inscrire aux notifications d’invitation à l’aide de XGameInviteRegisterForEvent. Chaque fois qu’une invitation est acceptée, un URI formaté est transmis au titre via le rappel inscrit. L’URI peut être analysé pour déterminer l’expéditeur, le destinataire et la chaîne de connexion de l’invitation. La chaîne de connexion est propre au titre et est définie lors de la création de l’activité multijoueur. Pour les titres qui utilisent le service Multiplayer Activity, le format complet de l’URI est indiqué dans le tableau suivant.

Plateforme	Format
Microsoft Game Development Kit (GDK) ou XBOX One Software Development Kit sur console	`ms-xbl-<titleId>://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`
Microsoft Game Development Kit (GDK) ou plateforme Windows universelle (UWP) sur PC	`ms-xbl-multiplayer://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`

Lorsque les notifications d’invitation ne sont plus nécessaires, le rappel peut être désinscrit à l’aide de XGameInviteUnregisterForEvent. Voici un exemple de code permettant d’inscrire et de gérer les invitations acceptées.

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const char* inviteUri)
{
    if (inviteUri != nullptr)
    {
        std::string uri{ inviteUri };
        size_t invitedUserBegin = uri.find("invitedUser=");
        size_t senderBegin = uri.find("sender=");
        std::string invitedUser = uri.substr(invitedUserBegin, uri.find('&', invitedUserBegin) - invitedUserBegin);
        std::string sender = uri.substr(senderBegin, uri.find('&', senderBegin) - senderBegin);
        std::string connectionString = uri.substr(uri.find("connectionString="));

        // ...
    }
}

XTaskQueueRegistrationToken token = { 0 };
HRESULT hr = XGameInviteRegisterForEvent(
    queue,
    nullptr,
    MyXGameInviteEventCallback,
    &token
    );

// ...
bool result = XGameInviteUnregisterForEvent(token, true);

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Joueurs récents

Pour mettre à jour la liste des joueurs récents du joueur, le titre doit soumettre des listes d’autres joueurs ayant eu une interaction significative avec le joueur actuel. La liste est unidirectionnelle : le client de chaque joueur est responsable de la mise à jour de sa propre liste, et les listes des joueurs n’ont aucune incidence les unes sur les autres. Par exemple, supposons qu’un groupe de joueurs se trouve dans un salon d’avant-partie et soit mis en relation. Chaque joueur met à jour sa liste avec tous les autres xuids du salon au début du match. Si un nouveau joueur rejoint la partie, il peut être ajouté individuellement.

Vous pouvez décider de ce qui constitue une interaction significative. Pour un titre, il peut s’agir de la présence dans un salon. Pour un autre, du fait qu’un joueur tire sur un autre joueur. Pour un troisième, du simple fait qu’un autre joueur soit visible à l’écran.

Dans les scénarios où vous ne souhaitez pas que les équipes de joueurs soient visibles avant le début d’une session de match, vous pouvez différer l’écriture de la liste des joueurs jusqu’au moment où vous souhaitez qu’ils soient visibles les uns pour les autres. Pour vider la liste des joueurs récents côté client, vous pouvez appeler XblMultiplayerActivityFlushRecentPlayersAsync si vous avez besoin d’un vidage forcé immédiat. Sinon, la liste des joueurs récents est vidée automatiquement toutes les cinq secondes. Voici des exemples de code permettant de mettre à jour la liste des joueurs récents et de vider les mises à jour.

Mise à jour des joueurs récents

XblMultiplayerActivityRecentPlayerUpdate update{ xuid };
HRESULT hr = XblMultiplayerActivityUpdateRecentPlayers(xblContext, &update, 1);

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

Vidage des joueurs récents

auto async = std::make_unique<XAsyncBlock>();
async->queue = queue;
async->callback = [](XAsyncBlock* async)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // Take ownership of XAsyncBlock.
    HRESULT hr = XAsyncGetStatus(async, false);
};

HRESULT hr = XblMultiplayerActivityFlushRecentPlayersAsync(xblContext, async.get());
if (SUCCEEDED(hr))
{
    async.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Revenir au début de cette rubrique.

XBOX Services

PlayFab

Activités

Définition d’une activité

Obtention d’activités

Suppression d’une activité

Invitations

Envoi d’invitations sans interface utilisateur

Envoi d’invitations avec interface utilisateur

Réception d’invitations

Joueurs récents

Mise à jour des joueurs récents

Vidage des joueurs récents

​Activités

​Définition d’une activité

​Obtention d’activités

​Suppression d’une activité

​Invitations

​Envoi d’invitations sans interface utilisateur

​Envoi d’invitations avec interface utilisateur

​Réception d’invitations

​Joueurs récents

​Mise à jour des joueurs récents

​Vidage des joueurs récents

Activités

Définition d’une activité

Obtention d’activités

Suppression d’une activité

Invitations

Envoi d’invitations sans interface utilisateur

Envoi d’invitations avec interface utilisateur

Réception d’invitations

Joueurs récents

Mise à jour des joueurs récents

Vidage des joueurs récents