Last Updated: 8/26/2021, 1:07:16 AM

# Matchmaking with Dedicated Server

# Overview

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 team, which are groups of parties that are teamed 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.

# Prerequisites

# Create IAM Client Credentials

Before the Dedicated Server can be built, it must have IAM Client Credentials and permission to call the DSM. Follow the tutorials below to create IAM client credentials for DS Client and DS Uploader.

# Create the DS Client Credentials

  1. In the dashboard of the Admin Portal, go to the Platform Configuration section and click the OAuth Clients menu.

    matchmaking

  2. The list of existing clients appears. Click the Create New button.

    matchmaking

  3. Create the DS Client. Input the required information, and choose Confidential as the client type.

    matchmaking

  4. When you’re done, you will be directed to the Client page. From here you can add permissions to the client by clicking the Add button.

    matchmaking

  5. When the form appears, fill in the permission with the appropriate format. After you have finished, click the Confirm button to save the permission.

    matchmaking

    Here are the permissions you must add to the DS Client so that it can call the DSM.

    matchmaking

# Create the DS Uploader Client Credentials

  1. In the Admin Portal, go to the OAuth Clients page and click the Create New button to add new client credentials.

    matchmaking

  2. Create the client credentials for DS Uploader. Input the required information, and choose Confidential as the client type.

    matchmaking

  3. When you’re done, you will be directed to the Client page. From here youcan add permissions to the client by clicking the Add button.

    matchmaking

  4. When the form appears, fill in the permission with the appropriate format. After you have finished, click the Confirm button to save the permission.

    matchmaking

    Here is the permission you must add to the DS Uploader client credentials.

    matchmaking

# 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 Uploader has been compiled to Linux
  • The DS Upload Service has been deployed in your Kubernetes cluster.
    When you upload the file to the server you are required to input several commands, listed below:
Flag Shortcut Description
--hostname -H Justice FQDN
--client-id -i Justice DS Uploader Client ID
--client-secret -s Justice DS Uploader Client Secret
--filename -f Game server ZIP file
--version -v Game server version
--command -c Game 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 this command to upload the file from your local computer to the Docker registry.

    ./uploader -H <HOSTNAME -i <CLIENT_ID> -f <SERVER_FILE> -v <SERVER_VERSION> -c <CMD> -n <NAMESPACE>  
    Example:  
    ./uploader -H https://my.domain.tld -i hello -f gameFile.zip -v v1.2.3 -c"./bin/game --enable-lootbox --allow-friendly-fire" -n "myNamespace"  
    

    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 https://my.domain.tld -i hello -f gameFile.zip -v v1.2.3 -c"./bin/game --enable-lootbox --allow-friendly-fire" -n "myNamespace"  
    
    • If you want to use the command without an argument, execute this command.
    ./uploader -H https://my.domain.tld -i hello -f gameFile.zip -v v1.2.3 -c"./bin/game" -n "myNamespace"  
    
  2. 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

  5. Review your configuration and make sure it's correct before saving.

matchmaking

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

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

  1. 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.
  2. Click Add to complete the configuration.

# 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.
  1. Register your Local Dedicated Server to the DSM.
  1. 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.
  1. After a match request is received, the Dedicated Server will accept the connections from game clients and will be able to start the match.
  2. When the match is finished, the DS can use this function to update the player’s attributes in the Statistics service.
  1. To make sure the DS is no longer registered in the DSM, call this function to deregister the DS from the DSM.

# 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.
  1. Register your Managed Dedicated Server to the DSM.
  1. 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.
  1. After a match request is received, the Dedicated Server will accept the connections from game clients and will be able to start the match.
  2. When the match is finished, the DS can use this function to update the player’s attributes in the Statistics service.
  1. Your managed dedicated server can be shut down automatically using this function.

# 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.
  1. Wait for the Lobby service to send a notification that a match has been found.
  1. The Lobby service will notify the game client that the player is ready to join the match using this function.
  1. Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

# 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.
  1. Use the array when you call the StartMatchmaking function.
  1. 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.
  1. Wait for the Lobby service to send a notification that a match has been found.
  1. Notify the game client that the player is ready to join the match using this function.
  1. Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

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

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

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.