Queues and pools#

Control how matchmaking tickets are grouped, filtered, and matched in your game with queues and pools.

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 is possible to specify hosting information as well as the matchmaking logic to use when building matches with the tickets within the pool.

In this way, 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 are not compatible with any other pool. If we take our example with pools for each region, the default pool would be 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 Attributes section when you create a matchmaking ticket in your game client code.

The matchmaker supports two types of attribute values: text and numbers. Filters themselves can also be of the following two types:

• The Comparator type supports the four basic logical operations: =, !=, <, and >.
• The CEL type lets you write your own boolean expression. Refer to Language Definition (Google) for the full definition of the CEL language.

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 CEL filter type can be used to accept tickets with only a partial match.
• The Comparator filter type infers the text value type for you. CEL doesn't. Don't forget quotation marks to denote a literal text value when using CEL.
• The CEL language can be quite powerful, but ticket attributes are still limited to the key-value type, and values can only be text or numbers.

Examples of filters#

The following table demonstrates how to use each type of filter:

Ticket attributes#

The following code snippets show how to declare ticket attributes in C# or JSON.

• Unity SDK

  var attributes = new Dictionary<string, object>
  {
      { "platform", "windows" },
      { "playerRating", 1500 }
  };

• JSON

  "attributes": [
      {
          "platform": "windows",
          "playerRating": 1500
      }
  ]