C++ Setup

This page is in the process of being updated.

In order to get started with C++ modding, you should first begin by performing the setup the project for a Blueprint-based modding project, as shown in the Getting Started guide. This guide assumes that you have already installed all required dependencies and followed the setup process described there.

Background Information

To build C++ code, Unreal uses its own written build pipeline called the "Unreal Build Tool" (aka. UBT). The UBT then does the job of copying files, running the "Unreal Header Tool" (UHT), and building for the desired platform automatically. The UHT is a tool which analyzes the source code you have written and replaces specific macros, like the UFUNCTION-Macro, with automatically generated code. It also generates separate files containing even more additional automatically generated code for you.

The UBT will run in the "Development Editor" configuration automatically when you open the .uproject file in the editor or when you run a build in the Visual Studio solution file.

UBT uses multiple files placed into your source code for configuration of the source component you make. An overview of these files is provided below.

Targets

Targets are UBTs "programs" that you write. Most of the time, like in our modding case, there are two targets. One target is for compiling our modules compatible with the Unreal Editor, and the second target is for compiling our modules compatible with the final game. The configuration files for these modules will be located in the /Source/YourModReference folder of your mod. The target configurations follow the <ModuleName>.Target.cs naming pattern for the "shipping" configuration and the <ModuleName>Editor.Target.cs naming pattern for the "development editor" configuration.

Modules

Modules are UBTs components of programs. Each target depends on at least one module. A module can be a library, Unreal Engine itself, plugins, the headers of Satisfactory, or your mod code. Most modules are located within their own folders in the /Source folder of the project.

For example, the Satisfactory headers used to reference functions and data structures are contained in the "FactoryGame" module located under /Source/FactoryGame. Each module folder then has again a configuration file in its root folder. For the "FactoryGame" module, this will be the file /Source/FactoryGame/FactoryGame.Build.cs.

Module configuration files allow for writing custom code to control how your module is compiled. Unreal uses C# to implement this configuration system.

Example uses cases include:

Specifying dependencies to Satisfactory, Unreal Engine, or third-party code
Doing defines for public/private build based on env vars
Adding external .lib files
Calculating information (such as build ID) from the state of the file system

Using the Alpakit Template

The Alpakit Create Mod wizard contains a template that creates most of the files mentioned in the below sections automatically. You can learn more about the wizard on the Plugin Setup and Game World Module page.

Creating the Mod-Module From Scratch

To begin adding C++ code to your mod you’ll have to create a Module build configuration file.

Navigate to your mod’s folder, Mods/YourModReference/, where your 'YourModReference.uplugin' file is located. Create a new folder named Source and within it a subfolder named YourModReference. As a reminder, the concept of a mod reference is explained here. Within this folder, you should create a new file called YourModReference.Build.cs. You can do this by creating a new text file and then changing the extension to a .cs file, for example. If you chose to create the file in this manner, we suggest you turn on showing file name extensions to assist with this.

Within this new file you will need to add the following configuration text.

Make sure to replace all instances of YourModReference with your actual mod reference.

The latest version of this template can be found in the Starter Project Repository as an Alpakit template.

using UnrealBuildTool;
using System.IO;
using System;

public class YourModReference : ModuleRules
{
	public YourModReference(ReadOnlyTargetRules Target) : base(Target)
	{
		PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

		// FactoryGame transitive dependencies
		// Not all of these are required, but including the extra ones saves you from having to add them later.
		// Some entries are commented out to avoid compile-time warnings about depending on a module that you don't explicitly depend on.
		// You can uncomment these as necessary when your code actually needs to use them.
		PublicDependencyModuleNames.AddRange(new string[] {
			"Core", "CoreUObject",
			"Engine",
			"DeveloperSettings",
			"PhysicsCore",
			"InputCore",
			//"OnlineSubsystem", "OnlineSubsystemUtils", "OnlineSubsystemNull",
			//"SignificanceManager",
			"GeometryCollectionEngine",
			//"ChaosVehiclesCore", "ChaosVehicles", "ChaosSolverEngine",
			"AnimGraphRuntime",
			//"AkAudio",
			"AssetRegistry",
			"NavigationSystem",
			//"ReplicationGraph",
			"AIModule",
			"GameplayTasks",
			"SlateCore", "Slate", "UMG",
			//"InstancedSplines",
			"RenderCore",
			"CinematicCamera",
			"Foliage",
			//"Niagara",
			//"EnhancedInput",
			//"GameplayCameras",
			//"TemplateSequence",
			"NetCore",
			"GameplayTags",
			"Json", "JsonUtilities",
			"AssetRegistry"
		});

		// FactoryGame plugins
		PublicDependencyModuleNames.AddRange(new string[] {
			//"AbstractInstance",
			//"InstancedSplinesComponent",
			//"SignificanceISPC"
		});

		// Header stubs
		PublicDependencyModuleNames.AddRange(new string[] {
			"DummyHeaders",
		});

		if (Target.Type == TargetRules.TargetType.Editor) {
			PublicDependencyModuleNames.AddRange(new string[] {/*"OnlineBlueprintSupport",*/ "AnimGraph"});
		}
		PublicDependencyModuleNames.AddRange(new string[] {"FactoryGame", "SML"});

		PublicIncludePaths.AddRange(new string[] {
			// ... add public include paths required here ...
		});

		PrivateIncludePaths.AddRange(new string[] {
			// ... add private include paths required here ...
		});

		PublicDependencyModuleNames.AddRange(new string[] {
			// ... add public dependencies that you statically link with here ...
		});

		PrivateDependencyModuleNames.AddRange(new string[] {
			// ... add private dependencies that you statically link with here ...
		});

		DynamicallyLoadedModuleNames.AddRange(new string[] {
			// ... add any modules that your module loads dynamically here ...
		});
	}
}

Note that the file we just created is a C# file (.cs) and not a C++ file (.cpp).

This configuration will add the basic Unreal Engine framework, Satisfactory, and the Mod Loader as dependencies to your module, in addition to setting up some other useful stuff for you.

It’s important to note that this example lists more PublicDependencyModuleNames than are required bare minimum. They are included "just in case" - without them, if you were to include a FG header that happens to use one of those, you would get a confusing error because module dependencies are not transitive. Upon encountering that error you would need to add the module containing the mentioned header to this file, but the error message contains no indication of what that Module Name you need to add is.

You can come back to this configuration file later and change things here if needed.

It’s now time to get started adding the module source code.

Do this by creating a file called <your mod reference>Module.h and fill it with this template. Replace <mod reference> with your actual mod reference. Remember to replace all instances of YourModReference with your actual mod reference. Don’t keep the `<>`s.

#pragma once

#include "Modules/ModuleManager.h"

class FYourModReferenceModule : public FDefaultGameModuleImpl {
public:
	virtual void StartupModule() override;
};

Next up we need another new file called YourModReferenceModule.cpp. Go ahead and fill it with the following template code. Again, replace YourModReference with your actual mod reference.

#include "YourModReferenceModule.h"

void F<mod reference>Module::StartupModule() {

}

IMPLEMENT_GAME_MODULE(FYourModReferenceModule, YourModReference);

Adding the Module to the UPlugin

Next we need to tell the Unreal Editor to use our editor module. For this open up the YourModReference.uplugin file in your plugin root. Add the Modules array in the root json, then add your module with your mod_reference as name, Runtime as Type and Default as LoadingPhase. Like this:

"Modules": [
        {
            "Name": "YourModReference",
            "Type": "Runtime",
            "LoadingPhase": "Default"
        }
    ]

(the name used was YourModReference, make sure you use your own mod reference instead)

Finishing Up

Now that you have added your module folder, configuration, source, and added it to the targets, you will need to regenerate your Visual Studio project files. Directions on how to do this can be found here.

After this process completes, you should be able to start working on the C++ code for your mod.

Make always sure you code in a custom created module! Don’t write your code in the FactoryGame or SML modules by accident.

Adding a Class

When you want to add a new class, there are two generally safe ways to go about it. Note that you should not create new files from Visual Studio directly - it is not knowledgeable about the project structure and will create files in a temporary directory where they won’t be detected by UBT.

Navigate to the folder in which you want to add your class in Windows Explorer and create the .cpp-File and the .h-File manually. You can now open them in Visual Studio or a text editor of your choice. Fill them with a template code or just directly the class you need.
Open the Unreal editor and open the "tree view" of the content browser. Then navigate to the C++-Classes root folder and open the folder named with your mod reference. Within that folder, right-click into empty space and select New C++-Class. Then select your desired base class, hit next, and name your class. Change the other settings as your desire and finish with create class.

Make sure you select your custom C++-module when using the Unreal editor method of creating a new class file. In this screenshot, the mod reference is 'LightItUp'.