Migrate from Armada to AMS

Last updated on January 13, 2024

AccelByte Multiplayer Servers (AMS) is the next generation dedicated server management system from AccelByte. It is built on the experience learned from Armada, and designed to minimize the migration effort from Armada.

To learn more about AMS, see Introduction to AccelByte Multiplayer Servers (AMS).

Change the dedicated server code

note

The following configuration is required for the AccelByte OnlineSubsystem.

[OnlineSubsystemAccelByte]
bServerUseAMS=True
bRegisterServerOnAutoLogin=true

Make changes to the command line arguments

Unlike Armada, AMS does not run a docker container for each of the dedicated servers. As a result, it cannot utilize the docker network to facilitate port forwarding from an external port to the port that your dedicated server listens to in the local network. As such, the AMS orchestration layer will assign a port directly into your dedicated server as one of the command line arguments.

For the dedicated servers, they are required to listen to the value that is being passed from the command line argument -p ${port}.

To learn how to construct this command, see the Construct your dedicated server command.

Register a dedicated server to AMS

In AMS, the registration flow requires a RegisterServer() call to tell AMS that a new server is created, followed by the SendServerReady() call to tell AMS that the game server is ready to serve a game session, once it has sufficiently instantiate itself.

Unreal

AMS

FRegistry::ServerAMS.SendReadyMessage();

Armada

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

AccelByte OSS

AMS

const FOnRegisterServerComplete OnServerReady = FOnRegisterServerComplete::CreateUObject(this, &YourClass::OnServerReady);
SessionInterface->SendServerReady(SessionName, OnServerReady);

Armada

//Automatic

Unity

AMS

AccelByteServerPlugin.GetAMS().SendReadyMessage();

Armada

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

You will notice that the Ready API no longer requires you to handle the response. This is because, in AMS, the Ready signal is sent to a local watchdog agent instead of a remote service, the local watchdog agent is then responsible to handle the retries with the remote service on dedicated server's behalf.

(Optional) Listen to the drain signal

The drain signal is a new feature introduced in AMS. It tells a dedicated server that it will soon be terminated, the dedicated server will then be set to the Draining state and is subjected to the drain timeout. Upon reaching the drain timeout, the watchdog will automatically terminate the dedicated server, this gives a configurable period of time for your dedicated server to do any last minute action and then terminate itself peacefully.

Your dedicated servers are sent a drain signal for any of the following reasons:

• The fleet is deactivated, sending all dedicated servers in the Ready state into the drain state. (In Session dedicated servers will be allowed to run their course.)
• The nodes that host the dedicated servers need to be taken down for maintenance.
• The dedicated servers are sent the drain signal explicitly by an operator from your organization.

To register a handler to listen to the drain signal, implement this code.

Unreal

AccelByte::GameServerApi::ServerAMS::FOnAMSDrainReceived OnAMSDrainReceivedDelegate = AccelByte::GameServerApi::ServerAMS::FOnAMSDrainReceived::CreateThreadSafeSP(SharedThis(this), &ClassName::OnAMSDrain);
FRegistry::ServerAMS.SetOnAMSDrainReceivedDelegate(OnAMSDrainReceivedDelegate);

Unreal OSS

FOnAMSDrainReceivedDelegate OnAMSDrainReceivedDelegate = FOnAMSDrainReceivedDelegate::CreateUObject(this, &ClassName::OnAMSDrain);
OnAMSDrainReceivedHandle = SessionInterface->AddOnAMSDrainReceivedDelegate_Handle(OnAMSDrainReceivedDelegate);

Unity

AccelByteServerPlugin.GetAMS().OnDrainReceived += () =>
{
    //Drain callback
};

What happened to SendShutdownToDSM()?

Dedicated servers on AMS are managed and monitored by a local watchdog agent. The local watchdog agent is able to automatically detect when your dedicated server has exited itself and make the corresponding update to the remote service. As such, there is no equivalent to the SendShutdownToDSM() API on AMS. It can be safely removed from your dedicated server.

Test locally with the AMS SIM

The AMS Simulator (SIM) simulates how the watchdog interacts with the dedicated server. You can use this tool to verify how your dedicated server will react to state changes and unexpected events that originate from AMS, so that you can ensure that your dedicated server will work on the AMS environment without uploading a dedicated server build to test.

To learn more about AMS SIM, see Debug dedicated servers locally using the AMS SIM.

Set up the AMS environment using the Admin Portal

The AMS multi-tenant architecture is designed to enable resource sharing between AGS namespaces. By creating an AMS account and linking it to the namespaces that reside AGS namespaces under different hosting environments, it enables the namespaces to share resources such as dedicated server images, performance metrics, and billing information.

To learn about creating and linking AMS account, see Create an AMS account and Link AMS accounts.

Upload dedicated server images onto AMS

To learn about uploading dedicated server images onto AMS, see Download CLI tools from the Admin Portal.

Create fleets to manage dedicated server allocation

On AMS, aside from supported regions of a namespace, there are no generic namespace-wide configurations. The concept of timeouts, pod configuration and deployment are all combined and restructured under a fleet. A fleet encapsulates how you want to run a single dedicated server image, down to which virtual machine you want to run your dedicated servers on and how many dedicated servers you want to run on each of the supported per regions.

To learn about fleet creation and configuration, see Creating a fleet to manage dedicated server allocation.

Configure the session template to use AMS dedicated servers

The claim key is a new concept introduced in AMS that enables the session template to claim dedicated servers from one or more fleets. So that you can achieve special deployment flow such as blue or green deployment, canary fleet deployment, etc.

To learn about how to set up and utilize claim keys, see Dedicated server claim flow.

Assign claim keys onto a fleet

To lean about how to assign claim keys onto a fleet, Dedicated server claim flow.

Configure the session template

To learn about how to configure your session template to use the claim keys, see Use AMS with the session service.