Skill, Data Settings and Queries for Matchmaking

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.

Adding Skill Matches

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.

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:

• Native - ovr_Matchmaking_StartMatch()

• Unity - Platform.Matchmaking.StartMatch() `

• Native - ovr_Matchmaking_ReportResultInsecure()
• Unity - Platform.Matchmaking.ReportResultInsecure()

The matchmaking service will now track and account for the user’s skill when determining the quality of a match.

Data Settings

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.

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

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.

• 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 ovrMatchmakingOptionsHandle by calling ovr_MatchmakingOptions_Create(). When you’re finished with the handle, you can call ovr_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.

• ovr_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.
• ovr_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.

• ovr_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 ovr_Room_GetMatchedUsers. Then, within each of those, call ovr_MatchmakingEnqueuedUser_GetAdditionalUserIDsSize. If anybody has more than 1, loop through those using ovr_MatchmakingEnqueuedUser_GetAdditionalUserID, and place those users on the same team.

• ovr_MatchmakingOptions_SetEnqueueDataSettingsInt sets an integer Data Setting.
• ovr_MatchmakingOptions_SetEnqueueDataSettingsDouble sets a double Data Setting.
• ovr_MatchmakingOptions_SetEnqueueDataSettingsString sets a string Data setting.
• ovr_MatchmakingOptions_SetEnqueueIsDebug if true, debug information is returned with the response payload. See “Debugging” section for more information.
• ovr_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 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);       

Next Steps

Finally, you will need to test and troubleshoot your matchmaking implementation. For more information, review Testing and Tuning.