Catena Matchmaker

The Catena Matchmaker is responsible for grouping players or parties together to form games or matches.

It is not responsible for assigning dedicated game servers or fleet management. It is also not responsible for handling backfill. If you would like to learn more about how Catena handles dedicated game servers or backfill, refer to the Match Broker documentation.

Some additional details are found in a previous version of this page

Engine Integration

This page is dedicated to explaining key concepts for matchmaking in Catena, utilizing the Catena Matchmaker. If you are interested in how to integrate matchmaking within a particular game engine, refer to your engine's documentation.

• Unity - Matchmaking

How The Matchmaker Works

Tickets

The Catena Matchmaker accepts matchmaking tickets from players. Tickets may be submitted by a player for themselves if matchmaking alone, or may be submitted by a party leader on behalf of the entire party if partied up. These tickets can include metadata about the player(s), the party they are in, or the desired match properties.

Creating a ticket for matchmaking is done by submitting an Entity to StartMatchmaking.

An Entity is a special Catena data type used for passing and storing dynamic data in Catena without having to define rigid data types.

Tickets will be sorted into queues based on the queue_name that is provided in the ticket. This queue_name is a requirement.

An example ticket, in its simplest form, looks like this:

{
    "entity": {
        "id": "{{account-id}}",
        "entity_type": "ENTITY_TYPE_ACCOUNT",
        "entities": [],
        "metadata": {
            "queue_name": {
                "string_payload": "solo"
            }
        }
    }
}

Note: If you are using a Catena SDK in your game engine, ticket generation is done on your behalf.

Queues

The Catena Matchmaker utilizes separate queues to partition tickets. These queues act like mini-matchmakers, supporting many different game types and matchmaking needs.

• You may configure one or many queues, depending on the needs of your game.
• Each queue can have its own rules for match sizes, teams, matchmaking strategies (the algorithm used to make matches), or other custom requirements.
• Matchmaking tickets are never moved between queues and are never matched with other matchmaking tickets from other queues.
• The Catena Matchmaker will assign each matchmaking ticket to a queue based on the metadata it contains.

Matchmaking Strategies

The Catena Matchmaker uses matchmaking strategies within queues to define how matchmaking tickets are matched together.

The Catena Matchmaker contains built-in strategies that will be selected automatically based on team counts and sizes.

(Optional) Custom Strategies

Configuring custom matchmaking strategies is an advanced topic. If you are configuring the matchmaker for the first time, it is recommended you set up your proof of concept with Catena's built-in strategies.

Events

As matchmaking tickets progress through the Catena Matchmaker, events are emitted that either game clients or other Catena Services who are subscribed can ingest.

1. A MatchmakingStatusUpdateEvent is emitted to players on a given ticket periodically as the ticket progresses through the system. Status update types include:
   1. MATCHMAKING_STATUS_UPDATE_TYPE_IN_PROGRESS
   2. MATCHMAKING_STATUS_UPDATE_TYPE_COMPLETED
   3. MATCHMAKING_STATUS_UPDATE_TYPE_FAILED
   4. MATCHMAKING_STATUS_UPDATE_TYPE_CANCELLED
   5. MATCHMAKING_STATUS_UPDATE_TYPE_FINDING_SERVER
   6. MATCHMAKING_STATUS_UPDATE_MATCHMAKING_TIMED_OUT
2. A NewMatchEvent is emitted when a match is formed, which other Catena Services can use to spin up a dedicated game server for the match, if necessary.

(Optional) Matchmaking Hooks

Configuring custom matchmaking hooks is an advanced topic. If you are configuring the matchmaker for the first time, it is recommended you set up your proof of concept without custom matchmaking hooks.

Configuring The Catena Matchmaker

Tha Catena Matchmaker is configured using appsettings files in catena-tools-core.

Basic Example

There are many possible scenarios for matchmaking across many different genres of game. Let's start with a basic configuration that selects the "Catena Matchmaker" as the enabled matchmaking implementation and defines three queues.

{
    "Catena": {
        ...
        "Matchmaker": {
            "MatchmakingQueues": {
                "solo": {
                    "QueueName": "Solo",
                    "Teams": 1,
                    "PlayersPerTeam": 1,
                    "TicketExpirationSeconds": 180
                },
                "1v1": {
                    "QueueName": "1v1 (Face Off)",
                    "Teams": 2,
                    "PlayersPerTeam": 1,
                    "TicketExpirationSeconds": 180
                },
                "2v2": {
                    "QueueName": "2v2 (Team Play)",
                    "Teams": 2,
                    "PlayersPerTeam": 2,
                    "TicketExpirationSeconds": 180
                }
            },
            "StatusExpirationMinutes": 15
        }
        ...
    },
    "PreferredImplementations": {
        ...
        "ICatenaMatchmaker": "!CatenaMatchmaker"
        ...
    }
}

How these queues are utilized by your game is up to you, but a few examples include:

• A solo match could be satisfied by a single ticket, submitted by an individual player
• A 1v1 match could be satisfied by a single ticket containing two players, submitted by the leader of a party
• A 1v1 match could be satisfied by two separate players, each submitting their own individual ticket
• A 2v2 match could be satisfied by four separate players, each submitting their own individual tickets
• A 2v2 match could be satisfied by two tickets, each containing two players, submitted by to separate party leaders for two formed parties

Available Configuration Options

Let's take a look at all the available properties in the Matchmaker config.

Each queue defined with MatchmakingQueues will have its own properties.

First, the JSON key is the value that tickets will need to provide as their queue_name value. In the above basic example, they are solo, 1v1 and 2v2. This value is how tickets are sorted into queues.

What Next?

Now that you have your matchmaker configured, it's time to integrate the matchmaker with your game engine.

Alternatively, if you are interested in matchmaking players into dedicated game servers, proceed to the game server documentation.