Matchmaking with Dedicated Server

Last updated on 15 July, 2022 1:44 AM

Overview

AccelByte Cloud's Matchmaking service works with our Dedicated Server Manager to ensure your players have a smooth multiplayer experience. Dedicated servers handle every event that occurs in your game, host players' matchmaking sessions, and keep track of their scores.

There are two types of dedicated servers: local and managed. See the explanation below to find out 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

Once launched, local DS registers to the DSMC.
The player launches the game and logs in to AccelByte.
The player connects to the Lobby service through a WebSocket connection.
The player sends a matchmaking to localDS request to the Lobby service.
The Lobby service sends a request to the DSM to create a new game session with the match details.
The DSM checks whether the specified local DS exists.
If the local DS exists, the DSM sends back the DS details. If the local DS does not exist, the request fails.
The game client connects to the server using the provided DS details.

Prerequisites

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

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 Deregister endpoint, to tell the DSM that the match session is over.
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.
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 Cloud 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

The player connects to the Lobby service through a WebSocket connection.
The player sends a Matchmaking request to the Lobby service.
The Lobby service acts as a proxy and forwards the incoming message to the Matchmaking service.
When a match is found, the Matchmaking service notifies the Lobby service.
The Lobby service sends a request to the DSM to create a new game session with the match details.
The DSM checks whether a DS pod is available.
If an idle pod is available, the DSM assigns the available DS pod. If there are no idle pods available, the DSM spawns a new DS pod, claims it, and assigns the game to it.
Once complete, the DSM notifies the Lobby service that the session has been created and sends the DS details.
The Lobby service forwards the DS details to the game client.
The game client connects to the server using the DS details.

Prerequisites

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

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.
Game Client Build
- The game client must be capable of making HTTP requests to our backend.
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 a DS Client Credentials. Create a DS Client with Confidential as the client type. Here are the permissions you must add to the DS Client so that it can call the DSM.

Create DS Uploader Client Credentials. Create the client credentials for DS Uploader with Confidential as the client type. Here is the permission you must add to the DS Uploader client credentials.

Usage	Permission	Action
Create an STS Configuration	NAMESPACE:{namespace}:DSUS:CONFIG	Create
Create an Image	NAMESPACE:{namespace}:DSUS:IMAGE	Create
Check DS Status	NAMESPACE:{namespace}:DSUS:IMAGE	Read
Patch existing image version	NAMESPACE:{namespace}:DSM:SERVER	Create, Update
Check Image Version Availability on Armada	NAMESPACE:(namespace):DSM:CONFIG	Read

Tutorials

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:

Upload a New Server with DS Uploader

You can upload a new server using our DS Uploader. Before uploading a server for the first time, you'll have to create an IAM client for DS Uploader with the following permissions:

NOTE

You only need to create an IAM Client for DS Uploader the first time you use it to upload a server.

To upload a DS uploader, follow the steps below:

In the Admin Portal, open the desired game namespace, then go to the Dedicated Server Management section and open the Configurations menu.
On the Configurations page, click the Upload Instructions button in the Image Server and Deployment panel.
Download the version of the dedicated server uploader that matches your operating system. After that, click the Next button.
On the Generate Command page, fill in the fields below with the data from the game server you're uploading:
- Fill the Version field with the version of the game server.
- Fill the Command field with the game server's executable command. This can be found inside the game server directory.
- Fill the Local Path field with the game server's local path. You can use either a relative or absolute path.
- Fill the Artifact Directory field with the directory path where artifact files will be stored.
- Fill the S3 Directory field with the directory of your S3 bucket.
- Fill the Deployment field with the deployment that will be used for this image server.
- Select the Add Persistent Flag option if you don't want this server to be deleted when the maximum number of servers is reached.
- Select the Enable Debugging option if you want to install a package for debugging into the dedicated server image.
- Select the Show Upload Progress option if you want the DS image upload progress to appear in your CLI.
After that, click the Next button.

A command that you can use to upload your game server will be automatically generated for you. Before you use this command, make sure you replace the client_id and client_secret with the Client ID and Client Secret of the IAM Client for your DS Uploader. Open the CLI in the folder that contains the DS Uploader and the game server, and run the command.

The command will contain multiple flags denoting the information you entered earlier. The flags and their meanings are listed below for reference:

Flag	Shortcut	Description
--artifact string	-a	The directory path where artifact files will be stored.
--bucket string	-b	The name of your S3 bucket.
--command string	-c	The server's executable command.
--s3dirname string	-d	The directory path of your S3 bucket.
--debug-enabled		Use this flag to install a debugging package into the server.
--default-image		Use this flag to make this server the default server image.
--deployment string		Deployment that will be used for this image server
--hostname string	-H	The hostname path of the platform.
--id string	-i	The IAM Client ID of your DS Uploader.
--namespace string	-n	The namespace of your game.
--path string	-p	The local path of the game server.
--persistent		Use this flag to make the server persistent. Persistent servers aren't deleted when the server limit is reached.
--secret string	-s	The IAM Client Secret of your DS Uploader.
--show-progress		Use this flag to make the server image upload appear in your CLI during the upload.
--version string	-v	The game server version.

You can also view this information in your CLI by using the “<ds-uploader>.exe --help” command.

Upload the Dedicated Server Build

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

Execute this command to upload the file from your local computer to the Docker registry.

Command

call windows-amd64.exe syncFolder --hostname=%HOSTNAME% --namespace=%NAMESPACE% --id=%CLIENT_ID% --version=%VERSION% --command=%DS_STARTUP_COMMANDFILE% --path=%SERVER_PATH% --bucket=%S3_BUCKETNAME% --s3dirname=%S3_DIRECTORY%

Example

call windows-amd64.exe syncFolder --hostname=https://demo.accelbyte.io --namespace=myawesomegame --id=87bc17a36a62482aa46c14412922aa2c --version=0.0.1 --command=myawesomegame_server.x86_64 --path=D:\Project\Games\GameServer --bucket=justice-ds-upload-service-demo --s3dirname=myawesomegame_0.0.1

NOTE

if you have a space on your argument, you need to add quotes to your argument.

If you want to use a command with a flag, follow this execution command.

call windows-amd64.exe syncFolder --hostname=https://demo.accelbyte.io --namespace=myawesomegame --id=87bc17a36a62482aa46c14412922aa2c --version=0.0.1 --command=myawesomegame_server.x86_64 --path=D:\Project\Games\GameServer --bucket=justice-ds-upload-service-demo --s3dirname=myawesomegame_0.0.1

If you want to use the command using the shortcut, follow this execution command.

call windows-amd64.exe syncFolder -H "https://demo.accelbyte.io" -n "myawesomegame" -i "87bc17a36a62482aa46c14412922aa2c" -v "0.0.1" -c "myawesomegame_server.x86_64" -p "D:\Project\Games\GameServer" -b "justice-ds-upload-service-demo" -s "myawesomegame_0.0.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.

Use the function below to enable DS login with client credentials.

Unreal Engine
Unity

FRegistry::ServerOauth2.LoginWithClientCredentials(FVoidHandler::CreateLambda([]()
{
    // Do something if LoginWithClientCredentials has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if LoginWithClientCredentials has an error
    UE_LOG(LogTemp, Log, TEXT("Error LoginWithClientCredentials, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

AccelByteServerPlugin.GetDedicatedServer().LoginWithClientCredentials(result =>
        {
            if (result.IsError)
            {
                // Do something if LoginWithClientCredentials has an error
                Debug.Log($"Error LoginWithClientCredentials, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if LoginWithClientCredentials has been successful
            }
        });

Integrate a Local Dedicated Server to the DSM

Make sure you set up all this function when on the dedicated server scene or level. And the function is only called by the server, not the client.

Unreal Engine
Unity

FString IpAddress = FString("https://127.0.0.1");
int32 Port = 7777;
FString ServerName = FString("my-awesome-game-server");
 
FRegistry::ServerDSM.RegisterLocalServerToDSM(IpAddress, Port, ServerName, FVoidHandler::CreateLambda([]()
{
    // Do something if RegisterLocalServerToDSM has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if RegisterLocalServerToDSM has an error
    UE_LOG(LogTemp, Log, TEXT("Error RegisterLocalServerToDSM, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string ip = "https://127.0.0.1";
        uint port = 7777;
        string name = "my-awesome-game-server";

        AccelByteServerPlugin.GetDedicatedServerManager().RegisterLocalServer(ip, port, name, result =>
        {
            if (result.IsError)
            {
                // Do something if RegisterLocalServer has an error
                Debug.Log($"Error RegisterLocalServer, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if RegisterLocalServer has been successful
            }
        });

Once completed, if any match request is received, the Dedicated Server will accept the connections from game clients and will be able to start the match.
After the match is finished, you will need to make sure the Dedicated Server is no longer registered in the Dedicated Server Management. Call this function to deregister the Dedicated Server.

Unreal Engine
Unity

FString ServerName = FString("my-awesome-game-server");
         
FRegistry::ServerDSM.DeregisterLocalServerFromDSM(ServerName, FVoidHandler::CreateLambda([]()
{
    // Do something if DeregisterLocalServerFromDSM has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if DeregisterLocalServerFromDSM has an error
    UE_LOG(LogTemp, Log, TEXT("Error DeregisterLocalServerFromDSM, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

AccelByteServerPlugin.GetDedicatedServerManager().DeregisterLocalServer(result =>
        {
            if (result.IsError)
            {
                // Do something if DeregisterLocalServer has an error
                Debug.Log($"Error DeregisterLocalServer, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if DeregisterLocalServer has been successful
            }
        });

Integrate a Managed Dedicated Server to the DSM

Make sure when you call this function, you are already on the server side functionality not client side.

Unreal Engine
Unity

int32 Port = 7777;
         
FRegistry::ServerDSM.RegisterServerToDSM(Port, FVoidHandler::CreateLambda([]()
{
// Do something if RegisterServerToDSM has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if RegisterServerToDSM has an error
UE_LOG(LogTemp, Log, TEXT("Error RegisterServerToDSM, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

int portNumber = 7777;

 AccelByteServerPlugin.GetDedicatedServerManager().RegisterServer(portNumber, result =>
    {
        if (result.IsError)
        {
            // Do something if RegisterServer has an error
            Debug.Log($"Error RegisterServer, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if RegisterSErver has been successful
        }
    });

Wait until the DS gets a session. The DS should wait for a player to try to connect to the DS.

This function can be used to let the DS retrieve the session ID. If the session ID is empty, this indicates that the DS doesn't have a session yet.

Unreal Engine
Unity

FRegistry::ServerDSM.GetSessionId(THandler<FAccelByteModelsServerSessionResponse>::CreateLambda([](const FAccelByteModelsServerSessionResponse& Result)
{
// Do something if GetSessionId has been successful
FString Sessionid = Result.Session_id;
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetSessionId has an error
UE_LOG(LogTemp, Log, TEXT("Error GetSessionId, Error Code: %d ErrorMessage: %s"), ErrorCode, *ErrorMessage);
}));

AccelByteServerPlugin.GetDedicatedServerManager().GetSessionId(result =>
    {
        if (result.IsError)
        {
            // Do something if GetSessionId has an error
            Debug.Log($"Error GetSessionId, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if GetSessionId has been successful
            string sessionId = result.Value.session_id;
        }
    });

Your managed dedicated server can be shut down automatically using this function.

Unreal Engine
Unity

bool KillMe = true;
FString MatchId = FString("SomeMatchId");
     
FRegistry::ServerDSM.SendShutdownToDSM(KillMe, MatchId, FVoidHandler::CreateLambda([]()
{
// Do something if SendShutdownToDSM has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if SendShutdownToDSM has an error
UE_LOG(LogTemp, Log, TEXT("Error SendShutdownToDSM has an error, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

bool killMe = true;

  AccelByteServerPlugin.GetDedicatedServerManager().ShutdownServer(killMe, result =>
    {
        if (result.IsError)
        {
            // Do something if ShutdownServer has an error
            Debug.Log($"Error ShutdownServer, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if ShutdownServer has been successful
        }
    });

Make Session Joinable

Using the session ID from [Integrate a Managed Dedicated Server to the DSM] section, you can use this function to retrieve a match's session data.

Unreal Engine
Unity

FString MatchId = FString("SomeMatchId");

FRegistry::ServerMatchmaking.QuerySessionStatus(MatchId, THandler<FAccelByteModelsMatchmakingResult>::CreateLambda([](const FAccelByteModelsMatchmakingResult& Result)
{
// Do something if QuerySessionStatus has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if QuerySessionStatus has an error
UE_LOG(LogTemp, Log, TEXT("Error QuerySessionStatus, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string matchId = "SomeMatchId";

    AccelByteServerPlugin.GetMatchmaking().QuerySessionStatus(matchId, result =>
    {
        if (result.IsError)
        {
            // Do something if QuerySessionStatus has an error
            Debug.Log($"Error QuerySessionStatus, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if QuerySessionStatus has been successful
        }
    });

Then use the sessionStatus from the previous step in this function to make the session joinable.

Unreal Engine
Unity

FRegistry::ServerMatchmaking.EnqueueJoinableSession(MatchmakingResult, FVoidHandler::CreateLambda([]()
{
// Do something if EnqueueJoinableSession has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if EnqueueJoinableSession has an error
UE_LOG(LogTemp, Log, TEXT("Error EnqueueJoinableSession, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

AccelByteServerPlugin.GetMatchmaking().EnqueueJoinableSession(sessionData, result =>
    {
        if (result.IsError)
        {
            // Do something if EnqueueJoinableSession has an error
            Debug.Log($"Error EnqueueJoinableSession, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if EnqueueJoinableSession has been successful
        }
    });

Connect a Game Client to the Dedicated Server

Make sure the player is logged in.

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.

Unreal Engine
Unity

FString GameMode = FString("1v1");
FString ServerName = FString("my-awesome-game-server");

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::MatchmakingNotif.CreateLambda([](const FAccelByteModelsMatchmakingNotice& Result)
{
if (Result.Status == EAccelByteMatchmakingStatus::Done)
{
    FString MatchId = Result.MatchId;
}
}));
FRegistry::Lobby.SendStartMatchmaking(GameMode, ServerName);

string gameMode = "1v1";

AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().StartMatchmaking(gameMode, result =>
    {
        if (result.IsError)
        {
            // Do something if StartMatchmaking has an error
            Debug.Log($"Error StartMatchmaking, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if StartMatchmaking has been successful
        }
    });

Wait for the Lobby service to send a notification that a match has been found. After you successfully found a match we suggest you save the match id to a variable that then you can use again if needed.

Unreal Engine
Unity

Registry::Lobby.Connect();
FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::MatchmakingNotif.CreateLambda([](const FAccelByteModelsMatchmakingNotice& Result)
{
if (Result.Status == EAccelByteMatchmakingStatus::Done)
{
    FString MatchId = Result.MatchId;
}
}));

AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().MatchmakingCompleted += result =>
    {
        if (result.IsError)
        {
            // Do something if MatchmakingCompleted has an error
            Debug.Log($"Error MatchmakingCompleted, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if MatchmakingCompleted has been successful
            if (result.Value.status == "Done")
            {
                string matchId = result.Value.matchId;
            }
        }
    };

The Lobby service will notify the game client that the player is ready to join the match using this function.

Unreal Engine
Unity

FString MatchId = FString(“SomeMatchId”);

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetReadyConsentResponseDelegate(AccelByte::Api::Lobby::ReadyConsentResponse.CreateLambda([](const FAccelByteModelsReadyConsentRequest& Result)
{
if (Result.Code == "0")
{
    // Do something if ReadyConsentResponseDelegate has been successful
}
else
{
    // Do something if ReadyConsentResponseDelegate has an error
}
}));
FRegistry::Lobby.SendReadyConsentRequest(MatchId);

string matchId = "SomeMatchId";

    AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().ConfirmReadyForMatch(matchId, result =>
    {
        if (result.IsError)
        {
            // Do something if ConfirmReadyForMatch has an error
            Debug.Log($"Error ConfirmReadyForMatch, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if ConfirmReadyForMatch has been successful
        }
    });

Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

Unreal Engine
Unity

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetDsNotifDelegate(AccelByte::Api::Lobby::DsNotif.CreateLambda([](const FAccelByteModelsDsNotice& Result)
{
// Do something if SetDsNotifDelegate has been successful
FString IpAddress = Result.Ip;
int32 Port = Result.Port;
}));

AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().DSUpdated += result =>
    {
        if (result.IsError)
        {
            // Do something if DSUpdated has an error
            Debug.Log($"Error DSUpdated, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if DSUpdated has been successful
        }
    };

Connect a Game Client to Dedicated Servers in Multiple Regions

Make sure the player is logged in.

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

Unreal Engine
Unity

FRegistry::Qos.GetServerLatencies(THandler<TArray<TPair<FString, float>>>::CreateLambda([](const TArray<TPair<FString, float>>& Result)
{
// Do something if GetServerLatencies has been successful
TArray<TPair<FString, float>> AllLatencies = Result;
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetServerLatencies has an error
UE_LOG(LogTemp, Log, TEXT("Error GetServerLatencies, Error Code: %d Error Messsage: %s"), ErrorCode, *ErrorMessage);
}));

AccelBytePlugin.GetQos().GetServerLatencies(result =>
    {
        if (result.IsError)
        {
            // Do something if GetServerLatencies has an error
            Debug.Log($"Error GetServerLatencies, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if GetServerLatencies has been successful
            Dictionary<string, int> allLatencies = result.Value;
        }
    });

Use the array of latencies when you call the StartMatchmaking function.

Unreal Engine
Unity

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::MatchmakingNotif.CreateLambda([](const FAccelByteModelsMatchmakingNotice& Result)
{
// Do something if SetMatchmakingNotifDelegate has been successful
}));
FRegistry::Lobby.SendStartMatchmaking(GameMode, "", "", Latencies);

AccelBytePlugin.GetLobby().Connect();
            AccelBytePlugin.GetLobby().StartMatchmaking(gameMode, "", latencies, result =>
            {
                if (result.IsError)
                {
                    // Do something if StartMatchmaking has an error
                    Debug.Log($"Error StartMatchmaking, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
                }
                else
                {
                    // Do something if StartMatchmaking has been successful
                }
            });

Wait for the Lobby service to send a notification that a match has been found.

Unreal Engine
Unity

Registry::Lobby.Connect();
FRegistry::Lobby.SetMatchmakingNotifDelegate(AccelByte::Api::Lobby::MatchmakingNotif.CreateLambda([](const FAccelByteModelsMatchmakingNotice& Result)
{
if (Result.Status == EAccelByteMatchmakingStatus::Done)
{
    FString MatchId = Result.MatchId;
}
}));

AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().MatchmakingCompleted += result =>
    {
        if (result.IsError)
        {
            // Do something if MatchmakingCompleted has an error
            Debug.Log($"Error MatchmakingCompleted, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if MatchmakingCompleted has been successful
            if (result.Value.status == "Done")
            {
                string matchId = result.Value.matchId;
            }
        }
    };

Notify the game client that the player is ready to join the match using this function.

Unreal Engine
Unity

FString MatchId = FString(“SomeMatchId”);

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetReadyConsentResponseDelegate(AccelByte::Api::Lobby::ReadyConsentResponse.CreateLambda([](const FAccelByteModelsReadyConsentRequest& Result)
{
if (Result.Code == "0")
{
    // Do something if ReadyConsentResponseDelegate has been successful
}
else
{
    // Do something if ReadyConsentResponseDelegate has an error
}
}));
FRegistry::Lobby.SendReadyConsentRequest(MatchId);

string matchId = "SomeMatchId";

    AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().ConfirmReadyForMatch(matchId, result =>
    {
        if (result.IsError)
        {
            // Do something if ConfirmReadyForMatch has an error
            Debug.Log($"Error ConfirmReadyForMatch, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if ConfirmReadyForMatch has been successful
        }
    });

Wait for the DS to get the match details from the Lobby service. Then, connect to the DS using those details.

Unreal Engine
Unity

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetDsNotifDelegate(AccelByte::Api::Lobby::DsNotif.CreateLambda([](const FAccelByteModelsDsNotice& Result)
{
// Do something if SetDsNotifDelegate has been successful
FString IpAddress = Result.Ip;
int32 Port = Result.Port;
}));

AccelBytePlugin.GetLobby().Connect();
    AccelBytePlugin.GetLobby().DSUpdated += result =>
    {
        if (result.IsError)
        {
            // Do something if DSUpdated has an error
            Debug.Log($"Error DSUpdated, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if DSUpdated has been successful
        }
    };

Request Matchmaking with Party Attributes

You can call the below function to send more information related to your party attributes. The client will send the party information and the server will retrieve all information when all party or player success opens the server. to send more information about the party to the server and client will send all that information.

Client Perspective

You will see here how the client will call start matchmaking by sending the party attributes, so then the server will get all that information about the party attributes later for your custom logic on the server if needed.

Make sure the player is logged into the game.

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

Unreal Engine
Unity

TMap<FString, FString> PartyAttributes;
PartyAttributes.Add(FString("GameMap"), FString("EndlessBattle"));
PartyAttributes.Add(FString("GameplayMode"), FString("DeathMatch"));

FRegistry::Lobby.Connect();
FRegistry::Lobby.SetStartMatchmakingResponseDelegate(AccelByte::Api::Lobby::MatchmakingStartResponse.CreateLambda([](const FAccelByteModelsMatchmakingResponse& Result)
{
if (Result.Code == "0")
{
    // Do something if StartMatchmakingResponseDelegate has been successful
}
else
{
    // Do something if StartMatchmakingResponseDelegate has an error
}
}));
FRegistry::Lobby.SendStartMatchmaking(GameMode, PartyAttributes);

string gameMode = "2v2";
    Dictionary<string, object> partyAttributes = new Dictionary<string, object>
    {
        { "GameMap", "EndlessBattle" },
        { "GameplayMode", "DeathMatch" }
    };

    AccelBytePlugin.GetLobby().StartMatchmaking(gameMode, "", "", partyAttributes, result =>
    {
        if (result.IsError)
        {
            // Do something if StartMatchmaking has an error
            Debug.Log($"Error StartMatchmaking, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if StartMatchmaking has been successful
        }
    });

Once completed, you can follow the same steps as you would making other [matchmaking requests].

Server Perspective

You will get more information about the status of the party matchmaking by using the below function. You will need all this information to set up your custom statistic when the game is starting.

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

You need to call this query function to get the status and all information about the matchmaking

Unreal Engine
Unity

FString MatchId = FString("SomeMatchId");

FRegistry::ServerMatchmaking.QuerySessionStatus(MatchId, THandler<FAccelByteModelsMatchmakingResult>::CreateLambda([](const FAccelByteModelsMatchmakingResult& Result)
{
// Do something if QuerySessionStatus has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if QuerySessionStatus has an error
UE_LOG(LogTemp, Log, TEXT("Error QuerySessionStatus, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

string matchId = "SomeMatchId";

    AccelByteServerPlugin.GetMatchmaking().QuerySessionStatus(matchId, result =>
    {
        if (result.IsError)
        {
            // Do something if QuerySessionStatus has an error
            Debug.Log($"Error QuerySessionStatus, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
        }
        else
        {
            // Do something if QuerySessionStatus has been successful
        }
    });

Shutdown Server Delegate

The Dedicated Server will automatically shut down after a period of time when it has been claimed but contains no active players. 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.

Unreal Engine

FRegistry::ServerDSM.SetOnAutoShutdownResponse(FVoidHandler::CreateLambda([]()
{
    // Do something if OnAutoShutdownResponse has been successful
}));
FRegistry::ServerDSM.SetOnAutoShutdownErrorDelegate(FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if OnAutoShutdownErrorDelegate has an error
    UE_LOG(LogTemp, Log, TEXT("Error OnAutoShutdownErrorDelegate, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Connect Custom Services to the DS Log Manager using the Server SDKs

SDK Initialization

Before using the DS Log Manager service from the SDK you need to initialize your server-side SDK to make you authorized and able to perform any action from create, read, update, and delete.

Golang SDK Initialization

To start using the DS Log Manager service from the Golang SDK, you need to initialize the SDK by making sure that you've done the following requirements.

Create your OAuth Client and assign the necessary permission to access the Achievement service.
Logging in as a Client using the SDK.
Initialize the service using the following function.

Golang

terminatedServersService := &dslogmanager.TerminatedServersService{
    Client:          factory.NewDsLogManagerClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}

On a successful initialization, you can use the Golang SDK to create, read, update and delete DS Log Manager from your serverless app.

Python SDK Initialization

To start using the DS Log Manager service from the Python SDK, you need to initialize the SDK by making sure that you've done the following requirements.

Create your OAuth Client and assign the necessary permission to access the Achievement service.
Logging in as a Client using the SDK.

On a successful initialization, you can use the Python SDK to create, read, update and delete DS Log Manager from your serverless app.

.NET (C#) SDK Initialization

Before using the DS Log Manager service, you will need to set some permissions. Use the following .NET namespaces:

    using AccelByte.Sdk.Api.Dslogmanager.Model;
    using AccelByte.Sdk.Api.Dslogmanager.Operation;
    using AccelByte.Sdk.Api.Dslogmanager.Wrapper;

Java SDK Initialization

Before using the DS Log Manager service, you will need to set some permissions. Initialize the TerminatedServers wrapper from the DS Log Manager service using the following code:

TerminatedServers wTerminatedServers = new TerminatedServers(sdk);

Once completed, you can use the SDK to create, read, update, or delete logs.

Check Dedicated Server Logs

To check dedicated server logs, use the following function.

Golang
Python
C#

ok, err := terminatedServersService.CheckServerLogs(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.dslogmanager import check_server_logs

result, error = check_server_logs(
   pod_name="<your-pod-name>"
)
if error:
   print(error)

TerminatedServers wTerminatedServers = new TerminatedServers(_Sdk);

ModelsLogFileStatus? logs = wTerminatedServers.CheckServerLogs(
    CheckServerLogs.Builder
    .Build(_Sdk.Namespace, "<your_pod_name>"));

Retrieve All Terminated Servers

To retrieve all terminated server, use the following function:

Golang
Python
C#
Java

ok, err := terminatedServersService.ListTerminatedServers(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.dslogmanager import list_terminated_servers

result, error = list_terminated_servers(
   deployment="<your-deployment>",
   pod_name="<your-pod-name>"
)
if error:
   print(error)

TerminatedServers wTerminatedServers = new TerminatedServers(_Sdk);

ModelsListTerminatedServersResponse? tsResp = wTerminatedServers.ListTerminatedServers(ListTerminatedServers.Builder
    .SetLimit(10)
    .Build(_Sdk.Namespace));
Assert.IsNotNull(tsResp);

ModelsListTerminatedServersResponse tsResp = wTerminatedServers
                                .listTerminatedServers(ListTerminatedServers.builder()
                                                .namespace(namespace)
                                                .limit(10)
                                                .build());

Download Server Logs

To download dedicated server logs, use the following function.

Golang
Python
C#

err := terminatedServersService.DownloadServerLogs(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.dslogmanager import download_server_logs

result, error = download_server_logs(
   pod_name="<your-pod-name>"
)
if error:
   print(error)

TerminatedServers wTerminatedServers = new TerminatedServers(_Sdk);

wTerminatedServers.DownloadServerLogs(
    DownloadServerLogs.Builder
    .Build(_Sdk.Namespace, "<your_pod_name>"));

Connect Custom Services to the DSM Controller using the Server SDKs

SDK Initialization

Before using the DSM Controller service from the SDK, you will need to initialize your server-side SDK to ensure that you are authorized and able to perform create, read, update, and delete actions.

Golang SDK Initialization

Before using the DSM Controller service from the Golang SDK, you will need to initialize the SDK by following the steps below:

Create your OAuth Client and assign the necessary permissions to access the Achievement service.
Log in as a Client using the SDK.
Initialize the DSM Controller service using the following function:

Golang

sessionService := &dsmcontroller.SessionService{
    Client:          factory.NewDsmControllerClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}

Once completed, you can use the Golang SDK to create, read, update, or delete the DSM Controller from your serverless app.

Python SDK Initialization

Before using the DSM Controller service from the Python SDK, you will need to initialize the SDK by following the steps below:

Create your OAuth Client and assign the necessary permissions to access the Achievement service.
Log in as a Client using the SDK.

Once completed, you can use the Python SDK to create, read, update, or delete the DSM Controller from your serverless app.

.NET (C#) SDK Initialization

Before using the DSMC service, you will need to set some permissions. Use the following .NET namespaces:

   using AccelByte.Sdk.Api.Dsmc.Model;
   using AccelByte.Sdk.Api.Dsmc.Operation;
   using AccelByte.Sdk.Api.Dsmc.Wrapper;

Java SDK Initialization

Before using the DSMC service, you will need to set some permissions. Initialize the Session wrapper from the DSMC service using the following code:

net.accelbyte.sdk.api.dsmc.wrappers.Session wSession = new net.accelbyte.sdk.api.dsmc.wrappers.Session(sdk);

Once completed, you can use the SDK to create, read, update, or delete DSMCs.

Create a Session

Use the following function to create a game session:

Golang
Python
C#
Java

ok, err := sessionService.CreateSession(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.dsmc import create_session
from accelbyte_py_sdk.api.dsmc.models import ModelsCreateSessionRequest
from accelbyte_py_sdk.api.dsmc.models import ModelsRequestMatchMember
from accelbyte_py_sdk.api.dsmc.models import ModelsRequestMatchParty
from accelbyte_py_sdk.api.dsmc.models import ModelsRequestMatchingAlly

result, error = create_session(
   body=ModelsCreateSessionRequest.create(
       client_version="<client-version>",
       configuration="<configuration>",
       deployment="<deployment>",
       game_mode="<game-mode>",
       matching_allies=[
           ModelsRequestMatchingAlly.create(
               matching_parties=[
                   ModelsRequestMatchParty.create(
                       party_attributes={},
                       party_id="<party-id>",
                       party_members=[
                           ModelsRequestMatchMember.create(
                               user_id="<user-id>"
                           )
                       ]
                   )
               ]
           )
       ],
       namespace="<namespace>",
       pod_name="<pod-name>",
       region="<your-region>",
       session_id="<session-id>"
   )
)
if error:
   print(error)

Session wSession = new Session(sdk);

ModelsCreateSessionRequest sessionRequest = new ModelsCreateSessionRequest()
{
    ClientVersion = "0.3.0",
    Configuration = "",
    Deployment = "<deployment_name>",
    GameMode = "<game_mode>",
    MatchingAllies = new List<ModelsRequestMatchingAlly>()
    {
        new ModelsRequestMatchingAlly()
        {
            MatchingParties = new List<ModelsRequestMatchParty>()
            {
                new ModelsRequestMatchParty()
                {
                    PartyAttributes = new Dictionary<string, object>(),
                    PartyId = "<party_id>",
                    PartyMembers = new List<ModelsRequestMatchMember>()
                    {
                        new ModelsRequestMatchMember()
                        {
                            UserId = "<user_id>"
                        }
                    }
                }
            }
        }
    },
    Region = "",
    PodName = "",
    SessionId = "<session_id>",
    Namespace = sdk.Namespace,
};

ModelsSessionResponse? csResp = wSession.CreateSession(CreateSession.Builder
    .Build(sessionRequest, sdk.Namespace));

net.accelbyte.sdk.api.dsmc.models.ModelsSessionResponse csResp = wSession
                                .createSession(net.accelbyte.sdk.api.dsmc.operations.session.CreateSession.builder()
                                                .namespace(target_namespace)
                                                .body(sessionRequest)
                                                .build());

Claim a Dedicated Server

Use the following function to claim a dedicated server:

Golang
Python
C#
Java

err := sessionService.ClaimSession(input)
if err != nil {
  return err
}
return nil

from accelbyte_py_sdk.api.dsmc import claim_server
from accelbyte_py_sdk.api.dsmc.models import ModelsClaimSessionRequest

result, error = claim_server(
   body=ModelsClaimSessionRequest.create(
       session_id="<session-id>"
   )
)
if error:
   print(error)

Session wSession = new Session(sdk);

ModelsClaimSessionRequest claimServer = new ModelsClaimSessionRequest()
{
    SessionId = "<session_id>"
};
wSession.ClaimServer(ClaimServer.Builder.Build(claimServer, sdk.Namespace));

ModelsClaimSessionRequest claimServer = ModelsClaimSessionRequest.builder()
                .sessionId(session_id)
                .build();

wSession.claimServer(ClaimServer.builder()
                .namespace(target_namespace)
                .body(claimServer)
                .build());

Retrieve a Session

Use the following function to retrieve a session:

Golang
Python
C#
Java

ok, err := sessionService.GetSession(input)
if err != nil {
  return err
}

return nil

from accelbyte_py_sdk.api.dsmc import get_session


result, error = get_session(
   session_id="<session-id>"
)
if error:
   print(error)

Session wSession = new Session(sdk);

csResp = wSession.GetSession(GetSession.Builder
    .Build(sdk.Namespace, "<session_id>"));
Assert.IsNotNull(csResp);

net.accelbyte.sdk.api.dsmc.models.ModelsSessionResponse csResp = wSession
                                .createSession(net.accelbyte.sdk.api.dsmc.operations.session.CreateSession.builder()
                                                .namespace(target_namespace)
                                                .body(sessionRequest)
                                                .build());

Overview​

Local Dedicated Servers​

Matchmaking Flow​

Prerequisites​

Managed Dedicated Servers​

Matchmaking Flow​

Prerequisites​

Prerequisites

Tutorials​

Upload a New Server with DS Uploader​

NOTE

Upload the Dedicated Server Build​

NOTE

Enable DS Login with Client Credentials​

Integrate a Local Dedicated Server to the DSM​

Integrate a Managed Dedicated Server to the DSM​

Make Session Joinable​

Connect a Game Client to the Dedicated Server​

Connect a Game Client to Dedicated Servers in Multiple Regions​

Request Matchmaking with Party Attributes​

Client Perspective​

Server Perspective​

Shutdown Server Delegate​

Connect Custom Services to the DS Log Manager using the Server SDKs​

SDK Initialization​

Golang SDK Initialization​

Python SDK Initialization​

.NET (C#) SDK Initialization​

Java SDK Initialization​

Check Dedicated Server Logs​

Retrieve All Terminated Servers​

Download Server Logs​

Connect Custom Services to the DSM Controller using the Server SDKs​

SDK Initialization​

Golang SDK Initialization​

Python SDK Initialization​

.NET (C#) SDK Initialization​

Java SDK Initialization​

Create a Session​

Claim a Dedicated Server​

Retrieve a Session​

Related Concepts​

Overview

Local Dedicated Servers

Matchmaking Flow

Prerequisites

Managed Dedicated Servers

Matchmaking Flow

Prerequisites

Tutorials

Upload a New Server with DS Uploader

Upload the Dedicated Server Build

Enable DS Login with Client Credentials

Integrate a Local Dedicated Server to the DSM

Integrate a Managed Dedicated Server to the DSM

Make Session Joinable

Connect a Game Client to the Dedicated Server

Connect a Game Client to Dedicated Servers in Multiple Regions

Request Matchmaking with Party Attributes

Client Perspective

Server Perspective

Shutdown Server Delegate

Connect Custom Services to the DS Log Manager using the Server SDKs

SDK Initialization

Golang SDK Initialization

Python SDK Initialization

.NET (C#) SDK Initialization

Java SDK Initialization

Check Dedicated Server Logs

Retrieve All Terminated Servers

Download Server Logs

Connect Custom Services to the DSM Controller using the Server SDKs

SDK Initialization

Golang SDK Initialization

Python SDK Initialization

.NET (C#) SDK Initialization

Java SDK Initialization

Create a Session

Claim a Dedicated Server

Retrieve a Session

Related Concepts