Last Updated: 11/28/2021, 11:02:02 PM

# Matchmaking

# Overview

Matchmaking allows parties to be paired to compete against each other in your game. With AccelByte matchmaking services, you can create your own matchmaking rules (MMR) for how parties are matched. MMR are used to determine how parties are matched up under ideal conditions. You can also create flex rules, which dictate how to match parties when ideal matches aren’t possible. These flex rules usually include time limits for the matchmaking process, to ensure that players don’t have to wait too long to play your game.

Like our Party services, Matchmaking uses WebSocket to ensure real-time updates for players. Here’s the basic flow of our matchmaking service:

  1. Start Matchmaking A party leader can make a request to initiate the matchmaking process.
  2. Confirm Players are Ready During the matchmaking process, each player needs to confirm they are ready to play. When all of the players are ready to start, the game will begin.
    • Re-matchmaking Matchmaking will restart if any players in the matchup aren’t ready to play.
    • Cancel Matchmaking Party leaders can cancel the matchmaking process before it’s completed.

Players need to be in a party to use matchmaking. The Matchmaking service supports parties with single users or multiple users, and also supports matching parties with an asymmetrical number of users, e.g. a party with 1 user vs. a party with 3 users. You can configure all of the matchmaking rules in our Admin Portal.

# Prerequisites

# Create a Statistic Configuration Through the API

Before implementing the Matchmaking service, you need to define the Statistics that will be used by the Matchmaking service to match players together. Follow these steps to configure the statistics.

  1. Use the Create Stat: POST /v1/admin/namespaces/{namespace}/stats endpoint. Make sure you have the bearer access token for the authorization.
  2. Input the desired Namespace.
  3. Fill out the Request Body.
    • Input the defaultValue with the initial value assigned to the statistic. This value is the starting point for players.
    • Input a description of the statistics attribute.
    • Set the incrementOnly to sort the values of the statistic. Set to true to sort as incremental or false for decremental.
    • Input the minimum statistic value that can be assigned.
    • Input the maximum statistic value that can be assigned. For example, you can add a range of matchmaking points that players must fall into.
    • Input the name of the statistic.
    • Set the setAsGlobal field to true to make it so that every time the stat is updated it will also update the global stat value.
    • Input the setBy field with the game client or game server depending on which one will call the update stat value from the API.
    • Input the statCode field with a unique readable identifier that can be used for API Call or Function Call from the code. The allowed format for statCode is alphanumeric, lowercase, and hyphens.
    • Input the tags field with contextual information about how the stats are used.

Here is an example of a Request Body after it has been filled out:

{
  "defaultValue": 0,
  "description": "point used for matchmaking",
  "incrementOnly": true,
  "maximum": 99999,
  "minimum": 0,
  "name": "matchmaking point",
  "setAsGlobal": true,
  "setBy": "SERVER",
  "statCode": "match-point",
  "tags": [
    "match"
  ]
}

# Create a Statistic Configuration in the Admin Portal

In addition to using Swagger to configure statistics, you can also use the Admin Portal.

  1. In the Game Management section of the Admin Portal, go to Statistics and open the Configurations menu.

    matchmaking

  2. On the Configurations page, click Add Configuration to create a new statistics config.

    matchmaking

  3. A form will appear. Fill in the required information:

    • Input the Code field with a unique readable identifier that can be used for an API Call or Function Call from the code.
    • Input the Name of the statistic.
    • Input a Description of the statistic.
    • Input the Minimum statistic value allowed to be assigned.
    • Input the Maximum statistic value allowed to be assigned.
    • Input the Default Value with the initial statistic value assigned as the default.
    • Set the Increment to sort the value of the statistic. Set to true to sort as incremental or false for decremental.
    • Set the global stat value in the Set As Global field. Set to true to make every time the stat is updated it will also update the global stat value.
    • Select the Set By with the game client or server, depending on which client will call to update the stat value from the API.
    • Input the Tags field with contextual information about how the statistics will be used. For example, match.

    matchmaking

  4. Once you have finished, click Add and your new config will be added in the list.

    matchmaking

# Create User Statistics

After you configure the statistics, you need to tie the stats to the player by using the Create User’s Stat function. The function can be called using the client SDK, and will also be triggered every time the player logs in or the game initializes.

FAccelByteModelsBulkStatItemCreate TestStat;
TestStat.StatCode = "NUMBER_OF_KILLED";
FString UserID = "Game Client UserID";
FRegistry::Statistic.CreateUserStatItem({ TestStat },        THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([](const FAccelByteModelsBulkStatItemOperationResult& Result) {
                // Bulk Create user Multiple Stat code Success
            }),
        FErrorHandler::CreateLambda([](int32 Code, FString Message)
            {
                // Bulk Create user Multiple Stat code failed
            }));

# Set Up the Matchmaking Channel in the Admin Portal

  1. In the Admin Portal, choose the target game namespace.

    matchmaking

  2. In the Game Management section, open the Lobby and Matchmaking section and click Matchmaking Ruleset.

    matchmaking

  3. On the Matchmaking page, click Add Configuration to create a new matchmaking channel.

    matchmaking

  4. The Create Ruleset wizard will appear. Fill in the required information on each page.

    • Configuration

      matchmaking

      • Input a name for the game mode in the Game Mode field.
      • Input a description of the game mode in the Game Mode Description field.
      • Input the amount of time, in milliseconds, that the game client should spend finding a match before timing out in the Find Match Timeout field.
      • Input the amount of time, in milliseconds, the game server will wait to assign a Match ID to a newly initiated match in the Maximum Delay Time field.

      TIP

      The Maximum Delay Time can be used to help players be matched together in any situation where player count is low, such as during testing.

      • If you want your matchmaking to be joinable, select the Use Joinable Session option.
        • If you select Use Joinable Session, input how long, in seconds, a match should be joinable before timing out.

      After filling in all of the fields in the Configuration section, click Next.

    • Dedicated Server

      matchmaking

      • If you want to use Armada, select the Dedicated Server option.
        • Choose the Dedicated Server Deployment. If the deployment is left empty, Armada will spawn the default deployment.

      After filling the fields in the Dedicated Server section, click Next.

    • Ruleset

      • Choose Game Mode Only if your game only has one game mode.

        matchmaking

        • Input the maximum number of teams allowed in a match into the Max Teams field.
        • Input the minimum number of teams required for a match into the Min Teams field.
        • Input the maximum number of players allowed in a party into the Max Players field.
        • Input the minimum number of players required to form a party into the Min Players field.
      • Choose Sub Game Mode if your game hsa more than one game mode.

        matchmaking

        • Click Add Sub-Game Mode to add a ruleset for one of your game modes.

        • The Add Ruleset form appears. Fill in the required fields, as seen below:

          matchmaking

          • Input a name for the game mode in the Sub-Game Mode Name field.
          • Input the maximum number of teams allowed in a match into the Max Teams field.
          • Input the minimum number of teams required for a match into the Min Teams field.
          • Input the maximum number of players allowed in a party into the Max Players field.
          • Input the minimum number of players required to form a party into the Min Players field.
        • After filling the Add Ruleset form, click the Add button.

        Repeat this step, creating a ruleset for each of your different game modes. When you’re done, click Next.

    • Summary

      The summary of your configuration appears. Click Next to create the configuration.

      matchmaking

# Add Matching Rules

  1. In the Admin Portal, go to the Matchmaking page. Choose the to which Game Mode you want to add matchmaking rules. In the Action column, click the Ellipsis button and select View. You will be directed to the Matchmaking Detail page.

    matchmaking

  2. In the Matching Rule section, click the Add button.

    matchmaking

  3. Fill in the required information in the form that appears.

    matchmaking

    • Choose the player attribute. You can choose Stat Code if you’ve already created the related statistic configuration, or choose Custom if you want to use a custom attribute that doesn’t have a stat code. For this example, we’re going to choose stat code.
    • Input the player Attribute field with the statcode you used when you configured the related statistic, e.g. match-point. You do not need to fill in this field if you selected Custom above.
    • Input the Criteria for the matchmaking. Currently, the only supported value for criteria is Distance, which refers to the difference between players’ attributes. Matchmaking will match players based on their attribute distance.
    • Input the Reference point or number used for the criteria. As an example, if the distance reference is 1000 and the player’s attribute value is 2000, the matchmaking service will match players with attribute values between 1000 and 3000.
  4. Click Add to continue. The matching rule will be added to the list.

# Add Flexing Rules

  1. In the matchmaking detail page, find the Flexing Rule section and click Add.

    matchmaking

  2. Fill in the form that appears with the required information.

    matchmaking

    • Choose the player attribute. You can choose Stat Code if you’ve already created the related statistic configuration, or choose Custom if you want to use a custom attribute that doesn’t have a stat code. For this example, we’re going to choose stat code.
    • Input the player Attribute field with the statcode you used when you configured the related statistic, e.g. match-point. You do not need to fill in this field if you selected Custom above.
    • Input the Criteria for the matchmaking. Currently the only supported value for criteria is Distance, which refers to the difference between players’ attributes.
    • Input the Reference point or number used for the criteria. The reference for the flexing rule should be higher than the matching rule, since it’s used to broaden the search for matchmaking. For example, if the matching rule distance value is 1000, then the flexing rule should be 2000, so it can widen the search for available players.
    • Input the Duration of time it will take for the flexing rules to take effect if no matches are found under the matching rules.
  3. Click Add to save the rules. The new flexing rule will be added to the list.

# Add Optional Parameters

You can add optional parameters to your matchmaking rules by first defining the parameters you want, such as region or player level, and then define whether players should be matched when all of the chosen parameters match, when any of them match, or when none of them match. To add optional parameters to your matchmaking rules, follow the steps below:

  1. On the Matchmaking Ruleset page of the Admin Portal, scroll to the Optional Parameters section at the bottom of the page and click Add Optional Parameter to add a new parameter.

    matchmaking

  2. The Add Optional Parameters form appears. Fill it in with the required information.

    matchmaking

    • Input the desired parameter in the Parameter field. This can be Region, Language, Player Level, or anything else.
    • Select the desired Matching Option from the choices below:
      • Select Disabled if you want to turn off optional parameters.
      • Select All if you want players to be matched when all of the defined parameters match.
      • Select Any if you want players to be matched when any single parameter is a match.
      • Select Unique if you want players to be matched when none of the defined parameters match.

    When you’re done, click Add Parameter to add the new parameter.

  3. The parameter you created will appear in the Optional Parameters list in the Matching Rules panel at the bottom of the page. From here you can edit or delete any parameter.

    matchmaking

# Export and Import Matchmaking Configurations

# Export a Matchmaking Configuration

Follow the steps below to export a Matchmaking Configuration from a game namespace.

  1. In the Admin Portal, open the game namespace that contains the configuration you want to export. On the Matchmaking page, open the Add Configuration dropdown menu and select Export Configuration.

    matchmaking

  2. Your matchmaking configuration will be exported in a JSON file. Here is an example of the contents:

    IMPORTANT

    If you use our Dedicated Server Manager Armada, don’t forget to also export your Dedicated Server Configuration. You will need both configurations if you want to use them in a different game namespace.

# Import a Matchmaking Configuration

Follow the steps below to import a Matchmaking Configuration into a game namespace.

  1. In the Admin Portal, go to the game namespace where you want to import the configuration. On the Matchmaking page, open the Add Configuration dropdown menu and select Import Configuration.

    matchmaking

  2. The Import Configuration form appears. Here, select the configuration file you want to import and choose the import method from the options below:

    • Choose Replace if you want to completely replace the old configuration data for this namespace with the new data. Existing configurations with the same key will be replaced. New configurations with different keys will be added.
    • Choose Leave Out if you only want to add new data and leave the existing data as is. Existing configurations with the same key will not be changed. A new configurations with different keys will be added to the existing data.

    matchmaking

  3. A confirmation window appears. To confirm your selection, type IMPORT in the text box, then click the Import button.

    matchmaking

  4. Here you can see the configuration has been added to the namespace.

    matchmaking

    IMPORTANT

    If you use our Dedicated Server Manager Armada, don’t forget to also import your Dedicated Server Configuration. You will need both configurations in this namespace to use Armada.

# Implement Matchmaking using SDK

# Start the Matchmaking Process

The matchmaking can be started after the party leader invites another player to the party. The number of party members should match the configuration used when creating the matchmaking channel.

# Matchmaking Notifications

Once the matchmaking is finished, the matchmaking service will send a notification to the players to inform them that they've been matched. To implement this feature, use the function below.

# Cancel Matchmaking

The party leader can cancel matchmaking before a match is found. The players will also be notified that the matchmaking process is cancelled. To implement this feature, refer to the function below.

After the matchmaking process is completed, every player in each party needs to confirm their readiness to start the game. To implement this feature, refer to the function below.

# Restart Matchmaking

If a player doesn’t confirm their readiness for play, the matchmaking process will be repeated from the beginning. The team that contains a non-confirming player will be banned from matchmaking for 20 seconds. The default ban duration is configurable. To implement this feature, refer to the function below.

# Set Up the Matchmaking Channel in the API

You can configure the matchmaking channel using our API. Follow the steps below to perform a request:

  1. Use the Create a Channel: POST /matchmaking/namespaces/{namespace}/channels endpoint. Make sure you have the bearer access token for authorization.

  2. Input the desired Namespace.

  3. Fill out the Request Body.

    • Input a Description of the game mode.
    • Input the name of the game mode into the game_mode field. Possible game modes include duel and battle royale.
    • Define the ruleset of the game by filling in the team, matchmaking rule, and flexing rules.

    Fill in the attributes for the team to define how many teams will be matched.

    • Input the minimum number of teams required for the match into the min_number field.
    • Input the maximum number of teams allowed for the match into the max_number field.
    • Input the minimum number of players required in the team into the player_min_number field.
    • Input the maximum number of players allowed in a party into the player_max_number field.

    Fill in the attributes for the flexing rule. Flexing rules are used when the matchmaking service cannot find a match based on the matching rule. Flexing rules should be the same as matching rules, but with a higher reference point to allow for more possible matches.

    • Input the player Attribute field with the statcode you used when you configured the related statistic, e.g. match-point.
    • Input the Criteria for the matchmaking. Currently the only supported value for criteria is Distance, which refers to the difference between players’ attributes.
    • Input the Reference point or number used for the criteria. The reference for the flexing rule should be higher than the matching rule, since it’s used to broaden the search for matchmaking. For example, if the matching rule distance value is 1000, then the flexing rule should be 2000, so it can widen the search for available players.
    • Input the Duration of time it will take for the flexing rules to take effect if no matches are found under the matching rules.

    Fill in the attributes of the matching rule.

    • Input the player Attribute field with the statcode you used when you configured the related statistic, e.g. match-point.
    • Input the Criteria for the matchmaking. Currently, the only supported value for criteria is Distance, which refers to the difference between players’ attributes. Matchmaking will match players based on their attribute distance.
    • Input the Reference point or number used for the criteria.

# 1v1 Configuration

Here is an example of a channel configuration for a 1 vs 1 match. Two players will be matched together with this configuration.

{
   "slug":"namspace:string",
   "ruleSet":{
      "alliance":{
         "minNumber":2,
         "maxNumber":2,
         "playerMinNumber":1,
         "playerMaxNumber":1
      },
      "matchingRules":[
         {
            "attribute":"string",
            "criteria":"distance",
            "reference":0
         }
      ],
      "flexingRules":[
         {
            "duration":0,
            "attribute":"string",
            "criteria":"distance",
            "reference":0
         }
      ],
      "match_options":{
         "options":null
      },
      "sub_game_modes":{

      }
   },
   "namespace":"namespace",
   "gameMode":"string",
   "description":"string",
   "findMatchTimeoutSeconds":0,
   "sessionQueueTimeoutSeconds":0,
   "joinable":true,
   "socialMatchmaking":false,
   "use_sub_gamemode":false,
   "deployment":"-",
   "max_delay_ms":0
}

# 3v3v3 Configuration

This is a channel configuration for a 3v3v3 match where 9 individual players will be matched and play together.

{
   "slug":"namspace:string",
   "ruleSet":{
      "alliance":{
         "minNumber":3,
         "maxNumber":3,
         "playerMinNumber":3,
         "playerMaxNumber":1
      },
      "matchingRules":[
         {
            "attribute":"string",
            "criteria":"distance",
            "reference":0
         }
      ],
      "flexingRules":[
         {
            "duration":0,
            "attribute":"string",
            "criteria":"distance",
            "reference":0
         }
      ],
      "match_options":{
         "options":null
      },
      "sub_game_modes":{

      }
   },
   "namespace":"namespace",
   "gameMode":"string",
   "description":"string",
   "findMatchTimeoutSeconds":0,
   "sessionQueueTimeoutSeconds":0,
   "joinable":true,
   "socialMatchmaking":false,
   "use_sub_gamemode":false,
   "deployment":"-",
   "max_delay_ms":0
}