Integrate Amazon GameLift into a Unity project - Amazon GameLift
PrerequisitesInstall the pluginSet up an Anywhere fleet for testingAdd server code to your projectAdditional resources

Integrate Amazon GameLift into a Unity project

This topic explains how to set up the Amazon GameLift C# Server SDK plugin for Unity and integrate it into your game projects.

Additional resources:

Prerequisites

To use the Amazon GameLift C# server SDK plugin for Unity, you need the following components:

Set up UnityNuGet

If you don't have UnityNuGet set up for your game project, use the following steps to install the tool using the Unity package manager. Alternatively, you can use the NuGet CLI to manually download the DLLs. For more information, see the Amazon GameLift C# server SDK for Unity README.

To integrate UnityNuGet into your game project

  1. With your project open in the Unity Editor, go to the main menu and select Edit, Project Settings. From the options, choose the Package Manager section and open the Scoped Registries group.

  2. Choose the + button and enter the following values for the UnityNuGet scoped registry:

    Name: Unity NuGet
URL: https://unitynuget-registry.azurewebsites.net
Scope(s): org.nuget

  3. For Unity 2021 version users:

    After setting up UnityNuGet, check for Assembly Version Validation errors showing in the Unity console. These errors occur if binding redirects for strongly named assemblies in the NuGet packages are not resolving correctly to paths within your Unity project. To resolve this issue, configure Unity's assembly version validation:

    1. In the Unity Editor, go to the main menu and select Edit, Project Settings, and open the Player section.

    2. Deselect the Assembly Version Validation option.

Install the plugin

Use the following procedure to install the Amazon GameLift C# server SDK plugin for Unity and configure log4net logging.

To install the plugin

  1. With your project open in the Unity Editor, go to the main menu and select Window, Package Manager.

  2. Choose the + button to add a new package. Choose the option Add package from tarball.

  3. In Select packages on disk, locate the Amazon GameLift C# Server SDK plugin for Unity download files, and choose the Amazon GameLift Server SDK .tgz file. Choose Open to install the plugin.

The Amazon GameLift server SDK uses the log4net framework to output log messages. It is configured to output messages to the terminal of a server build by default, but Unity requires configuration to add file logging support. You can add this support to your project by importing the provided sample inside the Amazon GameLift Server SDK package. Use the following procedure to add the sample and configure log4net:

To configure log4net for file output

  1. With your project open in the Unity Editor, go to the main menu and select Window, Package Manager.

  2. From the dropdown menu, select Packages: In Project, and then select Amazon GameLift Server SDK from the list of packages. This opens the package details.

  3. In the package details, select the Samples group option and press Import.

  4. The log4net.config file and accompanying LoggingConfiguration.cs script automatically executes the configuration, which is now set up in the project's Assets/Samples folder.

    Note

    If you need to move your log4net.config file to a different folder in the project, then you must also update the config file's filepath in the script LoggingConfiguration.cs with the new path. For more information, see the log4net manual on configuring log4net.

For more detailed instructions and testing guidance, see the README located in the plugin download.

Set up an Amazon GameLift Anywhere fleet for testing

You can set up your development workstation as an Amazon GameLift Anywhere hosting fleet to iteratively test your Amazon GameLift integration. With this setup, you can start game server processes on your workstation, send player join or matchmaking requests to Amazon GameLift to start game sessions, and connect clients to the new game sessions. With your own workstation set up as a hosting server, you can monitor all aspects of your game integration with Amazon GameLift.

For instructions on setting up your workstation, see Test your integration using Amazon GameLift Anywhere fleets to complete the following steps:

  1. Create a custom location for your workstation.

  2. Create an Amazon GameLift Anywhere fleet with your new custom location. If successful, this request returns a fleet ID. Make a note of this value, as you'll need it later.

  3. Register your workstation as a compute in the new Anywhere fleet. Provide a unique compute name and specify the IP address for your workstation. If successful, this request returns a service SDK endpoint, in the form of a WebSocket URL. Make a note of this value, as you'll need it later.

  4. Generate an authentication token for your workstation compute. This short-lived authentication includes the token and an expiration date. Your game server uses it to authenticate communication with the Amazon GameLift service. Store the authentication on your workstation compute so that your running game server processes can access it.

Add Amazon GameLift server code to your Unity project

Your game server communicates with the Amazon GameLift service to receive instructions and report ongoing status. To accomplish this, you add game server code that uses the Amazon GameLift server SDK.

The provided code example illustrates the basic required integration elements. It uses a MonoBehavior to illustrate a simple game server initialization with Amazon GameLift. The example assumes that the game server runs on an Amazon GameLift Anywhere fleet for testing. It includes code to:

  • Initialize an Amazon GameLift API client. The sample uses the version of InitSDK() with server parameters for your Anywhere fleet and compute. Use the WebSocket URL, fleet ID, compute name (host ID), and authentication token, as defined in the previous topic Set up an Amazon GameLift Anywhere fleet for testing.

  • Implement callback functions to respond to requests from the Amazon GameLift service, including OnStartGameSession, OnProcessTerminate, and onHealthCheck.

  • Call ProcessReady() with a designated port to notify the Amazon GameLift service when the process is ready to host game sessions.

The code presented in this topic establishes communication with the Amazon GameLift service and . It also implements a set of callback functions that respond to requests from the . For more information on each function and what the code does, see Initialize the server process. For more information on the SDK actions and data types used in this code, read Amazon GameLift server SDK reference for C#.

This sample shows how to add all the required elements , as described in Add Amazon GameLift to your game server. It includes:

For more information on adding Amazon GameLift functionality, see these topics: 

using System.Collections.Generic;
using Aws.GameLift.Server;
using UnityEngine;

public class ServerSDKManualTest : MonoBehaviour
{    
    //This example is a simple integration that initializes a game server process 
    //that is running on an Amazon GameLift Anywhere fleet.
    void Start()
    {        
        //Identify port number (hard coded here for simplicity) the game server is listening on for player connections
        var listeningPort = 7777;

        //WebSocketUrl from RegisterHost call
        var webSocketUrl = "wss://us-west-2.api.amazongamelift.com";

        //Unique identifier for this process
        var processId = "myProcess";

        //Unique identifier for your host that this process belongs to
        var hostId = "myHost";

        //Unique identifier for your fleet that this host belongs to
        var fleetId = "myFleet";

        //Authorization token for this host process
        var authToken = "myAuthToken";

        //Server parameters are required for a GameLift Anywhere fleet.
        //They are not required for a GameLift managed EC2 fleet.
        ServerParameters serverParameters = new ServerParameters(
            webSocketUrl,
            processId,
            hostId,
            fleetId,
            authToken);

        //InitSDK establishes a local connection with an Amazon GameLift agent 
        //to enable further communication.
        var initSDKOutcome = GameLiftServerAPI.InitSDK(serverParameters);        
        if (initSDKOutcome.Success)
        {
            //Implement callback functions
            ProcessParameters processParameters = new ProcessParameters(
            //Implement OnStartGameSession callback
                (gameSession) => {
                    //GameLift sends a game session activation request to the game server 
                    //with game session object containing game properties and other settings.
                    //Here is where a game server takes action based on the game session object.
                    //When the game server is ready to receive incoming player connections, 
                    //it invokes the server SDK call ActivateGameSession().
                    GameLiftServerAPI.ActivateGameSession();
                },
                (updateGameSession) => {
                    //GameLift sends a request when a game session is updated (such as for 
                    //FlexMatch backfill) with an updated game session object. 
                    //The game server can examine matchmakerData and handle new incoming players.
                    //updateReason explains the purpose of the update.
                },
                () => {
                    //Implement callback function OnProcessTerminate
                    //GameLift invokes this callback before shutting down the instance hosting this game server.
                    //It gives the game server a chance to save its state, communicate with services, etc., 
                    //and initiate shut down. When the game server is ready to shut down, it invokes the 
                    //server SDK call ProcessEnding() to tell GameLift it is shutting down.
                    GameLiftServerAPI.ProcessEnding();
                }, 
                () => {
                    //Implement callback function OnHealthCheck
                    //GameLift invokes this callback approximately every 60 seconds.
                    //A game server might want to check the health of dependencies, etc.
                    //Then it returns health status true if healthy, false otherwise.
                    //The game server must respond within 60 seconds, or GameLift records 'false'.
                    //In this example, the game server always reports healthy.
                    return true;
                },
                //The game server gets ready to report that it is ready to host game sessions
                //and that it will listen on port 7777 for incoming player connections.
                listeningPort, 
                new LogParameters(new List<string>()
                {
                    //Here, the game server tells GameLift where to find game session log files.
                    //At the end of a game session, GameLift uploads everything in the specified 
                    //location and stores it in the cloud for access later.
                    "/local/game/logs/myserver.log"
                }));

            //The game server calls ProcessReady() to tell GameLift it's ready to host game sessions.
            var processReadyOutcome = GameLiftServerAPI.ProcessReady(processParameters);
            if (processReadyOutcome.Success)
            {
                print("ProcessReady success.");
            }
            else
            {
                print("ProcessReady failure : " + processReadyOutcome.Error.ToString());
            }
        }
        else
        {
            print("InitSDK failure : " + initSDKOutcome.Error.ToString());
        }
    }  

    void OnApplicationQuit()
    {
        //Make sure to call GameLiftServerAPI.ProcessEnding() and GameLiftServerAPI.Destroy() before terminating the server process.
        //These actions notify Amazon GameLift that the process is terminating and frees the API client from memory. 
        GenericOutcome processEndingOutcome = GameLiftServerAPI.ProcessEnding();
        GameLiftServerAPI.Destroy();
        if (processEndingOutcome.Success)
        {
            Environment.Exit(0);
        }
        else
        {
            Console.WriteLine("ProcessEnding() failed. Error: " + processEndingOutcome.Error.ToString());
            Environment.Exit(-1);  
        }
    }
}

Additional resources

Use the following resources to test your game server and expand the functionality: