多人游戏管理器概述

本主题介绍了通过管理会话、匹配和游戏邀请来添加多人游戏功能的高级 API。 API 提供了基于状态和基于事件的编程模型。

Xbox 服务为将多人游戏功能添加到你的游戏提供了广泛的支持，以便游戏可以连接世界各地的 Xbox 成员。 这包括丰富的匹配方案、玩家加入好友正在进行中的游戏的功能等。

直接使用多人游戏 API 实现 Xbox 服务多人游戏可能是一项复杂的任务。 它需要大量的设计和测试来验证你是否遵循最佳做法并满足认证要求。

多人游戏管理器通过管理会话和匹配，以及提供基于状态和基于事件的编程模型，可以轻松地将多人游戏功能添加到游戏中。

多人游戏管理器是一组 API。 其设计目的是使采用对等托管多人游戏设计的 Xbox 服务游戏轻松实现多人游戏场景。

多人游戏管理器提供了一个以常见的多人游戏场景为中心的 API，例如与好友进行多人游戏、处理游戏邀请、处理加入进程和匹配等。

多人游戏管理器支持多个本地用户。 如果你使用第三方匹配服务，它还可以让游戏更轻松地与多人游戏会话目录 (MPSD) 集成。 只需调用几个 API 即可完成其中很多方案。

关键功能

多人游戏管理器 API 的主要功能如下所示。

• 轻松的会话管理和 Xbox 服务匹配
• 基于状态和基于事件的编程模型
• 确保 Xbox 服务最佳做法以及兼容多人游戏 XR
• 执行 2015 多人游戏流程图

有关多人游戏管理器 API 设计的重要信息如下所示。

• 不支持大型 MPSD 会话（超过 100 个成员）。
• 仅针对对等托管多人游戏设计。 具有专用服务器的游戏应改为使用多人游戏活动服务或多人游戏服务 API 和服务到服务调用（NDA 主题）要求授权。

重要

若要通过认证，你的游戏仍必须实现在线多人游戏所需的事件。

概述

多人游戏管理器以以下重要概念为中心。

• 大厅会话：一个永久会话，用于管理设备的本地用户和想要一起玩的受邀好友。

  组可以玩游戏；例如，多个回合、地图和关卡。 大厅会话会跟踪好友的核心组（包括设备的本地玩家）。 通常，当主机可能正在浏览菜单，并与组成员聊天以决定他们想玩哪种游戏模式时，就会形成此组。

• 游戏会话：跟踪正在玩特定游戏实例的玩家。

  例如，竞赛、地图或关卡。 可以通过包含大厅会话成员的 XblMultiplayerManagerJoinGameFromLobby 创建一个新的游戏会话。

  当成员接受邀请时，会将他们添加到大厅和游戏会话中（如果还有空间）。

  如果启用匹配，则可以将其他玩家添加到游戏会话中，但不会将他们添加到大厅会话中。 这意味着，游戏结束后，大厅会话中的玩家仍在一起，但匹配多出的玩家则不在一起。

• XblMultiplayerManagerMember：代表已在某个本地或远程设备上登录的个人用户。

• XblMultiplayerManagerDoWork：确保在游戏和 Xbox 服务多人游戏服务之间保持正确的游戏状态更新。

  若要确保最佳性能，必须频繁调用 XblMultiplayerManagerDoWork，例如每帧调用一次。

  XblMultiplayerManagerDoWork 提供一组 XblMultiplayerEvent 回调事件供游戏处理。

状态机

若要确保保持最新状态，需要执行 XblMultiplayerManagerDoWork 调用。 为了让多人游戏管理器完成其工作，必须定期调用 XblMultiplayerManagerDoWork 方法。 执行此操作的最可靠方法是至少每帧调用一次。

XblMultiplayerManagerDoWork 在不工作的情况下会快速返回，因此无需担心调用过于频繁。

线程处理

不应认为多人游戏管理器 API 返回的所有对象都是线程安全的。 但是，如果从多个线程中调用它，则会为你提供控制权以执行线程同步。

该库具有内部多线程保护。 但是，如果需要一个线程访问任何值，则仍然需要实现自己的锁定操作；例如，当另一个线程可能在调用 XblMultiplayerManagerDoWork 时浏览成员列表。

基于状态的模型更新

多人游戏管理器会维护一个基于状态的模型，当玩家加入、离开或更新会话时，该模型会在后台更新会话。 为帮助避免 UI 线程与游戏线程之间发生线程同步问题，多人游戏管理器不会更新会话的应用可见状态，直到调用 XblMultiplayerManagerDoWork 方法为止。

以往，你会收到有关后台线程上的会话更改等事件的通知，然后，必须将其与 UI 线程同步才能显示这些更改。 使用多人游戏管理器，可以在后台完成此项工作。

可在选择时在主线程上调用 XblMultiplayerManagerDoWork，以获取多人游戏管理器在后台缓冲状态的最新快照。

事件和通知

多人游戏管理器定义一组重要事件（见 XblMultiplayerEvent），并在这些事件发生时通过 XblMultiplayerManagerDoWork 方法通知游戏。 例如，事件包括远程玩家加入或离开、成员属性更改或会话状态更改等。

所有多人游戏管理器 API 都是异步的。 当这些异步操作完成后，XblMultiplayerManagerDoWork 方法会返回事件列表。 游戏应根据你的情况适当处理这些事件。 有关更多详细信息，请参阅 XblMultiplayerEvent 类文档。

每个返回的 XblMultiplayerEvent 都包含一个 EventArgsHandle，必须使用它来获取事件类型的相应 args。 例如，如果 XblMultiplayerEventType 为 MemberJoined，则可以调用 XblMultiplayerEventArgsMembersCount 和 XblMultiplayerEventArgsMembers。

以下示例演示了如何使用 XblMultiplayerManagerDoWork 来处理事件。

扁平 C API

size_t eventCount{ 0 };
const XblMultiplayerEvent* events{ nullptr };
HRESULT hr = XblMultiplayerManagerDoWork(&events, &eventCount);
if (FAILED(hr))
{
    // Handle failure.
}

for (auto i = 0u; i < eventCount; ++i)
{
    switch (events[i].EventType)
    {
        case XblMultiplayerEventType::MemberJoined:
        {
            // Handle MemberJoined.
            size_t memberCount = 0;
            hr = XblMultiplayerEventArgsMembersCount(events[i].EventArgsHandle, &memberCount);
            assert(SUCCEEDED(hr));

            std::vector<XblMultiplayerManagerMember> members(memberCount);
            hr = XblMultiplayerEventArgsMembers(events[i].EventArgsHandle, memberCount, members.data());
            assert(SUCCEEDED(hr));
            ...

            break;
        }

        case XblMultiplayerEventType::SessionPropertyChanged:
        {
            // Handle SessionPropertyChanged.
            const char* changedProperty{ nullptr };
            hr = XblMultiplayerEventArgsPropertiesJson(events[i].EventArgsHandle, &changedProperty);
            assert(SUCCEEDED(hr));
            ...

            break;
        }
        ...
    }
}

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

• XblMultiplayerEvent
• XblMultiplayerEventArgsMembers
• XblMultiplayerEventArgsMembersCount
• XblMultiplayerEventArgsPropertiesJson
• XblMultiplayerEventType
• XblMultiplayerManagerDoWork
• XblMultiplayerManagerMember

场景

本节介绍常见场景以及你会在每个场景中调用的 API。 还会提供一些有关多人游戏管理器在后台运行的内容的信息。

• 启用使用多人游戏管理器与好友一起玩多人游戏
• 使用多人游戏管理器通过 SmartMatch 查找一款多人游戏
• 使用多人管理器发送游戏邀请
• 使用多人游戏管理器处理协议激活以启动游戏

有关 API 的高级概述，请参见多人游戏管理器 API 概述。

多人游戏管理器不执行的操作

多人游戏管理器可以更轻松实现多人游戏场景并从你那里提取一些数据。 但是，多人游戏管理器不处理以下内容：

• 永久在线服务器游戏，例如大型多人在线 (MMO) 游戏或其他需要大型会话（会话中超过 100 名玩家）的游戏类型
• 服务器到服务器会话管理
• 将 MPSD 调用限制为遵守细化速率限制
• 多人游戏服务 API 和多人游戏管理器 API 的混合

注意

多人游戏管理器不限于任何特定的网络技术，应该与任何网络通信层一起使用。

资源

有关 API 的工作示例，请参阅 NetRumble 示例。

有关 API 文档，请参阅 multiplayer_manager_c。 还可以查看 multiplayer_manager_c.h 头文件。

如果你在使用多人游戏管理器时有任何疑问、反馈或问题，请联系开发者客户经理 (DAM) 或在 https://forums.xboxlive.com 中的论坛上发布支持话题。