> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiplayer Manager API 概述

> XBOX Multiplayer Manager API 中最重要的方法和类的概述,包括大厅会话、游戏会话、成员和多人游戏事件。

本主题介绍 Multiplayer Manager API 中最重要的方法。

有关详细的 API 信息,请参阅[参考文档](https://docs.xbox.com/zh-CN/reference/live/gc-reference-live-toc.md)。

有关如何在应用程序中使用这些 API 的示例,请参阅 [NetRumble 示例(NDA 主题)](https://learn.microsoft.com/gaming/gdk/docs/services/gdk-dev/development-downloads/gdk-samples-list)。

## 命名空间

Multiplayer Manager 包含在以下命名空间中。

| 语言 | 命名空间 |
| - | - |
| C | `XblMultiplayerManager*` 前缀 |
| C++ | `xbox::services::multiplayer::manager` |

你应该了解以下主要类。

* [Multiplayer Manager API 概述]()
  * [命名空间](#namespace)
  * [Multiplayer Manager 类](#multiplayer-manager-class)
  * [Multiplayer Event 类](#multiplayer-event-class)
  * [Multiplayer Member 类](#multiplayer-member-class)
  * [Multiplayer Lobby Session 类](#multiplayer-lobby-session-class)
  * [Multiplayer Game Session 类](#multiplayer-game-session-class)

## Multiplayer Manager 类 

Multiplayer Manager 是一个单例类,它包含一个大厅会话对象和一个游戏会话对象。

至少,你必须在此类上调用 [XblMultiplayerManagerInitialize](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerinitialize.md) 和 [XblMultiplayerManagerDoWork](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) 方法,Multiplayer Manager 才能正常工作。

下表描述了一些(但不是全部)较常用的方法和属性。有关成员的完整、描述性列表,请参阅[参考文档](https://docs.xbox.com/zh-CN/reference/live/gc-reference-live-toc.md)。

| C | C++ | 描述 |
| - | - | - |
| **方法** | | |
| [XblMultiplayerManagerInitialize](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerinitialize.md) | `initialize()` | 初始化 Multiplayer Manager。在使用 Multiplayer Manager 之前必须调用此方法。 |
| [XblMultiplayerManagerDoWork](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) | `do_work()` | 更新应用可见的会话状态。你应该每帧至少调用此方法一次。你的游戏应处理该方法返回的多人游戏事件。 |
| [XblMultiplayerManagerJoinLobby](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoinlobby.md) | `join_lobby()` | 提供一种通过 `handleId`(唯一标识用户要加入的大厅)加入好友大厅会话的方式,或当用户接受邀请导致游戏被协议激活时使用。 |
| [XblMultiplayerManagerJoinGameFromLobby](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby.md) | `join_game_from_lobby()` | 如果存在大厅的游戏会话且有空位,则加入该游戏会话。如果会话不存在,则使用现有的大厅成员创建新的游戏会话。这不会将现有的大厅会话属性迁移到游戏会话。加入后,你可以通过 `*SetSynchronizedProperties` API 设置属性或主机。所有想要加入游戏会话的客户端都必须调用此 API。 |
| [XblMultiplayerManagerJoinGame](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingame.md) | `join_game()` | 通过全局唯一的会话名称加入现有游戏会话,该名称通常通过第三方匹配服务找到。你可以传入希望参与游戏的 XBOX 用户 ID 列表。 |
| [XblMultiplayerManagerFindMatch](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerfindmatch.md) | `find_match()` | 使用 XBOX 服务匹配来查找并加入游戏。 |
| [XblMultiplayerManagerLeaveGame](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerleavegame.md) | `leave_game()` | 离开游戏并将该成员及所有本地成员返回到大厅。 |
| **属性** | | |
| `LobbySession` | `lobby_session()` | 表示大厅会话对象的句柄。 |
| `GameSession` | `game_session()` | 表示游戏会话对象的句柄。 |

## Multiplayer Event 类 

| 语言 | 类 |
| - | - |
| C | [XblMultiplayerEvent](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md) |
| C++ | `multiplayer_event` |

当你调用 [XblMultiplayerManagerDoWork](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) 时,Multiplayer Manager 返回一个事件列表,表示自你上次调用 `XblMultiplayerManagerDoWork` 以来会话的变更。这些事件包括诸如成员已加入会话、成员已离开会话、成员属性已更改或主机客户端已更改等变更。

有关所有可能的事件类型的列表,请参阅 [XblMultiplayerEventType](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype.md) 枚举。

每个返回的 [XblMultiplayerEvent](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent.md) 都包含一个 `EventArgsHandle`。你必须使用它来获取事件类型对应的 `args`。例如,如果 [XblMultiplayerEventType](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype.md) 为 `MemberJoined`,则应调用 [XblMultiplayerEventArgsMembersCount](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmemberscount.md) 和 [XblMultiplayerEventArgsMembers](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayereventargsmembers.md)。

在调用 [XblMultiplayerManagerDoWork](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork.md) 后,你的游戏应根据需要处理每个事件。

## Multiplayer Member 类 

| 语言 | 类 |
| - | - |
| C | [XblMultiplayerManagerMember](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember.md) |
| C++ | `multiplayer_member` |

此类表示大厅或游戏会话中的玩家。它包含有关成员的属性,例如玩家的 XBOX 用户 ID、玩家的网络连接地址以及每个玩家的自定义属性。

## Multiplayer Lobby Session 类 

| 语言 | 类 |
| - | - |
| C | `XblMultiplayerManagerLobbySession*` 前缀 |
| C++ | `multiplayer_lobby_session` |

此类创建一个持久会话,用于管理此设备本地的用户以及想要一起游戏的受邀好友。大厅会话必须至少包含一个成员,Multiplayer Manager 才能执行任何多人游戏操作。你最初可以通过调用 [XblMultiplayerManagerLobbySessionAddLocalUser](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser.md) 方法来创建新的大厅会话。

下表描述了此类中一些(但不是全部)较常用的方法和属性。有关类成员的完整、描述性列表,请参阅[参考文档](https://docs.xbox.com/zh-CN/reference/live/gc-reference-live-toc.md)。

| C | C++ | 描述 |
| - | - | - |
| **方法** | | |
| [XblMultiplayerManagerLobbySessionAddLocalUser](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionaddlocaluser.md) | `add_local_user()` | 将本地用户(已在本地设备上登录的玩家)添加到大厅会话。如果这是添加到大厅会话的第一个成员,此方法将创建一个新的大厅会话。 |
| [XblMultiplayerManagerLobbySessionRemoveLocalUser](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionremovelocaluser.md) | `remove_local_user()` | 从大厅和游戏会话中删除指定成员。 |
| [XblMultiplayerManagerLobbySessionInviteFriends](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninvitefriends.md) | `invite_friends()` | 打开标准 XBOX UI,允许玩家从其好友列表中选择好友,然后邀请这些玩家加入游戏。 |
| [XblMultiplayerManagerLobbySessionInviteUsers](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessioninviteusers.md) | `invite_users()` | 邀请指定的 XBOX 玩家加入游戏。 |
| [XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberconnectionaddress.md) | `set_local_member_connection_address()` | 设置本地成员的网络地址。游戏可以使用此网络地址在成员之间建立网络通信。 |
| [XblMultiplayerManagerLobbySessionSetLocalMemberProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetlocalmemberproperties.md) | `set_local_member_properties()` | 为本地成员设置自定义属性。该属性以 JSON 字符串形式存储。 |
| [XblMultiplayerManagerLobbySessionDeleteLocalMemberProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessiondeletelocalmemberproperties.md) | `delete_local_member_properties()` | 删除本地成员的自定义属性。 |
| [XblMultiplayerManagerLobbySessionSetProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties.md) / [XblMultiplayerManagerLobbySessionSetSynchronizedProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetsynchronizedproperties.md) | `set_properties()` / `set_synchronized_properties()` | 为大厅会话设置自定义属性。该属性以 JSON 字符串形式存储。如果该属性在设备之间共享,并且可以由多个设备同时更新,请使用该方法的同步版本。 |
| [XblMultiplayerManagerGameSessionIsHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionishost.md) | `is_host()` | 指示当前设备是否充当大厅主机。 |
| [XblMultiplayerManagerGameSessionSetSynchronizedHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionsetsynchronizedhost.md) | `set_synchronized_host()` | 设置大厅的主机。 |
| **属性** | | |
| [XblMultiplayerManagerLobbySessionLocalMembers](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionlocalmembers.md) | `local_members()` | 已在本地设备上登录的成员集合。 |
| [XblMultiplayerManagerLobbySessionMembers](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionmembers.md) | `members()` | 大厅会话中的成员集合。 |
| [XblMultiplayerManagerLobbySessionSetProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionsetproperties.md) | `properties()` | 表示大厅会话属性集合的 JSON 对象。 |
| [XblMultiplayerManagerLobbySessionHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerlobbysessionhost.md) | `host()` | 大厅的主机成员。 |

## Multiplayer Game Session 类 

| 语言 | 类 |
| - | - |
| C | `XblMultiplayerManagerGameSession*` 前缀 |
| C++ | `multiplayer_game_session` |

游戏会话表示参与实际游戏实例的 XBOX 服务成员组。这可以包括通过匹配服务匹配到的玩家。

要启动包含来自大厅会话成员的新游戏会话,请调用 [XblMultiplayerManagerJoinGameFromLobby](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingamefromlobby.md)。如果你想使用 XBOX 服务匹配,请调用 [XblMultiplayerManagerFindMatch](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerfindmatch.md)。如果你使用第三方匹配服务,请调用 [XblMultiplayerManagerJoinGame](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerjoingame.md)。

下表描述了 Multiplayer Manager 中一些(但不是全部)较常用的方法和属性。有关类成员的完整、描述性列表,请参阅该类的 API 参考。

| C | C++ | 描述 |
| - | - | - |
| **方法** | | |
| [XblMultiplayerManagerGameSessionSetProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionsetproperties.md) / [XblMultiplayerManagerGameSessionSetSynchronizedProperties](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionsetsynchronizedproperties.md) | `set_properties()` / `set_synchronized_properties()` | 为游戏会话设置自定义属性。该属性以 JSON 字符串形式存储。如果该属性在设备之间共享,并且可以由多个设备同时更新,请使用该方法的同步版本。 |
| [XblMultiplayerManagerGameSessionIsHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionishost.md) | `is_host()` | 指示当前设备是否充当游戏主机。 |
| [XblMultiplayerManagerGameSessionSetSynchronizedHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionsetsynchronizedhost.md) | `set_synchronized_host()` | 设置游戏的主机。 |
| **属性** | | |
| [XblMultiplayerManagerGameSessionMembers](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionmembers.md) | `members()` | 游戏会话中的成员集合。 |
| [XblMultiplayerManagerGameSessionPropertiesJson](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionpropertiesjson.md) | `properties()` | 表示游戏会话属性集合的 JSON 对象。 |
| [XblMultiplayerManagerGameSessionHost](https://docs.xbox.com/zh-CN/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagergamesessionhost.md) | `host()` | 游戏的主机成员。 |


## Related topics

- [Multiplayer Manager 概述](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-overview.md)
- [概述](https://docs.xbox.com/zh-CN/services/xbox-services/fundamentals/live-xbl-overview.md)
- [匹配概述](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/matchmaking/live-matchmaking-overview.md)
- [邀请概述](https://docs.xbox.com/zh-CN/services/xbox-services/multiplayer/invites/live-multiplayer-invites-overview.md)
- [独立 SDK 概述](https://docs.xbox.com/zh-CN/services/playfab/sdks/sdk-overview.md)