多人游戏管理器 API 概述
本主题介绍多人游戏管理器 API 中最重要的方法。
有关详细的 API 信息，请参阅 参考文档。
有关如何在应用程序中使用这些 API 的示例，请参阅 NetRumble 示例（NDA 主题）要求授权。
命名空间
多人游戏管理器包含以下命名空间。
| 语言 | 命名空间 |
|---|---|
| C |
XblMultiplayerManager* 前缀 |
| C++ | xbox::services::multiplayer::manager |
应了解以下主要类。
多人游戏管理器类
多人游戏管理器是一个单一实例类，其中包含单个大厅会话对象和一个游戏会话对象。
至少必须对此类调用 XblMultiplayerManagerInitialize 和 XblMultiplayerManagerDoWork 方法，多人游戏管理器才能正常工作。
下表描述了一些（但不是全部）更常用的方法和属性。 有关完整的描述性成员列表，请参阅 参考文档。
| C | C++ | 描述 |
|---|---|---|
| 方法 | ||
| XblMultiplayerManagerInitialize | initialize() |
初始化多人游戏管理器。 使用多人游戏管理器之前必须先调用此方法。 |
| XblMultiplayerManagerDoWork | do_work() |
更新应用可见会话状态。 每个帧至少应调用一次此方法。 您的游戏应处理方法返回的多人游戏事件。 |
| XblMultiplayerManagerJoinLobby | join_lobby() |
提供一种通过 handleId 加入好友大厅会话的方法，该可唯一标识用户要加入的大厅，或者当用户接受导致游戏激活协议的邀请时。 |
| XblMultiplayerManagerJoinGameFromLobby | join_game_from_lobby() |
加入大厅的游戏会话（如果存在）以及是否有空间。 如果会话不存在，它会使用当前大厅成员创建新游戏会话。 这不会将现有的大厅会话属性迁移到游戏会话。 加入后，可以通过 *SetSynchronizedProperties API 设置属性或主机。 游戏需要在所有想要加入游戏会话的客户端上调用此 API。 |
| XblMultiplayerManagerJoinGame | join_game() |
给定全局唯一会话名称（通常通过第三方匹配服务找到）加入现有游戏会话。 你可以传入要加入游戏的 Xbox 用户 ID 列表。 |
| XblMultiplayerManagerFindMatch | find_match() |
使用 Xbox 服务匹配查找和加入游戏。 |
| XblMultiplayerManagerLeaveGame | leave_game() |
离开游戏，并将此成员和所有本地成员返回到大厅。 |
| 属性 | ||
LobbySession |
lobby_session() |
表示大厅会话的对象的句柄。 |
GameSession |
game_session() |
表示游戏会话的对象句柄。 |
多人游戏事件类
| 语言 | 类 |
|---|---|
| C | XblMultiplayerEvent |
| C++ | multiplayer_event |
调用 XblMultiplayerManagerDoWork时，多人游戏管理器将返回一个事件列表，这些事件表示自上次调用 XblMultiplayerManagerDoWork以来对会话所做的更改。
这些事件包括成员已加入会话、成员已离开会话、成员属性已更改或主机客户端已更改等更改。
有关所有可能的事件类型的列表，请参阅 XblMultiplayerEventType 枚举。
每个返回 的 XblMultiplayerEvent 都包含一个 EventArgsHandle。 必须使用它来获取事件类型的适当。 args
例如，如果 XblMultiplayerEventType 为 MemberJoined，则可以调用 XblMultiplayerEventArgsMembersCount 和 XblMultiplayerEventArgsMembers。
调用 XblMultiplayerManagerDoWork 后，游戏将根据需要处理每个事件。
多人游戏成员类
| 语言 | 类 |
|---|---|
| C | XblMultiplayerManagerMember |
| C++ | multiplayer_member |
此类表示大厅或游戏会话中的玩家。 它包含有关成员的属性，例如玩家的 Xbox 用户 ID、玩家的网络连接地址以及每个玩家的自定义属性。
多人游戏大厅会话类
| 语言 | 类 |
|---|---|
| C |
XblMultiplayerManagerLobbySession* 前缀 |
| C++ | multiplayer_lobby_session |
此类创建一个持久会话，用于管理此设备本地用户和想要一起玩游戏的受邀好友。 大厅会话必须包含至少一个成员，多人游戏管理器才能执行任何多人游戏操作。 最初可以通过调用 XblMultiplayerManagerLobbySessionAddLocalUser 方法来创建新的大厅会话。
下表介绍了此类的一些（但不是全部）更常用的方法和属性。 有关类成员的完整描述性列表，请参阅 参考文档。
多人游戏会话类
| 语言 | 类 |
|---|---|
| C |
XblMultiplayerManagerGameSession* 前缀 |
| C++ | multiplayer_game_session |
游戏会话表示正在参加实际游戏实例的 Xbox 服务成员组。 这可能包括通过匹配服务进行匹配的玩家。
若要启动包含大厅会话成员的新游戏会话，请调用XblMultiplayerManagerJoinGameFromLobby。 如果要使用 Xbox 服务匹配，请调用 XblMultiplayerManagerFindMatch。 如果使用的是第三方匹配服务，可调用 XblMultiplayerManagerJoinGame。
下表介绍了多人游戏管理器的一些（但不是全部）更常用的方法和属性。 有关类成员的完整描述性列表，请参阅此类的 API 参考。
| C | C++ | 描述 |
|---|---|---|
| 方法 | ||
| XblMultiplayerManagerGameSessionSetProperties / XblMultiplayerManagerGameSessionSetSynchronizedProperties | set_properties() / set_synchronized_properties() |
设置游戏会话的自定义属性。 此属性存储在 JSON 字符串中。 如果属性在设备之间共享，并且可由多个设备同时更新，请使用该方法的同步版本。 |
| XblMultiplayerManagerGameSessionIsHost | is_host() |
指示当前设备是否充当游戏主机。 |
| XblMultiplayerManagerGameSessionSetSynchronizedHost | set_synchronized_host() |
设置游戏的主机。 |
| 属性 | ||
| XblMultiplayerManagerGameSessionMembers | members() |
游戏会话中的成员集合。 |
| XblMultiplayerManagerGameSessionPropertiesJson | properties() |
表示游戏会话的属性集合的 JSON 对象。 |
| XblMultiplayerManagerGameSessionHost | host() |
游戏的主持人。 |