> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.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 信息,请参阅[参考文档](/reference/live/gc-reference-live-toc)。

有关如何在应用程序中使用这些 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)<a name="multiplayer-manager-class" />
  * [Multiplayer Event 类](#multiplayer-event-class)<a name="multiplayer-event-class" />
  * [Multiplayer Member 类](#multiplayer-member-class)<a name="multiplayer-member-class" />
  * [Multiplayer Lobby Session 类](#multiplayer-lobby-session-class)<a name="multiplayer-lobby-session-class" />
  * [Multiplayer Game Session 类](#multiplayer-game-session-class)<a name="multiplayer-game-session-class" />

## Multiplayer Manager 类 <a name="multiplayer-manager-class" />

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

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

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

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

## Multiplayer Event 类 <a name="multiplayer-event-class" />

| 语言  | 类                                                                                                |
| --- | ------------------------------------------------------------------------------------------------ |
| C   | [XblMultiplayerEvent](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayerevent) |
| C++ | `multiplayer_event`                                                                              |

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

有关所有可能的事件类型的列表,请参阅 [XblMultiplayerEventType](/reference/live/xsapi-c/multiplayer_manager_c/enums/xblmultiplayereventtype) 枚举。

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

在调用 [XblMultiplayerManagerDoWork](/reference/live/xsapi-c/multiplayer_manager_c/functions/xblmultiplayermanagerdowork) 后,你的游戏应根据需要处理每个事件。

## Multiplayer Member 类 <a name="multiplayer-member-class" />

| 语言  | 类                                                                                                                |
| --- | ---------------------------------------------------------------------------------------------------------------- |
| C   | [XblMultiplayerManagerMember](/reference/live/xsapi-c/multiplayer_manager_c/structs/xblmultiplayermanagermember) |
| C++ | `multiplayer_member`                                                                                             |

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

## Multiplayer Lobby Session 类 <a name="multiplayer-lobby-session-class" />

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

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

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

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

## Multiplayer Game Session 类 <a name="multiplayer-game-session-class" />

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

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

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

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

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


## Related topics

- [Multiplayer Manager 概述](/zh-CN/services/xbox-services/multiplayer/mpm/live-multiplayer-manager-overview.md)
- [PFMultiplayer C/C++ API 概述 - PFMultiplayer.h](/zh-CN/services/playfab/multiplayer/lobby/playfabmultiplayerreference-cpp/pfmultiplayer/pfmultiplayer_members.md)
- [概述](/zh-CN/services/xbox-services/multiplayer/overviews/index.md)
- [Social Manager 概述](/zh-CN/services/xbox-services/community/social-manager/live-social-manager-overview.md)
- [匹配概述](/zh-CN/services/xbox-services/multiplayer/matchmaking/live-matchmaking-overview.md)