Match Listing
Where the matchmaker can be used by players to find opponents (or teammates) to play with in a new match, match listing is used to show players currently active matches that they can join right away.
You can use match listing to simply return any given number of active matches, but using the match label to query active matches and filter the results according to your player’s desired criteria will provide more relevant matches and a more engaging user experience.
In addition the a match label, you can filter results by their authoritative status and player count. See the function reference for all available parameters.
Filter vs. query
There are two ways of using match label fields to list results: exact-match filtering and querying.
For example, if we want to list matches with a label skill=100-150, exact-match filtering would be as follows:
Remember that here we are filtering based on the string value of the label, so results will only include matches with the exact label skill=100-150. A match with label skill=100 or skill=150 would not be returned.
While any returned result would be precisely what the player is searching for, this can lead to frustration when no matching results are found at all.
The alternative would be using a query to list available matches filtered based on our desired criteria, in this case a range in skill:
With this method, the results will include any match will a skill label between 100 and 150, inclusive.
Learn how to use the query syntax grammar to filter and sort results.
Find or create
To provide a seamless gameplay experience for your users, if match listing fails to return any matching results you can create a new match for the user directly.
Using our filter example from above:
The same can be done when querying matches as well:
Examples
Player count
The minSize and maxSize parameters can be used to list only matches containing the specified number of players. This can be useful for returning results that are already nearly full (and so the match is almost ready to start).
For example, let’s assume a match will begin once 8 players join so we’ll only list matches with between 5-7 players: