Armada

Overview

Armada is a dynamic game server manager that can balance low hosting cost with high performance. With Armada you can have different fleets of servers for different regions, and each fleet can be made up of a mix of cloud, bare metal, and local servers. These fleets can be used to maximize your global reach while only paying for the hosting you need.

Armada offers several advantages for game developers, including:

  • Link multiple server providers to give your game both the high availability of cloud hosting and the reduced cost of bare metal machines. This also allows you to shop around for the best price, without being tied to only one hosting provider.

  • Cost-aware scaling ensures that hosting costs are taken into account when scaling up or down. When scaling up, Armada ensures the bare metal machines are filled before bursting into the cloud. And when scaling down, Armada looks for opportunities to reduce the load on the cloud machines without impacting performance or player experience.

  • Multi-region hosting for greater global coverage and better game performance across more regions. With Armada you aren’t tied to one hosting solution, which means you can make sure that your hosting providers cover each other’s blind spots.

  • Integrated Matchmaking and Lobby services provide geolocation support, so that you can match players in the same region for optimal player experience. But if you have a matchmaking and lobby service you already love, we can help you integrate Armada with that instead of using ours.

Armada consists of a Dedicated Server Manager (DSM) and Dedicated Server Manager Controller (DSMC). Our DSM uses Agones to manage dedicated servers, which are tracked by our DSMC.

How It Works

The Basics of Server Management

Armada works by connecting servers from different providers, as seen in the diagram below:

armada

How Our Matchmaking Service Uses Armada

Below is a diagram of how Armada can work with our Matchmaking service.

armada

  1. The player connects to the Lobby service through a websocket connection.
  2. The player sends a matchmaking request to the Lobby service.
  3. The Lobby service will act as a proxy and forward the incoming message to the Matchmaking service.
  4. When a match is found, the Matchmaking service will notify the Lobby service.
  5. The Lobby service will send a request to the DSM to create a new game session with the match details.
  6. The DSM will check whether a DS pod is available.
  7. If there’s an idle pod available, the DSM will send a claim request to the DS Fleet (Agones).
  8. If there are no idle pods available, the DS Fleet (Agones) will spawn a new DS pod.
  9. The Agones controller claims the pod and assigns the game session to it.
  10. After the process is complete, the DSM notifies the Lobby service that the session has been created, and sends the DS details.
  11. The Lobby service forwards the DS details to the game client.

Tutorials

Upload a New Server with DS Uploader

You can upload a new server using our DS Uploader, which you can download from our Nexus repository. Follow the directions below to download the DS Uploader and upload a new server image.

Download DS Uploader

  1. DS Uploader can be downloaded from our Nexus repository. To make it easy to find, run a search using ds-uploader-prod/ as the keyword.

  2. Browse the list of search results that appears until you find the latest version of the uploader. There are three files you need to download to run DS Uploader, as seen in the image below:

    armada

Upload Your Server Image

  1. After you’ve downloaded the DS Uploader files, run the executable.

  2. Before you can upload the server image, you must set the environment variables. To do so, run the following commands:

    • SET UPLOADER_BIN to define the location of DS Uploader.
    • SET UPLOADER_CLIENTID to define the client ID of DS Uploader. To find the client ID in the Admin Portal, open Platform Configurations and search for the DS Uploader client ID in the OAuth Clients list.
    • SET DS_PATH to define the location of the server image.
    • SET DS_ENTRYPOINT to define the file runner that will run the game server.
    • SET DS_VERSION to define the version number of the server image.
    • SET NAMESPACE to define your game’s namespace. Make sure you use the game namespace, not the publisher namespace.
  3. When you’re finished setting the environment variables, you’re ready to upload your server image. To upload your server image, run the following command:

    %UPLOADER_BIN% -H https://demo.accelbyte.io -i %UPLOADER_CLIENTID% -f %DS_PATH% -v %DS_VERSION% -c %DS_ENTRYPOINT% -n %NAMESPACE% -X 2

    See the example below for what setting the variables and running the upload command will look like:

    SET UPLOADER_BIN="C:\Program Files\Justice DS Uploader\windows-amd64-1.0.3.exe"
    SET UPLOADER_CLIENTID=8688fce6c3a7448d8614e15bf7771149
    SET DS_PATH="F:\justice-ue4-shootergame\ShooterGame\Binaries\DSbuild\prep\linuxserver.zip"
    SET DS_ENTRYPOINT=./ShooterGameServer.sh
    SET DS_VERSION=1.6.0.22
    SET NAMESPACE=abshooter
    %UPLOADER_BIN% -H https://demo.accelbyte.io -i %UPLOADER_CLIENTID% -f %DS_PATH% -v %DS_VERSION% -c %DS_ENTRYPOINT% -n %NAMESPACE% -X 2
  4. When the upload is complete, you can validate your new image server to ensure there were no issues with the upload. To do so, open your game’s namespace in the Admin Portal. From there go to Dedicated Server Management, Configurations, then Image Versions. The newly uploaded server image will appear in the list.

Add a Dedicated Server Configuration

After you upload a new server image, you can configure that server and its deployment in the Admin Portal.

Configure the Dedicated Server

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

    armada

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

    armada

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

    armada

  4. After the Add Configuration form appears, click the Add button next to Image Versions. Then fill in the form with the required information:

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

    armada

    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 listens for a connection.
    • Input the minimum number of DS allowed to spawn, 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 in the Buffer Count field. The DSM will spawn idle DS according to the buffer count. This ensures that there will always be a DS ready for players to use 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 field with the maximum number of cores that can be used by the dedicated server.
    • Input the Memory Limit field with the maximum amount of memory that can be used by the dedicated server.

    The following fields 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.

      armada

  5. Click Add to complete the configuration.

Configure the Server 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.

  2. After the configuration form appears, fill in the fields using the appropriate format.

    • Input the Name of the deployment configuration. You should use 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 allowed to spawn, 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 in the Buffer Count field. The DSM will spawn idle DS according to the buffer count. This ensures that there will always be a DS ready for players to use during matchmaking. Note: The Max. Count value should not be less than Min. Count value.

    armada

  3. Click Add to complete the configuration.

    armada

Verify the Dedicated Server Configuration

After you create a Dedicated Server Configuration, you should verify that the server has spawned correctly. In the Admin Portal, go to Dedicated Server Management and choose Servers.

armada

On the Servers page you’ll see the elements listed below:

  • Local Server shows the number of dedicated servers that run on your local computer. This type of dedicated server is used to perform testing before a game is published.

  • Server Overview shows the number of dedicated servers you have configured, from both AWS and GCP hosting providers. You can see the details of each server by clicking on the three dots next to the desired server and selecting View.

    armada armada armada

  • Available Regions shows the number of registered regions that you can run servers in. On this page you can see the status of each region.

    armada

  • Total Sessions shows the number of player sessions currently active. On this page you can see a list of players currently playing and the servers they’re using.

    armada

  • You can see detailed information about the servers and players by clicking on the three dots next to the desired session and selecting View.

    armada

Reserving a Server Using the API Gateway

When you use our Lobby service with Armada, it will create sessions and reserve servers for those sessions for you. If you prefer to use your own lobby, you can communicate with Armada via REST API to create a session and then reserve a server for that session. To do so, follow the steps below.

Create a Session

  1. Use the POST ​/dsmcontroller​/namespaces​/{namespace}​/sessions endpoint to create a session.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body.
    • Input the Game Mode taken from the matchmaking rules, e.g. 1v1, 3v3.
    • Input the Party ID with the ID of the party the session is for, in UUID format.
    • Input the Party Members with the user IDs of the players in the party. The user IDs should be in UUID format.
    • Input the game namespace into the Namespace field.
    • Input a Session ID using UUID format.
    • Input the game client version in the Client Version field.
    • Input the server configuration needed for the session in the Configuration field. If left empty, the default server configuration will be used.
    • Input the Pod Name. This field is only used for local servers, for other servers leave this blank.
    • Input the Region of the DSM.

Upon successful request, a new session will be created.

You can then check on the status of your session using the GET ​/dsmcontroller​/namespaces​/{namespace}​/sessions​/{sessionID} endpoint.

Claim a Server

  1. Use the POST ​/dsmcontroller​/namespaces​/{namespace}​/sessions​/claim endpoint to claim a server for your newly created session.
  2. Input the Namespace field with the game namespace.
  3. Fill out the Request Body.
    • Input the session’s Session ID.

Upon successful request, the DS will be claimed by your session.

What’s Next?

  • If you’re interested in Early Access to Armada, we’d love to talk to you. Shoot us an email about your project to get started.
  • Take a look at the API Gateway for Armada.
  • Check out our Matchmaking tutorial to learn more about our matchmaking service.