启用使用多人游戏管理器与好友一起玩多人游戏

在简单的多人游戏场景中，游戏的玩家可以与朋友在线玩游戏。 本主题介绍使用多人游戏管理器实现支持此场景所需的基本步骤。

发送和接受邀请的步骤

以下步骤使用多人游戏管理器向用户的好友发送邀请，以便好友可以加入正在进行的游戏。

1. 初始化多人游戏管理器
2. 通过添加本地用户创建大厅会话
3. 向好友发送邀请
4. 接受邀请
5. 加入来自大厅的游戏会话

在执行邀请的设备上完成步骤 1、2、3 和 5。 在通过协议激活启动应用后，通常会在被邀请者的设备上启动步骤 4。

有关详细信息，请参阅与好友一起玩游戏（流程图）。

初始化多人游戏管理器

当使用有效的会话模板名称初始化多人游戏管理器时，将自动创建大厅会话对象。 会话模板在服务配置中定义。

注意

在添加用户之前，不会创建服务上的大厅会话实例。

平面 C API

HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);

有关详细信息，请参阅XblMultiplayerManagerInitialize。

返回到本主题顶部。

通过添加本地用户创建大厅会话

将本地登录 Xbox 服务的用户添加到大厅会话。 添加第一个用户时，将托管新的大厅。 所有其他用户将作为辅助用户添加到现有大厅。

多人游戏管理器在 shell 中播发大厅，以便好友加入。 只有在添加本地用户后，才能通过 lobby() 发送邀请、设置大厅属性和访问大厅成员。

当本地用户加入大厅时，建议设置其连接地址和任何自定义属性。

您必须为本地登录的所有用户重复此过程。

返回到本主题顶部。

添加单个本地用户

平面 C API

HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set custom member properties.
const char* propName = "Name";
const char* propValueJson = "{}";
hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);

if (!SUCCEEDED(hr))
{
    // Handle failure.
}
...

有关详细信息，请参阅以下内容：

• XblMultiplayerManagerLobbySessionAddLocalUser
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress
• XblMultiplayerManagerLobbySessionSetProperties

返回到本主题顶部。

添加多个本地用户

平面 C API

std::vector<XblUserHandle> xblUsers;
for (XblUserHandle xblUserHandle : xblUsers)
{
    HRESULT hr = XblMultiplayerManagerLobbySessionAddLocalUser(xblUserHandle);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set member connection address.
    const char* connectionAddress = "1.1.1.1";
    hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
        xblUserHandle, connectionAddress, context);

    if (!SUCCEEDED(hr))
    {
        // Handle failure.
    }

    // Set custom member properties.
    const char* propName = "Name";
    const char* propValueJson = "{}";
    hr = XblMultiplayerManagerLobbySessionSetProperties(propName, propValueJson, context);
    ...
}

有关详细信息，请参阅以下内容：

• XblMultiplayerManagerLobbySessionAddLocalUser
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress
• XblMultiplayerManagerLobbySessionSetProperties

在下一个 XblMultiplayerManagerDoWork 调用上对更改进行批处理。 每次向大厅会话添加用户时，多人游戏管理器都会触发 XblMultiplayerEventType::UserAdded 事件。

建议检查事件的错误代码，以查看是否已成功添加该用户。 如果失败，错误消息将提供失败原因的详细信息。

多人游戏管理器通过添加本地用户执行以下函数来创建大厅会话。

• 通过 Xbox 服务多人游戏服务注册实时活动和多人游戏订阅。
• 创建大厅会话。
• 以活动身份加入所有本地玩家。
• 上传安全设备地址 (SDA)。
• 设置成员属性。
• 注册会话更改事件。
• 将大厅会话设置为活动会话。

返回到本主题顶部。

向好友发送邀请

显示标准 Xbox UI，玩家可在其中选择好友或最近玩家邀请加入游戏。 当玩家确认其选择时，多人游戏管理器会将邀请发送给所选玩家。

游戏还可以使用 XblMultiplayerManagerLobbySessionInviteUsers 方法向一组由其 Xbox 服务用户 ID 定义的玩家发送邀请。 如果使用自己的游戏内 UI 而不是标准 Xbox UI，则此方法非常有用。

平面 C API

size_t xuidsCount = 1;
uint64_t xuids[1] = {};
xuids[0] = 1234567891234567;
HRESULT hr = XblMultiplayerManagerLobbySessionInviteUsers(
    xblUserHandle, 
    xuids, 
    xuidsCount, 
    nullptr,    // ContextStringId 
    nullptr     // CustomActivationContext
);

有关详细信息，请参阅XblMultiplayerManagerLobbySessionInviteUsers。

多人游戏管理器执行以下功能，向好友发送邀请。

• 显示 Xbox 标准游戏可调用 UI （TCUI）
• 直接向所选玩家发送邀请

返回到本主题顶部。

接受邀请

当受邀玩家通过 shell UI 接受游戏邀请或加入好友游戏时，该游戏将在其设备上启动。

在基于 Microsoft Game Development Kit (GDK) 的游戏中，游戏开始后，通过调用 XGameInviteRegisterForEvent 来侦听邀请事件。

在基于 Xbox One 软件开发工具包和基于通用 Windows 平台 (UWP) 的游戏中，游戏开始后，多人游戏管理器可以使用协议激活的事件参数加入大厅。

如果未通过 XblMultiplayerManagerLobbySessionAddLocalUser 添加邀请的用户，则 XblMultiplayerManagerJoinLobby 将失败，并提供通过使用 JoinLobbyCompleted 事件调用 XblMultiplayerEventArgsXuid 发送邀请的 xuid。

加入大厅后，建议设置本地成员的连接地址，以及该成员的所有自定义属性。 如果不存在，也可以通过 XblMultiplayerManagerLobbySessionSetSynchronizedHost 设置主机。

最后，如果游戏已在进行并且还可以容纳被邀请者，则多人游戏管理器会自动将用户加入游戏会话。 通过 JoinGameCompleted 事件通知游戏，并提供适当的错误代码和消息。

错误或成功结果通过 JoinLobbyCompletedevent 进行处理。

平面 C API

void CALLBACK MyXGameInviteEventCallback(
    _In_opt_ void* context,
    _In_ const char* inviteUri)
{
    UNREFERENCED_PARAMETER(context);
    if (inviteUri != nullptr)
    {
        std::string inviteString(inviteUri);
        auto pos = inviteString.find("handle=");
        auto inviteHandleId = inviteString.substr(pos + 7, 36);

        // Now use inviteHandleId when calling XblMultiplayerManagerJoinLobby().  
        // See the example call as follows.
    }
}

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

HRESULT hr = XblMultiplayerManagerJoinLobby(inviteHandleId, xblUserHandle);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

// Set member connection address.
const char* connectionAddress = "1.1.1.1";
hr = XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress(
    xblUserHandle, connectionAddress, context);

有关详细信息，请参阅以下内容：

• XblMultiplayerManagerJoinLobby
• XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress

多人游戏管理器执行以下函数以接受邀请。

• 注册实时活动和多人游戏订阅。
• 加入大厅会话。
• 现有大厅状态清理。
• 加入处于活动状态的所有本地玩家。
• 上传 SDA。
• 设置成员属性。
• 注册会话更改事件。
• 将大厅会话设置为活动会话。
• 加入游戏会话（如果存在）。
• 使用传输句柄。

返回到本主题顶部。

加入来自大厅的游戏会话

接受邀请后，主机准备开始玩游戏，你可以通过调用 XblMultiplayerManagerJoinGameFromLobby 来开始一个新游戏，其中包括大厅会话的成员。

错误或成功结果通过 JoinGameCompletedevent 进行处理。

平面 C API

HRESULT hr = XblMultiplayerManagerJoinGameFromLobby(gameSessionTemplateName);
if (!SUCCEEDED(hr))
{
    // Handle error.
}

有关详细信息，请参阅 XblMultiplayerManagerJoinGameFromLobby。

多人游戏管理器执行以下功能以从大厅加入游戏会话。

• 创建游戏会话。
• 加入处于活动状态的所有本地玩家。
• 上传 SDA。
• 设置成员属性。
• 注册会话更改事件。
• 通过大厅会话播发游戏。

返回到本主题顶部。