Use the SDK to set up the server - Dedicated servers with AccelByte Multiplayer Servers (AMS) - (Unity module)

Last updated on March 15, 2024

Understand the AMS dedicated server flow​

Take some time to look at the flow of how a game server is managed by AccelByte Multiplayer Servers (AMS). For more information, read about the AMS dedicated server states in the AMS Integrate dedicated servers with SDK guide.

Unwrap the wrapper​

You are now ready to use AMS functions provided by the AccelByte Gaming Services (AGS) Game SDK.

The Byte Wars project uses a wrapper class named MultiplayerDSAMSWrapper that act as the wrapper to cache and handle AMS-related functionalities when using the AGS Game SDK.

The MultiplayerDSAMSWrapper class uses the ServerApiClient, ServerAMS, and ServerDSHub classes provided by the AccelByte Game SDK. They interact with AGS to provide the ability to register and unregister your server, receive notifications from DSHub and AMS, and handle multiplayer features.

What's in the Starter Pack​

The class MultiplayerDSAMSWrapper_Starter has been provided for you to act as a starter version of MultiplayerDSAMSWrapper so you can follow the tutorial from scratch. You can find the file in the Resources section and it consists of the following file:

  • MultiplayerDSAMSWrapper_Starter file: /Assets/Resources/Modules/MultiplayerDSEssentials/Scripts/MultiplayerDSAMSWrapper_Starter.cs

It already contains some functionalities:

  • Namespaces declaration for using the ServerAMS and ServerDSHub classes in the AGS Game SDK

    using AccelByte.Core;
    using AccelByte.Models;
    using AccelByte.Server;

  • Some Action events to give AMS notifications regarding connection and status changes.

    public event Action OnAMSConnectionOpened = delegate {};
    public event Action OnAMSDrainReceived = delegate {};

Integrate AMS using the SDK​

  1. Open Byte Wars in Unity.

  2. Open the predefined MultiplayerDSAMSWrapper_Starter C# script. Define some variables for DedicatedServer, ServerAMS, and ServerDSHub classes, then initialize those functions inside the Start() function to be able to call them.

    private DedicatedServer ds;
    private ServerAMS ams;
    private ServerDSHub dsHub;

    void Start()
    {
    #if UNITY_SERVER
        ds = AccelByteServerPlugin.GetDedicatedServer();
        ams = AccelByteServerPlugin.GetAMS();
        dsHub = MultiRegistry.GetServerApiClient().GetDsHub();
    #endif
    }

  3. Prepare a getter function to get the dedicated server ID. This DSId will be important for connecting to DSHub later. Its value can be retrieved from the provided config values in AccelByteServerPlugin.

    public string DedicatedServerId => AccelByteServerPlugin.Config.DsId;

  4. Start to prepare the server login. Create a callback function to inform when the login process completes.

    private void OnLoginWithClientCredentialsCompleted(Result result, ResultCallback customCallback = null)
    {
        if (!result.IsError)
        {
            BytewarsLogger.Log("Server login success.");
        }
        else
        {
            BytewarsLogger.Log($"Server login failed. Error code: {result.Error.Code}, message: {result.Error.Message}");
        }
        
        customCallback?.Invoke(result);
    }

  5. Create a wrapper function to call the DedicatedServer login function. The game server will try to log in with client credentials provided in AccelByteServerSDKOAuthConfig.json.

    public void LoginWithClientCredentials(ResultCallback resultCallback = null)
    {
        ds?.LoginWithClientCredentials(
            result => OnLoginWithClientCredentialsCompleted(result, resultCallback)
        );
    }

  6. Create a callback function to invoke the OnAMSConnectionOpened event that will inform when the AMS service successfully connects and is ready to use.

    private void OnAMSConnected()
    {
        BytewarsLogger.Log("[AMS] AMS Connected!");
        OnAMSConnectionOpened?.Invoke();
        ams.OnOpen -= OnAMSConnected;
    }

  7. Create a function to handle AMS notification events. Bind the previous OnAMSConnectionOpened() function to the AMS OnOpen notification event and invoke the OnAMSDrainReceived Action event when AMS OnDrainReceived triggers.

    public void SubscribeAMSEvents()
    {
        if (ams == null)
        {
            return;
        }

    #if UNITY_STANDALONE_WIN || UNITY_STANDALONE_LINUX
        OnAMSConnectionOpened?.Invoke();
    #else
        ams.OnOpen += OnAMSConnected;
    #endif
        ams.OnDrainReceived += () => OnAMSDrainReceived?.Invoke();
    }

  8. Create another function to send a ready message to AMS, informing that our server is ready. By sending the ready message, you are actually registering the server to AMS.

    public void SendReadyMessageToAMS()
    {
        ams?.SendReadyMessage();
    }

  9. Now that your dedicated server is ready, the game session will need to claim it. Prepare a wrapper function to connect to DSHub and get updates for your dedicated server. It will require your dsId to connect.

    public void ConnectToDSHub(string serverId)
    {
        dsHub?.Connect(serverId);
    }

  10. Prepare two callback functions that will handle on connected or on disconnected to DSHub. On disconnect, it will retry to reconnect to DSHub by calling the ConnectToDSHub() function.

    private void OnDSHubConnected()
    {
        BytewarsLogger.Log($"DS connected to DSHub");
    }
    private void OnDSHubDisconnected(WsCloseCode wsCloseCode)
    {
        BytewarsLogger.Log("DS disconnected from DSHub, trying to reconnect..");
        
        // Reconnect to DS
        if (!String.IsNullOrEmpty(DedicatedServerId) && dsHub != null)
        {
            ConnectToDSHub(DedicatedServerId);
        }
    }

  11. Create a wrapper function to subscribe to DSHub events and bind the functions you created earlier to their respective events.

    public void SubscribeDSHubEvents()
    {
        dsHub.OnConnected += OnDSHubConnected;
        dsHub.OnDisconnected += OnDSHubDisconnected;
    }

Resources​

Last updated on

On this page