As Xbox One titles enter Certification, compliance with Xbox Requirements (XRs) is verified through a series of test cases. The test cases for multiplayer gameplay represent a potentially complex set of scenarios. This white paper is intended to help title developers more successfully navigate multiplayer compliance as established in the XRs. It does not extend the XRs. Instead, it provides example high-level flow scenarios and some technical details related to the multiplayer XRs that can be used during title development and quality assurance testing. A minor revision to the previously published version, this update provides clarification and simplification of the test scenarios.
For more information on multiplayer flow or implementation, refer to the Xbox Live Multiplayer feature.
An in-game party invite occurs when a player invites a friend to join the party from within the title. The relevant XR for this scenario is XR-066, “Joining Parties.”
Example flow
Create a party.
Create an online game for the party.
From within the title, a player invites a friend to join the party, either by using the title-specific party invite flow or by using the Party app.
Expected behavior: The game successfully begins and can continue being played after the party invite has been sent.
Best practices
We recommend that titles provide a way for players to send party invites. The preferred method for doing so is to include an “invite to party” button that uses the Party Invite title-callable UI (TCUI).
Implementation notes
To handle party events a title should, at a minimum, subscribe to Party::PartyStateChanged and Party::PartyRosterChanged events. Monitoring these events will allow the title to detect party member and state changes.
It is still possible for a player to invite friends to the party by using the Party app. We’re recommending the best practice because the Party app may be less convenient than a title-specific implementation.
Join in-progress occurs whenever a player joins a party that is associated with active gameplay. The relevant XR for this scenario is XR-066, “Joining Parties.”
Example flow
Create a party.
Create an online game for the party.
Using the Friends app, another player joins the party.
Expected behavior: The new player joining the party should be pulled into the game at the appropriate time.
Best practices
Once a new party member has accepted the party invite, the game session arbiter (most commonly the host) should add the new party member to the session if the game and session state allow a new party member to join.
Implementation notes
To make join in-progress available for presence view in the Social app, the Multiplayer Session Directory (MPSD) session has to be linked to the current party with the Party::RegisterGameSessionAsync API. We recommend that only the arbiter performs this\ API call.
To handle party events a title should, at a minimum, subscribe to Party::PartyStateChanged and Party::PartyRosterChanged events. Monitoring these events will allow the title to detect party member and state changes.
Party scout refers to an initial player who attempts to bring the entire party into a game together. The relevant XRs for this scenario are XR-064, “Xbox Parties and Online Play,” and XR‑065, “Parties Play Together.”
Example flow
There are two scenarios to consider for party scouts:
Scenario 1: The party scout starts a multiplayer game in the title while another single player or multiple players are running a different title or app.
Expected behavior: Players who are in a different title get a system notification to change games. Players changing games are able to launch the title and subsequently be deep-linked to a section of the game where they can start gameplay immediately.
Scenario 2: The party scout starts a new multiplayer game in the title while another single player or multiple players are already running an instance of the title.
Expected behavior: Players who are already playing the existing instance of the title can be smoothly transitioned into the new title instance.
Best practices
Because platform notifications, also known as toasts, are only displayed if a title is not in focus, we recommend that titles implement a title-specific notification so that players are informed when a new game is available through the party. While implementing title-specific notifications, be mindful of all the XRs. For example, when transitioning to another title instance from a single-player instance, players should be able to save their progress as detailed in XR-023, “Confirmation of Destructive Actions or Data Loss.”
Implementation notes
When creating a new MPSD session, titles should add all available or possible party members to the MPSD session before the arbiter calls the RegisterGameSessionAsync method (or RegisterMatchSessionAsync). The arbiter should join the session and reserve slots for all other party members who are added to the session. After the new MPSD session is available, the arbiter should call Party::RegisterGameSessionAsync to register the session with the party.
When adding party members, if using XSAPI, call the AddMemberReservation method, setting the InitializeRequested property to true. This action allows for automatic system-joining, as well as Quality of Service (QoS) validation, and avoids potential race conditions.
A party of players, each of which might be playing various titles, can move together as a group into another game. The relevant XR for this scenario is XR-064, “Xbox Parties and Online Play.”
Example flow
There are several scenarios to consider for party game-changing activity. Various combinations arise depending on whether players are entering or exiting the title, and whether or not a player chooses to go along with the party during a title change.
Scenario 1 steps:
Start a multiplayer experience in the title.
Migrate the entire party to a new title.
Start a multiplayer game in the new title.
Migrate the entire party back to the original title.
Expected behavior: The players in the party can play together in both titles. Players get the system toast to “change party activity.” When changing to your title, the players are deep-linked into an experience where they can immediately start playing.
Scenario 2 steps:
Start a multiplayer experience in the title.
Migrate the party to another title and start a multiplayer game in the new title.
Only a portion of the players should accept the invite in Step 2, with some players remaining in the original title.
Expected behavior: All players finish their existing sessions, and both sessions can exist simultaneously.
Scenario 3 steps:
Start a multiplayer experience in another title (for example, through the PlayerRendezvous XDK sample).
A single player in the party launches an instance of your title and starts a multiplayer session.
Expected behavior: The player who started your title’s multiplayer game in Step 2 can decline the UI to join the other party members to the new title instance. Players should be able to continue matchmaking themselves.
Best practices
The notification process should be streamlined to avoid spamming players with redundant notifications when a party migration is available. Titles should ensure that the arbiter is migrated and that a valid arbiter is maintained when party members transition between titles.
Implementation notes
A title can verify the title ownership of a party by checking the PartyView.IsPartyInAnotherTitle property. It should use the Party::SwitchPartyTitleAsync API when the user enters the title’s multiplayer area and the party is not in the current title. This API will prompt the user through the TCUI, which a title should take into consideration.
A player can reject the title switch for the party, at which point a local party instance with only the local users will be created. The title needs to take this behavior into consideration and operate even if the PartyView.IsPartyInAnotherTitle property is true.
The testers will need an alternative title in order to test scenarios where the party migrates to or from another title. Developers who do not have multiple titles in their sandbox can work with their developer account manager (DAM) to ingest the PlayerRendezvous XDK sample into their sandbox.
Parties are a fundamental concept on Xbox One. All multiplayer experiences must provide a consistent party experience for players. The relevant XR for this scenario is XR-065, “Parties Play Together.”
Example flow
Multiple scenarios arise when players in a party enter matchmaking together. Titles should support the reserving of slots for party members when a scouting player enters matchmaking.
Scenario 1: A player acting as a scout starts matchmaking while the other party members are not running the game.
Expected behavior: The other players get the system notification when a suitable match is found. Players responding to the notification are able to launch the game and are subsequently pulled quickly into a suitable gameplay experience.
Scenario 2: A player acting as a scout starts matchmaking while other party members are currently running the game.
Expected behavior: Other players who are currently in the running title receive a title-specific match notification implemented by the title. Players should be able to respond to the notification and either join or decline the new game match.
Scenario 3: Multiple players simultaneously attempt to initiate matchmaking.
Expected behavior: The title should disambiguate the competing matchmaking requests and provide a consistent experience for all party members.
Best practices
If there is an existing match session registered with the party, the title should delete it and create a new one if a second matchmaking request occurs.
Get the MatchSession reference from the party.
Retrieve the actual match-session document from the MPSD.
Retrieve the ticket ID and hopper name from the appropriate location in the session document.
Call the matchmaking service to delete the ticket.
Wait for the MatchStatusChange event to return Cancel.
Create a new match session based on the second matchmaking request.
Call RegisterMatchSessionAsync again using a new match session.
Submit the match session to matchmaking to create a new ticket.
Implementation notes
All party members supported by the game mode should be added to the match session before the title calls Party::RegisterMatchSessionAsync, using the AddMemberReservation method with the InitializeRequested property set to true. Doing so allows for automatic system-joining as well as QoS validation, and it also avoids potential race conditions.
Party chat provides a general-purpose system chat implementation. Most multiplayer titles will provide their own game chat implementation to work with their own multiplayer experience. Because players can always use party chat, the transition between party chat and game chat should be tested thoroughly. The relevant XR for this scenario is XR-072, “Supporting Voice.”
Example flow
Players can switch back and forth between game chat and party chat in a multiplayer session.
Expected behavior: Multiple aspects of transitioning between game and party chat should be functional:
Party chat is functional between members of the party.
Game chat is functional between members of the party (or as implemented by the title).
Within the Party app, after party chat has been toggled on and off multiple times, game chat and party chat both remain functional and exclusive.
Best practices
To provide the best user experience, we recommend that titles adjust the chat encoding quality to be dependent on each player’s bandwidth. If a player has sufficient bandwidth available, the title should use high-quality encoding; otherwise, the title should use low- or medium-quality encoding.
A game chat library with source code is available as a full, Certification-compliant solution that can be integrated into a title. Titles should consider using this library or source code to minimize issues with party chat.
Implementation notes
Titles that choose not to use the provided library or source code should register and monitor the IChatSession::StateChangedEvent or IMMNotificationClient::OnDeviceStateChanged events to detect the state of party or game chat. Players’ privileges should always be verified through the Product::CheckPrivilegeAsync method. It is important to note that mute and do not play lists are not bidirectional.
A player can launch a title and find other players to play with through matchmaking. The relevant XRs for this scenario are XR-068, “Matchmaking Filtering by Reputation,” XR-069, “No Anonymous Matchmaking Between Blocked Players,” and XR-071, “Sponsored Users in Multiplayer Gameplay.”
Example flow
Multiple scenarios arise based on matchmaking compatibility; that is, based on whether or not players should be matched together.
Scenario 1: Compatible players are matched based on various matching criteria, such as game modes, required downloadable content (DLC), level/map choices, network address translation (NAT) types, and so forth.
Expected behavior: Players with compatible matching criteria are matched together.
Scenario 2: Incompatible players are not matched together.
Player reputation is considered during matchmaking.
Expected behavior: A player with a bad reputation should not be matched with a player who has a good reputation.
Use the party’s avoid list for matchmaking. The party’s avoid list should be constructed as the set theoretical union of all the avoid lists for individual party members. This conservative choice for the avoid list will be consistent with the avoid list of any individual party member.
Expected behavior: Each individual player’s avoid list is respected.
Best practices
Using criteria beyond the bad reputation flag to match players with each other can result in better matchmaking experiences. Titles should consider this approach when looking for matchmaking improvements.
If a title uses a custom matchmaking service, it should mimic the flow of the Xbox Smart Match ticket submission system. The service should cache a party’s blocklist on the server to minimize Xbox Live service calls.
Implementation notes
A title or custom matchmaking service can check bad reputation through the OverallReputationIsBad property. This is automatically handled for titles using Smart Match.
If a title uses custom title-based matchmaking, the blocklist for all players in the party can only be obtained through a service-to-service call.
In Xbox Live multiplayer game modes, an Xbox Live user can allow a friend to play as a guest on the same console. The relevant XR for this scenario is XR-071, “Sponsored Users in Multiplayer Gameplay.”
Example flow
Expected behavior: The presence of a guest accompanying an Xbox Live user does not impact matchmaking, party, or other scenarios described above.
Expected behavior: A guest cannot participate in an Xbox Live multiplayer experience unless he or she is accompanied by the Xbox Live user.
Best practices
Titles should verify the user type of every local user. Guests should only be considered to be valid users while the sponsoring user is signed in. Titles should provide a visual affordance for a guest to join a party.
Implementation notes
Titles should check a guest’s chat privileges through the Product::CheckPrivilegeAsync method and add the guest user to the party through Party::AddLocalUsersAsync.
The Xbox Requirement XR-47, “User-Profile Access,” specifically states that users must be given the option to access another user’s gamercard wherever that user’s display name is selectable. The best practice expands this requirement to ensure that such UI is exposed for all players with whom a user interacts, in particular, to support muting and reputation.
Example flow
Review all instances of displayed player names within the title.
Expected behavior: A player can select and view a gamercard for every instance of a player’s display name.
Best practices
Although it is not a requirement for certification, we recommend that titles also provide a player-feedback mechanism that can be invoked for every instance of a displayed player name.
Implementation notes
Use the ShowProfileCardAsync API to display a user’s gamercard and provide additional feedback through the reputation service.
Multiplayer-specific telemetry (along with all other required events) is appropriately instrumented with appropriate process lifetime management (PLM) and error-case handling. The relevant XR for this scenario is XR-053, “Instrumentation of Common Events.”
Expected behavior: PlayerSessionEnd and MultiplayerRoundEnd events should occur when a title is suspended or constrained by the user.
Best practices
Titles should consider including additional data beyond basic multiplayer round and session start events to review player behavior in the title. This will allow for future title or flow improvements and the creation of new achievements.
Titles should always fire events about sessions and multiplayer rounds during all flows, including error and PLM suspend flows.
Implementation notes
Titles use the EventRegister and EventWrite methods to send XDP events. MultiplayerRoundEnd, MultiplayerRoundStart, PlayerSessionEnd and PlayerSessionStart events are used for multiplayer session and round tracking.
Contact your DAM to configure access to Xbox One Data Platform event logs on Xbox Developer Insights (XDI).
Rich presence refers to the display of a user’s current state, and titles are required to provide multiplayer-specific presence updates. The XR relevant to this scenario is XR-049, “Rich Presence.”
Best practices
Titles should consider providing dynamic rich presence information. For example, rich presence can include the multiplayer level, mode, and so forth.
Implementation notes
A title should use the PresenceService::SetPresenceAsync method to simplify setting the rich presence information, but it can also use the equivalent RESTful endpoint. Stats are used to create dynamic rich presence information.
When all players have left a game session, the session is “cleaned up” to avoid ghost or otherwise inactive sessions. The XR relevant to this scenario is XR-067, “Synchronizing Session Information.”
Best practices
Titles should always remove the local players from the session when a game ends. The arbiter should unregister the session with the party when the last member has left.
Sessions can be left “orphaned” due to various improper termination scenarios, such as power outages, network failures, or title crashes. In such cases, the session cannot be cleaned up by the title. Therefore, a title should always query for all of a signed-in user’s sessions during startup, and then clean up any orphaned sessions returned by the query.
Implementation notes
When an individual player exits the match or game session, or gameplay has finished, remove the user from the session by calling the Leave method.
If a user is the last remaining party member to leave a session, call Party::RegisterMatchSession or Party::RegisterGameSession with a nullptr.
For detailed XR descriptions and test requirements, refer to the Xbox One Certification Requirements available on XGD. The flows that have been discussed in this white paper provide supplemental information and are not intended to replace or extend the XRs.