Example scenario
John wants to play a battle arena multiplayer game, but he wants to play a game where all the users select their hero randomly. He can retrieve a list of open game sessions and find the ones that include “random heroes” in their description by using multiplayer session browse. If the UI of the title has the option, he can select the “random hero” game mode and retrieve only the sessions that are tagged to indicate that they’re “RandomHero” games. When John finds a game session that he likes, he can join that session. After enough people have joined, the host of the game session can start it.Roles
A session that’s in the multiplayer session browse feature might specify that it’s recruiting users for specific roles. For example, a user might want to create a game session that specifies that it contains no more than five assault classes, but it must contain at least two healer roles, and at least one tank role. When another user applies for the session, they can pre-select their role. The service then decides if they can join the session based on how many open slots that are available for the selected role. If a user wants to reserve two slots for their friends to join, they can designate a “friends” role for the session, and only users that are friends with the host can fill the two slots that are dedicated to the “friends” role. For more information about roles, see Multiplayer roles.How multiplayer session browse works
Session browse works by using search handles. A search handle is a packet of data that contains a reference to the session, as well as additional metadata about the session, such as search attributes. When a title creates a new game session that’s eligible for multiplayer session browse, it creates a search handle for the session. The search handle is stored in the Multiplayer Service Directory (MPSD), which maintains the search handles for the title. When a title needs to retrieve a list of sessions, the title can send a search query to MPSD, which returns a list of search handles that meet the search criteria. The title can then use the list of sessions to display a list of joinable games to the user. When a session is full, or otherwise can’t be joined, your title can remove the search handle from MPSD so that the session doesn’t show up in multiplayer session browse queries.Search handles are used when displaying a list of sessions to a user.
Set up a session for multiplayer session browse
To use search handles for a session, the session must havesearchable and userAuthorizationStyle set to true.
The userAuthorizationStyle capability is only required for UWP games, but we recommend implementing them for all XBOX games, including Microsoft Game Development Kit (GDK) games. This ensures future portability for your title.
Configuring
userAuthorizationStyle to true changes the readRestriction and joinRestriction of the session to local instead of none. This means that titles must use search or transfer handles to join a game session.For multiplayer session browse, only create search handles on sessions that are used for actual gameplay. Don’t use them for lobby sessions.
Game session ownership
Many game session types, such as SmartMatch or a friends-only session, don’t require a host or owner. However, when setting up multiplayer session browse games, you might want an owner. Having an owner-managed session has some benefits for the host, such as removing other members from the session or changing the ownership status of other members. To use owners for a session, the session must havehasOwners set to true.
When using Multiplayer roles, you can set it so only owners can assign roles to users.
If an owner of a session has an XBOX member blocked, that member can’t join the session.
ownershipPolicy.migration policy that’s defined for the session.
If the policy is “oldest”, then the user that has been in the session the longest is set as the new owner.
If the policy is “endsession” (the default, if one isn’t supplied), then the service ends the session and removes all the remaining users from the session.
Search handles
A search handle is stored in MPSD as a JSON structure. In addition to containing a reference to the session, search handles also contain additional metadata for searches, known as search attributes. A session can only have one search handle that’s created for it at any time. To create a search handle for a session by using the XBOX Services API (XSAPI), call the XblMultiplayerCreateSearchHandleAsync method.Search attributes
Search attributes consists of the following components.-
The
tagsare string descriptors that people can use to categorize a game session, like a hashtag.- Tags must start with a letter, can’t contain spaces, and must be less than 100 characters.
- Example tags: “ProRankOnly”, “norocketlaunchers”, “cityMaps”.
-
The
stringsare text variables.- String names must start with a letter, can’t contain spaces, and must be less than 100 characters.
- Example string metadata: “Weapons”=“knives+pistols+rifles”, “MapName”=“UrbanCityAssault”, “description”=“Fun casual game, new people welcome.”
-
The
numbersare numeric variables. The XSAPIs retrieve number values as type float.- Number names must start with a letter, can’t contain spaces, and must be less than 100 characters.
- Example number metadata: “MinLevel” = 25, “MaxRank” = 10.
The letter casing of tags and string values is preserved in the service, but you must use the
tolower() function when you query for tags. This means that tags and string values are currently all treated as lowercase, even if they contain uppercase characters.Additional details
When you retrieve a search handle, the results also include useful data about the session, such as if the session is closed, and if there are any join restrictions. In the XSAPIs, these details, along with the search attributes, are included in theXblMultiplayerSearchHandle results that return after a search query.
Remove a search handle
When you want to remove a session from multiplayer session browse, such as when the session is full or closed, you can delete the search handle. In the XSAPIs, remove a search handle by using the XblMultiplayerDeleteSearchHandleAsync method.Create a search handle with metadata
The following code shows how to create a search handle for a session by using the XBOX multiplayer APIs.Flat C
Create a search query for sessions
When retrieving a list of search handles, you can use a search query to restrict the results of the sessions that meet specific criteria. The search query syntax is an OData-style syntax, with only the following operators that are supported.You can also use lambda expressions and the
tolower canonical function.tolower function in the search query.
The service only supports searching for lowercase strings.
The XBOX service only returns the first 100 results that match the search query.
Ensure that users can refine their search query if the results are too broad.
Logical
OR statements are supported in filter string queries.OR is allowed, and it must be at the root of your query.
You can’t have multiple OR statements in your query, nor can you create a
query that would result in OR not being at the top-most level of the query structure.
Search handle query examples
In a restful call, “Filter” is where you specify an OData Filter language string that’s run in your query against all search handles. In the multiplayer 2015 APIs, you can specify the search filter string by using thesearchFilter parameter of the XblMultiplayerGetSearchHandlesAsync method.
The following filter scenarios are currently supported.
Refreshing search results
Your game should avoid automatically refreshing a list of sessions. Give the user the option to manually refresh the list by using the UI. This is helpful if the user refines their search criteria to better filter the results. If a user attempts to join a session, but that session is full or closed, then your game should refresh the search results, as well.Too many search refreshes can lead to service throttling.
Query for search handles
The following code shows how to query for search handles. The API returns a collection ofXblMultiplayerSearchHandle objects that represent all the search handles that match the query.
Flat C
Join a session by using a search handle
After a user has retrieved a search handle for a session that they want to join, ensure that they can add themselves to the session by using XblMultiplayerWriteSessionByHandleAsync.The XblMultiplayerWriteSessionAsync methods can’t be used to join a multiplayer session browse session.
