Amazon GameLift
Developer Guide (Version )

FlexMatch Rules Reference

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

Learn more about creating FlexMatch rules:

Rule Types

The following rule types are allowed. Each rule type requires a set of properties as defined here.

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 levels of each other.

  • measurement – 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 – How to handle multiple-player (party) requests. Valid options are to use the minimum (min), maximum (max), or average (avg) values for a request's players. Default is avg.

Comparison rule (comparison)

Comparison rules compare a player attribute value against another value. There are two types of comparison rules. The first type compares an attribute value to a reference value. Specify the reference value and any valid comparison operation. For example, the rule might require that matched players have skill level 24 or greater. The second type compares an attribute value across all players in a team or match. This type omits the reference value and specifies either equals or not-equals (all or none of the players have the same attribute value). For example, the rule might require that all players chose the same game map.

  • measurement – 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 – How to sort multiple-player (party) requests. Valid options are to use the minimum (min), maximum (max), or average (avg) values for a request'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 collection of characters chosen by a team's players and require that it contain at least one of a certain character.

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

  • referenceValue – Value or collection of values to evaluate the measurement 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 – How to sort multiple-player (party) requests. Valid options are to use the union or intersection of values for a request's players. Default is union.

Latency rule (latency)

Latency rules evaluate player latency settings for acceptable matches. For example, a rule might require all matched players must have a regional latency under a maximum limit.

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

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

  • distanceReference – 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 – How to sort multiple-player (party) requests. Valid options are to use the minimum (min), maximum (max), or average (avg) values for a request's players. Default is avg.

Distance sort rule (distanceSort)

Distance sort is an explicit sort option that directs the matchmaker to pre-sort matchmaking requests based on a player attribute. A distance sort rule evaluates matchmaking requests based on the distance from the anchor request.

  • sortDirection – Direction to sort matchmaking requests. 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 anchor player, find the key with the lowest value.

    • maxValue: For the anchor player, find the key with the highest value.

  • partyAggregation – How to sort multiple-player (party) requests. Valid options are to use the minimum (min), maximum (max), or average (avg) values for a request's players. Default is avg.

Absolute sort rule (absoluteSort)

Absolute sort is an explicit sort option that directs the matchmaker to pre-sort matchmaking requests based on a player attribute. An absolute sort evaluates matchmaking requests based on whether its player attribute matches that of the anchor request.

  • sortDirection – Direction to sort matchmaking requests. 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 anchor player, find the key with the lowest value.

    • maxValue: For the anchor player, find the key with the highest value.

  • partyAggregation – How to sort multiple-player (party) requests. Valid options are to use the minimum (min), maximum (max), or average (avg) values for a request's players. Default is avg.

Property Expressions

Property expressions are used in a rule set to refer to certain matchmaking-related properties. Properties can include the player attribute values from matchmaking requests. For example, a rule might use a property expression to identify which player attribute to evaluate.

They generally take one of two forms:

  • Individual player data

  • Calculated team data, which takes the form of collections of individual player data.

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

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