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 complete the following:
- You have created or linked an AMS account to your namespace.
- You have integrated the dedicated server with the AGS SDK.
- You have downloaded the AMS SIM.
Use the AMS Simulator
To start 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.
Each namespace can register up to 10 local dedicated servers.
Set up the local dedicated server authentication IAM client
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 name | Action |
---|---|
NAMESPACE:{namespace}:AMS:LOCALDS | Create |
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://
).
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 theClientID
andClientSecret
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, theServerName
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.
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, and then leave the regions field blank. This will enable the matchmaker to put players into your local dedicated servers using the session template that you set up.
To learn more about matchmaking and session templates, check out the following guides: