Unreal Engine Third-Party Library Integration -- C++ Guide

Official Documentation (always consult for latest details)

Additional Community Resources

Plugin Template

UE ships a Third Party Library plugin template. In the editor: Plugins > New Plugin > Third Party Library (scroll to bottom). This generates the scaffolding for a DLL-based integration. For static libraries, the two-line approach in Build.cs is simpler.

Core Architecture

See references/build-system.md for the full Build.cs reference with all properties and path variables.

Integration flow:

Third-Party Source (or prebuilt binaries)
  |
  v
[Optional: Recompile with UE toolchain for ABI compat]
  |
  v
Place headers + libs in Plugin/Source/ThirdParty/
  |
  v
Create External Module (.Build.cs with ModuleType.External)
  |-- PublicIncludePaths        -> header directories
  |-- PublicAdditionalLibraries -> .lib / .a files
  |-- PublicDelayLoadDLLs       -> DLL names (Windows delay-load)
  |-- RuntimeDependencies       -> .dll / .so / .dylib staging
  |-- PublicDefinitions         -> preprocessor macros
  v
Consumer Module depends on External Module
  |-- PublicDependencyModuleNames.Add("MyThirdPartyLib")
  |-- #include with THIRD_PARTY_INCLUDES_START/END
  v
Use library API in UE C++ code

Recommended directory layout:

MyPlugin/
  MyPlugin.uplugin
  Source/
    MyPlugin/                        # Runtime module (your code)
      MyPlugin.Build.cs
      Private/
      Public/
    ThirdParty/
      MyLibrary/                     # External module (no source)
        MyLibrary.Build.cs           # Type = ModuleType.External
        include/                     # Library headers
        lib/
          Win64/  *.lib
          Linux/  *.a or *.so
          Mac/    *.a or *.dylib
  Binaries/
    ThirdParty/MyLibrary/Win64/      # DLLs (if dynamic linking)

Four Integration Approaches

See references/linking-patterns.md for detailed code examples of each approach.

Library File Types

Build.cs Quick Reference

Platform-Specific Considerations

See references/platform-specifics.md for Windows DLL loading, macOS @rpath/dylib, and Linux ABI/sysroot details.

Key rules:

• Windows: DLLs found by name only (no path in import table). Use FPlatformProcess::GetDllHandle() or delay-loading. UE searches Engine/Project/Plugin Binaries/Win64/ directories.
• macOS: Dylibs use @rpath install names. Set with install_name_tool -id @rpath/libfoo.dylib. UBT auto-adds RPATH entries.
• Linux: Must recompile C++ libs with UE's Clang + libc++ (not system libstdc++). C libs (stable ABI) don't need recompilation. Use UE's CMake toolchain file.

Common Patterns & Pitfalls

See references/patterns-and-pitfalls.md for implementation recipes, critical pitfalls, and troubleshooting.

Critical pitfalls:

• UE's check macro collides with third-party code using check as an identifier -- #undef check or wrap includes
• Compile with /MD (Multi-threaded DLL) to match UE's runtime -- mismatched CRT causes linker errors
• RTTI + Exceptions off by default -- Boost, PCL, and many C++ libs require bUseRTTI = true and bEnableExceptions = true in BOTH the External module AND every consuming module
• Release libs only -- UE uses Release CRT; Debug-built libs cause _ITERATOR_DEBUG_LEVEL mismatch and access violations
• VS project settings are ignored -- only .Build.cs matters; Visual Studio properties have zero effect on UBT
• Binaries/ThirdParty/ is NOT regenerated -- if deleted, the template's DLLs are gone; cannot be rebuilt by UBT
• Linux ABI mismatch -- C++ libs compiled with libstdc++ produce different symbol mangling than UE's libc++

UE Version-Specific Build.cs Changes

See references/build-system.md for the complete version-by-version changelog.

Key breaking changes affecting third-party integration:

• UE 5.0: FVector changed to 3 doubles; TObjectPtr replaces raw UObject pointers
• UE 5.2: bEnforceIWYU (bool) changed to IWYUSupport (enum)
• UE 5.3: BuildSettingsVersion.V4 defaults to C++20; TRemoveConst deprecated for std::remove_const
• UE 5.4: Default MSVC warning level changed to /W4; FText internals changed from TSharedRef to TRefCountPtr
• UE 5.5: New Engine/Build/BatchFiles/RunUBT scripts replace direct UBT invocation; PER_MODULE_BOILERPLATE no longer required; StructUtils plugin deprecated (moved to engine)
• UE 5.6: FString::Appendf enforces static constexpr format strings; GMalloc access deprecated
• UE 5.7: FindObject deprecates bExactClass in favor of EFindObjectFlags

Advanced Patterns

Barrier Modules (isolating incompatible compiler settings)

When a third-party library requires bUseRTTI = true and bEnableExceptions = true but you want to minimize the blast radius, create a barrier module that isolates the library behind a clean interface:

Plugin/
  Source/
    ThirdParty/MyLib/          # ModuleType.External (headers + libs)
    MyLibBarrier/              # Barrier module (bUseRTTI=true, bEnableExceptions=true)
      Public/  -> clean types only, no third-party headers, no UObject.h
      Private/ -> wraps third-party includes with BeginIncludes/EndIncludes
    MyPlugin/                  # Main module, depends on MyLibBarrier (NOT on MyLib directly)

Public headers of barrier modules must NOT include third-party headers or trigger UObject.h inclusion. All third-party types are passed as opaque barrier types. See the AGX Dynamics documentation for a production example.

CMake Integration via UE4CMake

The UE4CMake plugin provides CMakeTarget.add() in Build.cs to build CMake libraries as part of UBT:

CMakeTarget.add(Target, this, "TargetName",
    Path.Combine(ModuleDirectory, "../Libs/Source"),
    "-DCUSTOM_OPTION=ON", false);

It automatically populates PublicIncludePaths and PublicAdditionalLibraries from CMake output, registers source files in ExternalDependencies for change detection, and handles struct packing via PRAGMA_PUSH_PLATFORM_DEFAULT_PACKING / PRAGMA_POP_PLATFORM_DEFAULT_PACKING.

UnrealMacroNuke (comprehensive macro decontamination)

For libraries that conflict with many UE macros beyond just check, UnrealMacroNuke generates paired headers that undefine and redefine all conflicting macros:

#pragma warning(push)
#pragma warning(disable: <codes>)
#include "UndefineMacros_UE_5.3.h"
#include "third_party/library.hpp"
#include "RedefineMacros_UE_5.3.h"
#pragma warning(pop)

Conan Package Manager Integration

The conan-ue4cli package automates third-party library builds against UE's bundled dependencies. Build.cs spawns conan install and parses conanbuildinfo.json to extract include paths, library paths, and definitions. Critical for solving symbol interposition when both UE and a third-party library depend on different versions of the same library (e.g., zlib, libpng).

Android APL (Android Packaging Layer)

Android third-party libraries require APL XML files for native library deployment and Java integration:

// Build.cs -- Android
AdditionalPropertiesForReceipt.Add("AndroidPlugin",
    Utils.MakePathRelativeTo(
        Path.Combine(ThirdPartyPath, "LIBRARY_APL.xml"),
        Target.RelativeEnginePath));

ExternalDependencies for Change Detection

Register external files that should trigger rebuilds when modified:

ExternalDependencies.Add(Path.Combine(ModuleDirectory, "include", "version.h"));

This ensures UBT regenerates the makefile if the specified files change, useful for tracking header or library binary updates.

AddEngineThirdPartyPrivateStaticDependencies

Use engine-bundled libraries without maintaining your own copies:

AddEngineThirdPartyPrivateStaticDependencies(Target, "OpenSSL", "libWebSockets", "libcurl", "zlib");

This is the preferred way to consume libraries already shipped with the engine.