Catena - AWS FlexMatch

AWS FlexMatch is responsible for grouping players together to form games or matches. Catena's integration into FlexMatch currently supports FlexMatch's "standalone" configuration, meaning that it only supports making matches and does not support provisioning game servers via AWS GameLift.

If you would like to learn more about how Catena handles dedicated game servers, refer to the Match Broker documentation.

Engine Integration

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

• Unity - Matchmaking

What is AWS FlexMatch?

AWS FlexMatch, also known as "Amazon GameLift Servers FlexMatch" is Amazon's offering for matchmaking players.

A Note on AWS Service Limits and Costs

GameLift matchmaking configurations and rule sets are subject to account-level quotas. If you plan to run many logical matchmaking queues, check your current limits in the Service Quotas console before provisioning.

FlexMatch also bills for usage, even in standalone mode with no GameLift-hosted servers involved — you're charged for matchmaking hours and player packages processed, not just for the AWS resources this guide provisions. See FlexMatch pricing for current rates, and note that costs scale with matchmaking traffic, not with how this deployment is configured. To determine exact costs, you can use the Cost Calculator provided by AWS to detmine exact pricing for your targeted region(s).

If you're deploying FlexMatch alongside a new catena-core EC2 deployment, also see the service limits note in the AWS EC2 guide — the same Elastic IP/VPC quotas apply there.

Getting Started

1. Obtain Catena source code

Catena is distributed via Git. Instructions for installing Git can be found here.

To gain access to the Catena Source, please contact us to obtain a license. Once you have access, clone Catena to your machine.

git clone git@github.com:CatenaTools/catena-tools-core.git

To configure FlexMatch, you will also need to clone Catena's Infrastructure as Code repository.

git clone git@github.com:CatenaTools/infrastructure.git

Terraform

Terraform is an infrastructure-as-code (IaC) tool created by HashiCorp. It allows users to develop, modify, and version infrastructure components. With it, we can deploy Catena to AWS in a handful of commands.

To install Terraform, refer to their installation documentation.

Matchmaking Ruleset(s)

FlexMatch Rulesets define your game's team structure, size, and how to group players together for the best possible match.

Matchmaking Configuration(s)

FlexMatch Configurations expose matchmaking functionality to the outside world. These are how Catena makes matchmaking requests to AWS.

Simple Notification Service (SNS) Topic

AWS SNS gives FlexMatch a place to post matchmaking events as they occur (i.e. match created).

Simple Queue Service (SQS) Queue

AWS SQS gives applications a way to subscribe to events that are sent to SNS topics. This is how Catena listens for matchmaking events for specific matchmaking tickets.

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.

The queue_name you provide in your ticket will be used to determine the FlexMatch Matchmaking Configuration to use when entering matchmaking.

Events

As matchmaking tickets progress through Catena and ultimately through FlexMatch, 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.

What Next?

Now that we covered some background, its time to provison some resources. If you already went through the AWS EC2 deployment steps, follow these to deploy alongside your running Catena instance:

If you haven't deployed anything to AWS yet, follow our fresh deploy steps: