Multiplayer Activity 示例代码

本主题旨在作为使用 Multiplayer Activity 客户端 API 基本用法的快速入门指南。本主题讨论管理活动、发送邀请以及将玩家添加到最近玩家列表。活动邀请最近玩家

活动

设置活动

每当游戏开始或加入多人游戏体验时，都应创建一个活动。这样做可以让 shell 以及您游戏中的其他玩家看到该玩家的活动，并允许其他玩家可能加入正在进行的游戏。如果玩家想要加入您游戏的活动而它没有运行，将启动它并将连接字符串传递给它。当玩家加入或离开时，游戏应更新活动。这为其他玩家提供了活动的更丰富视图，并告知他们活动是否已满。有关活动字段的信息，请参阅活动内容。设置活动的代码示例如下。它同样适用于创建活动以及更新现有活动。

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

有关更多信息，请参阅以下内容：

返回本主题顶部。

获取活动

游戏可能希望了解其他玩家的活动。例如，游戏可能希望显示游戏中好友及其活动的游戏内 UI。检索活动的代码示例如下。

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

有关更多信息，请参阅以下内容：

返回本主题顶部。

删除活动

当玩家结束或离开多人游戏活动时，游戏应使用以下代码删除该活动。

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

有关更多信息，请参阅以下内容：

返回本主题顶部。

邀请

无 UI 发送邀请

玩家可能希望直接向一位或多位其他玩家发送邀请。发送邀请之前，游戏应确保已设置活动。这确保了 shell 与您游戏之间的连续性，因为 shell 根据当前活动发送邀请。若要在无 UI 的情况下发送邀请，在使用 XblMultiplayerActivitySetActivityAsync 设置活动后（参见上面的示例），游戏应调用 XblMultiplayerActivitySendInvitesAsync API，传入要邀请的玩家数组以及在当前活动中使用的相同连接字符串。有关邀请内容的信息，请参阅发送请求以邀请其他玩家加入多人游戏体验。。无 UI 发送邀请的代码示例如下。

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

有关更多信息，请参阅以下内容：

使用 UI 发送邀请

玩家可能希望直接向一位或多位其他玩家发送邀请。发送邀请之前，游戏应确保已设置活动。这确保了 shell 与您游戏之间的连续性，因为 shell 根据当前活动发送邀请。若要使用 UI 发送邀请，在使用 XblMultiplayerActivitySetActivityAsync 设置活动后（参见上面的示例），游戏应调用 XGameUiShowMultiplayerActivityGameInviteAsync API，传入请求用户。它将使用游戏的当前活动，并使用其连接字符串和设置邀请玩家。有关邀请内容的信息，请参阅发送请求以邀请其他玩家加入多人游戏体验。。使用 UI 发送邀请的代码示例如下。

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

有关更多信息，请参阅以下内容：

返回本主题顶部。

接收邀请

若要在玩家接受邀请时得到通知，游戏可以使用 XGameInviteRegisterForEvent 注册邀请通知。每次接受邀请时，都会通过已注册的回调将格式化的 URI 传递给游戏。可以解析该 URI 以确定邀请发送者、接收者和连接字符串。连接字符串是游戏特定的，在创建多人游戏活动时设置。对于使用 Multiplayer Activity 服务的游戏，URI 的完整格式如下表所示。

平台	格式
主机上的 Microsoft Game Development Kit (GDK) 或 XBOX One Software Development Kit	`ms-xbl-<titleId>://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`
PC 上的 Microsoft Game Development Kit (GDK) 或 Universal Windows Platform (UWP)	`ms-xbl-multiplayer://inviteAccept?invitedUser=<xuid>&sender=<xuid>&connectionString=<connectionString>`

当不再需要邀请通知时，可以使用 XGameInviteUnregisterForEvent 取消注册回调。注册和处理已接受邀请的代码示例如下。

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

有关更多信息，请参阅以下内容：

返回本主题顶部。

XBOX Services

PlayFab

活动

设置活动

获取活动

删除活动

邀请

无 UI 发送邀请

使用 UI 发送邀请

接收邀请

最近玩家

更新最近玩家

刷新最近玩家

​活动

​设置活动

​获取活动

​删除活动

​邀请

​无 UI 发送邀请

​使用 UI 发送邀请

​接收邀请

​最近玩家

​更新最近玩家

​刷新最近玩家

活动

设置活动

获取活动

删除活动

邀请

无 UI 发送邀请

使用 UI 发送邀请

接收邀请

最近玩家

更新最近玩家

刷新最近玩家