Register local dedicated servers with AMS

Introduction

You can register a locally-run dedicated server into AMS using the AMS Simulator. 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 Shared Cloud

For AGS Shared Cloud 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://).

AGS Shared Cloud

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 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.

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:

Unreal Engine

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.

Unity

1. The match pool being used is referencing a DS - AMS session template.
2. The game client includes the server_name attribute in AccelByteSDK.GetClientRegistry().GetApi().GetMatchmakingV2().CreateMatchmakingTicket (or in AccelByteSDK.GetClientRegistry().GetApi().GetSession().CreateGameSession if doing direct session creation rather than matchmaking).

info

• The value of server_name 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 locally test the DS individually. By default, the ServerName 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:

• Matchmaking
• Session template