Queues and pools
Control how matchmaking tickets are grouped, filtered, and matched in your game with queues and pools.
Read time 2 minutesLast updated 3 days ago
Queues and pools are important components for customizing matchmaking in your game. Queues let you separate tickets by game mode or ruleset, while pools provide an additional level of filtering within a queue, so you can target specific platforms, regions, or other player attributes.
Queues
A queue contains a mutually exclusive set of tickets that you can match together. Tickets in a queue are not matched with tickets found in another queue. This behavior is useful when building a game with discrete game modes that don't overlap, such as Team Deathmatch, Free-For-All, and Capture the Flag, or where the type of game is different, such as a competitive game with ranked and unranked modes.
Default queue
The default queue serves as a fallback queue if the ticket created doesn't specify the name of the queue. This fallback method allows you to dynamically switch to the default queue after the game goes live without changing the game client.
This ability to fall back to the default queue also supports legacy versions of Matchmaker where the game clients do not specify queue names. Therefore you do not need to update your game client to include a queue name when migrating your services.
Pools
A pool represents a dynamic separation of tickets within a queue. Pools contain filters that indicate which tickets the pool processes. The matchmaker assigns tickets that don't match the filters of a pool to a subsequent pool. If the ticket isn't compatible with any of the pools, it uses the default pool of that queue.
For each pool, it's possible to specify hosting information, and the matchmaking logic to use when building matches with the tickets within the pool.
You can separate pools by platform by using filters to target the specific platforms, such as a console or Windows. You can also use pools to target regions, such as North America, the European Union, or Asia.
Default pool
Similarly to queues, the default pool serves as a fallback to make sure you can still process tickets that aren't compatible with any other pool. For example, if you have pools for each region, the default pool is used to put players in a fallback region.
Filters
Filters are a way for pools to decide which tickets to process based on attribute values. You can add custom values under the section when you create a matchmaking ticket in your game client code.
AttributesThe matchmaker supports two types of attribute values: and . Filters themselves can also be of the following two types:
textnumbers- The type supports the four basic logical operations:
Comparator,=,!=, and<.> - The type lets you write your own boolean expression. Refer to Language Definition (Google) for the full definition of the CEL language.
CEL
Note the following rules:
- All filters are case sensitive.
- If a pool contains multiple filters, all filters must pass in order for a ticket to be accepted in this pool. The more flexible filter type can be used to accept tickets with only a partial match.
CEL - The filter type infers the
Comparatorvalue type for you.textdoesn't. Don't forget quotation marks to denote a literalCELvalue when usingtext.CEL - The language can be quite powerful, but ticket attributes are still limited to the key-value type, and values can only be
CELortext.numbers
Examples of filters
The following table demonstrates how to use each type of filter:
Type | Field | Operator | Value | Description |
|---|---|---|---|---|
| Comparator | platform | = | windows | The platform attribute in the tickets must be equal to `windows`. |
| CEL | n/a | n/a | platform == "windows" || platform == "ps5" | The platform attribute in the tickets must be equal to either |
Ticket attributes
The following code snippets show how to declare ticket attributes in C# or JSON.
var attributes = new Dictionary<string, object>{ { "platform", "windows" }, { "playerRating", 1500 }};
"attributes": [ { "platform": "windows", "playerRating": 1500 }]