All Oculus Quest developers MUST PASS the concept review prior to gaining publishing access to the Quest Store and additional resources. Submit a concept document for review as early in your Quest application development cycle as possible. For additional information and context, please see Submitting Your App to the Oculus Quest Store.
Note: You are viewing the Unity version of this topic. To view this topic for native development, see Skill, Data Settings and Queries for Matchmaking (Native). To view this topic for Unreal development, see Skill, Data Settings and Queries for Matchmaking (Unreal).
You can make your matches more precise by adding a skill component or asking the user for data and using this data to set up queries the system uses when making matches. You access data settings and queries by creating a pool and then modifying it in the Oculus dashboard. Following is an example of a list of matchmaking pools.
To add a skill component to a matchmaking pool, navigate to the Matchmaking page on the developer dashboard. Choose Skill Components under Matchmaking and click Create Skill Component.
Next associate the skill component with a matchmaking pool. Navigate to the pool you created for your game and select View/Edit Pool, then select the skill component and save your matchmaking pool.
Once you have saved the pool with the skill component, you can add to your game. To do this you’ll need to add two methods to your code:
The matchmaking service will now track and account for the user’s skill when determining the quality of a match.
Data Settings are the key/value pair data that the enqueuing player or room provides about itself at enqueue time. Data Settings can be used both to determine what a player is looking for in a match, as well as what a player looks like to another player. For example, if a player may be enqueued with the type of match they want to play, the map they want to play on, and the level they have achieved in the game. You may also use data settings to ensure that matches are only made with users who are using the same version of your app.
To modify the data settings for a pool, you will navigate to the Matchmaking Queries page. To do this:
You define a data setting as a key/value pair. The key should be unique and is used to reference the data setting in queries and in code. The value can be of type double, integer, a hex bitset or a string enumeration. You also provide a default value, which is used if the user does not provide a value.
You can learn more about data settings and how to apply them to users or rooms at enqueue time in the Adding Queries and Other Enqueue-time Data section.
Matchmaking queries are defined on matchmaking pools that you have created in in the developer dashboard. Queries enable you to set criteria that determines whether enqueued players and rooms are matched with each other. Queries compare the data settings of potential matches.
A Matchmaking Query is composed of one or more expressions to make a conditional statement. The Matchmaking service populates each expression with the specified match candidate data settings, and uses them to determine the quality of the potential match. See the How Matchmaking Works section of the Matchmaking Intro for more on how this information is used for matches.
To add a Matchmaking Query Expression to a Matchmaking Pool, navigate to in the Developer Dashboard, and navigate to the Matchmaking Queries page. To do this, click the ellipses (…) for the Pool, and select Manage Queries.
|Importance||Value||Match on Failure Time|
|Required||0||N/A. Never matches on failure.|
You can further configure the matchmaking service and use queries to compare potential matches. Some matchmaking requests accept an optional
ovrMatchmakingOptionsHandle that allow you to pass data settings and other enqueue specifics to be used when finding matches.
The following example demonstrates how Data Settings and Matchmaking Queries can be used. To complete the example, in the developer dashboard create a matchmaking pool called
my_pool, and enter the following Data Settings:
Then, create a Matchmaking Query called
my_pool, with the following query expressions:
In the game,
map_size bitmask has the following bit meanings:
Integrate the Matchmaking Queries in Code
First, create an instance of the
MatchmakingOptionsHandle by calling
MatchmakingOptions_Create(). When you’re finished with the handle, you can call
MatchmakingOptions_Destroy() to free the memory.
After you’ve created the handle, you’ll populate the user or room enqueue message with the data settings for the room or user.
Setting Data for a Room
Setting data for a Room during the create room process is available when calling
MatchmakingOptions_SetCreateRoomMaxUserswill override the value of “Max Users” for a Pool of the Developer Dashboard.
MatchmakingOptions_SetCreateRoomJoinPolicywill specify a join policy for the created room. If not provided, the join policy defaults to everyone.
Setting Data for a User
Setting data for a user during the enqueue processes is available when calling
MatchmakingOptions_AddEnqueueAdditionalUsersets additional users, using their userID, at enqueue-time as users to be added to a multiplayer session. Additional users will not receive notifications when they are enqueued, only when a match is made.
Note: Once the users are matched, you may then want to team people up based on their original groupings. You would loop through the matched users using
Room_GetMatchedUsers. Then, within each of those, call
MatchmakingEnqueuedUser_GetAdditionalUserIDsSize. If anybody has more than 1, loop through those using
MatchmakingEnqueuedUser_GetAdditionalUserID, and place those users on the same team.
MatchmakingOptions_SetEnqueueDataSettingsIntsets an integer Data Setting.
MatchmakingOptions_SetEnqueueDataSettingsDoublesets a double Data Setting.
MatchmakingOptions_SetEnqueueDataSettingsStringsets a string Data setting.
MatchmakingOptions_SetEnqueueIsDebugif true, debug information is returned with the response payload. See “Debugging” section for more information.
MatchmakingOptions_SetEnqueueQueryKeyspecifies a specific Matchmaking Query for filtering potential matches.
Example Integration Setting Enqueue-Time Data
Using the example data we defined earlier, the following native C++ example shows a user being enqueued in the matchmaking service to be matched with other players with Data Settings
map_size is large.
ovrMatchmakingOptionsHandle matchmakingOptions = ovr_MatchmakingOptions_Create(); ovr_MatchmakingOptions_SetEnqueueDataSettingsInt(matchmakingOptions, "player_level", 10); ovr_MatchmakingOptions_SetEnqueueDataSettingsString(matchmakingOptions, "game_mode", "CaptureTheFlag"); // I want large or medium map size ovr_MatchmakingOptions_SetEnqueueDataSettingsInt(matchmakingOptions, "map_size", 0x4); // Specify which Matchmaking Query to use with the Data Settings we provided ovr_MatchmakingOptions_SetEnqueueQueryKey(matchmakingOptions, "my_query"); ovr_Matchmaking_Enqueue2("my_pool", matchmakingOptions); // Destroy the matchmaking options now that we are done with it ovr_MatchmakingOptions_Destroy(matchmakingOptions);
Finally, you will need to test and troubleshoot your matchmaking implementation. For more information, review Testing and Tuning.