Integrate Amazon GameLift into an Unreal Engine project

Clone the Unreal Engine source to your development environment in a branch of your choice.

git clone https://github.com/EpicGames/UnrealEngine.git

Check out the tag of the version that you're using to develop your game. For example, the following example checks out Unreal Engine version 5.1.1:

git checkout tags/5.1.1-release -b 5.1.1-release

Navigate to the root folder of the local repository. When you're in the root folder, run the following file: Setup.bat.

While in the root folder, also run the file: GenerateProjectFiles.bat.

After running the files from the previous steps, an Unreal Engine solution file, UE5.sln, is created. Open Visual Studio, and in the Visual Studio editor open the UE5.sln file.

In Visual Studio, open the View menu and choose the Solution Explorer option. This opens the context menu of the Unreal project node. In the Solution Explorer window, right-click the UE5.sln file (it can be listed as just UE5), then choose Build to build the Unreal project with the Development Editor Win64 target.

With Visual Studio open, navigate to the Solution Explorer pane and choose the UE5 file to open the context menu for the Unreal project. In the context menu, choose the Set as Startup Project option.

At the top of your Visual Studio window, choose Start Debugging (green arrow).

This action starts your new source-built instance of Unreal Editor. For more information about using the Unreal Editor, see Unreal Editor Interface on the Unreal Engine documentation website.

Close the Visual Studio window you opened, since the Unreal Editor opens a another Visual Studio window that contains the Unreal project and your game project.

In the Unreal editor, do one of the following:

• Choose an existing Unreal project that you want to integrate with Amazon GameLift.

• Create a new project. To experiment with the Amazon GameLift plugin for Unreal, try using Unreal engine's Third Person template. For more information about this template, see Third Person template on the Unreal Engine documentation website.

  Alternatively, configure a new project with the following settings:

  • C++

  • With starter content

  • Desktop

  • A project name. In the examples in this topic, we named our project GameLiftUnrealApp.

In Visual Studio's Solution Explorer, navigate to the location of your Unreal project. In the Unreal Source folder, find a file named Your-application-name.Target.cs.

For example: GameLiftUnrealApp.Target.cs.

Make a copy of this file and name the copy: Your-application-nameServer.Target.cs.

Open the new file and make the following changes:

Download the Amazon GameLift C++ server SDK plugin for Unreal.

Download and install OpenSSL. For more information on downloading OpenSSL, read the Github OpenSSL build and install documentation.

For more information, read the OpenSSL Notes for Windows platforms documentation.

With the libraries downloaded, build the C++ server SDK libraries for Unreal Engine.

In the GameLift-Cpp-ServerSDK-<version> directory in the downloaded SDK, compile with the -DBUILD_FOR_UNREAL=1 parameter and build the server SDK. The following examples show how to compile using cmake.

Run the following commands in your terminal:

mkdir cmake-build
cmake.exe -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release -S . -B ./cmake-build -DBUILD_FOR_UNREAL=1 -A x64
cmake.exe --build ./cmake-build --target ALL_BUILD --config Release

The Windows build creates the following binary files in the out\gamelift-server-sdk\Release folder:

Copy the two library files to the ThirdParty\GameLiftServerSDK\Win64 folder in the Amazon GameLift Unreal Engine plugin package.

Locate the GameLiftServerSDK folder that you extracted from the plugin in the earlier procedure.

Locate the Plugins in your game project root folder. (If the folder does not exist, then create it there.)

Copy the GameLiftServerSDK folder into the Plugins.

This will allow the Unreal project to see the plugin.

Add the Amazon GameLift server SDK plugin to the game's .uproject file.

In the example, the app is called GameLiftUnrealApp, so the file will be GameLiftUnrealApp.uproject.

Edit the .uproject file to add the plugin to your game project.

"Plugins": [
    {
        "Name": "GameLiftServerSDK",
        "Enabled": true
    }
]

Make sure the game's ModuleRules takes a dependency on the plugin. Open the .Build.cs file and add the Amazon GameLiftServerSDK dependency. This file is found under Your-application-name/Source//Your-application-name/.

For example, the tutorial filepath is ../GameLiftUnrealApp/Source/GameLiftUnrealApp/GameLiftUnrealApp.Build.cs.

Add "GameLiftServerSDK" to the end of the list of PublicDependencyModuleNames.

using UnrealBuildTool;
using System.Collections.Generic;
public class GameLiftUnrealApp : ModuleRules  
  {
    public GameLiftUnrealApp(TargetInfo Target)
    {
      PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "GameLiftServerSDK" });
      bEnableExceptions = true;
    }
  }

In Visual Studio, open the .sln file for your application. For our example, the file GameLiftUnrealApp.sln is found in the root folder.

With the solution open, locate your application's Your-application-nameGameMode.h file. Example: GameLiftUnrealAppGameMode.h.

Change the header file to align with the following example code. Be sure to replace "GameLiftUnrealApp" with your own application name.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/GameModeBase.h"
#include "GameLiftServerSDK.h"
#include "GameLiftUnrealAppGameMode.generated.h"

DECLARE_LOG_CATEGORY_EXTERN(GameServerLog, Log, All);

UCLASS(minimalapi)
class AGameLiftUnrealAppGameMode : public AGameModeBase
{
    GENERATED_BODY()

public:
    AGameLiftUnrealAppGameMode();

protected:
    virtual void BeginPlay() override;

private:
    // Process Parameters needs to remain in scope for the lifetime of the app
    FProcessParameters m_params;

    void InitGameLift();
};

Open the related source file Your-application-nameGameMode.cpp file. In our Example: GameLiftUnrealAppGameMode.cpp. and change the code to align with the following example code. Be sure to replace "GameLiftUnrealApp" with your own application name.

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

#include "GameLiftUnrealAppGameMode.h"
#include "GameLiftUnrealAppCharacter.h"

#include "UObject/ConstructorHelpers.h"

DEFINE_LOG_CATEGORY(GameServerLog);

AGameLiftUnrealAppGameMode::AGameLiftUnrealAppGameMode()
{
    // set default pawn class to our Blueprinted character
    static ConstructorHelpers::FClassFinder<APawn> PlayerPawnBPClass(TEXT("/Game/ThirdPerson/Blueprints/BP_ThirdPersonCharacter"));
    if (PlayerPawnBPClass.Class != NULL)
    {
        DefaultPawnClass = PlayerPawnBPClass.Class;
    }
}

void AGameLiftUnrealAppGameMode::BeginPlay()
{
#if WITH_GAMELIFT
    InitGameLift();
#endif
}

void AGameLiftUnrealAppGameMode::InitGameLift()
{
    UE_LOG(GameServerLog, Log, TEXT("Initializing the GameLift Server"));

    //Getting the module first.
    FGameLiftServerSDKModule* gameLiftSdkModule = &FModuleManager::LoadModuleChecked<FGameLiftServerSDKModule>(FName("GameLiftServerSDK"));

    //Define the server parameters for a GameLift Anywhere fleet. These are not needed for a GameLift managed EC2 fleet.
    FServerParameters serverParameters;

    //AuthToken returned from the "aws gamelift get-compute-auth-token" API. Note this will expire and require a new call to the API after 15 minutes.
    if (FParse::Value(FCommandLine::Get(), TEXT("-authtoken="), serverParameters.m_authToken))
    {
        UE_LOG(GameServerLog, Log, TEXT("AUTH_TOKEN: %s"), *serverParameters.m_authToken)
    }

    //The Host/compute-name of the GameLift Anywhere instance.
    if (FParse::Value(FCommandLine::Get(), TEXT("-hostid="), serverParameters.m_hostId))
    {
        UE_LOG(GameServerLog, Log, TEXT("HOST_ID: %s"), *serverParameters.m_hostId)
    }

    //The Anywhere Fleet ID.
    if (FParse::Value(FCommandLine::Get(), TEXT("-fleetid="), serverParameters.m_fleetId))
    {
        UE_LOG(GameServerLog, Log, TEXT("FLEET_ID: %s"), *serverParameters.m_fleetId)
    }

    //The WebSocket URL (GameLiftServiceSdkEndpoint).
    if (FParse::Value(FCommandLine::Get(), TEXT("-websocketurl="), serverParameters.m_webSocketUrl))
    {
        UE_LOG(GameServerLog, Log, TEXT("WEBSOCKET_URL: %s"), *serverParameters.m_webSocketUrl)
    }

    //The PID of the running process
    serverParameters.m_processId = FString::Printf(TEXT("%d"), GetCurrentProcessId());
    UE_LOG(GameServerLog, Log, TEXT("PID: %s"), *serverParameters.m_processId);

    //InitSDK establishes a local connection with GameLift's agent to enable further communication.
    //Use InitSDK(serverParameters) for a GameLift Anywhere fleet. 
    //Use InitSDK() for a GameLift managed EC2 fleet.
    gameLiftSdkModule->InitSDK(serverParameters);

    //Implement callback function onStartGameSession
    //GameLift sends a game session activation request to the game server
    //and passes a game session object with 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().
    auto onGameSession = [=](Aws::GameLift::Server::Model::GameSession gameSession)
    {
        FString gameSessionId = FString(gameSession.GetGameSessionId());
        UE_LOG(GameServerLog, Log, TEXT("GameSession Initializing: %s"), *gameSessionId);
        gameLiftSdkModule->ActivateGameSession();
    };

    m_params.OnStartGameSession.BindLambda(onGameSession);

    //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.
    auto onProcessTerminate = [=]() 
    {
        UE_LOG(GameServerLog, Log, TEXT("Game Server Process is terminating"));
        gameLiftSdkModule->ProcessEnding();
    };

    m_params.OnTerminate.BindLambda(onProcessTerminate);

    //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.
    auto onHealthCheck = []() 
    {
        UE_LOG(GameServerLog, Log, TEXT("Performing Health Check"));
        return true;
    };

    m_params.OnHealthCheck.BindLambda(onHealthCheck);

    //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.
    m_params.port = 7777;

    //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.
    TArray<FString> logfiles;
    logfiles.Add(TEXT("GameLift426Test/Saved/Logs/GameLift426Test.log"));
    m_params.logParameters = logfiles;

    //The game server calls ProcessReady() to tell GameLift it's ready to host game sessions.
    UE_LOG(GameServerLog, Log, TEXT("Calling Process Ready"));
    gameLiftSdkModule->ProcessReady(m_params);
}

Build game project for both of the following target types: Development Editor and Development Server.

Once both builds are complete, close Visual Studio and open your project's .uproject file to open it in the Unreal Editor.

In Unreal Editor, package the server build of your game. To choose a target, go to Platforms, Windows and select Your-application-nameServer.

To start the process of building the server application, go to Platforms, Windows and select Package Project. When the build is complete, you should have an executable. In the case of our example, the file name is GameLiftUnrealAppServer.exe.

Building a server application in Unreal Editor produces two executables. One is located in the root of the game build folder and acts as a wrapper for the actual server executable.

When creating an Amazon GameLift fleet with your server build, we recommend that you pass in the actual server executable as the runtime configuration launch path. For example, in your game build folder, you might have a GameLiftFPS.exe file at the root and another at \GameLiftFPS\Binaries\Win64\GameLiftFPSServer.exe. When creating a fleet, we recommend you use C:\GameLiftFPS\Binaries\Win64\GameLiftFPSServer.exe as the launch path of the runtime configuration.

Make sure to open the necessary UDP ports on the Amazon GameLift fleet, so that the game server can communicate with game clients. By default, Unreal Engine uses port 7777. For more information, see UpdateFleetPortSettings in the Amazon GameLift service API reference guide.

Create an install.bat file for your game build. This install script runs whenever the game build is deployed to a Amazon GameLift fleet. Here's an example install.bat file:

VC_redist.x64.exe /q
UE5PrereqSetup_x64.exe /q

For some versions of Unreal Engine, the install.bat should instead be

VC_redist.x64.exe /q
UEPrereqSetup_x64.exe /q

Now you can package and upload your game build to Amazon GameLift.

The version of OpenSSL you package with your game build needs to match the version that the game engine used when building the game server. Make sure you package the correct OpenSSL version with your game server build. For the Windows OS, the OpenSSL format is .dll.