Skip to main content
本主题介绍用于通过管理会话、匹配和游戏邀请来添加多人游戏功能的高级 API。该 API 提供基于状态和基于事件的编程模型。 XBOX 服务提供了广泛的支持,可在你的游戏中添加多人游戏功能,以便你的游戏可以将全球的 XBOX 成员连接起来。 这包括丰富的匹配场景,玩家能够加入好友正在进行的游戏等。 直接使用 Multiplayer API 实现 XBOX 服务多人游戏可能是一项复杂的任务。它需要大量的设计和测试,以验证你正在遵循最佳实践并满足认证要求。 Multiplayer Manager 通过管理会话和匹配,并提供基于状态和基于事件的编程模型,使你的游戏可以轻松添加多人游戏功能。 Multiplayer Manager 是一组 API。它们旨在使实现具有对等承载多人游戏设计的 XBOX 服务游戏的多人游戏场景变得简单。 Multiplayer Manager 提供的 API 围绕常见的多人游戏场景,例如与好友玩多人游戏、处理游戏邀请、处理进行中加入、匹配等。 Multiplayer Manager 支持多个本地用户。如果你使用第三方匹配服务,它还使你的游戏更容易与多人游戏会话目录 (MPSD) 集成。许多场景只需几个 API 调用即可完成。

主要功能

Multiplayer Manager API 的主要功能如下。
  • 轻松会话管理和 XBOX 服务匹配
  • 基于状态和基于事件的编程模型
  • 确保遵循 XBOX 服务最佳实践并符合多人游戏 XR 规范
  • 实现 2015 多人游戏流程图
有关 Multiplayer Manager API 设计的重要信息如下。
要通过认证,你的游戏仍必须实现在线多人游戏所需的事件。

概述

Multiplayer Manager 围绕以下关键概念。
  • 大厅会话: 一个持久会话,用于管理本地设备的用户以及想要一起玩游戏的受邀好友。 该群组可以玩游戏;例如,多个回合、地图和关卡。大厅会话跟踪这个核心好友群组(包括本地设备上的玩家)。 通常,该群组在主机可能正在浏览菜单并与群组成员聊天以决定他们想玩何种游戏模式时形成。
  • 游戏会话: 跟踪正在玩特定游戏实例的玩家。 例如,一场比赛、地图或关卡。 你可以通过 XblMultiplayerManagerJoinGameFromLobby 创建一个新的游戏会话,该会话包含大厅会话中的成员。 当成员接受邀请时,他们将被添加到大厅和游戏会话中(如果有空位)。 如果启用了匹配,可以将其他玩家添加到游戏会话中,但那些其他玩家不会被添加到大厅会话中。 这意味着当游戏结束时,大厅会话中的玩家仍在一起,而来自匹配的额外玩家则不会。
  • XblMultiplayerManagerMember:表示在本地或远程设备上登录的单个用户。
  • XblMultiplayerManagerDoWork:确保游戏与 XBOX 服务多人游戏服务之间维护正确的游戏状态更新。 为确保最佳性能,必须频繁调用 XblMultiplayerManagerDoWork,例如每帧一次。 XblMultiplayerManagerDoWork 为你提供一个供游戏处理的 XblMultiplayerEvent 回调事件数组。

状态机

XblMultiplayerManagerDoWork 调用对于确保状态保持最新是必需的。 为了让 Multiplayer Manager 完成其工作,你必须定期调用 XblMultiplayerManagerDoWork 方法。 最可靠的方式是每帧至少调用一次。 当没有工作要做时,XblMultiplayerManagerDoWork 会快速返回,因此不必担心过于频繁地调用它。

线程

Multiplayer Manager API 返回的所有对象都不应被视为线程安全的。 但是,如果你从多个线程调用它,它会让你控制线程同步。 该库具有内部多线程保护。但是,如果你需要一个线程访问任何值,你仍然需要实现自己的锁定;例如,在遍历成员列表时,另一个线程可能正在调用 XblMultiplayerManagerDoWork

基于状态的模型更新

Multiplayer Manager 维护一个基于状态的模型,在玩家加入、离开或会话更新时在后台更新会话。 为了帮助避免 UI 线程与你的游戏线程之间的线程同步问题,Multiplayer Manager 在你调用 XblMultiplayerManagerDoWork 方法之前,不会更新应用可见的会话状态。 传统上,你会在后台线程上接收有关事件(例如会话更改)的通知,然后必须将其与 UI 线程同步以显示这些更改。 使用 Multiplayer Manager,这些幕后工作已经为你完成。 你可以在你选择的时间点在主线程上调用 XblMultiplayerManagerDoWork,以获取 Multiplayer Manager 在幕后为你缓冲的状态的最新快照。

事件和通知

Multiplayer Manager 定义了一组重要事件(请参阅 XblMultiplayerEvent),并在事件发生时通过 XblMultiplayerManagerDoWork 方法通知游戏。 例如,事件包括远程玩家加入或离开、成员属性更改或会话状态更改。 所有 Multiplayer Manager API 都是异步的。 当这些异步操作完成时,XblMultiplayerManagerDoWork 方法返回一个事件列表。 你的游戏应针对你的情况适当地处理这些事件。 有关详细信息,请参阅 XblMultiplayerEvent 类文档。 每个返回的 XblMultiplayerEvent 都包含一个 EventArgsHandle,你必须使用它来获取事件类型对应的 args。 例如,如果 XblMultiplayerEventTypeMemberJoined,则可以调用 XblMultiplayerEventArgsMembersCountXblMultiplayerEventArgsMembers 以下示例演示如何使用 XblMultiplayerManagerDoWork 处理事件。

扁平 C API

有关详细信息,请参阅以下内容:

场景

本节介绍常见场景以及在每种场景中你要调用的 API。 还提供了一些关于 Multiplayer Manager 在幕后所做工作的信息。 有关 API 的高级概述,请参阅 Multiplayer Manager API 概述

Multiplayer Manager 不做的事情

Multiplayer Manager 使实现多人游戏场景变得更加容易,并为你抽象了一些数据。但是,Multiplayer Manager 不处理以下内容:
  • 持久在线服务器游戏,例如大型多人在线 (MMO) 游戏或需要大型会话(会话中超过 100 名玩家)的其他游戏类型
  • 服务器到服务器的会话管理
  • 限制 MPSD 调用以遵守细粒度速率限制
  • 混合使用多人游戏服务 API 与 Multiplayer Manager API
Multiplayer Manager 不受任何特定网络技术的限制,应该可以与任何网络通信层一起使用。

资源

有关 API 的工作示例,请参阅 NetRumble 示例 有关 API 文档,请参阅 multiplayer_manager_c。 你还可以查看 multiplayer_manager_c.h 头文件。 如果你有疑问、反馈或在使用 Multiplayer Manager 时遇到问题,请联系你的开发者客户经理 (DAM) 或在论坛 https://forums.xboxlive.com 上发布支持帖子。
最后修改于 2026年8月25日