Test run AMS flow locally - Dedicated servers with AccelByte Multiplayer Servers (AMS) - (Unreal Engine module)

Last updated on December 19, 2024

Introduction

In this tutorial, you will learn how to test your dedicated server flow on AccelByte Multiplayer Servers (AMS) locally using AMS Simulator. AMS Simulator is the tool to verify how your dedicated server will react to state changes and unexpected events that originate from AMS. This way, you can make sure that your dedicated server will work properly with the flow without uploading the dedicated server first.

Run a local dedicated server

There are two ways of testing local dedicated servers in Unreal Engine: as a packaged dedicated server, or run an uncooked server using the editor. Packaged dedicated servers uses less resources to run, but it takes longer to build, while using the editor uses more resources and takes less time to build. Choose one of those method based on your needs.

Package dedicated server

Compile your project and open it in the Unreal Engine editor. Then, package your game server for Windows.

info

For more information on packaging Unreal projects, read Packaging Projects.

note

This tutorial uses the Development build to enable logging for debugging purposes. Building as Shipping will disable logging.

Run uncooked dedicated server

Run this command using PowerShell to start the game server with the editor:

& "<your_ue5_dir>\UnrealEditor.exe" "<your_project_dir>\AccelByteWars.uproject" -server

Test run dedicated server locally

This section will test your packaged game server locally to check whether it is able to handle the state changes within the lifecycle of AMS.

1. Log in to the AccelByte Gaming Services (AGS) Admin Portal and go to your game namespace dashboard.

2. From the side bar menu, select AccelByte Multiplayer Servers > Download Resource. Locate and download AMS Simulator for Windows. The amssim.exe file should be downloaded.

   note

   If you don't see Download Resource and instead see Setup AMS Account, you will need to set up your AMS account. To do this, you can follow the How-to guides for creating and linking AMS accounts.

3. Before you run the AMS Simulator, you need to set up a new IAM client for the simulator called ByteWars-AMSSim. To create it, you can follow the same steps when you set up the server and AMS CLI IAM, but this time you need to use the configuration below.

   AGS Shared Cloud

   When creating the AMS Simulator IAM client, choose the Create from Template option for the Create Options field. Then, choose the Dedicated Server Tools option for the Select Template field. This IAM client template has the necessary permissions for using AMS Simulator.

   AGS Private Cloud

   After creating the AMS Simulator IAM client, add the permission below.

   Resource	Permission
   NAMESPACE:{namespace}:AMS:LOCALDS	Create

4. After downloading AMS Simulator and creating the IAM client, open Windows PowerShell and run the AMS Simulator executable using the following command to generate a config file:

   .\amssim.exe generate-config

5. You will be able to see the config.json in the same path as the AMS Simulator executable. Open the file using a text editor and fill out the configuration with the information below. Replace the ClientID and the ClientSecret with the information of the ByteWars-AMSSim IAM client you created. Also, replace other placeholder values based on your game namespace and AGS environment.

   AGS Shared Cloud

   {
       "WatchdogPort": 5555,
       "AGSEnvironmentURL": "<game_namespace_id>.prod.gamingservices.accelbyte.io",
       "AGSNamespace": "<game_namespace_id>",
       "IAM": {
           "ClientID": "<ams_sim_iam_client_id>",
           "ClientSecret": "<ams_sim_iam_client_secret>"
       },
       "LocalDSHost": "127.0.0.1",
       "LocalDSPort": 7777,
       "ClaimKeys": [],
       "ServerName": "Your Local Server Name"
   }

   AGS Private Cloud

   {
       "WatchdogPort": 5555,
       "AGSEnvironmentURL": "<studio_name>.accelbyte.io",
       "AGSNamespace": "<game_namespace_id>",
       "IAM": {
           "ClientID": "<ams_sim_iam_client_id>",
           "ClientSecret": "<ams_sim_iam_client_secret>"
       },
       "LocalDSHost": "127.0.0.1",
       "LocalDSPort": 7777,
       "ClaimKeys": [],
       "ServerName": "Your Local Server Name"
   }
   info

   • WatchdogPort is the port the app is going to use to connect to your dedicated server.
   • AGSEnvironmentURL is the URL of the environment you want to register your local dedicated server to, without http://.
   • IAM is the ClientID and ClientSecret that were used to authenticate your AMS Simulator that you created in previous steps.
   • LocalDSHost and LocalDSPort are the IP and port respectively of the machine that runs the local dedicated server, so your play tester knows where to connect.
   • ClaimKeys provide the list of claim keys that the session service uses to claim your local dedicated server. By default, the ServerName is registered as one of the claim keys.
   • ServerName is the name you want to call your local dedicated server. By default, it is registered as one of the claim keys and automatically generated using your computer name, which you can change as preferred.
   tip

   • To find your game namespace ID, go to your Admin Portal and navigate to the Namespace page where your game namespaces are listed. Then, locate your game namespace under the GAMES section and click on the gear icon. On the new page, locate the Namespace ID property and there you can find your game namespace ID value.

6. Once the configuration is complete, run the AMS Simulator executable.

   .\amssim.exe run

   Here is the output of AMS Simulator. Notice that it provides an example ID format for your local dedicated server. This example is ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a. Copy it, as you will need it in the next step.

   AMS simulator url  ws://0.0.0.0:5555/watchdog
   AMS simulator session id:  01hfaxxvfqhe9gkk2zesfx0b66.
   AMS simulator session log path: session\01hfaxxvfqhe9gkk2zesfx0b66.log
   
   Ready to accept local DS
   
   Start the local DS with a valid DS ID that conforms to uuid standards
   An example that can be copied and pasted is:
   
   ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a
   
   ==================================Command list=================================================
       help                          show the command list again
       info                          show AMS simulator info
       ds
           status                    show status of the ds
           ready                     explicitly set ds into ready state.
           claim                     claim the ds for a game session.
           drain                     drain the ds
       exit, quit                    exit ams simulator
   =============================================================================================

7. Run the game server executable or the uncooked server using Unreal Editor using the following commands below in Windows PowerShell. Notice that it uses the ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a from the previous step as its local dedicated server ID.

   Packaged

   C:/WindowsServer/AccelByteWarsServer.exe -server -log -nosteam -dsid=ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a -watchdog_url="ws://localhost:5555/watchdog"

   Uncooked

   & "<your_ue5_dir>\UnrealEditor.exe" "<your_project_dir>\AccelByteWars.uproject" -server -log -nosteam -dsid=ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a -watchdog_url="ws://localhost:5555/watchdog"
   info

   • -log will show game server's log.
   • -nosteam is used to not run the Steam plugin on the game server side.
   • -server is used to run the game as a server.
   • -dsid is the dedicated server identification that will be used by the game server to initialize AMS configuration. You can use the example ID given by AMS Simulator. This example is ds_018c1f42-5eb6-7ca3-9650-a732ed75ce6a. Note that this launch parameter will be filled automatically on the AMS side when this dedicated server is launched in AMS.
   • -watchdog_url is the URL and the port that will be used to connect the game server to AMS. This example uses ws://localhost:5555/watchdog as the value as this is the default IP and port for AMS Simulator. You can change the configuration for AMS Simulator in config.json. Note that this launch parameter will be filled automatically on the AMS side when the dedicated server is launched in AMS.

8. Once your game server is running, check the server log to confirm the local server is connected to AMS, similar to what's shown below under LogAccelByteAMS of the AMS logs:

   LogAccelByteAMS: Connecting to ws://localhost:5555/watchdog
   LogAccelByteAMS: Connected

   You can also confirm the successful connection from the AMS Simulator.

   amssim> DS Connected

9. Check the dedicated server status using AMS Simulator by executing ds status. If the game server successfully registers, it will display the log below. Notice that the DS State has changed to Ready.

   ds status

   AMS Simulator will show the following log:

   amssim> ds status
   ID: xxxxx
   Connected at: 2023-XX-XX 10:00:00
   Last Heartbeat: 2023-XX-XX 10:00:00
   DS State: Ready
   info

   You can also check the local dedicated sever status from the Admin Portal by navigating to the side bar menu of the dashboard and select AccelByte Multiplayer Servers > Local Server.

10. To check the local dedicated server log, go to the /Saved folder from your packaged project (in our example, C:/WindowsServer/AccelByteWars/Saved/Logs/AccelByteWars.log). If you see the log lines below, your server was completely initiated:

    // Logged in to IAM successfully
    LogAccelByteOSS: Verbose: >>> FOnlineAsyncTaskAccelByteLoginServer::Initialize (AsyncTask method) was called.
    LogAccelByteOSS: Verbose: >>> FOnlineAsyncTaskAccelByteLoginServer::TriggerDelegates (AsyncTask method) was called. Args:   bWasSuccessful: true
    
    // Connected and registered (ready message sent) to AMS 
    LogAccelByteAMS: Connecting to ws://localhost:5555/watchdog
    LogAccelByteAMS: Connected
    LogAccelByteAMS: Send ready message to AMS
    {"ready":{"dsid":"testid"}}
    
    // Connected to DS Hub
    LogAccelByteDSHub: Connecting to wss://demo.accelbyte.io/dshub/
    LogAccelByteDSHub: Connected
    LogAccelByteDSHub: New message received from DSHub:
    {"MessageID":"","Code":200,"topic":"","payload":{}}
    
    // The wrapper log, the server completely initiated
    LogMultiplayerDSEssentials: UMultiplayerDSEssentialsSubsystem_Starter::OnRegisterServerComplete succeeded: TRUE
    info

    • DS log should be in your packaged server's Saved folder. Example: C:/WindowsServer/AccelByteWars/Saved/Logs/AccelByteWars.log
    • AMS Simulator Log should be in the <Your AMS Simulator Directory>/session folder.

11. You can also use the command below to simulate a game session claiming a dedicated server. Notice the DS State now has changed to InSession.

    ds claim

    AMS Simulator will show the following log:

    amssim> ds status
    ID: xxxxx
    Connected at: 2023-XX-XX 10:00:00
    Last Heartbeat: 2023-XX-XX 10:00:00
    DS State: InSession

12. You can also check if the game server is able to handle a drain state by executing ds drain. If you see the log lines below, your server successfully handles drain states. Notice that the DS State has changed to Draining.

    ds drain

    AMS Simulator will show the following log:

    amssim> ds status
    no connected dedicated server

    The game server log should show the following and then shut down the server.

    LogMultiplayerDSEssentials: Received AMS drain message; Shutting down the server now!

13. To quit AMS Simulator, execute the following command:

    quit

References

• AccelByte Multiplayer Servers: Watchdog
• AccelByte Multiplayer Servers: Run the AMS Simulator