多人游戏任务

• 订阅多人游戏会话目录 (MPSD) 会话更改通知
• 创建 MPSD 会话
• 为 MPSD 会话设置仲裁者
• 管理标题激活
• 使用户可加入
• 发送游戏邀请
• 从大厅会话加入游戏会话
• 从标题激活加入 MPSD 会话
• 设置用户的当前活动
• 更新 MPSD 会话
• 离开 MPSD 会话
• 在匹配期间填补空闲会话位置
• 创建匹配票证
• 获取匹配票证状态

​

订阅多人游戏会话目录 (MPSD) 会话更改通知

1. 对同一用户的所有调用使用相同的 XblContextHandle 对象。订阅与此对象的生存期绑定。如果有多个本地用户,请为每个用户使用单独的 XblContextHandle 对象。
2. 为 XblMultiplayerAddSessionChangedHandler 和 XblMultiplayerSessionSubscriptionLostHandler 实现事件处理程序。
3. 如果要订阅多个用户的更改,请向您的 XblMultiplayerAddSessionChangedHandler 事件处理程序添加代码以避免不必要的工作。使用 XblMultiplayerSessionChangeEventArgs::Branch 属性和 XblMultiplayerSessionChangeEventArgs::ChangeNumber 属性。使用这些属性可以跟踪看到的最后一次更改并忽略较旧的更改。
4. 调用 XblMultiplayerSetSubscriptionsEnabled 以允许订阅。
5. 创建本地会话对象,然后作为活动加入该会话。
6. 为每个用户调用 XblMultiplayerAddSessionChangedHandler,传入要通知的会话更改类型。
7. 按照本主题中的更新 MPSD 会话部分所述,将会话写入 MPSD。

​

解析重复的会话更改通知

• 为每个评估的 Branch 属性值存储最新的 ChangeNumber 属性值。
• 如果提醒通知的 ChangeNumber 属性值高于该 Branch 属性值的最新存储值,则处理该提醒通知,然后更新最新的 ChangeNumber 属性值。
• 如果提醒通知的 ChangeNumber 属性值对于该 Branch 属性值不更高,则跳过处理该提醒通知。该会话更改已被处理。

​

创建 MPSD 会话

1. 创建一个新的 XblContextHandle 对象。您的标题创建一次此对象,存储它,并根据源代码中的需要重用它。必须使用完全相同的上下文,尤其是在处理会话订阅时。
2. 使用 XblMultiplayerSessionCreateHandle 创建一个新的 XblMultiplayerSessionHandle,以准备 MPSD 创建新会话所需的所有会话数据。
3. 在将会话写入 MPSD 之前进行必要的更改。例如,当通过调用 XblMultiplayerSessionJoin 将成员加入会话时,客户端会添加隐藏的本地请求数据,告知 MPSD 在调用更新会话时加入。
4. 完成本地更改后,按照本主题中的更新 MPSD 会话部分所述将它们写入 MPSD。
5. 从 MPSD 接收新的 XblMultiplayerSessionHandle 对象,其中填充了许多字段。
6. 之后使用新的会话对象。丢弃包含创建新会话的隐藏请求的旧副本。

​

示例

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

​

为 MPSD 会话设置仲裁者

1. 通过调用 XblMultiplayerSessionMembers 从 MPSD 检索主机候选者的设备令牌。

   [!NOTE] 如果会话是由 SmartMatch 匹配创建的,您的客户端可以通过调用 XblMultiplayerSessionHostCandidates 使用来自 MPSD 的可用主机候选者。

2. 从主机候选者列表中选择所需的主机。
3. 调用 XblMultiplayerSessionSetHostDeviceToken 在 MPSD 的本地缓存中设置设备令牌。如果设置主机设备令牌的调用成功,则本地设备令牌将替换主机的令牌。
4. 如果在尝试设置主机设备令牌时收到 HTTP/412 状态代码,请查询会话数据。查看主机设备令牌是否用于本地主机。如果不是本地主机,则表示另一台主机已被指定为仲裁者。

   [!NOTE] 您的客户端应将 HTTP/412 状态代码与其他 HTTP 代码分开处理,因为 HTTP/412 不表示标准失败。有关此状态代码的详细信息,请参阅多人游戏会话状态代码。

5. 按照本主题中的更新 MPSD 会话部分所述更新 MPSD 中的会话。

   [!NOTE] 如果您没有更好的算法,则客户端可以实现贪婪算法,其中每个主机候选者尝试将自己设置为主机(如果尚未有人这样做)。有关详细信息,请参阅“多人游戏会话高级主题”主题中的会话仲裁者部分。

​

管理标题激活

1. 为 CoreApplicationView.Activated 事件设置事件处理程序。每当发生协议激活时,此处理程序都会触发,即使标题已经在运行也是如此。
2. 在标题激活时,启动会话并订阅会话更改通知。有关详细信息,请参阅本主题中的订阅 MPSD 会话更改通知。
3. 将用户作为活动加入会话。有关详细信息,请参阅本主题中的从标题激活加入 MPSD 会话。
4. 将大厅会话设置为通过个人资料 UI 公开的活动会话。有关详细信息,请参阅本主题中的设置用户的当前活动。
5. 将用户作为活动加入游戏会话。用户现在可以连接到对等方并进入游戏或大厅。

​

使用户可加入

1. 创建会话对象,然后根据需要修改属性。
2. 将用户作为活动加入会话。有关详细信息,请参阅本主题中的从标题激活加入 MPSD 会话。
3. 确定用户是否已被指定为会话仲裁者。
4. 如果用户不是仲裁者,则转到步骤 7。
5. 如果用户是仲裁者,则调用 XblMultiplayerSessionSetHostDeviceToken。
6. 尝试通过调用 XblMultiplayerWriteSessionAsync 写入会话。
7. 将会话设置为活动会话。有关详细信息,请参阅本主题中的设置用户的当前活动。

​

发送游戏邀请

• 为大厅会话发送邀请。
• 使用带游戏会话引用的通用 XBOX 平台邀请 UI 发送邀请。

1. 使邀请游戏玩家可加入。有关详细信息,请参阅本主题中的使用户可加入。
2. 确定邀请是通过大厅会话发送还是使用邀请 UI 发送。
3. 如果使用大厅会话,则通过调用 XblMultiplayerSendInvitesAsync 发送邀请。此方法可能需要通过调用 XGameUiShowPlayerPickerAsync 来构建游戏内 UI 名单。
4. 如果使用邀请 UI,则调用 XGameUiShowSendGameInviteAsync 显示邀请 UI。
5. 在远程玩家加入后为本地玩家处理 XblMultiplayerAddSessionChangedHandler。
6. 对于远程玩家,实现标题激活代码。有关详细信息,请参阅本主题中的管理标题激活。

​

从大厅会话加入游戏会话

1. 创建游戏会话时,使用 XblMultiplayerSetTransferHandleAsync API 创建将大厅会话和游戏会话链接起来的转移句柄。
2. 将转移句柄 GUID 存储在大厅会话中,而不是游戏会话的会话引用中。
3. 当标题想要将成员从大厅会话移动到游戏会话时,每个客户端使用大厅会话中的转移句柄通过 XblMultiplayerWriteSessionByHandleAsync API 加入游戏会话。
4. MPSD 查找大厅会话以验证尝试使用转移句柄加入游戏会话的成员是否也在大厅会话中。
5. 如果成员在大厅会话中,则他们可以访问游戏会话。

​

从标题激活加入 MPSD 会话

1. 为 CoreApplicationView.Activated 事件实现事件处理程序。它通知标题的激活。
2. 当处理程序触发时,检查 IActivatedEventArgs.Kind 属性。如果设置为 Protocol,则将事件参数强制转换为 ProtocolActivatedEventArgs 类。
3. 检查 ProtocolActivatedEventArgs 对象。如果 ProtocolActivatedEventArgs.Uri 属性中指示的 URI 与 inviteHandleAccept(对应于已接受的邀请)或 activityHandleJoin(对应于通过 shell UI 加入)匹配,则解析 URI 的查询字符串。它的格式为带有键/值对的正常 URI 查询字符串,提取以下字段。
   • 对于已接受的邀请:
     1. handle
     2. invitedXuid
     3. senderXuid
   • 对于加入:
     1. handle
     2. joinerXuid
     3. joineeXuid
4. 启动标题的多人游戏代码,应该包括调用 XblMultiplayerSetSubscriptionsEnabled。
5. 通过调用 XblMultiplayerSessionCreateHandle 创建本地 XblMultiplayerSessionHandle 对象。
6. 调用 XblMultiplayerSessionJoin 加入会话。使用以下参数设置,以便将加入设置为活动。
   • memberCustomConstantsJson = null
   • initializeRequested = false
   • joinWithActiveStatus = true
7. 调用 XblMultiplayerSessionSetSessionChangeSubscription 以在加入后会话更改时收到提醒通知。
8. 使用步骤 3 中所述获取的句柄调用 XblMultiplayerWriteSessionByHandleAsync。用户现在是会话的成员,可以使用会话中的数据连接到游戏。

​

设置用户的当前活动

​

更新 MPSD 会话

1. 根据需要对当前会话进行更改,例如,通过调用 XblMultiplayerSessionLeave。
2. 完成所有更改后,使用以下任一方法将本地更改写入 MPSD。
   • XblMultiplayerWriteSessionAsync
   • XblMultiplayerWriteSessionByHandleAsync
   如果您正在写入其他标题也可以修改的共享部分,请将写入模式设置为 XblMultiplayerSessionWriteMode::SynchronizedUpdate。有关详细信息,请参阅“多人游戏会话目录概述”主题中的会话更新的同步部分。 写入方法将加入写入服务器,并获取最新会话,从中发现其他会话成员及其主机的安全设备地址 (SDA)。有关在这些主机之间建立网络连接的详细信息,请参阅 XBOX One 上 Winsock 简介。
3. 丢弃旧的本地会话对象。使用新检索到的会话对象,以便未来的操作基于最新的已知会话状态。

​

离开 MPSD 会话

1. 为游戏会话调用 XblMultiplayerSessionLeave。
2. 按照本主题中的更新 MPSD 会话部分所述更新 MPSD 中的游戏会话。
3. 如有必要,为大厅会话调用 XblMultiplayerSessionLeave 方法,然后更新该会话。
4. 如果大厅会话需要,请通过调用 XblMultiplayerRemoveSubscriptionLostHandler 和 XblMultiplayerRemoveSessionChangedHandler 取消注册来关闭多人游戏 API。

​

在匹配期间填补空闲会话位置

1. 访问匹配期间创建的票证会话的最新会话状态。
2. 从大厅会话中添加可用于游戏玩法的玩家。
3. 确定票证会话是否已满。
4. 如果会话已满,则继续游戏。
5. 如果会话尚未满,请按照本主题中的创建匹配票证所述创建匹配票证。请务必将 preserveSession 参数设置为 Always 创建票证。
6. 继续匹配。有关详细信息,请参阅匹配概述。

​

创建匹配票证

1. 调用 XblMatchmakingCreateMatchTicketAsync,传入对票证会话的引用。该方法从 MPSD 读取票证会话并为会话中的用户启动匹配。在内部,该方法调用 POST (/serviceconfigs/{scid}/hoppers/{hoppername})。
2. 如果匹配服务要将会话成员匹配到新会话或另一个现有会话,请将 preserveSession 参数设置为 Never。将 preserveSession 参数设置为 Always 以允许标题重用现有游戏会话作为票证会话来继续游戏玩法。然后,匹配服务可以确保保留提交的会话,并将任何匹配的玩家添加到该会话。
3. 使用 CreateMatchTicketResponse 对象中返回的 XblCreateMatchTicketResponse::EstimatedWaitTime 来设置用户对匹配时间的期望。
4. 如果需要,使用响应对象中返回的 XblCreateMatchTicketResponse::MatchTicketId 通过删除票证来取消会话的匹配。票证删除使用 XblMatchmakingDeleteMatchTicketAsync。

​

获取匹配票证状态

1. 获取票证会话的 XblMultiplayerSessionHandle 对象。
2. 调用 XblMultiplayerSessionMatchmakingServer 以访问匹配中使用的 XblMultiplayerMatchmakingServer 对象。
3. 检查 XblMultiplayerMatchmakingServer 对象以确定匹配过程的状态、会话的典型等待时间以及目标会话引用(如果已找到匹配)。