Refine Matchmaking with Skill, Data Settings, and Queries (Deprecated)
Updated: Sep 21, 2023
For more information on the deprecation of this API, click here. Third-party solutions, such as Photon, can be used as an alternative to implement matchmaking in your app. For an example of how Photon, and other third-party solutions integrate with the Platform API, check here. 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 Meta Quest dashboard. Following is an example of a list of matchmaking pools.
To add a skill component to a matchmaking pool, navigate to the
Developer Dashboard. Select your app, then navigate to the
Platform Services > Matchmaking page. Choose
Skill Components under
Matchmaking and click
Create Skill Component.
Enter:
- A Skill Component Key (to identify your component in code)
- A Luck Factor
- A Draw Probability
- Skill Resets
- Click Save and Deploy
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.
Incorporate code to start a match 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:
ovr_Matchmaking_StartMatch()ovr_Matchmaking_ReportResultInsecure()
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:
- Find the pool in the list of matchmaking pools and click the ellipses (…) and select Manage Queries. The following image shows an example.
- On the Matchmaking Queries page, click Edit Data Settings.
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.
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.
Enter:
- Query Key - This is the unique string that you will use to reference this Matchmaking Query in code. The Query Key is case-sensitive, and the name you define in the Dashboard must exactly match the key you reference in your code. Click Add Expresson and then enter:
- Importance - You will configure an importance for the defined expression. A passing expression evaluates to a quality value of 1. A failing case evaluates to the importance value specified in the following table. Match-on-failure delay times below are calculated based on a rampdown time of 30 seconds. The greater the importance, the less likely a match will occur if the expression fails. And in the case of expressions with Required importance, a failure will never result in a match. The following table lists the importance string, the associated value and approximate match on failure time for that importance.
| Importance | Value | Match on Failure Time |
|---|
Required | 0 | N/A. Never matches on failure. |
High | ~.55 | 27 seconds |
Medium | ~.75 | 15 seconds |
Low | ~.9 | 6 seconds |
- Expression - The Expression defines the criteria for a match. You can define that a data setting must in a range of values or match the other users data setting.
Adding Matchmaking Queries and Other Enqueue-Time Data
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.
Data Settings and Queries Example
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:
player_level (INTEGER)game_mode (STRING)map_size (INTEGER_BITSET)
Then, create a Matchmaking Query called my_query for my_pool, with the following query expressions:
- Their “player_level” is equal to my “player_level”. Importance: Medium
- Their “game_mode” is equal to my “game_mode”. Importance: Required
- Their “map_size” is a bitmask AND of my “map_size”. Importance: Required
In the game, map_size bitmask has the following bit meanings:
- 0x4: large map size
- 0x2: medium map size
- 0x1: small map size
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 CreateRoom2 and CreateAndEnqueueRoom2.
MatchmakingOptions_SetCreateRoomMaxUsers will override the value of “Max Users” for a Pool of the Developer Dashboard.
Note: You can not exceed the ‘Max Users’ value that you set when creating your Pool.MatchmakingOptions_SetCreateRoomJoinPolicy will 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 Enqueue2, EnqueueRoom2, and Browse2.
MatchmakingOptions_AddEnqueueAdditionalUser sets 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_SetEnqueueDataSettingsInt sets an integer Data Setting.MatchmakingOptions_SetEnqueueDataSettingsDouble sets a double Data Setting.MatchmakingOptions_SetEnqueueDataSettingsString sets a string Data setting.MatchmakingOptions_SetEnqueueIsDebug if true, debug information is returned with the response payload. See “Debugging” section for more information.MatchmakingOptions_SetEnqueueQueryKey specifies 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 player_level=10, game_mode="CaptureTheFlag", and 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.
