Describe the rule set (required)Customize the match algorithm Declare player attributes Define match teams Set rules for player matching Allow requirements to relax over time

Design a FlexMatch rule set

This topic covers the basic structure of a rule set and how to build a rule set for small matches up to 40 players. A matchmaking rule set does two things: lay out a match's team structure and size and tell the matchmaker how to choose players to form the best possible match.

But your matchmaking rule set can do more. For example, you can:

Optimize the matchmaking algorithm for your game.
Set up minimum player latency requirements to protect the quality of gameplay.
Gradually relax team requirements and match rules over time so all active players can find an acceptable match when they want one.
Define handling for group matchmaking requests using party aggregation.
Process large matches of 40 or more players. For more information about building large matches, see Design a FlexMatch large-match rule set.

When building a matchmaking rule set, consider the following optional and required tasks:

Describe the rule set (required)
Customize the match algorithm
Declare player attributes
Define match teams
Set rules for player matching
Allow requirements to relax over time

You can build your rule set using the Amazon GameLift console or the CreateMatchmakingRuleSet operation.

Describe the rule set (required)

Provide details for the rule set.

name (optional) – A descriptive label for your own use. This value isn't associated with the rule set name that you specify when creating the rule set with Amazon GameLift.
ruleLanguageVersion – The version of the property expression language used to create FlexMatch rules. The value must be 1.0.

Customize the match algorithm

FlexMatch optimizes the default algorithm for most games to get players into acceptable matches with minimal wait time. You can customize the algorithm and adjust matchmaking for your game.

The following is the default FlexMatch matchmaking algorithm:

FlexMatch places all open matchmaking tickets and backfill tickets in a ticket pool.
FlexMatch randomly groups tickets in the pool into one or more batches. As the ticket pool gets larger, FlexMatch forms additional batches to maintain optimal batch size.
FlexMatch sorts the tickets by age, within each batch.
FlexMatch builds a match based on the oldest ticket of each batch.

To customize the match algorithm, add an algorithm component to your rule set schema. See FlexMatch rule set schema for the complete reference information.

Use the following optional customizations to impact different stages of your matchmaking process.

Add pre-batch sorting
Form batches based on batchDistance attributes
Prioritize backfill tickets
Favor older tickets with expansions

Add pre-batch sorting

You can sort the ticket pool before forming batches. This type of customization is most effective with games with large tickets pools. Pre-batch sorting can help speed up the matchmaking process and increase player uniformity in defined characteristics.

Define Pre-batch sorting methods using the algorithm property batchingPreference. The default setting is random.

Options for customizing pre-batch sorting include:

Sort by player attributes. Provide a list of player attributes to pre-sort the ticket pool.

To sort by player attributes, set batchingPreference to sorted, and define your list of player attributes in sortByAttributes. To use an attribute, first declare the attribute in the playerAttributes component of the rule set.

In the following example, FlexMatch sorts the ticket pool based on players' preferred game map and then by player skill. The resulting batches are more likely to contain similarly skilled players who want to use the same map.
```
"algorithm": {
    "batchingPreference": "sorted",
    "sortByAttributes": ["map", "player_skill"],
    "strategy": "exhaustiveSearch"
},
```
Sort by latency. Create matches with the lowest available latency or quickly create matches with acceptable latency. This customization is useful for rule sets forming large matches of more than 40 players.

Set the algorithm property strategy to balanced. The balanced strategy limits the available types of rule statements. For more information, see Design a FlexMatch large-match rule set.

FlexMatch sorts tickets based on players' reported latency data in one of the following ways:
- Lowest latency locations. The ticket pool is pre-sorted by the locations where players report their lowest latency values. FlexMatch then batches tickets with low latency in the same locations, creating a better game play experience. It also reduces the number of tickets in each batch, so matchmaking can take longer. To use this customization, set batchingPreference to fastestRegion, as shown in the following example.
```
"algorithm": {
    "batchingPreference": "fastestRegion",
    "strategy": "balanced"
},
```
- Acceptable latency matches quickly. The ticket pool is pre-sorted by locations where players report acceptable latency value. This forms fewer batches containing more tickets. With more tickets in each batch, finding acceptable matches is faster. To use this customization, set the property batchingPreference tolargestPopulation, as shown in the following example.
```
"algorithm": {
    "batchingPreference": "largestPopulation",
    "strategy": "balanced"
},
```
Note
The default value for the balanced strategy is largestPopulation.

Prioritize backfill tickets

If your game implements auto-backfill or manual backfill, you can customize how FlexMatch processes matchmaking tickets based on request type. The request type can be a new match or backfill request. By default, FlexMatch treats both types of requests the same.

Backfill prioritization impacts how FlexMatch handles tickets after it batches them. Backfill prioritization requires rule sets to use the exhaustive search strategy.

FlexMatch doesn't match multiple backfill tickets together.

To change prioritization for backfill tickets, set the property backfillPriority.

Match backfill tickets first. This option tries to match backfill tickets before creating new matches. This means that incoming players have a higher chance of joining an existing game.

It's best to use this if your game uses auto-backfill. Auto-backfill is often used in games with short game sessions and high player turnaround. Auto-backfill helps these games form minimum viable matches and get them started while FlexMatch searches for more players to fill open slots.

Set the backfillPriority to high.
```
"algorithm": {
    "backfillPriority": "high",
    "strategy": "exhaustiveSearch"
},
```
Match backfill tickets last. This option ignores backfill tickets until it evaluates all other tickets. This means that FlexMatch backfills incoming players into existing games when it can't match them into new games.

This option is useful when you want to use backfill as a last-chance option to get players into a game, such as when there aren't enough players to form a new match.

Set backfillPriority to low.
```
"algorithm": {
    "backfillPriority": "low",
    "strategy": "exhaustiveSearch"
},
```

Favor older tickets with expansions

Expansion rules relax match criteria when matches are difficult to complete. Amazon GameLift applies expansion rules when tickets in a partially completed match reach a certain age. The creation timestamps of the tickets determine when Amazon GameLift applies the rules; by default, FlexMatch tracks the timestamp of the most recently matched ticket.

To change when FlexMatch applies expansion rules, set the property expansionAgeSelection as follows:

Expand based on newest tickets. This option applies expansion rules based on the newest ticket added to the potential match. Each time FlexMatch matches a new ticket, the time clock is reset. With this option, resulting matches tend to be higher quality but take longer to match; match requests might time out before completing if they take too long to match. Set expansionAgeSelection to newest. newest is default.
Expand based on oldest tickets. This option applies expansion rules based on the oldest ticket in the potential match. With this option, FlexMatch applies expansions faster, which improves wait times for the earliest matched players, but lowers the match quality for all players. Set expansionAgeSelection to oldest.


"algorithm": {
    "expansionAgeSelection": "oldest",
    "strategy": "exhaustiveSearch"
},

Declare player attributes

In this section, list individual player attributes to include in matchmaking requests. There are two reasons you might declare player attributes in a rule set:

When the rule set contains rules that rely on player attributes.
When you want to pass a player attribute to the game session through the match request. For example, you might want to pass player character choices to the game session before each player connects.

When declaring a player attribute, include the following information:

name (required) – This value must be unique to the rule set.
type (required) – The data type of the attribute value. Valid data types are number, string, or string map.
default (optional) – Enter a default value to use if a matchmaking request doesn't provide an attribute value. If no default is declared and a request doesn't include a value, FlexMatch can't fulfill the request.

Define match teams

Describe the structure and size of the teams for a match. Each match must have at least one team, and you can define as many teams as you want. Your teams can have the same number of players or be asymmetric. For example, you might define a single-player monster team and a hunters team with 10 players.

FlexMatch processes match requests as either small match or large match, based on how the rule set defines team sizes. Potential matches of up to 40 players are small matches, matches with more than 40 players are large matches. To determine a rule set's potential match size, add up the maxPlayer settings for all teams defined in the rule set.

name (required) – Assign each team a unique name. You use this name in rules and expansions, and FlexMatch references for the matchmaking data in a game session.
maxPlayers (required) – Specify the maximum number of players to assign to the team.
minPlayers (required) – Specify the minimum number of players to assign to the team.
quantity (optional) – Specify the number of team to make with this definition. When FlexMatch creates a match, it gives these teams the provided name with an appended number. For example Red-Team1, Red-Team2, and Red-Team3.

FlexMatch attempts to fill teams to the maximum player size but does create teams with fewer players. If you want all teams in the match to be equally sized, you can create a rule for that. See the FlexMatch rule set examples topic for an example of an EqualTeamSizes rule.

Set rules for player matching

Create a set of rule statements that evaluate players for acceptance in to a match. Rules might set requirements that apply to individual players, teams, or an entire match. When Amazon GameLift processes a match request, it starts with the oldest player in the pool of available players and builds a match around that player. For detailed help on creating FlexMatch rules, see FlexMatch rule types.

name (required) – A meaningful name that uniquely identifies the rule within a rule set. Rule names are also referenced in event logs and metrics that track activity related to this rule.
description (optional) – Use this element to attach a free-form text description.
type (required) – The type element identifies the operation to use when processing the rule. Each rule type requires a set of additional properties. See a list of valid rule types and properties in FlexMatch rules language.
Rule type property (may be required) – Depending on the type of rule defined, you may need to set certain rule properties. Learn more about properties and how to use the FlexMatch property expression language in FlexMatch rules language.

Allow requirements to relax over time

Expansions allow you to relax rule criteria over time when FlexMatch can't find a match. This feature ensures that FlexMatch makes a best available when it can't make a perfect match. By relaxing your rules with an expansion, you gradually expand the pool of players that are an acceptable match.

Expansions start when the age of the newest ticket in the incomplete match matches an expansion wait time. When FlexMatch adds a new ticket to the match, the expansion wait time clock may be reset. You can customize how expansions start in the algorithm section of the rule set.

Here's an example of an expansion that gradually increases the minimum skill level required for the match. The rule set uses a distance rule statement, named SkillDelta to require that all players in a match be within 5 skill levels of each other. If no new matches are made for fifteen seconds, this expansion looks for a skill level difference of 10, and then ten seconds later looks for a difference of 20.


"expansions": [{
        "target": "rules[SkillDelta].maxDistance",
        "steps": [{
            "waitTimeSeconds": 15,
            "value": 10
        }, {
            "waitTimeSeconds": 25,
            "value": 20
        }]
    }]

With matchmakers that have automatic backfill enabled, don't relax your player count requirements too quickly. It takes a few seconds for the new game session to start up and begin automatic backfill. A better approach is to start your expansion after automatic backfill tends to kicks in for your games. Expansion timing varies depending on your team composition, so do testing to find the best expansion strategy for your game.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Build a rule set

Design a large-match rule set