Prerequisites Build Unreal Engine from source Configure your project for the server SDK Add server code to your project Next steps

Integrate Amazon GameLift Servers into an Unreal Engine project

This topic explains how to set up the Amazon GameLift Servers C++ server SDK for Unreal Engine and integrate it into your game projects.

Tip

Get a jump start on deploying your game server to Amazon GameLift Servers for hosting. With the Amazon GameLift Servers standalone plugin for Unreal Engine, you can integrate your game code, deploy simple but complete hosting solutions, and test your game components in action. See Amazon GameLift Servers plugin for Unreal Engine.

Additional resources:

Prerequisites

Before you procced, make sure you have the following prerequisites:

Prerequisites

A computer capable of running Unreal Engine. For more information on Unreal Engine requirements, see Unreal Engine's Hardware and Software Specifications documentation.
Microsoft Visual Studio 2019 or newer version.
CMake version 3.1 or later.
Python version 3.6 or later.
A Git client available on the PATH.
An Epic games account. Sign up for an account at the official Unreal Engine website.
A GitHub account associated with your Unreal Engine account. For more information, see Accessing Unreal Engine source code on GitHub on the Unreal Engine website.

Build Unreal Engine from source

Standard versions of the Unreal Engine editor, downloaded through the Epic launcher, only allow Unreal client application builds. In order to build an Unreal server application, you need to download and build Unreal Engine from source, using the Unreal Engine Github repo. For more information, see the Building Unreal Engine from Source tutorial on the Unreal Engine documentation website.

Note

If you haven't already done so, follow the instructions at Accessing Unreal Engine source code on GitHub to link your GitHub account to your Epic Games account.

To clone the Unreal Engine source to your development environment

Clone the Unreal Engine source to your development environment in a branch of your choice.
```
git clone https://github.com/EpicGames/UnrealEngine.git
```
Get the Unreal Engine version that's supported by the Amazon GameLift Servers plugin. See For game servers for Unreal version support.

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.

Note
The build can take over an hour to complete.

Once the build is complete, you are ready to open the Unreal Development Editor and create or import a project.

Configure your Unreal project for the server SDK

Follow these steps to get the server SDK for Amazon GameLift Servers for Unreal Engine ready for your game server projects.

To configure your project for the server SDK

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 Servers.
- Create a new project. To experiment with the server SDK for Amazon GameLift Servers, 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:

Change the class and constructor to match the filename.
Change the Type from TargetType.Game to TargetType.Server.

The final file will look like the following example:


   public class GameLiftUnrealAppServerTarget : TargetRules
    {  
        public GameLiftUnrealAppServerTarget(TargetInfo Target) : base(Target)
        {
            Type = TargetType.Server;
            DefaultBuildSettings = BuildSettingsVersion.V2;
            IncludeOrderVersion = EngineIncludeOrderVersion.Unreal5_1;
            ExtraModuleNames.Add("GameLiftUnrealApp");
        }
    }

Your project is now configured to use the server SDK for Amazon GameLift Servers.

The next task is to build the C++ server SDK libraries for Unreal so that you can import them into your project.

To build the C++ server SDK libraries for Unreal

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

Note
Putting the SDK in the default download directory can result in build failure due to the path exceeding the 260 character limit. For example: C:\Users\Administrator\Downloads\GameLift-SDK-Release-06_15_2023\GameLift-Cpp-ServerSDK-5.0.4
We recommend that you move the SDK to another directory, for example C:\GameLift-Cpp-ServerSDK-5.0.4.
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.

Note
The version of OpenSSL that you use to build the server SDK for Amazon GameLift Servers should match the version of OpenSSL used by Unreal to package your game server. You can find version information in the Unreal installation directory ...Engine\Source\ThirdParty\OpenSSL.
With the libraries downloaded, build the C++ server SDK libraries for Unreal Engine.

Navigate to the GameLift-Cpp-ServerSDK-<version> directory in the downloaded SDK, then follow the steps for your platform:
Linux
For a quick and easy automated build for Amazon Linux compatible binaries and OpenSSL and OpenCrypto dependencies, see the Building the server SDK for Amazon GameLift Servers for Unreal Engine 5 on Amazon Linux.

If you want to do this manually instead, follow the steps here. This method expects that the correct OpenSSL version that matches your Unreal Engine is configured in your Linux environment, and the OpenSSL and OpenCrypto libraries have been copied to your server build.
Run the following commands:

mkdir out cd out cmake -DBUILD_FOR_UNREAL=1 .. make

This builds the file:

prefix/lib/aws-cpp-sdk-gamelift-server.so

Copy the file that was built to this location in the Unreal plugin folder:

GameLiftPlugin/Source/GameLiftServer/ThirdParty/GameLiftServerSDK/Linux/x86_64-unknown-linux-gnu/

Once complete, verify that you have a filepath similar to this example:

GameLiftPlugin/Source/GameLiftServer/ThirdParty/GameLiftServerSDK/Linux/x86_64-unknown-linux-gnu/aws-cpp-sdk-gamelift-server.so
Windows
Run the following commands:

mkdir out cd out cmake -G "Visual Studio 17 2022" -DBUILD_FOR_UNREAL=1 .. msbuild ALL_BUILD.vcxproj /p:Configuration=Release

This produces the following binary files required by the server SDK:

prefix\bin\aws-cpp-sdk-gamelift-server.dll prefix\lib\aws-cpp-sdk-gamelift-server.lib

Copy the files that were built to this location in the Unreal plugin folder:

GameLiftPlugin\Source\GameLiftServer\ThirdParty\GameLiftServerSDK\Win64\

Once complete, verify that you have two filepaths similar to this example:

GameLiftPlugin\Source\GameLiftServer\ThirdParty\GameLiftServerSDK\Win64\aws-cpp-sdk-gamelift-server.dll GameLiftPlugin\Source\GameLiftServer\ThirdParty\GameLiftServerSDK\Win64\aws-cpp-sdk-gamelift-server.lib
Cross Compile from Windows to Linux
Follow the steps in Building the server SDK for Amazon GameLift Servers for Unreal Engine 5 on Amazon Linux to download a Linux build of the C++ Server SDK libaws-cpp-sdk-gamelift-server.so. The download bundle also includes the files libcrypto.so-.1.1 and libssl.so.1.1 that will be used in later steps after you package the Unreal Project.

Copy the file libaws-cpp-sdk-gamelift-server.so to the amazon-gamelift-plugin-unreal/GameLiftPlugin/Source/GameliftServer/ThirdParty/GameLiftServerSDK/Linux/x86_64-unknown-linux-gnu/ folder inside the Amazon GameLift Servers Unreal plugin foleder in your project.
For more detailed instructions on how to build the C++ SDK, refer to the README.md file located in the C++ SDK directory.

Use the following procedure to import the server SDK for Amazon GameLift Servers into your example project.

Import the server SDK for Amazon GameLift Servers

Locate the GameLiftServerSDK folder that you extracted from the download 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 server SDK.
Add the server SDK for Amazon GameLift Servers 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 server SDK to your game project.


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

Make sure the game's ModuleRules takes a dependency on the server SDK. Open the .Build.cs file and add the Amazon GameLift ServersServerSDK 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;
    }
  }

The server SDK should now be working for your application. Continue with the next section to integrate Amazon GameLift Servers functionality into your game.

Add Amazon GameLift Servers server code to your Unreal project

You've configured and set up your Unreal Engine environment, and you can now integrate a game server with Amazon GameLift Servers. The code presented in this topic makes required calls to the Amazon GameLift Servers service. It also implements a set of callback functions that respond to requests from the Amazon GameLift Servers service. 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 uised in this code, see C++ (Unreal) server SDK 5.x for Amazon GameLift Servers -- Actions.

To initialize a game server with Amazon GameLift Servers, use the following procedure.

Note

The Amazon GameLift Servers-specific code provided in the following section depends on the use of a WITH_GAMELIFT preprocessor flag. This flag is true only when both of these conditions are met:

Target.Type == TargetRules.TargetType.Server
The game project recognizese the server SDK for Amazon GameLift Servers binaries.

This ensures that only Unreal server builds invoke Amazon GameLift Servers's backend API. It also lets you to write code that will execute properly for all the different Unreal targets your game might produce.

Integrate a game server with Amazon GameLift Servers

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 Servers, as described in Add Amazon GameLift Servers to your game server. This includes:

Initializing an Amazon GameLift Servers API client.
Implementing callback functions to respond to requests from the Amazon GameLift Servers service, including OnStartGameSession, OnProcessTerminate, and onHealthCheck.
Calling ProcessReady() with a designated port to notify the Amazon GameLift Serversservice when ready to host game sessions.


#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 an Amazon GameLift Servers Anywhere fleet. These are not needed for an Amazon GameLift Servers 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)
    }

    if (FParse::Value(FCommandLine::Get(), TEXT("-awsregion="), serverParameters.m_awsRegion))
    {
        UE_LOG(GameServerLog, Log, TEXT("AWS_REGION: %s"), *serverParameters.m_awsRegion)
    }


    if (FParse::Value(FCommandLine::Get(), TEXT("-accesskey="), serverParameters.m_accessKey))
    {
        UE_LOG(GameServerLog, Log, TEXT("ACCESS_KEY: %s"), *serverParameters.m_accessKey)
    }
    if (FParse::Value(FCommandLine::Get(), TEXT("-secretkey="), serverParameters.m_secretKey))
    {
        UE_LOG(GameServerLog, Log, TEXT("SECRET_KEY: % s"), *serverParameters.m_secretKey)
    }
    if (FParse::Value(FCommandLine::Get(), TEXT("-sessiontoken="), serverParameters.m_sessionToken))
    {
        UE_LOG(GameServerLog, Log, TEXT("SESSION_TOKEN: %s"), *serverParameters.m_sessionToken)
    }

    //The Host/compute-name of the Amazon GameLift Servers 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)
    }



    FString glProcessId = "";
    if (FParse::Value(FCommandLine::Get(), TEXT("-processId="), glProcessId))
    {
        serverParameters.m_processId = TCHAR_TO_UTF8(*glProcessId);
    }
    else
    {
        // If no ProcessId is passed as a command line argument, generate a randomized unique string.
        FString TimeString = FString::FromInt(std::time(nullptr));
        FString ProcessId = "ProcessId_" + TimeString;
        serverParameters.m_processId = TCHAR_TO_UTF8(*ProcessId);
    }

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

    //InitSDK establishes a local connection with the Amazon GameLift Servers Agent to enable further communication.
    //Use InitSDK(serverParameters) for an Amazon GameLift Servers Anywhere fleet. 
    //Use InitSDK() for Amazon GameLift Servers managed EC2 fleet.
    gameLiftSdkModule->InitSDK(serverParameters);

    //Implement callback function onStartGameSession
    //Amazon GameLift Servers 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
    //Amazon GameLift Servers 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 Amazon GameLift Servers 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
    //Amazon GameLift Servers 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 Amazon GameLift Servers 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 Amazon GameLift Servers where to find game session log files.
    //At the end of a game session, Amazon GameLift Servers 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 Amazon GameLift Servers 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.

Note
You don't need to rebuild the solution. Instead, build just the project under the Games folder that matches the name of your app. Otherwise Visual Studio rebuilds the entire UE5 project, which might take up to an hour.
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 Servers 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 Servers 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 service API reference guide for Amazon GameLift Servers.
On Windows: Create an install.bat file for your game build. This install script runs whenever the game build is deployed to a Amazon GameLift Servers 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
```
Note
The file path to the <>PrereqSetup_x64.exe file is Engine\Extras\Redist\en-us.
Now you can package and upload your game build to Amazon GameLift Servers.

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.
Note
Package the OpenSSL DLL/SO files in your game server build. Be sure to package the same version of OpenSSL that you used when building the game server.
- libssl-1_1-x64.dll (Windows) or libssl.so.1.1 (Linux)
  
  libcrypto-1_1-x64.dll (Windows) or libcrypto.so.1.1 (Linux)
Package your dependencies along with your game server executable in the root of a zip file. For example, on Windows, openssl-lib dlls should be in the same directory as the .exe file.

Next steps

You've configured and set up your Unreal Engine environment, and you can now start integrating Amazon GameLift Servers into your game.

For more information about adding Amazon GameLift Servers to your game, see the following:

For instructions about testing your game, see Set up local testing with Amazon GameLift Servers Anywhere .

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

O3DE: Add Amazon GameLift Servers to your game

Integration with Unity