Configure match rulesets

Last updated on November 15, 2024

Overview​

Match rulesets define the logic that AccelByte Gaming Services (AGS) Matchmaking will use to determine if and when match tickets can be paired together. Here are some key terms associated with rulesets:

  • Attributes: Also referred to as statistics, these are numeric values, such as matchmaking rating (MMR), that can be used to compare tickets to determine whether they should be matched together. These values must be stored in AGS Statistics to be used during matchmaking.

  • Custom Parameters: Key-value pairs that represent player preferences passed to AGS Matchmaking from the game client as part of the match request. Examples include map, language, and crossplay player preferences.

  • Rule Flexing: The process by which a configured rule will be relaxed over time. Configuring rule flexing can help prevent players from experiencing long queue times.

This article will show you how to configure rules to enable team-based, skill-based, and custom parameter matching between players. It will also show you how to flex those rules over time to help reduce wait times in situations where there may be low player traffic or a large skill variance between players.

Goals​

This page aims to provide you with an overview of match rulesets and an understanding of:

  • Configuring rulesets in the AGS Admin Portal.
  • The different types of behaviors that can be enabled as part of a ruleset.
  • Enabling flexing of the defined behavior to prevent players from waiting in a long queue.

Prerequisites​

To complete all the steps in this article, you will need:

Team-based matchmaking​

To configure team-based matchmaking, you will need to define the number of teams and number of players per team that should be targeted for a match in the JSON as shown in the example below. The example configuration below specifies that there needs to be two teams, with no less than five players in the game for the match to start.

note

alliance in the JSON block defines the team configuration that will be followed during evaluation.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    }
}
  • Auto backfill: Specifies that the matchmaking will automatically backfill open spots in the game session until the match (game session) is full.
  • Min number: Specifies the minimum number of required teams for the match to start.
  • Max number: Specifies the maximum number of teams that can participate in the match.
  • Player min number: Specifies the minimum number of players required per team for the match to start.
  • Player max number: Specifies the maximum number of players that can participate in a team during the match.

Rule flexing for teams​

In the case that the minimum number of players required to start a match can't be found, you can configure rule flexing to allow for the match to start with fewer players. The example configuration below specifies that the minimum number of players per team required will reduce from five to three after 60 seconds of the match ticket entering the queue.

note

alliance_flexing_rule in the JSON block defines how the rule will be relaxed after the specified duration. To add additional flexing rules for teams, add them as their own comma-separated blocks within alliance_flexing_rule.

tip

AccelByte highly recommends using alliance flexing rules to elevate your overall gaming experience. This optimization allows your game to start quicker with just a few players as it significantly improves your players' chances of being matched up in the same session rather than ending up in separate lobbies.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "alliance_flexing_rule": [
        {
            "duration": 60,
            "min_number": 2,
            "max_number": 2,
            "player_min_number": 3,
            "player_max_number": 5
        }
    ]
}
  • Duration: Specifies the amount of time in seconds that must pass before the service will start flexing the rule.
  • Min number: Specifies the updated minimum number of required teams for the match to start.
  • Max number: Specifies the updated maximum number of teams that can participate in the match.
  • Player min number: Specifies the updated minimum number of players required per team for the match to start.
  • Player max number: Specifies the updated maximum number of players that can participate during the match.

Skill-based matchmaking​

To configure skill-based matching, you will need to configure AGS Statistics to track metrics that represent a player's skill. Once a statistic is defined, it can be used to compare the distance between players to determine if they should match together. The example configuration below specifies a match should contain two teams of five players, with a +/- 200 matchmaking rating (MMR) variance allowed between players.

note

matching_rule in the JSON block defines which statistic will be compared during evaluation. To add additional rules for more statistics, add them as their own comma-separated block within matching_rule.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200,
            "max": 3000
        }
    ]
}
  • Attribute: Specifies the statistic that will be used to compare players for match fitness.
  • Criteria: Specifies the criteria that will be used to compare the statistic. NOTE: "distance" is the only criterion currently supported.
  • Reference: Specifies the variance between statistics allowed. In this example, players must be +/- 200 to be matched.
  • Max: Specifies the maximum value for the statistic attributes. This will be used for the matching and rebalancing process.

Rule flexing for statistics​

In the event that there aren't enough players with a statistic value within the specified range, you can configure rule flexing to allow players to match at a larger variance. The example configuration below specifies that for every 15 seconds of waiting, the allowed variance will expand by 100 points, maxing out at 500 points.

note

flexing_rule in the JSON block defines how the rule will be relaxed after the specified duration. To add additional flexing rules for statistics, add them as their own comma-separated block within flexing_rule.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200
        }
    ],
    "flexing_rule": [
        {
            "duration": 15,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 300
        },
        {
            "duration": 30,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 400
        },
        {
            "duration": 45,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 500
        }
    ]
}
  • Duration: Specifies the amount of time in seconds that must pass before the service will start flexing the rule.
  • Attribute: Specifies the statistic that will be used to compare players for match fitness.
  • Criteria: Specifies the criteria that will be used to compare the statistic. NOTE: "distance" is the only criterion currently supported.
  • Reference: Specifies the new variance between statistics allowed. In this example, it increases over time to +/- 500 to be matched.

Custom parameter matchmaking​

In some cases, it may be preferable to allow the game client to pass custom parameters containing player preferences as part of the match request to be used as matching criteria. Some examples include map selection, language, or if they want to participate in crossplay. The example configuration below specifies that players can only match if they have both specified at least one matching map as their preference to play.

note

matching_options in the JSON block defines which customer parameters passed in from the game client will be used during evaluation. To add additional rules for more custom parameters, add them as their own comma-separated block within options .

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "match_options": {
        "options": [
            {
                "name": "map_names",
                "type": "any"
            }
        ]
    }
}
  • Name: Specifies the name (key) of the parameter that will be passed in from the game client.
  • Type: Specifies how the custom parameter should be evaluated during matching.
    • All: Indicates players must be matched with others who have the same parameters and values.
    • Any: Indicates players must be matched with others who have the same option parameter name and at least have one matching value.
    • Unique: Indicates players must be matched with others who have the same option parameter name, but different values.

Add custom parameters to the matchmaking request in the game client​

To pass custom parameters from the game client, you will need to implement a way for players to select their preferences that can then be passed as part of the match request. Then, using the example below, you can implement adding those preferences as custom parameters to include in the request.

note

The name specified for the parameter must match what is configured in the match ruleset JSON.

const IOnlineSubsystem* Subsystem = Online::GetSubsystem(GetWorld());
if (!ensure(Subsystem != nullptr))
{
    return;
}

const FOnlineSessionAccelBytePtr SessionInterface = StaticCastSharedPtr<FOnlineSessionV2AccelByte>(Subsystem->GetSessionInterface());
if (!ensure(SessionInterface.IsValid()))
{
    return;
}
const FUniqueNetIdPtr LocalPlayerId = GetUniquePlayerId();
if (!ensure(LocalPlayerId.IsValid()))
{
    return false;
}

// Create a new search handle instance for matchmaking. IMPORTANT: You will need to set the match pool that you are searching for with SETTING_SESSION_MATCHPOOL, as shown below.
TSharedRef<FOnlineSessionSearch> MatchmakingSearchHandle = MakeShared<FOnlineSessionSearch>();
MatchmakingSearchHandle->QuerySettings.Set(SETTING_SESSION_MATCHPOOL, FString(TEXT("YOUR_MATCHPOOL_NAME_GOES_HERE")), EOnlineComparisonOp::Equals);

// Add the map names as values for the custom parameter
MatchmakingSearchHandle->QuerySettings.Set(
    FName(TEXT("map_names")),
    TEXT("map_01"), EOnlineComparisonOp::Equals);

// Bind a function that has a return type of void and these parameters:
// FName SessionName, bool bWasSuccessful
const FOnMatchmakingCompleteDelegate OnMatchmakingCompleteDelegate = /* Bind to lambda or class method */;
SessionInterface->AddOnMatchmakingCompleteDelegate_Handle(OnMatchmakingCompleteDelegate);

if (SessionInterface->StartMatchmaking(USER_ID_TO_MATCHMAKING_USER_ARRAY(LocalPlayerId.ToSharedRef()), NAME_GameSession, FOnlineSessionSettings(), MatchmakingSearchHandle, OnStartMatchmakingCompleteDelegate))
{
    // Update the current search result handle class member with the search handle passed to AGS Matchmaking.
    CurrentMatchmakingSearchHandle = MatchmakingSearchHandle;
}

More on backfill​

The matchmaking backfill process is designed to maintain balanced and fair player matchups in online multiplayer games, particularly when players leave or disconnect mid-game and when the game session is created without full capacity. By default, matchmaking will prioritize backfilling the session that still has an open slot before creating a new match (game session).

When you specify auto_backfill: true in the match ruleset, all the matches (game session) created from the matchmaking process will be marked as backfillable. After the game session is full, the backfill proposal for that particular session will be stopped even though there may be players left after the session is full. The Dedicated Game Server (DS) can also manually control the backfill status by creating or removing the backfill ticket on the game session. The game admin can utilize the manual backfill in some cases. For example, if you want all the new matches to be formed with full players in the session and only enable the backfill to the game session when there is a player who leaves the session before a minute. More details on managing the backfill ticket can be read in this section.

By default, the matchmaking will use the attributes and region inside the game session when the backfill ticket is created to look for matching players to be backfilled. However, there can be a case when the game session attributes are being changed/updated by the DS during the gameplay. It will impact the backfill flow when the DS recreates the backfill ticket after the session attributes update because the latest attributes will be used to look for matching players. For example case, consider the matchmaking ticket will contain attributes "start_map" as follows:

Match Ticket

{
  "attributes": {
    "start_map": "City_Center" 
  },
  "latencies": {
    "us-west-2":44,
    "eu-west-2":187,
    "ap-northeast-1":600
  },
  "matchPool": "matchpool_test",
  "sessionID": ""
}

Ruleset

{
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "match_options": {
        "options": [
            {
                "name": "start_map",
                "type": "all"
            }
        ]
    }
}

Since the matchmaking ticket contains an attributes value, it will always be included in the game session attributes. After the match starts, the DS updates the session attributes to include some values:

Session data

...
attributes: {
    "start_map": "City_Center",
    "experience_booster": "normal",
    "difficulty": "normal"
}
...

Right after the match starts, two players leave the session and the DS enables backfill. In this case, the start_map, experience_booster, and difficulty attributes will be considered when looking for matching players in the queue. And since the match ticket only contains the start_map attributes, there will not be any players who will be refilled for the session. To avoid this issue, we can use the match_options_referred_for_backfill config so that matchmaking will only refer to the "match_options" config to look for the matching players.

Updated ruleset

{
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 5,
        "player_max_number": 5
    },
    "match_options": {
        "options": [
            {
                "name": "start_map",
                "type": "all"
            }
        ]
    },
    "match_options_referred_for_backfill": true
}

If the match_options_referred_for_backfill flag is enabled, the matchmaking will only use start_map attributes regardless of the game session attributes. So, in the example case above, the players still can be backfilled to the game session even though the DS already added some additional attributes to the game session data.

Region expansion ruleset​

Since you want to provide the best matchmaking experience, the matchmaking logic has strict rules when it comes to matching players based on latency. However, there are times when a game has a small player base, so it would be difficult for them to find a match if they are only looking in their region. The region expansion ruleset is specifically for games that support players that are spread across multiple regions. In the example below, players will be able to request matchmaking based on their preference and on the regions provided by the game. This configuration can be used to match players in different regions based on player latencies, which will flex over time based on the value that has been set in the match ruleset.

{
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 1,
        "player_max_number": 1
    },
    "auto_backfill": false,
    "region_latency_initial_range_ms": 50,
    "region_expansion_range_ms": 50,
    "region_expansion_rate_ms": 10000,
    "region_latency_max_ms": 200
}
  • region_latency_initial_range_ms: Specifies the initial ticket latency that determines whether a player's ticket search needs to be expanded or not.
  • region_expansion_range_ms: Specifies how many milliseconds (ms) will be added to the pivot latency on each matchmaking tick.
  • region_expansion_rate_ms: Specifies how many ms rates for the additional region_expansion_range_ms will be added to the pivot ticket.
  • region_latency_max_ms: Specifies the maximum limitation of latency that can be expanded.

The match ruleset example above will work as follows:

  1. "region_latency_initial_range_ms": 50 means:
    • If a player has less than 50 ms of latency, the ticket search doesn't need to be expanded. For example, if two players each have less than 50 ms, they will be matched to each other immediately.
    • If a player has greater than 50 ms of latency, the ticket search will expand depending on how much latency the player has. For example, if two players each have 90 ms of latency, they will need to wait for 10 seconds (first search expansion) to be matched to each other.
  2. "region_expansion_rate_ms": 10000 means after every 10000 ms (10 seconds), the ticket search is expanded.
  3. "region_expansion_range_ms": 50 means when a ticket search is expanded (every 10 seconds in this example), it will increase the latencies by 50 ms.
  4. "region_latency_max_ms": 200 means a player who has greater than 200 latency will be unable to match.

Bidirectional region or latency match​

When filtering the matching player candidates (match tickets), matchmaking will apply the region expansion logic based on the age of each player's match ticket. The search for a match will only allow candidate players who have the same region as the pivot player (match ticket) or have already expanded to the same region with the pivot players.

For each {region} in [pivot player's regions]
  For each candidate tickets:
    apply region expansion logic based on candidate ticket's age
    include candidate ticket only if it has expanded to {region}

Here's a sample scenario of two tickets with a specific ruleset:

  • Tickets:

    • player 1 latencies: us-east-1: 50ms, us-east-2: 50ms, us-west-2: 80ms, eu-west-1: 100ms, eu-central-1: 102ms, ap-southeast-1: 200ms
    • player 2 latencies: us-east-1: 150ms, us-east-2: 100ms, us-west-2: 122ms, eu-west-1: 30ms, eu-central-1: 55ms, ap-southeast-1: 200ms

  • Ruleset:

    {
        "alliance": {
            "min_number": 2,
            "max_number": 2,
            "player_min_number": 1,
            "player_max_number": 1
        },
        "auto_backfill": false,
        "region_latency_initial_range_ms": 30,
        "region_expansion_range_ms": 50,
        "region_expansion_rate_ms": 10000,
        "region_latency_max_ms": 350
    }

Assuming that matchmaking is set to tick every 10 seconds and Player 1 is a pivot. Player 1 will search for eu-west-1 and eu-central-1 on the third expansion, which is at 130 milliseconds (ms ). If Player 3 submits a match ticket when Player 1 has already expanded to 110ms, Player 2 will not be matched to Player 1 since Player 2 is not on the region expansion yet and is still searching within the eu-west-1 region.

However, at some point, you may want to allow tickets that are too old to skip the bi-directionality and find a match with tickets that are in its expansion range. To do this, you can use the disable_bidirectional_latency_after_ms (in milliseconds) option in the ruleset. By default, it is disabled (0 or negative), which means it will always adhere to bi-directionality. But, if set, any pivot ticket older than disable_bidirectional_latency_after_ms will skip the step of filtering candidate tickets.

Rebalance of matched teams with multiple attributes​

Rebalance is a process where Matchmaking will arrange players who already matched together into a balanced team. In a competitive game, the rebalance process is important to make sure that the gameplay is fair and the overall MMR is similar among match teams. You can find more about the rebalancing process in the matchmaking rebalance topic.

By default, the attribute that will be used for the rebalance process is the first configuration in the matching rule. For example:

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 25,
        "player_max_number": 25
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200
        },
        {
            "attribute": "elo",
            "criteria": "distance",
            "reference": 100
        },
    ]
}

In the sample ruleset above, only the attribute mmr will be used for the rebalance process. However, we can set both attributes to be considered in the rebalancing process using the is_for_balancing flag.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 25,
        "player_max_number": 25
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200,
            "is_for_balancing": true
        },
        {
            "attribute": "elo",
            "criteria": "distance",
            "reference": 100,
            "is_for_balancing": true
        },
    ]
}

AccelByte recommends defining the max value for any statistic code that will be used in the matching rule config. By configuring the maximum stats value, the matchmaking can normalize the stats attribute and put a better weight for the matching and rebalance process.

{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 25,
        "player_max_number": 25
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200,
            "max": 2000,
            "is_for_balancing": true
        },
        {
            "attribute": "elo",
            "criteria": "distance",
            "reference": 100,
            "max": 3000,
            "is_for_balancing": true
        },
    ]
}

Matchmaking reserved keys​

AGS Matchmaking has some reserve keys which the game client can use when submitting the matchmaking request (ticket). The basic matchmaking ticket structure can be seen below:

{
    "sessionId": "string", // OPTIONAL - the party/game session ID that is being used for matchmaking
    "matchPool": "string", // REQUIRED - the matchpool name that will be used for matchmaking
    "latencies": "string", // OPTIONAL - the player latencies to the datacenter. It is the result for QoS call if you are using Accelbyte Multiplayer Server (AMS)
    "attributes": {}, // OPTIONAL - any matchmaking attributes from the game client to be considered for the matchmaking and backfill process
}

The game client can set any attributes data in the matchmaking ticket. This data will be used for searching for the matching player's candidate and an open session for the backfill process. All the attributes from the matchmaking ticket will be included in the game session attributes by default. However, some reserved keys can be set inside the attributes object that will not be included in the game session. Here is the list of reserved keys inside the attributes object:

  • client_version: "string" - This attribute refers to the game version or dedicated game server version that will be used for matchmaking. When you integrate with Accelbyte Multiplayer Servers (AMS) and the client_version value is set, the game session will first request a dedicated server from the development fleet that has the same claim key as the client_version value.
  • server_name: "string": The local dedicated server name if you are using AMS for the dedicated server management.
  • role: {} - Specifies the player's role preference for role-based matchmaking.
  • cross_platform: "string" - The current platform value of the player. See cross-play matchmaking for more details.
  • current_platform: [] - The list of platforms that the player wants to match to. See the cross-play matchmaking for more details.
  • new_session_only: boolean - Specifies if the player wants to skip being backfilled and only start a new session. The default value is false.
danger

Please do not use the reserved keys above for any other purpose. Otherwise, the new match and backfill processes can result in unexpected behavior.

Configure rulesets in the Admin Portal​

  1. First, determine the desired logic you want the ruleset to use when comparing players for a match. Once the JSON has been defined, continue with creating the ruleset.

  2. In the AGS Admin Portal, navigate to your desired namespace and go to Multiplayer > Matchmaking > Matchmaking Configuration.

  3. On the Match Ruleset tab, click + Create Rulesets. The Create Match Ruleset page will appear.

  4. In the Ruleset Name field, enter the name for this ruleset.

  5. In the Configuration (JSON) field, replace the body with your desired JSON.

  6. If there are no validation errors, click Create.

Example: Team 8 vs. 8​

In this example, the JSON will configure matchmaking to function with this criteria:

  • Auto-backfill is disabled.
  • There must be two teams before the match can start.
  • There can't be more than two teams.
  • There must be at least four players on each team before the match can start.
  • There can't be more than eight players per team.
{
    "auto_backfill": false,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 4,
        "player_max_number": 8
    }
}

Example: 4-player co-op with player level and rating matching​

In this example, the JSON will configure matchmaking to function with this criteria:

  • Auto-backfill is enabled.
  • There will only be one team as this is a co-op match.
  • There must be four players before the match can start.
  • Matchmaking will attempt to find four players within two levels and 20 rating points of the pivot player.
    • In this example, "rating" specifies a players rating according to others they have played with.
{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 4,
        "player_max_number": 4
    },
    "matching_rule": [
        {
            "attribute": "level",
            "criteria": "distance",
            "reference": 2
        },
        {
            "attribute": "rating",
            "criteria": "distance",
            "reference": 20
        }
    ]
}

Example: 25-player free for all with MMR flexing​

In this example, the JSON will configure matchmaking to function with this criteria:

  • Auto-backfill is enabled.
  • There will only be one team as this is a free for all match.
    • Note: there will always need to be one underlying team, even if players aren't working together.
  • There must be 25 players before the match can start.
  • Matchmaking will attempt to find 25 players within 200 matchmaking rating (MMR) of the pivot player.
  • If after 15 seconds 25 players haven't been matched, matchmaking will attempt to find additional players within 300 MMR of the pivot player.
  • If after 30 seconds 25 players haven't been matched, matchmaking will attempt to find additional players within 400 MMR of the pivot player.
  • If after 45 seconds 25 players haven't been matched, matchmaking will attempt to find additional players within 500 MMR of the pivot player.
{
    "auto_backfill": true,
    "alliance": {
        "min_number": 1,
        "max_number": 1,
        "player_min_number": 25,
        "player_max_number": 25
    },
    "matching_rule": [
        {
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 200
        }
    ],
    "flexing_rule": [
        {
            "duration": 15,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 300
        },
        {
            "duration": 30,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 400
        },
        {
            "duration": 45,
            "attribute": "mmr",
            "criteria": "distance",
            "reference": 500
        }
    ]
}

Example: Team 4 vs 4 with crossplay preference validation​

In this example, the JSON will configure matchmaking to function with this criteria:

  • Auto-backfill is disabled.
  • There must be two teams before the match can start.
  • There can't be more than two teams.
  • There must be at least four players on each team before the match can start.
  • There can't be more than four players per team.
  • Only players who select to crossplay on the same platforms will be matched.
{
    "auto_backfill": false,
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 4,
        "player_max_number": 4
    },
    "match_options": {
        "options": [
            {
                "name": "cross_platform",
                "type": "all"
            }
        ]
    }
}
Last updated on

On this page