| name | unreal-thirdparty |
| description | Expert guide for integrating third-party C/C++ libraries into Unreal Engine 5.x projects and plugins. Covers static linking, dynamic linking (DLL/SO/dylib), Build.cs configuration, ModuleType.External, delay loading, runtime dependency staging, wrapping patterns, cross-platform considerations (Windows/macOS/Linux), ABI compatibility, RTTI/exceptions, header inclusion with THIRD_PARTY_INCLUDES_START/END, and common pitfalls. Use when the user asks about adding external libraries, third-party code, linking .lib/.a/.dll/.so/.dylib files, Build.cs PublicAdditionalLibraries, PublicDelayLoadDLLs, RuntimeDependencies, ModuleType.External, wrapping a C++ library for UE, FPlatformProcess::GetDllHandle, cross-compiling libraries for UE on Linux, or troubleshooting linker errors / DLL load failures with third-party code.
|
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.
| Approach | When to Use | Build.cs Properties |
|---|
| Static library | Simplest; single executable; no DLL distribution | PublicAdditionalLibraries |
| Dynamic + import lib | DLL with compile-time symbol resolution | PublicAdditionalLibraries + PublicDelayLoadDLLs + RuntimeDependencies |
| Dynamic, no import lib | Runtime function pointer lookup via GetDllExport | RuntimeDependencies only |
| Multi-platform static | Cross-platform plugin with per-platform libs | PublicAdditionalLibraries with Target.Platform switch |
Library File Types
| Platform | Static | Dynamic | Import Lib | Prefix |
|---|
| Windows | .lib | .dll | .lib | none |
| Linux / Android | .a | .so | n/a | lib |
| macOS / iOS | .a | .dylib | n/a | lib |
Build.cs Quick Reference
| Property | Purpose |
|---|
Type = ModuleType.External | Module wraps prebuilt libs, no UE source compilation |
PublicIncludePaths | Header search directories |
PublicSystemIncludePaths | Same but suppresses warnings from these headers |
PublicAdditionalLibraries | Static / import library file paths |
PublicDelayLoadDLLs | DLL filenames for Windows delay-loading |
RuntimeDependencies | Files to stage alongside executable for packaging |
PublicDefinitions | Preprocessor defines ("WITH_MYLIB=1") |
PublicFrameworks | macOS frameworks |
bUseRTTI | Enable RTTI (required by Boost, some C++ libs) |
bEnableExceptions | Enable C++ exceptions (required by many libs) |
bForceEnableRTTI | Force RTTI engine-wide (in TargetRules) |
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:
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.
