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.

Install the plugin

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

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:

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 Set up local testing with Amazon GameLift Anywhere to complete the following steps:

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:

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 5.x for C# and Unity: Actions.

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: