Meet rule-based matchmaking in Game Center

Welcome. My name is Philip Smith. I'm an engineer on the Game Center Services team.

I'm going to be sharing with you a new rule-based matchmaking feature in Game Center.

This feature provides customized matchmaking for your game, which will improve the quality of matches for a more engaging and fair gaming experience.

I will start with a brief overview of Game Center matchmaking functionality that allows players of realtime multiplayer games to discover and connect with other players.

Then I'm going to share how to set up rule-based matchmaking.

Let's dive in.

Matchmaking is all about giving your players a fun and engaging experience. If your players are engaged, then you are going to retain those players for a longer time.

Now, every game is unique and so there are many different matchmaking use cases.

You may wish to create unique game modes with their own rules for a personalized gaming experience, or ensure fair and balanced matchups by grouping players based on skill level or preferences so you can avoid mismatched games that lead to frustration or boredom.

Some game modes may involve teams playing each other where you want to have balanced teams so the experience isn't one-sided.

Another use case is to set up private matches for friends or a wider social group using a party code. But nothing can be more frustrating than having to wait a long time to get a match. So it is important to be able to relax constraints in order to balance wait times against match quality.

With Game Center Classic matchmaking, you can already enable your players to discover and connect with others in real time multiplayer games.

But now with rule-based matchmaking, you are going to be able to do so much more.

You will be able to provide custom rules for fair and balanced matches with the ability to relax constraints with time and easily update rules to adjust to actual patterns of use.

Now let's take a look at how the parts of the matchmaking system work together.

The classic Game Center matchmaking system is a black box about how players are matched. In this example, Alice and Bob want to play now.

The game, through GameKit, submits a match request. The GameKit API allows the game to restrict matches to requests with the same player group. As soon as Game Center finds a match, GameKit is notified and proceeds to create a realtime connection between the devices. Today I'm gonna open up the black box to share more specifics about rule-based matchmaking to allow you to customize how players are matched in your game for a better player experience.

I can now use the App Store Connect API to configure rules to best suit my game. On the game side, GameKit SDK provides APIs for me to specify the match request queue along with custom properties for a player to be used by my rules.

Game Center service periodically runs an algorithm to find matches between requests in my queue using my rules.

When a match is found, GameKit is notified and proceeds to create a real-time connection between the devices.

With rule-based matchmaking, Game Center provides a matchmaking framework where I can configure queues and rulesets customized for my game. I can use a powerful rules language to express matchmaking constraints. And GameKit provides new APIs for my game to include custom player properties to be used by my rules.

Also provided are developer tools to allow me to test out my rules with sample requests and get metrics to help me understand real player experience.

I will walk you through how to configure, test and observe rule-based matchmaking.

There are six steps to set up rule-based matchmaking. Let's look at them one by one. The first step is to prepare to use the App Store Connect API.

The rules configuration is achieved using REST endpoints of the App Store Connect API. And if you're familiar with this, it should be straightforward for you.

To access the APIs you need to create a private API key using your organization's App Store Connect account. Calls to the API require a JSON web token for authorization. Please see the Apple developer documentation on how to create API keys for App Store Connect API and how to generate authentication tokens. Next, let's cover the steps for creating rulesets and adding rules to customize matchmaking.

The use case I'm exploring for my game is skill-based matchmaking. Being matched with players of a similar skill level leads to a better gaming experience. However, if I enforce a strict maximum skill difference, a player could be waiting to match for a long time. I think it is a better experience if I can balance wait time against skill difference by relaxing the maximum skill difference the longer I wait. Rule-based matchmaking allows me to loosen constraints over time in order to balance match quality against wait time.

In this example, I have three players in my queue with different skill levels. I think a good match for my game is for players to have a skill value difference of 20 or less, but at this moment there are no players that satisfy this constraint.

What I would like is after waiting for five seconds to expand the required maximum skill difference to be 40. Now it looks like the players with skills 20 and 45 will match.

But for my example, I'm gonna say the player with a skill of 45 drops out and cancels their request, leaving the remaining players with no match.

Again, I would like to expand the skill range after waiting, say, another five seconds to 100, the maximum possible skill difference for my game to make sure players get a match. Well now we have a match. So although my players had to wait, they do get a match and can enjoy playing a game. Next time I'm sure they will match with a player closer in skill.

I use the App Store Connect API endpoints to configure rulesets and rules for my organization. I used the GameCenterMatchmakingRuleSets endpoint to configure a ruleset.

And for my game I created a ruleset called SkillBasedRules.

I add rules to my ruleset using the GameCenterMatchmakingRules endpoint. Now my game has different app versions that aren't compatible, and so I also add a rule to require matches only for compatible app versions.

I add another rule to prefer players with lower latency.

Finally, I add a rule to require all matched players to have a skill value within a given range. Going into more detail on the request content, here I first create a ruleset to contain the rules, passing in a reference name, the minimum number of players, and the maximum number of players.

All these properties are specific to my game. rulesets and queues are associated with the App Store Connect provider organization, and so we recommend using a reverse domain name prefix of the game bundle ID for the ruleset name to avoid any name clashes.

Here's the response which contains the ID of the newly created ruleset. I will need this in subsequent API calls to add a rule and create a queue.

The next step is to add a rule using the GameCenterMatchmakingRules endpoint. I'm just going to show the details of the SkillDifference rule for now.

Add the rule to the ruleset we just created, referencing the ID from the last response.

Make the rule type match.

Add a description.

Give the rule a name.

And most importantly, an expression to be evaluated.

The expression grammar is an open source JSON query language called JMESPath.

Let's dive into this expression a bit.

You can see this is a comparison where we're making sure the left hand side value is less than or equal to the right hand side.

The left hand side is a diff function, which calculates the difference between the lowest and highest skill level from the current candidate requests.

The right hand side is a fixed value of 20.

Now this expression requires match requests to have a maximum skill difference of 20. And this expression is okay for initial testing, but I think in real use I will find some players are waiting a long time for a match.

What I want is to expand the skill range as requests age so that my players match in a reasonable time and are able to enjoy a game. To do that, I need to use a different expression.

To update a rule, I use the GameCenterMatchmakingRules endpoint with a PATCH method.

The URL and content for this operation require the ID of the rule.

An updated description is included and an updated expression. This one should work a lot better.

Here I have a more complex expression.

We have the same left hand side and comparison.

The right hand side is now a function called agedValues that will expand the skill range based on the average age of the candidate requests. The first parameter is the average age of the candidate requests.

Then the next parameter is the initial skill range of 20 I want to enforce when the age of the requests are less than five seconds.

The next parameter is an array of expanded skill range values, where 40 indicates the first skill range expansion where the age is greater than or equal to five seconds and less than 10 seconds, and 100 indicates the second expansion where the skill range is increased to 100 when the age is greater than or equal to 10 seconds.

Finally, the last parameter is an array of age value boundaries where the skill range will get expanded, which we have configured to be five seconds and 10 seconds.

Now I'm going to test the ruleset to make sure it is working as intended.

The App Store Connect API gameCenterMatchmakingRuleSetTests is provided to allow testing and validation of rules before integration with your app.

The content required for the endpoint is quite verbose and it is helpful to hide the complexity by using a script that accepts much simpler input and allows for a more efficient way to test rules.

Check the list of resources for this video to download the Python script.

All the details on using the App Store Connect API, including the GameCenterMatchmakingRuleSetTests endpoint may be found in the Apple developer documentation for the App Store Connect API. Here is an example of the use of the testrules Python script.

I'm running the script using the ID of the ruleset I created earlier and we have a queue with three requests. Now the first request has a skill of 10 and is brand new in the queue. The second request has a skill of 50 and has been in the queue for five seconds. The third and last has a skill of 90 and has been in the queue for 10 seconds. Now recall, I set up my rules to require a skill difference of 20 or less for new requests, 40 for requests that have been in the queue for longer than five seconds. Will the first and second request match? I don't think so, because the skill difference is more than 20.

Will the second and third requests match? Yes, they have a difference of 40 but have been in the queue for five seconds.

And the output shows the second and third requests have matched, and so my rules are working as expected.

Of course, I will run more test cases to make sure my rules are good.

The next step is to configure a queue for requests.

If you recall where I left off with the configuration, I had created the ruleset and rules.

I just tested the rules and they are working as I expected. Now I use the GameCenterMatchmakingQueues endpoint to create a queue for my app requests associated with my ruleset. Here I have called it skill queue.

Here in more detail is the content required to create a queue linked to the ruleset I created earlier. I reference the ruleset ID and provide a suitable name for the queue. I use the reverse domain name prefix for the queue name just as with the ruleset name.

And that is all the App Store Connect API configuration for my matchmaking rules.

Next, I will cover the code to add to an app to integrate with rule-based matchmaking.

Use the existing GameKit framework classes, GKMatchRequest, and GKMatch.

These have new object properties, queueName and properties to support rule-based matchmaking.

In my app, I add code to create a GKMatchRequest object and set the matchmaking rule properties to use the skill level queue and its set of rules to find players.

I set the queue name property to the reference name of the queue I previously created. I set the GKMatchRequest properties to a dictionary of key value pairs that provide values that are used in my rule expressions.

My rules only use the one property for the local player's skill value.

I submit the match request using the GKMatchmaker method to find a match without presenting a user interface. You might alternatively present the GKMatchmaker view to find a match.

The last step is to observe how your matchmaking rules are working with actual players.

You can diagnose problems with your matchmaking rules using the App Store Connect API Metrics endpoints. Metrics include request counts by outcome. Those can be matched, canceled, or expired. The time taken to reach an outcome. And how many active requests in a queue. There are also metrics on rule evaluation errors and results. You can get these metrics data at different time granularities, every 15 minutes for eight hours, hourly over 24 hours, or daily for 30 days.

If Game Center takes too long to find matches or fails to find matches, see the Apple developer documentation article, Troubleshooting Matchmaking Rules Using Metrics.

In this example, the query is to return the count and time in the queue of requests with a granularity of one day. The response contains data points with a datetime range and metrics values.

And with some scripting magic, I can turn the response data into charts that allow me to see how successful are players using my matchmaking rules.

Well, that concludes our update on rule-based matchmaking.

This new feature is available now. I hope you'll use this great new capability.

Check out the Apple developer documentation to find out how to use all its features.

We'd love to hear from you. If you have any feature requests for Game Center, please let us know through Apple's Feedback Assistant. Thanks for joining me today.