Integrate dedicated servers with the AccelByte Server SDK

Last updated on October 24, 2024

info

Armada is deprecated, replaced by AccelByte Multiplayer Servers (AMS), our next-generation dedicated server orchestration product. AGS Private Cloud customers can ask your AccelByte account team about enabling AMS for your environments.

AGS Shared Cloud

Armada is not available on AGS Shared Cloud tier, use AMS instead.

Overview

This guide walks you through integrating Armada with the AccelByte Gaming Services (AGS) Game SDK and provides an understanding of the lifecycle of a dedicated server.

Prerequisites

• You have an IAM client set up for dedicated servers with the following permission:

  Permission name	Action
  NAMESPACE:{namespace}:DSM:SERVER	Update

  :::tip Maintain one IAM client for all your dedicated servers to use. :::

• Have a dedicated server executable built using the Linux architecture.

• The AccelByte Game SDK has been installed in your project. The AccelByte Game SDK is available on both Unreal and Unity.

Lifecycle of a dedicated server

Armada uses states to keep track of the lifecycle of a dedicated server. The states are:

• Creating: the server is spinning up and loading necessary resources to serve a game session.
• Ready: the server is ready to serve a game session.
• Busy: the server is serving a game session.
• Unresponsive: the server has failed one or more health checks.
• Removing: the server is being removed from service by Armada.

The change of states are best described by the following diagram:

note

Registering a dedicated server is required. This is because the dedicated server sometimes requires loading its own assets (such as meshes for a game level) in order to serve a game session. The time required to load such assets varies from studio to studio. The register server API is used so that the dedicated server has time to do this, and can then notify Armada that it is ready to serve game sessions. Armada will then change the dedicated server state from "Creating" to "Ready".

Register a dedicated server to Armada

When your server is created by Armada, it will be in the "Creating" state. During this time, the server will start to initialize and load all the necessary assets that it requires to serve a game session. The server is also subjected to the creation timeout, which will automatically remove the server when the timeout is exceeded.

Once your server has finished loading and is ready to serve a game session, your server will notify Armada by calling the respective API:

Unreal

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 RegisterLocalServerToDSM has an error
 UE_LOG(LogTemp, Log, TEXT("Error RegisterLocalServerToDSM, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

var dsm = AccelByteSDK.GetServerRegistry().GetApi().GetDedicatedServerManager();

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

dsm.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}");
        return;
    }
   
    // Do something if RegisterLocalServer has been successful
});

Verify your local dedicated server

Once you have called the registration endpoint, log in to your Admin Portal, and then go to Dedicated Server Management > Servers.

You will see local servers running. To examine your local servers and their statuses, click Local Servers.

Deregister a local dedicated server

Your local dedicated server will stay registered for 24 hours before it is automatically removed. You can also click the Delete button next to your local server in the Admin Portal to manually delete it. If you want to do so programmatically, use the following APIs from the respective SDKs:

Unreal

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

Unity

var dsm = AccelByteSDK.GetServerRegistry().GetApi().GetDedicatedServerManager();

int portNumber = 7777;
dsm.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}");
        return;
    }

    // Do something if RegisterServer has been successful
});

After a successful registration, your dedicated server will now be in the "Ready" state. It is no longer subject to the creation timeout, and will wait until a game session comes to claim it.

Troubleshoot issues

In this section, you can find common errors and issues that can occur when using Armada and recommendations on how to resolve them.

Why has my dedicated server become inactive after a few minutes?

Aside from any crashes that may occur in your dedicated servers, this may be caused by having your dedicated servers exceed a certain timeout. To find out why your dedicated server has become inactive:

In the Admin Portal, go to Dedicated Server Management > Historical Logs. Find your dedicated server session in the logs and click View next to it in the Action column. The server allocation and state change log can be found on the right side of the screen.

Why did the API call to register my server fail?

It is possible that your SDK is misconfigured. Check the configuration file in your SDK to ensure the following:

1. The Client ID and Client Secret values in the configuration match your IAM client for dedicated servers.
2. The Base URL value in the configuration is correct.
3. The Namespace value in the configuration matches the namespace that your dedicated server was uploaded to.