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

Set Up the Statistics Service

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
}));

Tutorials

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 alliance, matchmaking rule, and flexing rules.

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

    • Input the minimum number of alliances required for the match into the min_number field.
    • Input the maximum number of alliances allowed for the match into the max_number field.
    • Input the minimum number of players required in the allies 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.

{
"description": "1v1 duel match",
"game_mode": "duel",
"rule_set": {
"alliance": {
"min_number": 2,
"max_number": 2,
"player_min_number": 1,
"player_max_number": 1
},
"flexing_rule": [{
"attribute": "match-point",
"criteria": "distance",
"reference": 100,
"duration": 120
}],
"matching_rule": [{
"attribute": "match-point",
"criteria": "distance",
"reference": 50
}]
}
}
3v3v3 Configuration

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

{
"description": "3v3v3 battle royale",
"game_mode": "battle royale",
"rule_set": {
"alliance": {
"min_number": 2,
"max_number": 3,
"player_min_number": 3,
"player_max_number": 3
},
"flexing_rule": [{
"attribute": "match-point",
"criteria": "distance",
"reference": 100,
"duration": 120
}],
"matching_rule": [{
"attribute": "match-point",
"criteria": "distance",
"reference": 50
}]
}
}

Setup the Matchmaking Channel in the Admin Portal

In addition to using Swagger to set up the matchmaking channel, you can also use the Admin Portal.

  1. In the Lobby and Matchmaking section of the Admin Portal, click Matchmaking Ruleset.

    matchmaking

  2. In the Matchmaking window, click Add Configuration to create a new Game Mode.

    matchmaking

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

    • Input the name of the Game Mode.
    • Define the timeout limit for finding a match in the Find Match Timeout field.
    • If you want your matchmaking to be Joinable, tick the Use Joinable Session.
      • Input the Joinable Session Timeout with how long the joinable session is in the queue. The value is in seconds.
    • If you want to use the Dedicated Server Service, tick the Use Dedicated Server Service.
      • Choose the Dedicated Server Deployment. If the deployment is left empty, Armada will spawn the default deployment.
    • Input a Description of the game mode.
    • Input the maximum number of alliances allowed in the match into the max_number field.
    • Input the minimum number of alliances required for the match into the min_number field.
    • Input the maximum number of players allowed in a party into the player_max_number field.
    • Input the minimum number of players required to form a party into the player_min_number field.

    For example, if you want to create a 3vs3vs3 matchmaking channel configuration where 9 players are divided into 3 teams, use the inputs seen in the image below.

    matchmaking

  4. Click Save to save the configuration.

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.

Implement Matchmaking Using the 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.

FRegistry::Lobby.SetStartMatchmakingResponseDelegate(Lobby::FMatchmakingResponse::CreateLambda([](FAccelByteModelsMatchmakingResponse Result)
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Start Matchmaking Success!"));
if (Result.Code != "0")
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Start Matchmaking Failed!"));
}
}));
const FString ChannelName = "1vs1";
FRegistry::Lobby.SendStartMatchmaking(ChannelName);

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.

FRegistry::Lobby.SetMatchmakingNotifDelegate(Lobby::FMatchmaking::CreateLambda([](const FAccelByteModelsMatchmakingNotice& Notice)
{
if (Notice.Status == "done")
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Match found"));
}
}));

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.

FRegistry::Lobby.SetCancelMatchmakingResponseDelegate(Lobby::FMatchmakingResponse::CreateLambda([](FAccelByteModelsMatchmakingResponse result)
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Cancel Matchmaking Success!"));
if (result.Code != "0")
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Cancel Matchmaking Failed!"));
}
}));
const FString ChannelName = "1vs1";
FRegistry::Lobby.SendCancelMatchmaking(ChannelName);

Ready Consent

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.

FRegistry::Lobby.SetReadyConsentResponseDelegate(Lobby::FReadyConsentResponse::CreateLambda([](FAccelByteModelsReadyConsentRequest result)
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Ready Consent Send!"));
}));
FRegistry::Lobby.SetReadyConsentNotifDelegate(Lobby::FReadyConsentNotif::CreateLambda([](FAccelByteModelsReadyConsentNotice result)
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Get Ready Consent Notice!"));
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("User %s is ready for match."), *result.UserId);
}));
const FString MatchId = "a1b2c3d4e5";
FRegistry::Lobby.SendReadyConsentRequest(MatchId);

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.

FRegistry::Lobby.SetRematchmakingNotifDelegate(Api::Lobby::FRematchmakingNotif::CreateLambda([](FAccelByteModelsRematchmakingNotice result)
{
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("Get Rematchmaking Notification!"));
UE_LOG(LogAccelByteLobbyTest, Log, TEXT("User %s received: banned for %d secs"), *UserCreds[0].GetUserId(), result.BanDuration);
}));

Related Concepts