FlexMatch rules language - Amazon GameLift

FlexMatch rules language

Use the following property expression syntax when writing rules for FlexMatch rule sets.

Learn more about creating FlexMatch rules:

Rule types

FlexMatch supports the following rule types. Each rule type requires a set of properties, which are described here.

Absolute sort rule (absoluteSort)

Absolute sort is an explicit sort option that directs the matchmaker to sort a batch of matchmaking tickets based on a player attribute. An absolute sort evaluates matchmaking tickets based on whether its player attribute matches that of the oldest ticket.

Absolute sort rule properties

  • sortDirection – Direction to sort matchmaking tickets. Valid options are ascending or descending.

  • sortAttribute – Player attribute to sort players by.

  • mapKey – How to evaluate the player attribute if it's a map. Valid options include:

    • minValue: For the oldest ticket, find the key with the lowest value.

    • maxValue: For the oldest ticket, find the key with the highest value.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Collection rule (collection)

Collection rules evaluate collections of player attribute values. A collection might contain attribute values for multiple players, a player attribute that is a collection (a string list), or both. For example, a collection rule might look at the characters chosen by the players in a team, and require that the team have at least one of a certain character.

Collection rule properties

  • measurements – Collection of player attribute values to evaluate. Attribute values must be string lists.

  • referenceValue – Value (or collection of values) to evaluate the measurements against for a prospective match.

  • operation – How to evaluate a measurement collection. Valid operations include:

  • minCount/maxCount – Maximum or minimum count value allowed for a successful match.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the union or intersection of values for a ticket's players. Default is union.

Comparison rule (comparison)

Comparison rules measure a player attribute value against another value. There are two types of comparison rules. The first type compares an attribute value to a provided reference value. Specify the reference value and a valid comparison operation. For example, the rule might require that matched players have skill level 24 or greater. The second type compares player attribute values across players in a team or match to determine whether all players or none of the players have the same attribute value. With this type of comparision rule, omit the reference value and specify either the equal ("=") or not-equal ("!=") operation. For example, the rule might require that all players in the match choose the same game map or that no players on a team choose the same character.

Comparison rule properties

  • measurements – Player attribute value to compare.

  • referenceValue – Value to evaluate the measurement against for a prospective match.

  • operation – How to evaluate the measurement. Valid operations include: <, <=, =, !=, >, >=.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Distance rule (distance)

Distance rules measure the difference between two number values, such as the distance between skill levels. For example, a distance rule might require that all players be within two skill levels of each other.

Distance rule properties

  • measurements – Player attribute value to measure distance for; must be a number value.

  • referenceValue – Number value to measure distance against for a prospective match.

  • minDistance/maxDistance – Maximum or minimum distance value allowed for a successful match.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Batch distance rule (batchDistance)

Batch distance rules measure the difference between two number values, such as the distance between skill levels. It can be helpful when you want to verify players have an attribute value within a certain range of other players.

Batcg distance rule properties

  • batchAttribute – Player attribute value used to form batches; must be a number value.

  • minDistance/maxDistance – Maximum or minimum distance value allowed for a successful match.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Distance sort rule (distanceSort)

Distance sort is an explicit sort option that directs the matchmaker to sort a batch of matchmaking tickets based on a player attribute. A distance sort rule evaluates tickets based on the distance from the oldest ticket.

Distance sort rule properties

  • sortDirection – Direction to sort matchmaking tickets. Valid options are ascending or descending.

  • sortAttribute – Player attribute to sort players by.

  • mapKey – How to evaluate the player attribute if it's a map. Valid options include:

    • minValue: For the oldest ticket, find the key with the lowest value.

    • maxValue: For the oldest ticket, find the key with the highest value.

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Latency rule (latency)

Latency rules evaluate player latency reports by region For example, a rule might require that matched players must have a latency in the same region that is under a maximum limit. This is the only rule type that is allowed for large matches, and setting maxLatency is the only allowed property.

Latency rule properties

  • maxLatency – Highest acceptable latency value for a region. For each ticket, ignore all regions that exceed this latency.

  • maxDistance – Maximum difference between the latency of each ticket and the distance reference value.

  • distanceReference – Use with maxDistance. Number value to measure distance against for a successful match. For latency, this value is an aggregate of latency values for multiple players. Valid options are minimum (min) or average (avg) player latency value. (See the Property Expressions section.)

  • partyAggregation – Method for handling tickets with multiple players (parties). Valid options are to use the minimum (min), maximum (max), or average (avg) values for a ticket's players. Default is avg.

Property expressions

Property expressions can be used to define certain matchmaking-related properties. They allow you to use calculations and logic when defining a property value. Property expressions generally result in one of two forms:

  • Individual player data.

  • Calculated collections of individual player data.

A valid property expression identifies a specific value for a single player, a team, or a match. The following partial expressions illustrate how to identify teams and players:

Goal Input Meaning Output
To identify a specific team in a match: teams[red] The Red team Team
To identify all teams in a match: teams[*] All teams List<Team>
To identify players in a specific team: team[red].players Players in the Red team List<Player>
To identify players in a match: team[*].players Players in the match, grouped by team List<List<Player>>

The following table illustrates some valid property expressions that build on the previous examples:

Expression Meaning Resulting Type

teams[red].players[playerid]

The player IDs of all players on the red team List<string>
teams[red].players.attributes[skill] The "skill" attributes of all players on the red team List<number>
teams[*].players.attributes[skill] The "skill" attributes of all players in the match, grouped by team List<List<number>>

Property expressions can be used to aggregate team data by using the following functions or combinations of functions:

Aggregation Input Meaning Output
min List<number> Get the minimum of all numbers in the list. number
max List<number> Get the maximum of all numbers in the list. number
avg List<number> Get the average of all numbers in the list. number
median List<number> Get the median of all numbers in the list. number
sum List<number> Get the sum of all numbers in the list. number
count List<?> Get the number of elements in the list. number
stddev List<number> Get the standard deviation of all numbers in the list. number
flatten List<List<?>> Turn a collection of nested lists into a single list containing all elements. List<?>
set_intersection List<List<string>> Get a list of strings that are found in all string lists in a collection. List<string>
All above List<List<?>> All operations on a nested list operate on each sublist individually to produce a list of results. List<?>

The following table illustrates some valid property expressions that use aggregation functions:

Expression Meaning Resulting Type
flatten(teams[*].players.attributes[skill]) The "skill" attributes of all players in the match (not grouped) List<number>
avg(teams[red].players.attributes[skill]) The average skill of the red team players number
avg(teams[*].players.attributes[skill]) The average skill of each team in the match List<number>
avg(flatten(teams[*].players.attributes[skill])) The average skill level of all players in the match. This expression gets a flattened list of player skills and then averages them. number
count(teams[red].players) The number of players on the red team number
count (teams[*].players) The number of players on each team in the match List<number>
max(avg(teams[*].players.attributes[skill])) The highest team skill level in the match number