Debug dedicated servers locally using the AMS Simulator

Overview​

The AccelByte Multiplayer Servers (AMS) Simulator (SIM) simulates how the watchdog interacts with the dedicated server. It is a great tool to verify how your dedicated server will react to state changes and unexpected events that originate from AMS, so that you can be sure that your dedicated server will work on the AMS environment without uploading a dedicated server build to test.

Prerequisites​

Before you begin this guide, you must have:

Run the AMS Simulator​

To run the amssim, use this command:

> amssim run

Generate a config.json file​

The first time when you call the run command, a config.json file will be automatically generated for you. config.json is located in the same directory with your amssim executable and it contains settings that are essential to run your dedicated servers. Feel free to change any of these values to match how you would want your dedicated server to run.

Here's an example of a config.json file:

{
 "WatchdogPort": 5555,
 "AGSEnvironmentURL": "",
 "AGSNamespace": "",
 "IAM": {
  "ClientID": "",
  "ClientSecret": ""
 },
 "LocalDSHost": "",
 "LocalDSPort": 0,
 "ClaimKeys": [],
 "ServerName": "my-computer-name"
}

Alternatively, you can use the following command to generate or replace your config.json with default values.

> amssim generate-config

Generate a session​

Every time you start the amssim, a unique session will be created. You can review your session information by using the info command:

amssim> info

AMS simulator url  ws://0.0.0.0:5555/watchdog
AMS simulator session id:  01hcnefg15exp386j9rx901saa.
AMS simulator session log path: session\01hcnefg15exp386j9rx901saa.log
no connected dedicated server

Launch a dedicated server​

When you have integrated your dedicated server with the AccelByte SDK, you can launch your dedicated server directly from your IDE. If you have not changed the WatchdogPort in the config.json file, the AccelByte SDK will automatically connect to the AMS SIM instance at ws://localhost:5555/watchdog. Otherwise, make sure that the dedicated server is connecting to the correct AMS Simulator by using the -watchdog_url command line argument for Unreal or -watchdogUrl for Unity.

If the connection is successful, you will see that the ds state is Creating or Ready, depending on whether your dedicated server has called the Ready API on time.

When running in AMS, a server in the Creating state will be subjected to the creation timeout and will be terminated if it does not signal that it is ready within that timeout. amssim does not enforce timeouts.

At any point if you want to check your dedicated server state, use this status command:

amssim> ds status

Set dedicated servers to the Ready state without calling the Ready API​

The Ready command allows you to set your dedicated server state from Creating (or claimed) to Ready, without making your dedicated server call itself.

To set your dedicated server to the Ready state, use this command:

amssim> ds ready

Simulate a claim action​

A claim happens when a game session requires a dedicated game server to serve. This claim action is usually initiated by the AccelByte session service. When the claim action happens, it will set the dedicated server state from Ready to In Session.

When running in AMS, a server in the In Session state is subject to the session timeout.

To simulate this action, use this command:

amssim> ds claim

Send drain signal to the server​

The drain signal tells a dedicated server it will be shut down. When running in AMS, a server that has been sent the drain signal is subjected to the drain timeout, giving the dedicated server time to perform any last minute operation, and then exit itself before it is terminated forcibly.

When the drain signal is sent to the dedicated server, the signal will trigger the OnDrainReceived() handler. Your dedicated server can then override the handler to execute a code path to handle the drain signal.

Your dedicated server should respond to the drain signal by exiting cleanly after doing whatever shutdown logic it needs to execute.

To send a drain signal to your dedicated server, use this command:

amssim> ds drain

Register a locally run dedicated server with AMS​

Using the AMS simulator, you can register one locally run dedicated server into AMS. This allows you to utilize the matchmaker and session services to put players into your local dedicated servers, enabling you to test your game flow end-to-end without having to upload dedicated servers into AMS.

info

Each namespace can register up to 10 local dedicated servers.

Set up the local dedicated server authentication IAM client​

AGS Starter

For AGS Starter customers, this step is not required. All confidential IAM clients contain the necessary permissions for a local dedicated server.

Before you can register your local dedicated server into AMS, you should set up a confidential IAM client on the Admin Portal with the following permissions:

Permission nameAction
NAMESPACE:{namespace}:AMS:LOCALDSCreate

The IAM client is used to verify the identity of the AMS Simulator. To learn about authorization in AGS, see Authorization.

Configure the AMS Simulator​

Modify the following properties in the config.json:

  • AGSEnvironmentURL: Use the URL of the environment you want to register your local dedicated server to, without the scheme (e.g., http://).
AGS Starter

For AGS Starter customers, your AGSEnvironmentURL is ${gamenamespace_name}.dev.gamingservices.accelbyte.io.

  • AGSNamespace: Use the namespace within the environment to which you want to register the local dedicated server.

  • IAM: Use the ClientID and ClientSecret that were used to authenticate your AMS Simulator.

  • LocalDSHost, LocalDSPort: Use the IP and Port of the machine that runs the local dedicated server, so that your playtester 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 key.

  • ServerName: Provide the name you want to call your local dedicated server. By default, it is automatically generated using your computer name, which you can change as preferred. Note that, by default, this is registered as one of the claim keys.

Run the local dedicated server​

When the local dedicated server connects to the AMS Simulator, the simulator will automatically register the local dedicated server to the environment as specified in the config.json file. If the registration is successful, you will see an entry on the Admin Portal in the Local Server tab, under the AccelByte Multiplayer Servers section in the sidebar.

Image shows the Local Server page10

Set up session template to claim local dedicated server​

The local dedicated servers are considered to have no region. You can set up a session template with the session type DS - AMS with the appropriate claim keys as described in the local dedicated server view. You can leave the regions field blank, or if you are using the same session template for non-local DS and want default regions for that you can set whichever regions you want. This will enable the matchmaker to put players into your local dedicated servers using the session template that you set up.

You don't have to create a new dedicated session template for testing with local DS. You can reuse an existing session template as long as the following conditions are met:

  1. The match pool being used is referencing a session template of type DS - AMS
  2. The game client includes the SETTING_GAMESESSION_SERVERNAME attribute in the FOnlineSessionV2AccelByte::StartMatchmaking() (or in the FOnlineSessionV2AccelByte::CreateSession() if doing direct session creation rather than matchmaking).
info
  • The value of SETTING_GAMESESSION_SERVERNAME must match with the ServerName defined in the ams config.json
  • The value of ClaimKeys in the ams config.json can be left blank if you want to test the DS solo locally. By default, the ServerName is registered as one of the claim key.

Below is an example on how to route the local server name from within the game client during matchmaking request.

// Set local server name for matchmaking request, if any.
// This is useful if you want to try matchmaking using a local dedicated server.
FString ServerName;
FParse::Value(FCommandLine::Get(), TEXT("-ServerName="), ServerName);
if (!ServerName.IsEmpty())
{
    UE_LOG_MATCHMAKINGDS(Log, TEXT("Requesting local server with name: %s"), *ServerName)
    MatchmakingSearchHandle->QuerySettings.Set(SETTING_GAMESESSION_SERVERNAME, ServerName, EOnlineComparisonOp::Equals);
}
...
GetSessionInt()->StartMatchmaking(
    LocalPlayers,
    SessionName,
    FOnlineSessionSettings(),
    MatchmakingSearchHandle,
    CompletionDelegate);

Refer to Byte Wars: Matchmaking with DS for the full code example.

To learn more about matchmaking and session templates, check out the following guides:

Last updated on

On this page