Multiplayer Manager API overview
This topic describes the most important methods in the Multiplayer Manager API.
For detailed API information, see the reference documentation.
For examples of how to use these APIs in an application, see the NetRumble sample (NDA topic)Authorization required.
Namespace
Multiplayer Manager is included the following namespace.
| Language | Namespace |
|---|---|
| C | XblMultiplayerManager* prefix |
| C++ | xbox::services::multiplayer::manager |
You should understand the following major classes.
Multiplayer Manager class
Multiplayer Manager is a singleton class that contains a single lobby session object and a single game session object.
At a minimum, you must call the XblMultiplayerManagerInitialize and XblMultiplayerManagerDoWork methods on this class for Multiplayer Manager to function.
The following table describes some, but not all, of the more commonly used methods and properties. For a complete, descriptive list of members, see the reference documentation.
| C | C++ | Description |
|---|---|---|
| Methods | ||
| XblMultiplayerManagerInitialize | initialize() |
Initializes Multiplayer Manager. You must call this method before using Multiplayer Manager. |
| XblMultiplayerManagerDoWork | do_work() |
Updates the app-visible session states. You should call this method at least once per frame. Your game should handle the multiplayer events that are returned by the method. |
| XblMultiplayerManagerJoinLobby | join_lobby() |
Provides a way to join a friend's lobby session through a handleId that uniquely identifies the lobby that the user wants to join or when the user accepts an invite that causes the title to get protocol-activated. |
| XblMultiplayerManagerJoinGameFromLobby | join_game_from_lobby() |
Join the lobby's game session if one exists and if there's room. If the session doesn't exist, it creates a new game session with the existing lobby members. This doesn't migrate existing lobby session properties over to the game session. After joining, you can set the properties or the host via the *SetSynchronizedProperties APIs. The title is required to call this API on all clients that want to join the game session. |
| XblMultiplayerManagerJoinGame | join_game() |
Joins an existing game session given a globally unique session name, typically found through third-party matchmaking services. You can pass in the list of Xbox user IDs that you want to be part of the game. |
| XblMultiplayerManagerFindMatch | find_match() |
Use Xbox services matchmaking to find and join a game. |
| XblMultiplayerManagerLeaveGame | leave_game() |
Leaves a game and returns the member and all local members to the lobby. |
| Properties | ||
LobbySession |
lobby_session() |
A handle to an object that represents the lobby session. |
GameSession |
game_session() |
A handle to an object that represents the game session. |
Multiplayer Event class
| Language | Class |
|---|---|
| C | XblMultiplayerEvent |
| C++ | multiplayer_event |
When you call XblMultiplayerManagerDoWork, Multiplayer Manager returns a list of events that represent the changes to the sessions since you last called XblMultiplayerManagerDoWork.
These events include changes such as a member has joined a session, a member has left a session, member properties have changed, or the host client has changed.
For a list of all possible event types, see the XblMultiplayerEventType enumeration.
Each returned XblMultiplayerEvent includes an EventArgsHandle. You must use it to get the appropriate args for the event type.
For example, if the XblMultiplayerEventType is MemberJoined, you would call XblMultiplayerEventArgsMembersCount and XblMultiplayerEventArgsMembers.
Your game should handle each of the events as necessary after calling XblMultiplayerManagerDoWork.
Multiplayer Member class
| Language | Class |
|---|---|
| C | XblMultiplayerManagerMember |
| C++ | multiplayer_member |
This class represents a player in a lobby or game session. It contains properties about the member, such as the Xbox user ID for the player, the network connection address for the player, and custom properties for each player.
Multiplayer Lobby Session class
| Language | Class |
|---|---|
| C | XblMultiplayerManagerLobbySession* prefix |
| C++ | multiplayer_lobby_session |
This class creates a persistent session that's used for managing users that are local to this device and the invited friends who want to play together. A lobby session must contain at least one member for Multiplayer Manager to take any multiplayer actions. You can initially create a new lobby session by calling the XblMultiplayerManagerLobbySessionAddLocalUser method.
The following table describes some, but not all, of the more commonly used methods and properties for this class. For a complete, descriptive list of class members, see the reference documentation.
| C | C++ | Description |
|---|---|---|
| Methods | ||
| XblMultiplayerManagerLobbySessionAddLocalUser | add_local_user() |
Adds a local user (a player who has signed in on the local device) to the lobby session. If this is the first member added to a lobby session, this method creates a new lobby session. |
| XblMultiplayerManagerLobbySessionRemoveLocalUser | remove_local_user() |
Removes a specified member from the lobby and game session. |
| XblMultiplayerManagerLobbySessionInviteFriends | invite_friends() |
Opens a standard Xbox UI that allows the player to select friends from their friends list, and then invites those players to the game. |
| XblMultiplayerManagerLobbySessionInviteUsers | invite_users() |
Invites the specified Xbox players to the game. |
| XblMultiplayerManagerLobbySessionSetLocalMemberConnectionAddress | set_local_member_connection_address() |
Sets the network address for the local member. Games can use this network address to establish network communications between members. |
| XblMultiplayerManagerLobbySessionSetLocalMemberProperties | set_local_member_properties() |
Sets a custom property for a local member. The property is stored in a JSON string. |
| XblMultiplayerManagerLobbySessionDeleteLocalMemberProperties | delete_local_member_properties() |
Removes a custom property for a local member. |
| XblMultiplayerManagerLobbySessionSetProperties / XblMultiplayerManagerLobbySessionSetSynchronizedProperties | set_properties() / set_synchronized_properties() |
Sets a custom property for the lobby session. The property is stored in a JSON string. If the property is shared between devices, and can be updated by several devices at the same time, use the synchronized version of the method. |
| XblMultiplayerManagerGameSessionIsHost | is_host() |
Indicates if the current device is acting as the lobby host. |
| XblMultiplayerManagerGameSessionSetSynchronizedHost | set_synchronized_host() |
Sets the host of the lobby. |
| Properties | ||
| XblMultiplayerManagerLobbySessionLocalMembers | local_members() |
The collection of members that are signed in on the local device. |
| XblMultiplayerManagerLobbySessionMembers | members() |
The collection of members that are in the lobby session. |
| XblMultiplayerManagerLobbySessionSetProperties | properties() |
A JSON object that represents a collection of properties for the lobby session. |
| XblMultiplayerManagerLobbySessionHost | host() |
The host member for the lobby. |
Multiplayer Game Session class
| Language | Class |
|---|---|
| C | XblMultiplayerManagerGameSession* prefix |
| C++ | multiplayer_game_session |
The game session represents the group of Xbox services members that are participating in an instance of actual game play. This can include players who have been matched up via matchmaking services.
To start a new game session that includes members from the lobby session, call XblMultiplayerManagerJoinGameFromLobby. If you want to use Xbox services matchmaking, call XblMultiplayerManagerFindMatch. If you're using a third-party matchmaking service, call XblMultiplayerManagerJoinGame.
The following table describes some, but not all, of the more commonly used methods and properties for Multiplayer Manager. For a complete, descriptive list of class members, see the API reference for this class.
| C | C++ | Description |
|---|---|---|
| Methods | ||
| XblMultiplayerManagerGameSessionSetProperties / XblMultiplayerManagerGameSessionSetSynchronizedProperties | set_properties() / set_synchronized_properties() |
Sets a custom property for the game session. The property is stored in a JSON string. If the property is shared between devices, and can be updated by several devices at the same time, use the synchronized version of the method. |
| XblMultiplayerManagerGameSessionIsHost | is_host() |
Indicates if the current device is acting as the game host. |
| XblMultiplayerManagerGameSessionSetSynchronizedHost | set_synchronized_host() |
Sets the host of the game. |
| Properties | ||
| XblMultiplayerManagerGameSessionMembers | members() |
The collection of members that are in the game session. |
| XblMultiplayerManagerGameSessionPropertiesJson | properties() |
A JSON object that represents a collection of properties for the game session. |
| XblMultiplayerManagerGameSessionHost | host() |
The host member for the game. |