- Session overview
- Member properties
- Session capabilities
- Session size
- Session user states
- Visibility and joinability
- Session time-outs
- Multiple signed-in users on a single console
- Process lifecycle management
- Cleanup of inactive sessions
- Session arbiter
Session overview
A session in Multiplayer Session Directory (MPSD) has a session name and is identified as an instance of a session template. A session template is a JSON document that provides default settings for the session. The session template is part of a service configuration with a service configuration identifier (SCID), which is a GUID. The session template is on Partner Center. Service configurations are the developer-facing resources used for ingestion, management, and security policy. When a session is accessed through MPSD, principal authorization is performed against the service configuration according to the access policies set by the developer through Partner Center. Secondary access checks, like session membership validation, are performed at the session level when the session is loaded after access to the service configuration is authorized.Functionality that’s set through a template can’t be changed through writes to MPSD. To change the values, you must create and submit a new template with the necessary changes. Any items that aren’t set through a template can be changed through writes to MPSD.
Contract version number
This topic assumes that your template uses contract version 107, which is the version used by the current MPSD for XBOX One (or later).Session reference
Each MPSD session is uniquely referred to by a session reference, represented in the multiplayer API by the XblMultiplayerSessionReference structure. The session reference contains the following string values.- Service configuration identifier (SCID)
- Session template name
- Session name
authority is sessiondirectory.xboxlive.com.
Elements of a session
Each session contains groups of elements that enforce mutability and security rules. They vary by session element, along with read-only housekeeping information (metadata). This section describes the groups of session elements that are included in the JSON files to configure your session, and in the JSON file for the template that you choose.If you’re using custom wrappers for an HTTP/REST implementation, your session and template must define JSON objects that precisely reflect the functionality of the implementation.
-
System objects: These objects have a fixed schema that’s enforced and interpreted by MPSD. They’re validated and merged. Because MPSD defines and knows what they mean, it can act on them. For the full definition of each of the system objects, see the references for both the
XblMultiplayerSessionprefix and the Session Directory URIs. - Custom objects: These objects are optional and have no schema. They’re used to store metadata that relates to a multiplayer game. Because MPSD can’t interpret this data, it isn’t acted on. Game data or saved information should be stored in Title-Managed Storage (TMS). For more information about TMS, see XBOX services Title Storage overview.
Session constants
Session constants are set only at creation time by the creator or by the session template. The/constants/system object is used to define constants for the multiplayer system as it’s known through MPSD.
The wrapper that’s associated with this object is represented by the XblMultiplayerSessionConstants structure.
The /constants/system object can define a number of items. They include a capabilities object, a metrics object, a managedInitialization (template contract version 104 or 105) or memberInitialization (contract version 107) object, a peerToPeerRequirements object, a peerToHostRequirements object, and a measurementsServerAddresses object.
Session properties
Use the/properties/system object to define session properties for MPSD.
The wrapper that’s associated with this object is the XblMultiplayerSessionProperties structure.
Session properties are writable by session members at any time.
Examples of session properties in JSON format are joinRestriction, initializationSucceeded, and the matchmaking object.
For an example of the use of this element group, see Target session initialization and QoS.
Member constants
Set the member constants at join time for each session member. The JSON object is/members/{index}/constants/system.
The wrapper class that represents a session member is the XblMultiplayerSessionMember structure.
Return to the top of this topic.
Member properties
Member properties are writable only by a session member. They’re set in the/members/{index}/properties/system object and reflect the elements of the XblMultiplayerSessionMember structure.
Here’s an example.
Server elements
Servers are non-users that have joined or been invited into a session. The associated JSON objects are/servers/{server-name}/constants/system and /servers/{server-name}/properties/system.
These objects are writable only by servers.
The
/servers/{server-name}/constants/system object isn’t currently used.Session configuration
You can control the configuration of sessions in the following ways.- Use session templates ingested through Partner Center.
- Use calls to the multiplayer and matchmaking APIs or REST APIs. You must still use a template, but it doesn’t have to contain the values that you want to configure. Note that your title can’t override the constants that are already set in the template.
We recommend that most titles (using XBOX Services API (XSAPI)) use contract version 105 and session template version 107.
Session templates
Each session template is a JSON document, part of the service configuration, that defines the framework for the session being created and provides constants for the new session. For more information, see Multiplayer session templates. Return to the top of this topic.Session capabilities
Capabilities are constants in the MPSD session that configure behavior that MPSD should apply to that session. You most commonly use Partner Center to set capabilities in the session template. Capabilities are set in the/constants/system/capabilities object.
If no capabilities are needed, use an empty capabilities object.
Titles almost never change or access session capabilities by using the multiplayer API or the matchmaking API.
- Connectivity
- Gameplay
- Large size
- Connection required for active members
SessionCapabilities member (which is of type XblMultiplayerSessionCapabilities) that defines the following properties that relate to session capabilities.
CapabilitiesConnectivityCapabilitiesGameplayCapabilitiesLarge
If the title defines a dynamic session capability, the corresponding property is set to
true for session constants.Session size
The size of an MPSD session is determined by the number of members in that session.Maximum session size
The maximum size of a session is the maximum number of session members it can accommodate. It’s represented by the XblMultiplayerSessionConstants::MaxMembersInSession property.
The maximum member size is set in the /constants/system object.
The maximum session size is between 1 and 100 session members and defaults to 100 if not set on creation.
If the required size is over 100, the session is called a “large” session and is set in a special way.
Disconnect
Setting a maximum size for a session can cause an open slot to appear as full during certain disconnect scenarios. For example, if a player is disconnected as a result of a network or power failure, the delay isn’t immediately reflected in the session. The member is set to Inactive by using the disconnect detection feature. For more information, see the MPSD change notification handling and disconnect detection section in the Multiplayer Session Directory overview topic. In comparison, a peer mesh that uses a heartbeat to detect a disconnection is often aware of a disconnect within two to three seconds and can open up the player slot immediately. However, the arbiter can’t remove other members.Large sessions
A large MPSD session can have up to 1,000 members, but it has some session features disabled, like getting a list of all members. Session largeness is represented by the XblMultiplayerSessionCapabilities::Large property.
This property is set to true to indicate a large session. The “large” capability is indicated in the /constants/system/capabilities object.
For more information, see Session capabilities.
Return to the top of this topic.
Session user states
MPSD defines a user state as the status of a user who has been added to a session. Possible user states are defined by the XblMultiplayerSessionStatus enumeration. The user also is considered to have a status of “available” before being added to a session. You can use XblMultiplayerSessionCurrentUserSetStatus to change the session user state. Make this change for REST by setting/members/{index}/properties/system correctly in the game session JSON document.
Reserved user state
The user is placed in the Reserved user state when the arbiter has selected the user to fill one of the open slots within the session. In this state, the user hasn’t yet officially accepted the invite to the session or joined the session to begin connecting with peers.Active user state
When a user is in the Active state, the title has joined the session on behalf of the user, and the user is actively participating in the session. The user continues in this state as long as they’re playing the game. When a title is first launched, it should check to see if the user is already a member of any sessions, typically by checking the session state. If the user is a session member, the title can go straight into the game and set any participating local members to the Active user state. A user should remain in the Active state while playing in the session. If a user leaves the session by using the in-game UI, they should be removed from the session by calling XblMultiplayerSessionLeave. If the user is only temporarily away from the game, as when the title is constrained, it should keep the user in the Active state for a reasonable amount of time. It’s appropriate to change the user state to Inactive if the user hasn’t returned after a title-specified time period.Inactive user state
In the Inactive state, the user isn’t currently engaged with the game but still has a saved slot in the session. In other words, the user is “not active.” It’s the user’s own console that’s responsible for setting them to the Inactive user state in the session. The arbiter can’t do this. Example scenarios where a user is put into the Inactive state include the following:- The title receives a Suspending event.
- The user has been inactive (no input or controller response) for a title-defined time period. We recommend two minutes for a competitive multiplayer game.
- The title has been in constrained mode for more than two minutes or for a title-defined time period. This constrained mode time-out period is the expected amount of time that a user might be away from the title for by using a related app or other experience related to the title.
- The user has been disconnected ungracefully from the session. For more information, see the MPSD change notification handling and disconnect detection section in the Multiplayer Session Directory overview topic.
User state when the session is over
When the session is over, gameplay is discontinued. The title must allow all users to remove themselves by using XblMultiplayerSessionLeave. The session activities that were associated with the users are automatically cleared when they leave the session. Return to the top of this topic.Visibility and joinability
Session access is controlled at the MPSD level by two settings: session visibility and session joinability. The visibility and joinability recommendations that we make in this topic apply to the most common title scenarios. Titles should follow these settings, if possible. They should use in-title logic to make the final, authoritative determination as to whether a new player is admitted into a session.Session visibility
Session visibility is represented by a constant that’s set at session creation. It’s typically defined in the session template and determines which types of users have read and write access to a session. The possible values for session visibility are defined by XblMultiplayerSearchHandleGetVisibility. The settings that are permitted for the visibility constant in a JSON file areopen, visible, and private.
Recommended game session visibility: open
Open game sessions don’t require player reservations, which simplifies the invite process. The arbiter doesn’t reserve players in MPSD after an invite has been sent, but only tracks invited players locally. As a result, players can immediately connect to the arbiter and determine whether they should join a session, are rejected, or should wait (if waiting players are supported). The arbiter is the ultimate authority. They respond and instruct the new member to either stay in or leave the session. Using open game session visibility requires the invited player to launch a title and connect to the arbiter before the final decision has been made. You can display an error message to the user if a session is full or if an invite has been rejected. To establish a connection to the arbiter, a secure device address is required. The XblMultiplayerSessionProperties::HostDeviceToken property is used to find out which session member is the current arbiter of a session and which secure device address an invited player should use for connection.
Session joinability
Session joinability determines which types of users can join a session. It can be set dynamically during a session. The possible values for session joinability are as follows.- None (default): There are no restrictions on who can join the session.
- Local: Only local users can join the session.
- Followed: Only local users and users who are followed by other session members can join the session without a reservation.
Session time-outs
Sessions can be changed by timers and other external events. Session time-outs define the periods for which session members can remain in specific states before they’re automatically made inactive or removed from the session. MPSD also supports time-outs to manage session lifetime.Time-out settings are made in
/constants/system/timeouts, or within the managed initialization object, for template contract version 104 or 105. For version 107 or later, the settings are made individually in /constants/system or within the managed initialization object.Session time-outs aren’t stacked. Only one is applied for a state transition against each session member on an update.
Currently defined time-outs
This section describes the time-outs that are currently defined by MPSD.- All time-outs are specified in milliseconds.
- A value of 0 is allowed and indicates an immediate time-out.
- A time-out with no value is considered infinite.
null for an infinite time-out.
evaluationTimeout
This time-out indicates the amount of time for a session member to make and upload the evaluation decision. If no decision is received, the decision counts as a failure. This time-out is placed in the managed initialization object.inactiveRemovalTimeout
This time-out is set for a session member who has joined a session but isn’t currently engaged in the game. By default, the member is removed from the session after two hours.This time-out is designated the inactive time-out for template contract version 104 or 105.
joinTimeout
This time-out indicates the number of milliseconds that a user has to join the session. Reservations are removed for users who fail to join the session. This time-out is placed in the managed initialization object.measurementTimeout
This time-out indicates the amount of time that a session member has to upload measurements. A member who fails to upload measurements is marked with a failure reason of “timeout”. This time-out is placed in the managed initialization object.During matchmaking, a 45-second time-out for QoS measurements is enforced. As a result, we recommend that you use a measurement time-out that’s less than or equal to 30 seconds during matchmaking.
readyRemovalTimeout
This time-out is set for a session member who has joined the session and is trying to get into the game. This usually means that the shell has joined the user on behalf of the title and it’s being launched. By default, the member is removed from the session and placed in the Inactive state after three minutes.This time-out is designated the ready time-out for contract version 104 or 105.
reservedRemovalTimeout
This time-out is set for a session member who has been added to the session by someone else but hasn’t yet joined the session. The reservation is deleted, and the member is considered inactive when the time-out expires. The default value is 30 seconds.This time-out is designated the reserved time-out for contract version 104 or 105.
sessionEmptyTimeout
This time-out indicates the number of milliseconds after a session becomes empty when it’s deleted. The default value is 0.This time-out is designated the
sessionEmpty time-out for contract version 104 or 105.Session time-out example
- A session is started with four players.
- Two players, A and B, are disconnected because of a power failure. Their status in the game remains Active.
- The other two players, C and D, quit properly by using XblMultiplayerSessionLeave.
- The session remains open. Players A and B are disconnected but are still in the Active state.
- A few days later, Player A returns and starts the game.
- Player A’s game checks for sessions that Player A is a member of (performs a read) and finds the orphaned session from a few days ago.
-
The session does a presence check against the two players who are still in the session (A and B).
- Because Player A is running the title, the presence check against Player A succeeds. The player’s Active state in the match stays the same.
- Player B isn’t running the title. As a result, the presence check for Player B fails. The service sets Player B’s state to Inactive. At this point, the inactive time-out starts for Player B.
- Player A exits the session properly by using the XblMultiplayerSessionLeave method.
- The inactive time-out expires for Player B, who is removed from the session on the next read or write that’s done by anyone.
- The session now has zero members and is removed from the service.
Multiple signed-in users on a single console
When multiple users are signed in on the same console, it’s possible for some users to be in a game session while other users aren’t in the session or aren’t active in the current title. Game invites can also be received and accepted for multiple users, having an effect on game session membership. Consider this information for your title so that it can correctly handle all session membership scenarios. In a common scenario, a new player signs in, becomes active in the game, and needs to be added to an existing game session. As with creating a new game session, a title should only add a user when it’s appropriate during gameplay. With multiple signed-in users, one or more users can also receive invites to another game session. Titles don’t need to handle these scenarios in any specific way. Session state and member events notify the title of any updates to the game session and user membership. To handle multiple signed-in users for an online session, the title subscribes for shoulder taps for all users, using a separateXboxLiveContext Class object for each user.
The title uses the XblMultiplayerSessionInfo::ChangeNumber property to determine particular changes in the session and ignore duplicate shoulder taps.
Return to the top of this topic.
Process lifecycle management
Just like a non-multiplayer title, a title in a multiplayer session can encounter title suspension and termination of process lifecycle events. As a result, the session arbiter should periodically save session state. In case the arbiter is suspended, the title should attempt arbiter migration and save the game state as appropriate. A new arbiter can then restore session state. It’s then possible for a full multiplayer session to be suspended and resumed later if the session is still valid in MPSD. Only one designated peer, typically the game host, should update the global game state.Storage of game metadata
A title stores game metadata in the MPSD session. Game metadata is the information that’s needed to display session data and enable the title to find and join the game session. The title stores player-specific metadata in the custom properties section for the session member. For example, player color and preferred player weapon for the session. Session-wide metadata, like current map, is stored in the global custom properties section of the MPSD session.Storage of game state
Game state is stored in TMS by using the Title Storage service. Storage using this location allows a title to migrate the arbiter without permission concerns. For more information, see Migrating an arbiter.The title shouldn’t attempt to save game state to TMS more frequently than once every five minutes unless it’s being suspended.
Cleanup of inactive sessions
IfsessionEmptyTimeout is set to 0, an MPSD session is automatically deleted when the last player leaves the session.
To learn how to prevent an unused session from containing players after a crash or disconnection, see the MPSD change notification handling and disconnect detection section in the Multiplayer Session Directory overview topic.
Improper handling of unused sessions after a crash or disconnection can cause issues when a title is querying sessions for a player.
We recommend that you clean up inactive sessions by having the title query all sessions for a particular user by calling XblMultiplayerGetSessionAsync and then evaluating the sessions.
When the title encounters a stale session, the title calls XblMultiplayerSessionLeave for all local players in the session.
This call eventually drops the member count to 0 and cleans up the sessions.
Return to the top of this topic.
Session arbiter
Some multiplayer methods should only be called by one client within a game session. This client is one of the consoles that’s participating in the session, called the arbiter, or the host. If at least one session member is in a game, the session should have an arbiter to monitor joins in progress.Setting the arbiter
When a session is created by the client, it designates one console as the arbiter. For more information, see the Set an arbiter for an MPSD session section in the Multiplayer tasks topic.Saving session state
As described in the Process lifecycle management section, the arbiter should periodically save session state. A new arbiter must be able to restore session state in the case of arbiter migration by the title. For more information, see Migrating an arbiter.Managing game session members and joins in progress
The most important role of the session arbiter is to manage users coming into the game session to play. This includes handling game invites, notifying waiting players, and working with players who quit the game.Receiving notifications
The arbiter must listen for new players who want to join the game session by using XblMultiplayerSessionChangedHandler.Finding players to fill empty game session slots
The arbiter finds players to fill empty game session slots by using one of the following operations.- If your title uses a lobby session or another mechanism to allow delayed joins, find new session members by using that mechanism.
- Create another match ticket session.
