多人游戏会话目录概述

• MPSD 会话
• MPSD 更改通知处理和断开连接检测
• MPSD 会话句柄
• 会话更新的同步
• 调用 MPSD
• 多人游戏会话浏览器

​

MPSD 会话

• 它由游戏创建和管理。
• 它具有唯一的 URI。有关详细信息,请参阅会话目录 URI。
• 它支持用户(称为会话成员)之间的连接。
• 它存储支持游戏玩法的数据,如每个成员的属性、游戏设置、引导信息和游戏服务器信息。

​

MPSD 更改通知处理和断开连接检测

• 基于游戏发起的事件订阅,在会话更改发生时发送简短通知(shoulder tap)。
• 检测用户断开连接。
• 根据断开连接检测,将用户设置为非活动,然后将其从会话中删除。

​

建立用户连接

1. 游戏调用 XblMultiplayerSetSubscriptionsEnabled。此方法告知 XSAPI 客户端打算将 RTA 连接用于多人游戏目的。
2. 当游戏首次调用 XblMultiplayerWriteSessionAsync 或 XblMultiplayerWriteSessionByHandleAsync,将当前用户设置为活动状态时,将创建连接并挂接到 MPSD。

​

订阅会话更改

​

处理 shoulder tap

​

处理连接状态更改的通知

• XblMultiplayerSessionSubscriptionLostHandler 处理程序 — 在游戏与 MPSD 的 RTA 服务连接丢失时触发。当此事件发生时,游戏应关闭多人游戏。
• XblRealTimeActivityConnectionStateChangeHandler 处理程序 — 在游戏与 RTA 服务的连接运行状况发生临时变化时触发。游戏在收到此事件时不需要采取任何操作,但该事件对于诊断目的可能很有用。

​

断开客户端连接

​

断开连接检测

​

处理 RTA 重新连接

void* context{ nullptr };
XblFunctionContext connectionIdChangedFunctionContext = XblMultiplayerAddConnectionIdChangedHandler(
    xblContextHandle,
    [](void* context) {
        XblMultiplayerSessionHandle sessionHandle; // Retrieve the MPSD session to update
        XblMultiplayerSessionCurrentUserSetStatus(sessionHandle, XblMultiplayerSessionMemberStatus::Active);

        auto asyncBlock = std::make_unique<XAsyncBlock>();
        asyncBlock->queue = queue;
        asyncBlock->context = nullptr;
        asyncBlock->callback = [](XAsyncBlock* asyncBlock)
        {
            std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock };

            XblMultiplayerSessionHandle sessionHandle;
            HRESULT hr = XblMultiplayerWriteSessionResult(asyncBlock, &sessionHandle);
            if (SUCCEEDED(hr))
            {
                // If the write call succeeds, the connection ID has been updated and no further action is needed.
            }
            else
            {
                // If the write call fails, it's likely that the user has been removed from the session.
            }
        };

        auto hr = XblMultiplayerWriteSessionAsync(xblContextHandle, sessionHandle, XblMultiplayerSessionWriteMode::UpdateExisting, asyncBlock.get());
        if (SUCCEEDED(hr))
        {
            asyncBlock.release();
        }
    }, 
    context);

​

MPSD 会话句柄

​

句柄类型

​

邀请句柄

​

创建邀请句柄

​

创建活动句柄

​

使用句柄

1. 从游戏激活参数获取句柄 ID。
2. 创建本地 MPSD 会话对象,然后以活动状态加入。
3. 写入会话,传入相应的句柄。

​

会话更新的同步

• 由仲裁者更新会话的共享部分。如果你的实现涉及单个仲裁者,则可以避免对大多数写入操作使用同步更新。游戏可以避免对以下情况进行同步。
  • 仲裁者对会话共享部分所做的任何更新,除非它们与传达仲裁者的身份有关
  • 游戏对会话内成员区域所做的任何更新

  [!NOTE] 尽管前面提到的更新类型不需要同步,但同步对 XblMultiplayerSessionProperties::HostDeviceToken 属性的任何更新仍很重要。 此属性用于传达仲裁者的身份,例如作为仲裁者迁移的一部分。

• 所有客户端都更新会话的共享部分。在这种情况下,对会话共享部分的所有更新都必须同步。但是,游戏仍然可以在不同步的情况下写入自己的成员区域。

​

使用多人游戏 API 更新会话同步

• XblMultiplayerWriteSessionAsync
• XblMultiplayerWriteSessionByHandleAsync

​

使用多人游戏 REST API 更新会话同步

​

调用 MPSD

• 我们建议你使用多人游戏 API,其中包含充当 RESTful 功能包装器的类。有关详细信息,请参阅 XblMultiplayer 前缀函数。对于 SmartMatch 对战匹配,请使用由 XblMatchmaking 前缀函数表示的对战匹配 API。
• 使用对包含在 XBOX services RESTful 参考中的多人游戏和对战匹配 REST API 的直接标准 HTTP 调用。适用的 URI 在”会话目录 URI”(用于多人游戏)和”对战匹配 URI”(用于对战匹配)部分进行了描述。相关的 JSON 对象在 JavaScript 对象表示法 (JSON) 对象引用部分描述。

​

使用多人游戏 API 调用 MPSD

​

使用多人游戏 REST API 与 MPSD 交互

​

查询会话和会话模板 (REST)

​

查询基本会话信息

​

查询会话模板

• /serviceconfigs//sessiontemplates
• /serviceconfigs//sessiontemplates/

​

查询会话状态

• /serviceconfigs//sessions
• /serviceconfigs//sessiontemplates//sessions

​

多人游戏会话浏览器

​

访问多人游戏会话浏览器

​

打开主页

1. 打开该工具的主页。它显示安全上下文(登录用户和沙盒)以及沙盒中 SCID 的列表。
2. 按下 Menu 按钮将此页面固定到主页,这样就不必重新输入 URI。

​

显示可用会话和模板

1. 在工具中选择一个 SCID 以显示该 SCID 中将登录用户作为成员的会话列表。
2. 在同一页面上,可以选择该 SCID 并显示该 SCID 服务配置中的会话模板和本地化字符串。这些项目通过合作伙伴中心引入。

​

显示会话的全部内容

• GET 调用可能使用 X-Xbl-Contract-Version 标头中较旧的协定版本。多人游戏会话浏览器始终使用最新的协定版本显示会话。
• 通过 GET 正常请求会话时,可以触发转换和副作用,如已过期的超时。多人游戏会话浏览器显示会话的存储快照,而不执行任何逻辑、转换或副作用。
• nextTimer JSON 对象字段在 MPSD 会话中不存在,因为它与副作用同时计算。

​

另请参阅

• “多人游戏会话高级主题”主题中的会话概述一节
• 多人游戏会话状态代码
• “多人游戏任务”主题中的更新 MPSD 会话一节
• “多人游戏任务”主题中的从游戏激活加入 MPSD 会话一节
• “多人游戏任务”主题中的订阅 MPSD 会话更改通知一节
• 对战匹配概述