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.

How It Works

The Matchmaking service works along with our Dedicated Server Manager to ensure your players have a smooth multiplayer experience. Dedicated servers will handle every event that occurs in the game, hosting the players’ matchmaking session, and keep track of their scores.

There are two types of dedicated servers: local and managed. See the explanation below to know how matchmaking is handled by each dedicated server.

Local Dedicated Servers

A Local Dedicated Server is a type of dedicated server that runs on your local computer. This type of dedicated server is used to perform testing before a game is published.

Matchmaking Flow

matchmaking

  1. The Dedicated Server (DS) registers itself to the Dedicated Server Manager (DSM).
  2. The game client requests matchmaking through the Lobby service.
  3. The Lobby service forwards the matchmaking request to the Matchmaking service.
  4. Once a match is found, the Matchmaking service will notify the Lobby.
  5. The Lobby then notifies the game client that a match has been found.
  6. Then, the game client sends a message to the Lobby service indicating that the client is ready to receive players for the match.
  7. After the players confirm they’re ready for the match, the Lobby asks the DSM to spawn a DS with the players’ details, such as their game version, region, and alliances, which are groups of parties that are allied together.
  8. The DS sends a heartbeat to the DSM.
  9. The DSM passes the match details to the DS using the heartbeat response.
  10. The DSM passes back the local DS details such as region, IP address, and port.
  11. After that, the Lobby forwards the DS details to the game client.
  12. The game client connects to the DS and the game starts.
  13. Once the game ends, the DS sends the updated player attributes such as MMR and points to the Statistics service.

Prerequisites

Here are the requirements to be able to use a Local Dedicated Server:

  1. Dedicated Server Build
    • The Dedicated Server must be capable of making HTTP requests to our backend.
    • The Dedicated Server must have an accessible IP Address and Port from the game client.
    • The Dedicated Server’s IP Address and Port should be saved somewhere, since you’ll need them when configuring the DS.
    • The Dedicated Server must have IAM Client Credentials, including permission to call the DSM.
    • The Dedicated Server must perform a client token grant upon startup.
    • The Dedicated Server must call the following DSM endpoints:
      • The Register endpoint to tell the DSM that the DS is ready to accept players.
      • The Heartbeat endpoint periodically, to tell the DSM that the DS is still active. The DSM will respond with matchmaking data if any match has claimed the DS.
      • The Deregister endpoint, to tell the DSM that the match session is over.
  2. Game Client Build
    • A game client must be capable of making HTTP requests to our backend.
    • A game client must be able to connect to Dedicated Server’s IP and port.
  3. Access to our Admin Portal
    • You must have permission to manage the Statistics config.
    • You must have permission to manage the Matchmaking config.
    • You must have permission to manage the Dedicated Server Manager.

Managed Dedicated Servers

A Managed Dedicated Server is managed by AccelByte to ensure smooth player experience and maximize your game’s performance, especially during multiplayer sessions with many players playing the game at once.

Matchmaking Flow

matchmaking

  1. The game client requests matchmaking through the Lobby service.
  2. The Lobby forwards the matchmaking request to the Matchmaking service.
  3. When a match is found, the Matchmaking service notifies the Lobby service.
  4. Then, the Lobby notifies the game client that a match has been found.
  5. The game client indicates that it’s ready for the match.
  6. The Lobby asks the Dedicated Server Manager (DSM) to spawn a Dedicated Server (DS) and also passes the match details to the DSM.
  7. The DSM spawns a DS docker instance.
  8. The DS registers itself to the DSM.
  9. The DS sends a heartbeat periodically to the DSM. Then the DSM includes the match details in a heartbeat response to the DS.
  10. The DSM sends the DS details to the Lobby service.
  11. The Lobby service forwards the DS details to the game client.
  12. The game client connects to the DS and the game starts.
  13. Once the game ends, the DS sends the updated player attributes such as MMR and points to the Statistics service.

Prerequisites

Here are the requirements to be able to use a Managed Dedicated Server.

  1. Dedicated Server Build
    • The Dedicated Server must be containerized as a Linux Docker image and uploaded to ECR. You can use our uploader tool to make uploading easier.
    • The Dedicated Server must have IAM client credentials, including permission to call the DSM.
    • The Dedicated Server must perform a client token grant upon startup.
    • The Dedicated Server must call the following DSM endpoints:
      • The Register endpoint to tell the DSM that the DS is ready to accept players.
      • The Heartbeat endpoint periodically, to tell the DSM that the DS is still active. The DSM will respond with matchmaking data if any match has claimed the DS.
      • The Shutdown endpoint to notify the DSM that the matchmaking session is over.
  2. Game Client Build
    • The game client must be capable of making HTTP requests to our backend.
  3. Access to our Admin Portal
    • You must have permission to manage the Statistics config.
    • You must have permission to manage the Matchmaking config.
    • You must have permission to manage the DSM.

Tutorials

Set Up a Dedicated Server Manager

To set up a Dedicated Server Manager, the first thing you have to do is upload your dedicated server. To do so, make sure you have fulfilled the following requirements:

  • The DS Binary has been compiled to Linux
  • The Justice DS Uploader has been deployed in your Kubernetes cluster. When you upload the file to the server you are required to input several commands, listed below:
FlagShortcutDescription
--hostname-HJustice FQDN
--client-id-iJustice DS Uploader Client ID
--client-secret-sJustice DS Uploader Client Secret
--filename-fGame server ZIP file
--version-vGame server version
--command-cGame server command with flags

Upload the Dedicated Server Build

Follow the steps below to upload the file from your local computer to the Docker registry.

  1. Execute the following command to authenticate the user.
./uploader login -H <HOSTNAME> -i <IAM_CLIENT_ID> -s <IAM_CLIENT_SECRET>
  1. After the login process is finished, the authorization process will show the result in your console. If authorization has succeeded, you may proceed to the next step. If it has failed, re-check your Client ID and Client Secret and try again.
  2. Execute this command to upload the file from your local computer to the Docker registry.
./uploader -H <HOSTNAME> -f <SERVER_FILE> -v <SERVER_VERSION> -c “<CMD>”
Example:
./uploader -H gameServerFQDN -f gameFile.zip -v v6.6.6 -c “./bin/game --allow-friendly-fire --enable-lootbox”

Note:

  • The Server File must be in ZIP format.

  • If you are using a flag, you must surround the input in quotation marks if it continues a argument, as seen below:

    • If you want to use command and argument, execute this command to upload the file.
    ./uploader -H <HOSTNAME> -v <GAME_VERSION> -f <SERVER_FILE> -c “./bin/game --enable-lootbox”
    • If you want to use the command without an argument, execute this command.
    ./uploader -H <HOSTNAME> -v <GAME_VERSION> -f <SERVER_FILE> -c ./bin/game
  1. When the upload is finished, the console will return an output containing parameters that you need to input to configure your Dedicated Server in the Admin Portal.

Add the Dedicated Server Configuration

  1. In the Admin Portal, choose the Namespace for the game for which you want to create the configuration.

    matchmaking

  2. Go to the Dedicated Server Management section and open the Configurations menu.

    matchmaking

  3. In the Server Configurations menu, click Add Configuration.

    matchmaking

  4. After the Configuration Form appears, Click the Add button on the Image Version. Fill it in with the required information.

    matchmaking

    matchmaking

    • Input the Version of your dedicated server build with the appropriate format, seen in the image above.
    • Input the Image field with the dedicated server image you received after uploading your build. This also needs to follow the formatting rules shown above.

    Click the Add button to add the Image Version. Then, continue to fill in the Configuration Form with the required information.

    • Input the Port where your DS is listening for a connection.
    • Input the minimum number of DS spawned, whether active or idle, in the Min. Count field.
    • Input maximum number of DS allowed to spawn in the Max. Count field.
    • Input the default number of ready DS. The DSM will spawn idle DS according to the Buffer Count. This ensures that there will be a DS ready for players during matchmaking.
    • Input the minimum number of cores needed by the dedicated server with the appropriate format in the CPU Request field.
    • Input the minimum amount of memory needed by the dedicated server in the Memory Request field.
    • Input the CPU Limit with the maximum number of cores that can be used by the dedicated server.
    • Input the Memory Limit with the maximum amount of memory that can be used by the dedicated server.

    The fields below are optional:

    • Input the Creation Timeout field with the time limit for the dedicated server to register itself to the Lobby service after being spawned. If the time limit is exceeded, the DSM will remove the DS.
    • Input the Claim Timeout field with the time limit for the Lobby service to claim a DS after being requested. The DSM will remove the DS if the time limit is exceeded.
    • Input the Session-Timeout field with the time limit for an active session to finish. The DSM will remove the DS if the time limit is exceeded.
    • Input the Heartbeat Timeout field with the time limit for a registered DS to call the heartbeat endpoint as an indicator that the DS is active. If the DS is unreachable it will be marked as such by the DSM.
    • Input the Unreachable Timeout field with the time limit for an unreachable dedicated server to call the heartbeat endpoint. If the time limit is exceeded, the DSM will remove the DS.

    Note:

    • The Max. Count value should not be less than Min. Count value.
    • The values for CPU Request, Memory Request, CPU Limit, and Memory Limit must be formatted in Kubernetes, e.g. CPU of 1000m is equal to 1 core and Memory of 512Mi is equal to 512MB.

matchmaking

  1. Click Add to complete the configuration.

Differentiate DS Deployments

You can create multiple, distinct DS deployments your game needs more than one DS build. For example, if your game has several different maps that players can choose from you need to differentiate the DS deployments so that each configuration of your game will have a different DS build.

You can differentiate your DS configurations by their Image Version, Pod Configuration, and the Region of the DS in deployment. See the tutorials below to add differentiation for each parameter in the Admin Portal.

Configure the Image Versions You learned how to add the Image Versions when you configured the Dedicated Server. Here you’ll learn how to add more Image Versions.

  1. In the Admin Portal, click Configurations in the left navigation bar. In the list of the Server Configurations, choose your Dedicated Server Build and you will be directed to the Configuration Details. Click Add in the bottom-right corner of the page to add a new Image Version.

matchmaking

  1. Fill in the form that appears.

matchmaking

  • Input the Version of your dedicated server build with the appropriate format shown in the image above.
  • Input the Image with the dedicated server image that you received after uploading your build.
  1. Once the new image version has been added, you can choose which Image Version is the default by selecting the checkbox next to the desired image version in the Default column.

Configure the Pod Configuration New pod configurations can have different CPU, Memory Requests, and also different Parameter arguments. Follow these steps to add a new Pod Configuration.

  1. In the Configuration Details window of the Admin Portal, go to the Pod Configurations tab and click the Add button.

    matchmaking

  2. After the configuration form appears, input the fields with the appropriate format.

    matchmaking

    • Input the Name of the Pod Configuration. You can input the game mode you’re using, such as Duel or Battle Royale, to make the pod configuration easy to find.
    • Input the CPU Request field with the minimum number of cores needed.
    • Input the Memory Request field with the minimum amount of memory needed.
    • Input the CPU Limit with the maximum number of cores that can be used by the dedicated server.
    • Input the Memory Limit with the maximum amount of memory that can be used.
    • Input the Parameter argument if you want to apply any custom parameters to your game. Leave this field empty if you don’t want to add any parameters.

    Note:

    • The values for CPU Request, Memory Request, CPU Limit, and Memory Limit must be formatted in Kubernetes, e.g. CPU of 1000m is equal to 1 core and Memory of 512Mi is equal to 512MB.
  3. Click Add to proceed.

Configure the Deployments After you have configured a different Image Version and Pod Configuration, next you can configure the Deployment. You can add another deployment with a different pod, version, and server region. Follow the steps below to add a new pod configuration.

  1. In the Configuration Details window of the Admin Portal, go to the Deployments tab and click Add.

    matchmaking

  2. After the configuration form appears, input the fields with the appropriate format.

    matchmaking

    • Input the Name of the deployment configuration. You should have a descriptive and readable name.
    • Select the Version of the image you want to deploy.
    • Select the Pod Configuration you want to use for this deployment.
    • Choose the Region where the DS will be deployed.
    • Input the Min. Count with the minimum number of DS spawned, whether active or idle.
    • Input the Max. Count with the maximum number of the DS allowed to spawn.
    • Input the default number of ready DS. The DSM will spawn idle DS according to the Buffer Count. This ensures that there will be a DS ready for players during matchmaking.

    Note:

    • The Max. Count value should not be less than Min. Count value.
  3. Click Add to complete the configuration.

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

Set Up the Matchmaking Channel in the API Gateway

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 Game Management section of the Admin Portal, click Matchmaking.

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

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

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

    matchmaking

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

    • 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.
  3. Click Add to save the rules. The new flexing rule will be added to the list.

    matchmaking

Integrate a Local Dedicated Server to the DSM

  1. Run your Dedicated Server.

  2. On startup, configure the heartbeat to send the heartbeat periodically to the DSM.

    bool bIsAutomatic = true; //Is the heartbeat sent automatically?
    uint32 HeartBeatPeriod = 5; //The heartbeat will be send every x seconds
    uint32 ErrorRetry = 5; //Still sending a heartbeat after 4xx error for x times
    FRegistry::ServerDSM.ConfigureHeartBeat(bIsAutomatic, HeartBeatPeriod, ErrorRetry);
  3. Register your Local Dedicated Server to the DSM.

    // Please put a reachable IP address from the game client.
    FString IPAddress = "127.0.0.1";
    int32 PortNumber = 7777;
    FString ServerName = "your-awesome-game-server";
    AccelByte::FRegistry::ServerDSM.RegisterLocalServerToDSM(
    IPAddress,
    PortNumber,
    ServerName,
    FVoidHandler::CreateLambda([]()
    {
    //Register successful
    }),
    FErrorHandler::CreateLambda([OnError](int32 Code, FString Message)
    {
    // Register Local Server to DSM Failed!
    }));
  4. Once the Dedicated Server is registered to the DSM, the heartbeat will be sent periodically to the DSM. The DSM will receive match requests from the Lobby service, and those requests will be forwarded to the Dedicated Server in a heartbeat response. The Dedicated Server will be notified if there is a match request using a callback.

    FRegistry::ServerDSM.SetOnMatchRequest(
    THandler<FAccelByteModelsMatchRequest>::CreateLambda([]
    (const FAccelByteModelsMatchRequest& MatchRequest)
    {
    //Receive match details to verify game clients connections and start the match
    }));
  5. After a match request is received, the Dedicated Server will accept the connections from game clients and will be able to start the match.

  6. When the match is finished, the DS can use this function to update the player’s attributes in the Statistics service.

    #include "GameServerApi/AccelByteServerStatisticApi.h"
    // for example we are going to update 1 user
    FAccelByteModelsBulkStatItemInc MVP;
    MVP.inc = 1;
    MVP.statCode = StatisticStatCode;
    FRegistry::ServerStatistic.BulkAddUserStatItemValue({ MVP }, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([](TArray<FAccelByteModelsBulkStatItemOperationResult> Result){
    // Bulk Add user STATITEMS SUCCESS!
    }), FErrorHandler::CreateLambda([](int32 Code, FString Message)
    {
    // Bulk Add user STATITEMS Failed
    })
    );
  7. To make sure the DS is no longer registered in the DSM, call this function to deregister the DS from the DSM.

    FString ServerName = "your-awesome-game-server";
    AccelByte::FRegistry::ServerDSM.DeregisterLocalServerFromDSM(
    ServerName,
    FVoidHandler::CreateLambda([](){
    // Deregister success
    }),
    FErrorHandler::CreateLambda([OnError](int32 Code, FString Message)
    {
    // Deregister failed
    })
    );

Integrate a Managed Dedicated Server to the DSM

  1. Run your Dedicated Server.

  2. On startup, configure the heartbeat to send the heartbeat periodically to the DSM.

    bool bIsAutomatic = true; //Is the heartbeat sent automatically?
    uint32 HeartBeatPeriod = 5; //The heartbeat will be send every x seconds
    uint32 ErrorRetry = 5; //Still sending a heartbeat after 4xx error for x times
    FRegistry::ServerDSM.ConfigureHeartBeat(bIsAutomatic, HeartBeatPeriod, ErrorRetry);
  3. Register your Managed Dedicated Server to the DSM.

    RegisterServerToDSM(
    7777,
    FVoidHandler::CreateLambda([]()
    {
    //Register successful
    }),
    FErrorHandler::CreateLambda([](int32 Code, FString Message)
    {
    // Bulk Add user STATITEMS Failed
    }));
  4. Once the Dedicated Server is registered to the DSM, the heartbeat will be sent periodically to the DSM. The DSM will receive match requests from the Lobby service, and those requests will be forwarded to the Dedicated Server in a heartbeat response. The Dedicated Server will be notified if there is a match request using a callback.

    FRegistry::ServerDSM.SetOnMatchRequest(
    THandler<FAccelByteModelsMatchRequest>::CreateLambda([]
    (const FAccelByteModelsMatchRequest& MatchRequest)
    {
    //Receive match details to verify game clients connections and start the match
    }));
  5. After a match request is received, the Dedicated Server will accept the connections from game clients and will be able to start the match.

  6. When the match is finished, the DS can use this function to update the player’s attributes in the Statistics service.

    #include "GameServerApi/AccelByteServerStatisticApi.h"
    // for example we are going to update 1 user
    FAccelByteModelsBulkStatItemInc MVP;
    MVP.inc = 1;
    MVP.statCode = StatisticStatCode;
    FRegistry::ServerStatistic.BulkAddUserStatItemValue({ MVP }, THandler<TArray<FAccelByteModelsBulkStatItemOperationResult>>::CreateLambda([](TArray<FAccelByteModelsBulkStatItemOperationResult> Result){
    // Bulk Add user STATITEMS SUCCESS!
    }), FErrorHandler::CreateLambda([](int32 Code, FString Message)
    {
    // Bulk Add user STATITEMS Failed
    })
    );
  7. Your managed dedicated server can be shut down automatically using this function.

    FString ServerName = "your-awesome-game-server";
    AccelByte::FRegistry::ServerDSM.SendShutdownToDSM(
    true, //KillMe
    “some-match-id”, //MatchId
    FVoidHandler::CreateLambda([](){
    // Shutdown success
    }),
    FErrorHandler::CreateLambda([OnError](int32 Code, FString Message)
    {
    // Shutdown failed
    })
    );

Connect a Game Client to the Dedicated Server

  1. Make sure the player is logged in.

  2. Call this function to request the Lobby service to start matchmaking. We provide a unique DS name to make sure that the player will connect to the local DS. An empty server name means the DSM will create an instance of a managed DS.

    // Make sure you use same server name from Local Dedicated Server Above
    FString GameMode = TEXT("1v1");
    FString ServerName = TEXT("your-awesome-game-server");
    AccelByte::FRegistry::Lobby.SendStartMatchmaking(GameMode, ServerName );
  3. Wait for the Lobby service to send a notification that a match has been found.

    AccelByte::FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::FMatchmakingNotif::CreateLambda([&](const FAccelByteModelsMatchmakingNotice& Response)
    {
    if (Response.Status == EAccelByteMatchmakingStatus::Done)
    {
    // Match found
    FString MatchId = Response.MatchId;
    // send ready consent
    AccelByte::FRegistry::Lobby.SendReadyConsentRequest(MatchId);
    }
    // show loading for non leader party member
    else if (Response.Status == EAccelByteMatchmakingStatus::Start)
    {
    // matchmaking has started
    }
    else
    {
    if (Response.Status == EAccelByteMatchmakingStatus::Cancel)
    {
    //Matchmaking canceled by party leader
    }
    else if (Response.Status == EAccelByteMatchmakingStatus::Timeout)
    {
    //Matchmaking failed: Timeout
    }
    else if (Response.Status == EAccelByteMatchmakingStatus::Unavailable)
    {
    // dedicated server unavailable
    }
    else
    {
    // matchmaking failed
    }
    }
    }));
  4. The Lobby service will notify the game client that the player is ready to join the match using this function.

    AccelByte::FRegistry::Lobby.SendReadyConsentRequest(MatchId);
  5. Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

    AccelByte::FRegistry::Lobby.SetDsNotifDelegate(AccelByte::Api::Lobby::FDsNotif::CreateLambda([&](const FAccelByteModelsDsNotice& Notice)
    {
    UE_LOG(LogOnlineGame, Log, TEXT("DS Notif Status: %s"), *Notice.Status);
    if (Notice.Status.Compare(TEXT("READY")) == 0)
    {
    FString ServerAddress = FString::Printf(TEXT("%s:%i"), *Notice.Ip, Notice.Port);
    // Use this IP address and port to connect to your server.
    }
    }));

Connect a Game Client to Dedicated Servers in Multiple Regions

  1. Make sure the player is logged in.

  2. Use the GetServerLatencies function to get the latencies from each region. This will return an array of pairs of regions and latency in ms.

    bool bGetServerLatenciesSuccess = false;
    TArray<TPair<FString, float>> Latencies;
    FRegistry::Qos.GetServerLatencies(THandler<TArray<TPair<FString, float>>>::CreateLambda([&bGetServerLatenciesSuccess, &Latencies](const TArray<TPair<FString, float>>& Result)
    {
    UE_LOG(LogAccelByteQosTest, Log, TEXT("Get Server Latencies Success! Count: %d"), Result.Num());
    bGetServerLatenciesSuccess = true;
    Latencies = Result;
    }), QosTestErrorHandler);
  3. Use the array when you call the StartMatchmaking function.

    //Start matchmaking to play on a managed DS in a region.
    Lobby.SendStartMatchmaking(ChannelName, "", "", Latencies);
  4. The DSM will create a DS in a region with the lowest latency. To select one region, you can pass the region you want in one element array.

    //Start matchmaking to play on a managed DS in a region.
    Lobby.SendStartMatchmaking(ChannelName, "", "", Latencies);
  5. Wait for the Lobby service to send a notification that a match has been found.

    AccelByte::FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::FMatchmakingNotif::CreateLambda([&](const FAccelByteModelsMatchmakingNotice& Response)
    {
    if (Response.Status == EAccelByteMatchmakingStatus::Done)
    {
    // Match found
    FString MatchId = Response.MatchId;
    // send ready consent
    AccelByte::FRegistry::Lobby.SendReadyConsentRequest(MatchId);
    }
    // show loading for non leader party member
    else if (Response.Status == EAccelByteMatchmakingStatus::Start)
    {
    // matchmaking has started
    }
    else
    {
    if (Response.Status == EAccelByteMatchmakingStatus::Cancel)
    {
    //Matchmaking canceled by party leader
    }
    else if (Response.Status == EAccelByteMatchmakingStatus::Timeout)
    {
    //Matchmaking failed: Timeout
    }
    else if (Response.Status == EAccelByteMatchmakingStatus::Unavailable)
    {
    // dedicated server unavailable
    }
    else
    {
    // matchmaking failed
    }
    }
    }));
  6. Notify the game client that the player is ready to join the match using this function.

    AccelByte::FRegistry::Lobby.SendReadyConsentRequest(MatchId);
  7. Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

    AccelByte::FRegistry::Lobby.SetDsNotifDelegate(AccelByte::Api::Lobby::FDsNotif::CreateLambda([&](const FAccelByteModelsDsNotice& Notice)
    {
    UE_LOG(LogOnlineGame, Log, TEXT("DS Notif Status: %s"), *Notice.Status);
    if (Notice.Status.Compare(TEXT("READY")) == 0)
    {
    FString ServerAddress = FString::Printf(TEXT("%s:%i"), *Notice.Ip, Notice.Port);
    // Use this IP address and port to connect to your server.
    }
    }));

Request Matchmaking with Custom Attributes

Client Side

  1. Make sure the player is logged into the game.

  2. Connect to the Lobby service and request matchmaking with the Party attributes parameter.

    FString GameMode = TEXT("1v1");
    FString ServerName = TEXT("Fill-if-you-use-local-DS");
    FString ClientVersion = TEXT("Fill-when-you-request-different-ds-version");
    TArray<TPair<FString, float>> Latencies;
    TMap<FString, FString> PartyAttributes;
    PartyAttributes.Add("GameMap", "BasicTutorial");
    PartyAttributes.Add("MapCustom", "SuddenDeath");
    AccelByte::FRegistry::Lobby.SendStartMatchmaking(GameMode, PartyAttributes);
  3. After that, you can follow the same steps as you would making other matchmaking requests.

Server Side

  1. Make sure the DS is authenticated and registered in the DSM.

  2. Subscribe to the OnMatchRequest callback and get the Party Attribute from the callback when the DS gets a match.

    TMap<FString, FString> PartyAttributes;
    FRegistry::ServerDSM.SetOnMatchRequest(
    THandler<FAccelByteModelsMatchRequest>::CreateLambda
    ([&PartyAttributes](const FAccelByteModelsMatchRequest& MatchRequest)
    {
    //Receive match details to verify game clients connections and start the match
    PartyAttributes = MatchRequest.Matching_allies[0].Matching_parties[0].Party_attributes;
    }));

Cleaning Up

To make sure the local DS is already deregistered from the DSM, use our DSM swagger and follow these steps.

  1. Make sure you have the bearer access token for authorization.

  2. Check if the local DS is still registered in the DSM with this endpoint.

    GET /dsm/admin/namespaces/{namespace}/servers/local
  3. Call this endpoint to remove the DS.

    DELETE /dsm/admin/namespaces/{namespace}/servers/local/{name}

DS Auto Shutdown

The Dedicated Server will automatically shut down after a period of time when it has been claimed but contains no active players. You can set the countdown on

ConfigureHeartBeat() function or disable it by setting the countdown to -1.
bool bIsAutomatic = true; //Is the heartbeat sent automatically?
uint32 HeartBeatPeriod = 5; //The heartbeat will be send every x seconds
uint32 ErrorRetry = 5; //Still sending a heartbeat after 4xx error for x times
int ShutdownCountdown = 30; //DS will shutdown after x seconds inactivity, set to -1 to disable
FRegistry::ServerDSM. ConfigureHeartBeat(bIsAutomatic, HeartBeatPeriod, ErrorRetry, ShutdownCountdown);

You can also set a delegate when the auto shutdown is called using the SetOnAutoShutdownResponse(). If the auto shutdown fails, the error will be sent to SetOnAutoShutdownErrorDelegate(), as shown below.

FRegistry::ServerDSM.SetOnAutoShutdownResponse(FVoidHandler::CreateLambda([]()
{
UE_LOG(LogTemp, Log, TEXT("Auto Shutting down!"));
}));
FRegistry::ServerDSM.SetOnAutoShutdownErrorDelegate(FErrorHandler::CreateLambda([](int32 ErrorCode, FString ErrorMessage)
{
UE_LOG(LogTemp, Fatal, TEXT("Error code: %d\nError message:%s"), ErrorCode, *ErrorMessage);
}));

What’s Next?