Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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-system

About 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.csBuild.cs Anatomy
Target.cs, BuildSettingsVersion, IncludeOrderVersion, target typesTarget.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 errorsResolving 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

FieldUse when
PublicDependencyModuleNamesA type from the module appears in one of your Public/ headers (base class, member, parameter, return type, UPROPERTY). Downstream modules inherit the include paths.
PrivateDependencyModuleNamesThe module is used only in Private/ .cpp files or private headers.
PublicIncludePathModuleNames / PrivateIncludePathModuleNamesYou need the module's headers (forward declarations, inline types) but link nothing from it.
DynamicallyLoadedModuleNamesYou 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 ↗