Register local dedicated servers with AMS
Introduction
You can register a locally-run dedicated server (DS) with AMS using the AMS Simulator. This allows you to test your game flow end-to-end, including matchmaking and session formation, without having to upload dedicated servers into AMS. This guide walks you through the steps to register your local dedicated server with AMS.
This section is about running AMS Simulator in "cloud integrated" mode, meaning that it will register your local dedicated server with AMS environment for use with Matchmaking and Session services. If you haven't used AMS Simulator before, or if you wish to run AMS Simulator in standalone mode (completely local), refer to Run the AMS Simulator (Standalone mode).
Each namespace can register up to 10 local dedicated servers.
Set up the local dedicated server authentication IAM client
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 |
For AGS Shared Cloud customers, use a confidential IAM clients with Create
on AMS->Watchdog Permissions.
The IAM client is used to verify the identity of the AMS Simulator. To learn about authorization, 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 Shared Cloud 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.
Claim a local dedicated server
The local dedicated servers are considered to have no region and will always be considered before the regions given in the claim request. To claim a local server that has been registered with AMS, you just need to make sure the server is in the "ready" state and the claim request includes at least one claim key matching either the claim keys you listed, or the server name, in config.json.
The rest of this document assumes you are using AccelByte Gaming Services (AGS) for your matchmaking and session management, and gives a more detailed example to help your game clients matchmake into your local DS.
When using AGS, You can set up an AGS session template with the session type DS - AMS
and with claim keys that match any of the claim keys specified in amssim's config.json file. Note that you can leave the claim keys blank as well, as long as you are provding the server_name in the matchmaking/session creation request as described below.
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:
- Unreal Engine
- Unity
- The match pool being used is referencing a session template of type
DS - AMS
- The game client includes the
SETTING_GAMESESSION_SERVERNAME
attribute in theFOnlineSessionV2AccelByte::StartMatchmaking()
(or in theFOnlineSessionV2AccelByte::CreateSession()
if doing direct session creation rather than matchmaking).
- The value of
SETTING_GAMESESSION_SERVERNAME
must match with theServerName
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, theServerName
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.
- The match pool being used is referencing a
DS - AMS
session template. - The game client includes the
server_name
attribute inAccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2().CreateMatchmakingTicket
(or inAccelByteSDK.GetClientRegistry().GetApi().GetSession().CreateGameSession
if doing direct session creation rather than matchmaking).
- The value of
server_name
must match with theServerName
defined in the AMS config.json. - The value of
ClaimKeys
in the AMS config.json can be left blank if you want to locally test the DS individually. By default, theServerName
is registered as one of the claim keys.
Below is an example on how to route the local server name from within the game client during a matchmaking request.
var matchmaking = AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2();
// Set local server name for matchmaking request, if any.
// This is useful if you want to try matchmaking using a local dedicated server.
string serverName = "your-server-name";
string matchPoolName = "your-match-pool-name-ams";
var optionalParams = new MatchmakingV2CreateTicketRequestOptionalParams
{
attributes = new Dictionary<string, object>
{
{ "server_name", serverName }
},
};
matchmaking.CreateMatchmakingTicket(matchPoolName, optionalParams, result =>
{
if (result.IsError)
{
// Do something if CreateMatchmakingTicket has an error
Debug.Log($"Error CreateMatchmakingTicket, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
return;
}
// Do something if CreateMatchmakingTicket has been successful
});
Refer to Byte Wars: Matchmaking with DS.
To learn more about matchmaking and session templates, check out the following guides: