Integrate Amazon GameLift into an Unreal Engine project
This topic explains how to set up the Amazon GameLift C++ server SDK for Unreal Engine and integrate it into your game projects.
Tip
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
Note
If you haven't already done so, follow the instructions at Accessing Unreal Engine source
code on GitHub
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 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 theUE5.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 justUE5
), 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 Amazon GameLift server SDK 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.
-
Create a new project. To experiment with the Amazon GameLift server SDK, 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.csFor example:
GameLiftUnrealApp.Target.cs
.Make a copy of this file and name the copy:
.Your-application-name
Server.Target.csOpen the new file and make the following changes:
Change the
class
andconstructor
to match the filename.Change the
Type
fromTargetType.Game
toTargetType.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 Amazon GameLift server SDK.
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 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 Amazon GameLift server SDK 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-
directory in the downloaded SDK, then follow the steps for your platform:<version>
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 Amazon GameLift server SDK into your example project.
Import the Amazon GameLift server SDK
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 thePlugins
.This will allow the Unreal project to see the server SDK.
-
Add the Amazon GameLift server SDK to the game's
.uproject
file.In the example, the app is called
GameLiftUnrealApp
, so the file will beGameLiftUnrealApp.uproject
. -
Edit the
.uproject
file to add the server SDK to your game project."Plugins": [ { "Name": "GameLiftServerSDK", "Enabled": true } ]
Make sure the game's ModuleRules takes a dependency on the server SDK. 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 ofPublicDependencyModuleNames
.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 functionality into your game.
Add Amazon GameLift server code to your Unreal project
The server SDK is now ready to use, but you haven't written code to use it. To get
started, use the existing GameMode
files included with the Unreal
Engine example project. The following code examples include modified
GameMode.h
and GameMode.cpp
files.
GameMode.h
// Copyright Epic Games, Inc. All Rights Reserved. #pragma once #include "CoreMinimal.h" #include "GameFramework/GameModeBase.h" #include "GameLift426TestGameMode.generated.h" DECLARE_LOG_CATEGORY_EXTERN(GameServerLog, Log, All); UCLASS(minimalapi) class AGameLift426TestGameMode : public AGameModeBase { GENERATED_BODY() public: AGameLift426TestGameMode(); protected: virtual void BeginPlay() override; private: void InitGameLift(); };
GameMode.cpp
// Copyright Epic Games, Inc. All Rights Reserved. #include "GameLift426TestGameMode.h" #include "GameLift426TestCharacter.h" #include "UObject/ConstructorHelpers.h" #include "GameLiftServerSDK.h" DEFINE_LOG_CATEGORY(GameServerLog); AGameLift426TestGameMode::AGameLift426TestGameMode() { UE_LOG(LogInit, Log, TEXT("Game Mode Constructor")); // set default pawn class to our Blueprinted character static ConstructorHelpers::FClassFinder<APawn> PlayerPawnBPClass(TEXT("/Game/ThirdPersonCPP/Blueprints/ThirdPersonCharacter")); if (PlayerPawnBPClass.Class != NULL) { DefaultPawnClass = PlayerPawnBPClass.Class; } } void AGameLift426TestGameMode::BeginPlay() { #if WITH_GAMELIFT InitGameLift(); #endif } void AGameLift426TestGameMode::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 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 ID 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 EC2 or 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 will establish a local connection with GameLift's agent to enable further communication. gameLiftSdkModule->InitSDK(serverParameters); //When a game session is created, GameLift sends an activation request to the game server and passes along the game session object containing game properties and other settings. //Here is where a game server should take action based on the game session object. //Once the game server is ready to receive incoming player connections, it should invoke GameLiftServerAPI.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(); }; FProcessParameters params; params.OnStartGameSession.BindLambda(onGameSession); //OnProcessTerminate callback. GameLift will invoke this callback before shutting down an instance hosting this game server. //It gives this game server a chance to save its state, communicate with services, etc., before being shut down. //In this case, we simply tell GameLift we are indeed going to shutdown. params.OnTerminate.BindLambda([=]() { UE_LOG(GameServerLog, Log, TEXT("Game Server Process is terminating")); gameLiftSdkModule->ProcessEnding(); }); //This is the HealthCheck callback. //GameLift will invoke this callback every 60 seconds or so. //Here, a game server might want to check the health of dependencies and such. //Simply return true if healthy, false otherwise. //The game server has 60 seconds to respond with its health status. GameLift will default to 'false' if the game server doesn't respond in time. //In this case, we're always healthy! params.OnHealthCheck.BindLambda([]() { UE_LOG(GameServerLog, Log, TEXT("Performing Health Check")); return true; }); //This game server tells GameLift that it will listen on port 7777 for incoming player connections. params.port = 7777; //Here, the game server tells GameLift what set of files to upload when the game session ends. //GameLift will upload everything specified here for the developers to fetch later. TArray<FString> logfiles; logfiles.Add(TEXT("GameLift426Test/Saved/Logs/GameLift426Test.log")); params.logParameters = logfiles; //Calling ProcessReady tells GameLift this game server is ready to receive incoming game sessions! UE_LOG(GameServerLog, Log, TEXT("Calling Process Ready")); gameLiftSdkModule->ProcessReady(params); }
To build your game server
When you've finished adding server SDK code to your project, take the following steps to create a game server build and upload it to Amazon GameLift for hosting.
-
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. -
When 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 have an executable, such as
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 useC:\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. -
On Windows: Create an
file for your game build. This install script runs whenever the game build is deployed to a Amazon GameLift fleet. Here's an exampleinstall.bat
install.bat
file:VC_redist.x64.exe /q UE5PrereqSetup_x64.exe /q
-
Now you can package and upload your game build to Amazon GameLift.
The version of OpenSSL you use for your build needs to match the version used by 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 use the DLL/SOs for the same version as you used when you build the game server.
-
libssl-3-x64.dll
(Windows) orlibssl.so.1.1
(Linux) -
libcrypto-3-x64.dll
(Windows) orlibcrypto.so.1.1
(Linux)
Package your dependencies along with your game server executable in 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 into your game.
For more information about adding Amazon GameLift to your game, see the following:
For instructions about testing your game, see Test your integration using Amazon GameLift Local.