Queues and pools

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

Read time 2 minutes

Last updated 5 months ago

Important

Unity Matchmaker will support Multiplay Hosting until the deprecation date of March 31st, 2026. To aid your migration away from Multiplay Hosting, migration examples for alternative hosting providers are available. Matchmaker will continue to work with Relay and Distributed Authority after the Multiplay Hosting deprecation.

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

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:

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 `windows` or `ps5` .

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    }]

Documentation

Development

User Acquisition

Monetization

Industry