ue-module-build-system
Use when writing or fixing Build.cs, Target.cs, .uproject or .uplugin files, creating a module or plugin, or resolving an Unreal build error. Also use when the user mentions 'unresolved external symbol', 'LNK2019', 'cannot open include file', 'C1083', 'MODULENAME_API', 'PublicDependencyModuleNames', 'IWYU', 'PCHUsage', 'IMPLEMENT_MODULE', 'IMPLEMENT_PRIMARY_GAME_MODULE', 'LoadingPhase', 'circular dependency', 'Missing precompiled manifest', 'EngineAssociation', 'IncludeOrderVersion', 'Live Coding'. For UCLASS/UPROPERTY rules see ue-cpp-foundations; for editor modules see ue-editor-tools; for Game Feature plugins see ue-game-features.
quodsoler · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add quodsoler/unreal-engine-skills --skill ue-module-build-systemAbout this skill
name: ue-module-build-system description: "Use when writing or fixing Build.cs, Target.cs, .uproject or .uplugin files, creating a module or plugin, or resolving an Unreal build error. Also use when the user mentions 'unresolved external symbol', 'LNK2019', 'cannot open include file', 'C1083', 'MODULENAME_API', 'PublicDependencyModuleNames', 'IWYU', 'PCHUsage', 'IMPLEMENT_MODULE', 'IMPLEMENT_PRIMARY_GAME_MODULE', 'LoadingPhase', 'circular dependency', 'Missing precompiled manifest', 'EngineAssociation', 'IncludeOrderVersion', 'Live Coding'. For UCLASS/UPROPERTY rules see ue-cpp-foundations; for editor modules see ue-editor-tools; for Game Feature plugins see ue-game-features." metadata: version: "2.0.0" engine: "5.8"
UE Module & Build System
Target engine: UE 5.8. APIs below are verified against the 5.8 headers and UnrealBuildTool sources; older forms are listed under "Deprecated — do not use".
This skill covers UnrealBuildTool (UBT) ModuleRules (*.Build.cs) and TargetRules (*.Target.cs), the .uproject and .uplugin descriptors, module registration (IModuleInterface and IMPLEMENT_MODULE in Modules/ModuleManager.h, module Core), plugin discovery (IPluginManager in Interfaces/IPluginManager.h, module Projects), and the compiler, linker, UHT and UBT errors those files cause.
Context
Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing.
Identify the area from the request and the codebase. Ask only when two plausible readings would produce different code.
| Request is about… | Go to |
|---|---|
Dependencies, include paths, PCH, warnings in an existing Build.cs | Build.cs Anatomy |
Target.cs, BuildSettingsVersion, IncludeOrderVersion, target types | Target.cs |
.uproject, module Type, LoadingPhase, enabling plugins | .uproject File |
Adding a module (IMPLEMENT_MODULE, module interface, StartupModule) | Creating a New Module |
Adding a plugin (.uplugin, runtime + editor modules, dependencies) | Creating a Plugin |
| "Which module do I add to use type X?" | Which Module Provides This Type |
| LNK2019, C1083, UHT, UBT or runtime module-load errors | Resolving Build Errors |
Build.cs Anatomy
Every module has <ModuleName>.Build.cs next to its Public/ and Private/ folders. The class name must equal the module name.
// Source/MyGame/MyGame.Build.cs
using UnrealBuildTool;
public class MyGame : ModuleRules
{
public MyGame(ReadOnlyTargetRules Target) : base(Target)
{
PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
// Types from these modules appear in this module's Public/ headers
PublicDependencyModuleNames.AddRange(new string[]
{
"Core",
"CoreUObject",
"Engine",
"InputCore",
"EnhancedInput",
});
// Used only inside Private/ .cpp files; not re-exported downstream
PrivateDependencyModuleNames.AddRange(new string[]
{
"Slate",
"SlateCore",
"UMG",
});
// Loaded through FModuleManager at runtime, never linked
DynamicallyLoadedModuleNames.Add("OnlineSubsystem");
}
}
Public vs Private Dependencies
| Field | Use when |
|---|---|
PublicDependencyModuleNames | A type from the module appears in one of your Public/ headers (base class, member, parameter, return type, UPROPERTY). Downstream modules inherit the include paths. |
PrivateDependencyModuleNames | The module is used only in Private/ .cpp files or private headers. |
PublicIncludePathModuleNames / PrivateIncludePathModuleNames | You need the module's headers (forward declarations, inline types) but link nothing from it. |
DynamicallyLoadedModuleNames | You call FModuleManager::Get().LoadModule(...) yourself; UBT only ensures the module is built. |
Start private and promote to public only when a public header forces it. Everything-public inflates compile time for every downstream module.
Include Paths and IWYU
UBT discovers Public/, Internal/ and Private/ automatically; PublicIncludePaths/PrivateIncludePaths exist for extra subfolders only. Under BuildSettingsVersion.V2 and later, bLegacyPublicIncludePaths is false, so headers from other modules are written relative to that module's Public/ (or Classes/) root:
// Source/MyGame/Private/MyActor.cpp
#include "MyActor.h" // own header first
#include "GameFramework/Actor.h" // Engine/Classes/GameFramework/Actor.h
#include "Engine/World.h" // only what this file uses directly
#include "GameFramework/PlayerController.h"
IWYUSupport defaults to IWYUSupport.Full, which lets UnrealBuildTool -Mode=IWYU rewrite the module's includes; set IWYUSupport = IWYUSupport.KeepAsIs for code you maintain by hand.
API Export Macro
UBT defines <MODULENAME>_API (module name upper-cased plus _API) as DLLEXPORT while compiling the module and DLLIMPORT for importers; monolithic builds define it empty. Anything referenced from another module needs it:
// Source/MyGame/Public/MyGameTypes.h
#pragma once
#include "CoreMinimal.h"
class MYGAME_API FMyGameTypes
{
public:
void DoSomething();
};
MYGAME_API void MyGameFreeFunction();
Engine headers wrap this as #define UE_API CORE_API at the top of a file and #undef UE_API at the bottom (Async/Mutex.h). That is an engine-only convention; project code writes MYGAME_API directly. Missing MYGAME_API on a class another module references is the most common cause of LNK2019.
Warnings and Compiler Flags
bWarningsAsErrors = true;
CppCompileWarningSetti
Read the complete source ↗