使用多人游戏管理器使用 SmartMatch 查找多人游戏

本主题介绍使用多人游戏管理器实现 SmartMatch 匹配所需的基本步骤。

玩家在想要玩游戏时可能没有足够的在线好友，或者他们只想在线与随机玩家一起玩游戏。 可以使用 SmartMatch 服务查找其他 Xbox 玩家。

查找匹配

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

1. 初始化多人游戏管理器
2. 通过添加本地用户创建大厅会话
3. 向好友发送邀请（可选）
4. 接受邀请（可选）
5. 查找匹配

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

有关详细信息，请参阅使用 SmartMatch 匹配玩游戏（流程图）。

初始化多人游戏管理器

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

注意

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

平面 C API

HRESULT hr = XblMultiplayerManagerInitialize(lobbySessionTemplateName, queueUsedByMultiplayerManager);

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

返回到本主题顶部。

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

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

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

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

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

添加单个本地用户

平面 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 加入好友的游戏时，游戏将使用协议激活在其设备上启动。 游戏开始后，多人游戏管理器可以使用协议激活的事件参数加入大厅。

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

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

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

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

平面 C API

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。
• 设置成员属性。
• 注册会话更改事件。
• 将大厅会话设置为活动会话。
• 加入游戏会话（如果存在）。
• 使用传输句柄。

查找匹配项

接受邀请并且主机已准备好开始玩游戏后，可以使用 SmartMatch 执行下列操作之一：

• 通过调用 XblMultiplayerManagerFindMatch，查找具有足够开放玩家槽位的现有游戏，以供大厅会话中的所有成员使用。
• 创建包含大厅会话中所有成员的新游戏会话，并通过调用 XblMultiplayerManagerJoinGameFromLobby， 后跟 XblMultiplayerManagerAutoFillMembersDuringMatchmaking来填充其他玩家的空位。

在调用 XblMultiplayerManagerFindMatch 之前，必须先在服务配置中配置漏斗。 漏斗定义 SmartMatch 用于匹配玩家的规则。

平面 C API

uint32_t timeoutInSeconds = 30;
HRESULT hr = XblMultiplayerManagerFindMatch(hopperName, attributesJson, timeoutInSeconds);
if (!SUCCEEDED(hr))
{
    // Handle failure.
}

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

多人游戏管理器执行以下函数来查找匹配项。

• 创建匹配票证。
• 处理所有服务质量 （QoS） 阶段。
• 处理名单更改。
• 重新提交（如果需要）。
• 加入目标游戏会话。
• 通过大厅会话播发游戏。

返回到本主题顶部。