Menu
Amazon GameLift
Developer Guide (Version )

FlexMatch Rules Reference

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

Rule Types

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

Distance rule (distance)

Distance is used to measure the difference between two values, such as the distance between two skill levels. For example, a rule might specify that matched players must be within one level of each other.

  • referenceValue – Reference point to use when measuring distance.

  • minDistance/maxDistance – Distance constraints that must be satisfied for a successful match.

  • 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.

Comparison rule (comparison)

Comparison is used to compare two values. For example, a rule might specify that all matched players must have a certain map choice have achieved at least level 24.

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

  • operation – How to evaluate the measurement against the reference value. 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 is used for evaluating the player attributes of multiple players. For example, a rule might specify that each team include at least one player playing a certain character.

  • operation – How to evaluate the collection against the reference value.

    • intersection measures the number of strings that are common among all players.

    • contains measures the number of players that contain a certain reference value.

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

  • minCount/maxCount – Constraints on the acceptability of values resulting from the operation.

  • 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 is used to evaluate player latency settings for acceptable matches. For example, a rule might specify that all matched players must have a regional latency under a maximum limit.

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

  • maxDistance – Maximum difference between the latency of a prospective match and the latency of players already in the match (based on the distance reference).

  • distanceReference – How to compare latency values of multiple players. Valid options are to use the minimum (min) or average (avg) values for the players.

  • 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, which directs the matchmaker to pre-sort matchmaking requests based on a player attribute. The distance sort 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, which 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 properties related to matchmaking. Property expressions can be used in rules and expansions. For example, either a rule or an expansion might use a property expression to reference a specific player attribute to evaluate.

Matchmaking-related properties can include the player attribute values from matchmaking requests. 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<?>
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