How to Integrate the AWS C++ SDK with Unreal Engine

Game developers increasingly require cloud technologies to support their games and provide the best experience to their players. Leveraging cloud services provided by AWS can help with important game components such as managing and deploying game servers, running analytics on various game metrics, and utilizing AI/ML to detect player health and retention. Creating and maintaining all of these systems from scratch can take crucial developer time away from building those fun, innovative gaming experiences that can satisfy and delight players.

For game development, it is important to be able to use AWS with popular game engines such as Unreal Engine. Unreal Engine (UE) is an advanced real-time 3D creation tool for photorealistic visuals and immersive experiences. It has become one of the most widely used engines due to its high graphical fidelity and developer features, making it a popular choice for games as well as other industries such as architecture, film & television, broadcast, live events, animation, & more.

To use AWS services within a game engine such as Unreal Engine, you can use the AWS Software Development Kits (SDKs). The AWS SDK is an easy way to programmatically access your AWS account and its services. It’s used widely by developers to access resources in AWS through their code. Since Unreal Engine scripting is done in C++, we would need the C++ version of the AWS SDK. Additionally, we want to encapsulate it inside an Unreal Engine plugin so that it’s portable to other projects if needed. This blog post will guide you through integrating the AWS C++ SDK with Unreal Engine as a plugin.

Requirements and Recommendations

• An AWS account
• Git (for vcpkg only)
• Recommended: Unreal Engine 4.27 or greater (including UE5)
  This method has not been validated for lower versions, but should work the same.
• Recommended: Visual Studio 2019 (Visual Studio 2022 should also work)
• Recommended: Windows 10 or higher (I will show commands and code designed for the Windows platform. Other platforms will work with this method, but will require some tweaking of the code and commands shown)
• Some prior experience in C++ and Unreal Engine

Visual Studio Setup

When installing or modifying Visual Studio. Make sure you install both the “Desktop development with C++” workload and “Game development with C++“ workload like so:

Under “Individual Components” make sure you have installed .NET Core 3.1 (this specific version) and the latest .NET Framework in Visual Studio (any version above 4.6 is fine):

For more information on how to modify your Visual Studio installation see this documentation from Microsoft: https://docs.microsoft.com/en-us/visualstudio/install/modify-visual-studio?view=vs-2022

Compiling AWS C++ SDK

There are two ways to acquire the AWS SDK for use in Unreal Engine. You can build it from source on your own by downloading the source code from our Github repository or use a package manager like vcpkg. For this guide I’ll be using vcpkg to install the SDK packages.

• Open a command prompt or terminal in your working directory.
• Clone the vcpkg repository by running git clone https://github.com/microsoft/vcpkg
• Run the bootstrap script to build vcpkg: .\vcpkg\bootstrap-vcpkg.bat (for Windows)
  ./vcpkg/bootstrap-vcpkg.sh if you’re on Linux or MacOS

• Navigate to the vcpkg directory and run this command to install packages with vcpkg: .\vcpkg install aws-sdk-cpp[core,kinesis,cognito-identity]:x64-windows --recurse. Put whatever service SDKs you want to install in the [ brackets ]. Make sure to at least install the SDK Core (ie “core”). Additionally, don’t forget to specify the platform you’re on. x64-windows/x64-linux/x64-osx for 64-bit Windows, Linux, and MacOS respectively.
  • In this tutorial, I’ll be installing the core, kinesis, and cognito-identity SDKs on 64-bit Windows
  • If you’re running into an error here, make sure you’re in the vcpkg directory when you run the command
• The above command will install the specific service SDKs you need as well as any dependencies. After it’s finished running (this will take a few minutes) go into vcpkg/installed/[platform] and take note of these folders:
  • bin/ folder has the dynamic libraries (.dll files)
  • lib/ has the static libraries (.lib files)
  • include/ folder has the header files (.h files)
  • Keep these in mind for later

Creating a Plugin from the SDK

In this section, I’ll be placing the AWS SDK inside of a module that is housed in a plugin. Unreal Engine modules are like the building blocks of your project and can contain code or external dependencies (like an SDK). A plugin is a portable container for modules and other content that is easily transferrable to other projects.

Read more about modules and plugins in the Unreal documentation.

Setup

Before we begin, ensure that your project is a C++ project not a Blueprint-only project. You can change this when creating the project like this:

(For reference, my project directory is D:\Epic\Unreal Projects\ExampleProject\)

Steps

• Open your Unreal Engine project and open Edit > Plugins on the top left. Create a new blank plugin and name it whatever you like (I named it AWSPlugin below).

• Navigate to the newly created Plugin folder. Under Source/ create a new folder to house the AWS SDK. Again, name this whatever you like, but keep the name distinct from the plugin name. This will be our SDK module folder. (If you do not see the source folder, then your project is a blueprint-only project or you’ve created a content-only plugin. This will only work for C++ projects)
• Add folders for libraries and the header files. I’ve named them Binaries/ and Include/ respectively. Add a file called [MODULE_NAME].Build.cs. The module name is the same as the folder name (in this case AWSSDK).

• Copy over the header files from the vcpkg include/ folder earlier into the new include/ folder. This will provide a central location for your code to reference header files.
• Put static and dynamic libraries (.lib and .dll files) in your platform’s folder under Binaries/. If you remember, these files will come from the bin/ and lib/ folders from the vcpkg installation.

• Fill your [MODULE_NAME].Build.cs file with code similar to below:

AWSSDK.Build.cs

using System;
using System.Collections.Generic;
using System.IO;
using UnrealBuildTool;

public class AWSSDK : ModuleRules
{
    // list every library you plan to use here
    private List<string> LibraryNames = new List<string>()
    {
        "aws-c-auth",
        "aws-c-cal",
        "aws-c-common",
        "aws-c-compression",
        "aws-c-event-stream",
        "aws-checksums",
        "aws-c-http",
        "aws-c-io",
        "aws-c-mqtt",
        "aws-cpp-sdk-access-management",
        "aws-cpp-sdk-cognito-identity",
        "aws-cpp-sdk-core",
        "aws-cpp-sdk-iam",
        "aws-cpp-sdk-kinesis",
        "aws-crt-cpp",
        "aws-c-s3",
    };

    public AWSSDK(ReadOnlyTargetRules Target) : base(Target)
    {
        // ModuleType.External tells the engine not to look for (or compile) any source code.
        Type = ModuleType.External;
        PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs;

        // add the header files for reference
        PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Include"));

        // AWS SDK relies on certain identifiers being undefined, so this produces warnings
        // Unreal engine treats certain warnings as errors and fails the build
        // this line will disable those warnings:
        bEnableUndefinedIdentifierWarnings = false;

        // Dynamically linking to the SDK requires us to define the
        // USE_IMPORT_EXPORT symbol for all build targets using the
        // SDK. Source: https://github.com/aws/aws-sdk-cpp/blob/main/Docs/SDK_usage_guide.md#build-defines
        PublicDefinitions.Add("USE_IMPORT_EXPORT");
        PublicDefinitions.Add("AWS_CRT_CPP_USE_IMPORT_EXPORT");


        if (Target.Platform == UnrealTargetPlatform.Win64)
        {
            PublicDefinitions.Add("USE_WINDOWS_DLL_SEMANTICS");
        }

        // do this for each lib and dll
        foreach (string libName in LibraryNames)
        {
            string LibraryPath = Path.Combine(ModuleDirectory, "Binaries", Target.Platform.ToString());
            // add a new section for each platform you plan to compile for (only Win64 is included for this example)
            if (Target.Platform == UnrealTargetPlatform.Win64)
            {
                PublicAdditionalLibraries.Add(Path.Combine(LibraryPath, libName + ".lib"));
                // Stage the library along with the target, so it can be loaded at runtime.
                RuntimeDependencies.Add("$(BinaryOutputDir)/" + libName + ".dll", Path.Combine(LibraryPath, libName + ".dll"));
            }
            else if (Target.Platform == UnrealTargetPlatform.Mac)
            {
                // add mac libraries
            }
            else if (Target.Platform == UnrealTargetPlatform.Linux)
            {
                // add linux libraries
            }
        }

        PrivateDependencyModuleNames.AddRange(
        new string[] {
                    "CoreUObject",
                    "Engine",
                    "Slate",
                    "SlateCore",   
        });
    }
}

(This build file was created using guidance from Ambit Scenario Designer Plugin for Unreal Engine. For more details, check out the Ambit source code)

• Navigate to your Project’s Build.cs file (should be in a location like: [ProjectName]\Source\[ProjectName]\[ProjectName].Build.cs). Add the AWS SDK Module you created earlier as a dependency (You will see below I added “AWSSDK” in the list) and add the bEnableUndefinedIdentifierWarnings = false; line.

ExampleProject.Build.cs

PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "AWSSDK" });
//...
bEnableUndefinedIdentifierWarnings = false;

(bEnableUndefinedIdentifierWarnings = false is necessary to get the build working. The AWS C++ SDK naturally generates warnings which will cause Unreal to fail builds, but that’s nothing to worry about)

• Navigate back to your project’s root directory and right click the .uproject file. Click on Generate Visual Studio project files and wait for it to finish. Once that is completed, open Visual Studio and click Reload All to register the new files in the editor.

• If you did everything correctly, it will compile successfully in both Visual Studio and Unreal Engine.

Testing

Create a new C++ Actor in any module where you included the AWSSDK module as a dependency (in the above step, we added it to the main project module).

• Create a “New C++ Class” in the Content Browser tab

• Select Actor

• Name it and select the module to deploy it into (I’ve created it in the ExampleProject main module)

• Add the following code in the BeginPlay function of the Actor:

MyActor.cpp

#include "MyActor.h"
#include <aws/core/Aws.h>
// ...
void MyActor::BeginPlay()
{
    Aws::SDKOptions options;
    Aws::InitAPI(options);
    // do something with API
    Aws::ShutdownAPI(options);
    return 0;
}
// ...

• Drag the actor into the level viewport and click Play:

To expand on the actor code refer to the basic SDK use here.

Note: To actually use any service in your AWS account, you will require some form of authentication. You can follow the instructions here to add a credentials file where AWS can use it or generate credentials at runtime with an identity provider like Amazon Cognito. Make sure that if you include a credentials file, it is for development only and not a production environment. NEVER share your AWS credentials. Keep in mind that, while possible to integrate the SDK directly with the game client and is a pattern that is done by developers, a security best practice is to have a layer of indirection between your game client and AWS. To learn more about this, read this blog.

Troubleshooting

• Make sure to generate VS project files after you add any new files or modify any XXX.Build.cs files
• There is an issue in UE5 live coding that affects compilations. Disable live coding and compile through Visual Studio if you’re having trouble compiling in Unreal Engine 5
• Error C4668: '_______' is not defined as a preprocessor macro, replacing with '0' for '#if/#elif' — The AWS C++ SDK naturally produces these warnings, which Unreal treats as errors and refuses to compile. This is normal and not a sign of anything wrong. Make sure to include this line in your Build.cs files to fix this: bEnableUndefinedIdentifierWarnings = false;

Conclusion

At this point you should have successfully integrated the AWS C++ SDK with Unreal Engine and you can begin using AWS services in your games! For continued learning and reference material, see these additional resources below:

• Providing credentials to the SDK
• Using the AWS C++ SDK
• SDK API Reference
• Third Party Libraries | Unreal Documentation