ue-module-build-system

What this skill does

# UE Module & Build System

You are an expert in Unreal Engine's module and build system. You understand Unreal Build Tool (UBT), ModuleRules, TargetRules, the .uproject manifest, plugin architecture, and the IWYU include discipline enforced by UE5.

## Before Starting

Read `.agents/ue-project-context.md` if it exists — it provides module names, engine version, active plugins, and build targets that affect dependency and include configuration.

Ask which situation applies:
1. Configuring dependencies in an existing Build.cs
2. Creating a new module from scratch
3. Creating a new plugin
4. Resolving a build error (linker, include, or IWYU)
5. Setting up Target.cs for a new build target

---

## Build.cs Anatomy

Every UE module has a `ModuleName.Build.cs` file next to its `Public/` and `Private/` directories.

```csharp
// Source/MyModule/MyModule.Build.cs
using UnrealBuildTool;

public class MyModule : ModuleRules
{
    public MyModule(ReadOnlyTargetRules Target) : base(Target)
    {
        // PCH settings — use IWYU in UE5
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
        // Enable strict IWYU (recommended for new modules in UE5)
        bEnforceIWYU = true;

        // Types accessible to modules that depend on MyModule
        PublicDependencyModuleNames.AddRange(new string[]
        {
            "Core",
            "CoreUObject",
            "Engine",
        });

        // Types used only internally (not re-exported in public headers)
        PrivateDependencyModuleNames.AddRange(new string[]
        {
            "Slate",
            "SlateCore",
        });

        // Load at runtime but don't link at compile time
        DynamicallyLoadedModuleNames.Add("OnlineSubsystem");
    }
}
```

### Public vs Private Dependencies

| Field | When to use |
|---|---|
| `PublicDependencyModuleNames` | A type from the dependency appears in your **public headers** |
| `PrivateDependencyModuleNames` | The dependency is consumed only in **Private/** .cpp files |

A common mistake: putting everything in `PublicDependencyModuleNames`. This bloats transitive include paths for every downstream module. Only promote to public when your public headers actually `#include` headers from that module.

### Include Paths

```csharp
// Expose extra paths to modules that depend on you
PublicIncludePaths.Add(Path.Combine(ModuleDirectory, "Public/Interfaces"));

// Expose extra paths only to this module's own source
PrivateIncludePaths.Add(Path.Combine(ModuleDirectory, "Private/Helpers"));
```

UBT automatically adds `Public/` and `Private/` — you rarely need to set these manually unless you have nested subdirectory headers you want to import without path prefixes.

### API Export Macro

UBT generates `MODULENAME_API` from the module's directory name, uppercased. Any class, function, or variable that must be visible across DLL boundaries needs this macro:

```cpp
// Public/MyClass.h
#pragma once
#include "CoreMinimal.h"

class MYMODULE_API FMyClass
{
public:
    void DoSomething();
};

// Standalone exported function
MYMODULE_API void MyFreeFunction();
```

Missing `MYMODULE_API` on a class that another module references causes "unresolved external symbol" linker errors.

### PCH and IWYU

```csharp
// UE5 recommended — each file includes exactly what it uses
PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;
bEnforceIWYU = true;

// Legacy — one monolithic PCH (avoid for new modules)
PCHUsage = PCHUsageMode.UseSharedPCHs;
```

With IWYU, every `.cpp` file includes its own `.h` first, then only what it directly uses:

```cpp
// Private/MyClass.cpp
#include "MyClass.h"       // own header first
#include "Engine/Actor.h"  // only includes this file directly uses
```

### Compiler Flags

```csharp
// C++ exceptions — disable unless third-party code requires them
bEnableExceptions = false;

// Runtime type information — disable unless using dynamic_cast
bUseRTTI = false;

// Third-party static libraries shipped with the engine
AddEngineThirdPartyPrivateStaticDependencies(Target, "zlib", "OpenSSL");
```

---

## Target.cs

Located at `Source/ProjectName.Target.cs` (and `Source/ProjectNameEditor.Target.cs`).

```csharp
// Source/MyGame.Target.cs
using UnrealBuildTool;
using System.Collections.Generic;

public class MyGameTarget : TargetRules
{
    public MyGameTarget(TargetInfo Target) : base(Target)
    {
        Type = TargetType.Game;
        DefaultBuildSettings = BuildSettingsVersion.Latest;
        IncludeOrderVersion = EngineIncludeOrderVersion.Latest;

        // All game modules that UBT should compile
        ExtraModuleNames.AddRange(new string[] { "MyGame", "MyGameUtilities" });
    }
}

// Source/MyGameEditor.Target.cs
public class MyGameEditorTarget : TargetRules
{
    public MyGameEditorTarget(TargetInfo Target) : base(Target)
    {
        Type = TargetType.Editor;
        DefaultBuildSettings = BuildSettingsVersion.Latest;
        IncludeOrderVersion = EngineIncludeOrderVersion.Latest;
        ExtraModuleNames.AddRange(new string[] { "MyGame", "MyGameEditor" });
    }
}
```

### Target Types

| TargetType | Use for |
|---|---|
| `Game` | Standalone game executable |
| `Editor` | Editor build (includes editor-only modules) |
| `Client` | Networked client without server logic |
| `Server` | Dedicated server (no renderer) |
| `Program` | Standalone non-game tool |

**Build configurations**: `Debug` (full symbols, no optimization), `DebugGame` (engine optimized, game debug), `Development` (default; balanced), `Test` (like shipping but with console/stats), `Shipping` (final release, strips all debug).

---

## .uproject File

```json
{
    "FileVersion": 3,
    "EngineAssociation": "5.4",
    "Category": "",
    "Description": "",
    "Modules": [
        {
            "Name": "MyGame",
            "Type": "Runtime",
            "LoadingPhase": "Default"
        },
        {
            "Name": "MyGameEditor",
            "Type": "Editor",
            "LoadingPhase": "Default"
        }
    ],
    "Plugins": [
        {
            "Name": "ModelingToolsEditorMode",
            "Enabled": true
        },
        {
            "Name": "MyPlugin",
            "Enabled": true
        }
    ]
}
```

### Module Types

| Type | When to use |
|---|---|
| `Runtime` | Core game logic, ships with game |
| `RuntimeNoCommandlet` | Runtime, excluded from commandlet processes |
| `Editor` | Editor-only — stripped from shipping builds |
| `EditorNoCommandlet` | Editor, excluded from commandlets |
| `Developer` | Tools usable in Editor and Development builds |
| `DeveloperTool` | Developer module, shows in editor UI |
| `CookedOnly` | Included only in cooked (packaged) builds |
| `UncookedOnly` | Included only in uncooked (development) builds |
| `RuntimeAndProgram` | Runtime module that also compiles into standalone Programs |
| `EditorAndProgram` | Editor module that also compiles into standalone Programs |
| `Program` | Standalone programs (UnrealHeaderTool etc.) |

### Loading Phases

| Phase | Use for |
|---|---|
| `EarliestPossible` | First possible phase — core engine modules only |
| `PostSplashScreen` | After splash screen renders |
| `PreEarlyLoadingScreen` | Before the early loading screen |
| `PreLoadingScreen` | Before the main loading screen |
| `PostConfigInit` | Systems that must configure before engine starts |
| `PreDefault` | Modules that must be ready before Default modules |
| `Default` | Standard game modules (most common) |
| `PostDefault` | Modules that depend on Default modules being up |
| `PostEngineInit` | After full engine initialization |
| `None` | Not auto-loaded — requires `FModuleManager::LoadModule()` |

---

## Creating a New Module

### Directory Structure

```
Source/
  MyModule/
    Public/
      MyModule.h          (optional module interface header)
      MyClass.h
    Private/
      MyModule.cpp        (module registration)
      MyClass.cpp
    MyModule.Build.cs
```

### Module Interface

```cpp
// Public/MyModule.h
#pragma