unreal-thirdparty について
Unreal Engine の C++ プラグインにサードパーティライブラリを組み込むためのリファレンススキルです。リンク方式、プラットフォームや ABI の制約、パッケージング、ビルド時の問題を扱います。
主な機能
- 01静的・動的ライブラリのリンク方式
- 02Build.cs のプロパティとモジュール設定
- 03プラットフォーム別 ABI とパッケージング
- 04コンパイラー設定を分離するバリアモジュール
- 05一般的な問題と UE バージョン変更
活用シーン
- 01Unreal Engine プラグインへの事前ビルドライブラリの追加
- 02DLL などの実行時依存ファイルのパッケージング
- 03リンカーやプラットフォーム ABI の問題調査
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/unreal-thirdpartyを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/build-system.mdlinking-patterns.mdpatterns-and-pitfalls.mdplatform-specifics.md詳細
Unreal Engine サードパーティライブラリの統合 -- C++ ガイド
公式ドキュメント（最新情報は必ずご確認ください）
| ソース | URL |
|---|---|
| Epic：サードパーティライブラリの統合 | https://dev.epicgames.com/documentation/unreal-engine/integrating-third-party-libraries-into-unreal-engine |
| Epic コミュニティ：静的ライブラリ + Blueprint チュートリアル | https://dev.epicgames.com/community/learning/tutorials/0yJy/unreal-engine-fab-c-creating-your-own-3rd-party-function-library-and-using-it-in-blueprints |
| UE フォーラム：仕組みを理解する | https://forums.unrealengine.com/t/adding-third-party-libraries-to-unreal-understanding-how-this-works/211244 |
| georgy.dev：サードパーティライブラリの統合 | https://georgy.dev/posts/third-party-integration/ |
| unrealcode.net：ライブラリをラップする | https://www.unrealcode.net/WrappingALibrary/ |
| Linux ABI / Sysroot ガイド | https://pgaleone.eu/2023/06/18/unreal-engine-third-party-linux-sysroot-dependencies/ |
| GitHub：Boost/PCL プラグインの例 | https://github.com/ValentinKraft/Boost_PCL_UnrealThirdPartyPlugin |
| GitHub：UnrealImGui（参考実装） | https://github.com/IDI-Systems/UnrealImGui |
| Engine の ThirdParty ソース | Engine/Source/ThirdParty/（バンドルする前にご確認ください。Epic は libcurl、zlib、libpng、OpenSSL などを同梱しています。） |
コミュニティの追加リソース
プラグインテンプレート
UE にはサードパーティライブラリのプラグインテンプレートが用意されています。エディターで、プラグイン > 新規プラグイン > サードパーティライブラリ（一番下までスクロール）を選択します。これにより、DLL ベースの統合に必要なひな形が生成されます。静的ライブラリの場合は、Build.cs での 2 行の方法がより簡単です。
コアアーキテクチャ
すべてのプロパティとパス変数を含む Build.cs の完全なリファレンスについては、references/build-system.md を参照してください。
統合フロー：
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
推奨ディレクトリ構成：
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)
4 つの統合方法
各方法の詳しいコード例については、references/linking-patterns.md を参照してください。
| 方法 | 使用する場面 | Build.cs のプロパティ |
|---|---|---|
| 静的ライブラリ | 最も簡単な方法。単一の実行ファイルで、DLL の配布は不要 | PublicAdditionalLibraries |
| 動的ライブラリ + インポートライブラリ | コンパイル時にシンボルを解決する DLL | PublicAdditionalLibraries + PublicDelayLoadDLLs + RuntimeDependencies |
| 動的ライブラリ、インポートライブラリなし | GetDllExport による実行時の関数ポインター検索 | RuntimeDependencies のみ |
| マルチプラットフォーム静的ライブラリ | プラットフォームごとのライブラリを使用するクロスプラットフォームプラグイン | Target.Platform の切り替えを含む PublicAdditionalLibraries |
ライブラリのファイル形式
| プラットフォーム | 静的 | 動的 | インポートライブラリ | プレフィックス |
|---|---|---|---|---|
| Windows | .lib | .dll | .lib | なし |
| Linux / Android | .a | .so | 該当なし | lib |
| macOS / iOS | .a | .dylib | 該当なし | lib |
Build.cs クイックリファレンス
| プロパティ | 目的 |
|---|---|
Type = ModuleType.External | モジュールはビルド済みライブラリをラップし、UE ソースのコンパイルは行いません |
PublicIncludePaths | ヘッダーの検索ディレクトリ |
PublicSystemIncludePaths | 同じ用途ですが、これらのヘッダーからの警告を抑制します |
PublicAdditionalLibraries | 静的ライブラリ／インポートライブラリのファイルパス |
PublicDelayLoadDLLs | Windows の遅延読み込みに使用する DLL のファイル名 |
RuntimeDependencies | パッケージング時に実行ファイルと一緒に配置するファイル |
PublicDefinitions | プリプロセッサ定義（"WITH_MYLIB=1"） |
PublicFrameworks | macOS フレームワーク |
bUseRTTI | RTTI を有効化します（Boost や一部の C++ ライブラリで必須） |
bEnableExceptions | C++ の例外を有効化します（多くのライブラリで必須） |
bForceEnableRTTI | エンジン全体で RTTI を強制的に有効化します（TargetRules 内） |
プラットフォーム固有の考慮事項
Windows の DLL 読み込み、macOS の @rpath/dylib、Linux の ABI/sysroot の詳細については、references/platform-specifics.md を参照してください。
主なルール：
- Windows： DLL は名前のみで検索されます（インポートテーブルにパスはありません）。
FPlatformProcess::GetDllHandle()または遅延読み込みを使用してください。UE は Engine/Project/Plugin のBinaries/Win64/ディレクトリを検索します。 - macOS： dylib は
@rpathのインストール名を使用します。install_name_tool -id @rpath/libfoo.dylibで設定してください。UBT は RPATH エントリーを自動的に追加します。 - Linux： C++ ライブラリは UE の Clang +
libc++（システムのlibstdc++ではありません）で再コンパイルする必要があります。C ライブラリ（安定した ABI）は再コンパイル不要です。UE の CMake ツールチェーンファイルを使用してください。
よくあるパターンと落とし穴
実装レシピ、重大な落とし穴、トラブルシューティングについては、references/patterns-and-pitfalls.md を参照してください。
重大な落とし穴：
- UE の
checkマクロは、checkを識別子として使用するサードパーティコードと衝突します。#undef checkを使用するか、インクルードをラップしてください /MD（マルチスレッド DLL）でコンパイルし、UE のランタイムに合わせてください。CRT が一致しないとリンカーエラーが発生します- RTTI と例外はデフォルトで無効です。Boost、PCL、および多くの C++ ライブラリでは、External モジュールとそれを使用するすべてのモジュールの両方で
bUseRTTI = trueとbEnableExceptions = trueが必要です - Release ライブラリのみを使用してください。UE は Release CRT を使用するため、Debug でビルドしたライブラリは
_ITERATOR_DEBUG_LEVELの不一致やアクセス違反を引き起こします - VS のプロジェクト設定は無視されます。有効なのは
.Build.csのみで、Visual Studio のプロパティは UBT にまったく影響しません Binaries/ThirdParty/は再生成されません。削除するとテンプレートの DLL が失われ、UBT では再ビルドできません- Linux の ABI 不一致。
libstdc++でコンパイルした C++ ライブラリは、UE のlibc++とは異なるシンボルマングリングを生成します
UE のバージョンごとの Build.cs の変更
バージョンごとの完全な変更履歴については、references/build-system.md を参照してください。
サードパーティとの連携に影響する主な破壊的変更：
- UE 5.0：
FVectorが 3 つの double に変更されました。TObjectPtrが生の UObject ポインターに置き換わりました - UE 5.2：
bEnforceIWYU（bool）がIWYUSupport（enum）に変更されました - UE 5.3：
BuildSettingsVersion.V4のデフォルトが C++20 になりました。TRemoveConstは非推奨となり、std::remove_constに置き換わりました - UE 5.4： デフォルトの MSVC 警告レベルが
/W4に変更されました。FTextの内部実装がTSharedRefからTRefCountPtrに変更されました - UE 5.5： 新しい
Engine/Build/BatchFiles/RunUBTスクリプトが、UBT の直接呼び出しに置き換わりました。PER_MODULE_BOILERPLATEは不要になりました。StructUtilsプラグインは非推奨となり、エンジンに移動しました - UE 5.6：
FString::Appendfでstatic constexprの書式文字列が必須になりました。GMallocへのアクセスは非推奨になりました - UE 5.7：
FindObjectではbExactClassが非推奨となり、EFindObjectFlagsが使用されます
高度なパターン
バリアモジュール（互換性のないコンパイラー設定の分離）
サードパーティライブラリで bUseRTTI = true と bEnableExceptions = true が必要でも、その影響範囲を最小限に抑えたい場合は、ライブラリをクリーンなインターフェースの背後に隔離するバリアモジュールを作成します。
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)
バリアモジュールのパブリックヘッダーにサードパーティヘッダーをインクルードしたり、UObject.h のインクルードを発生させたりしてはいけません。すべてのサードパーティ型は、不透明なバリア型として渡します。本番環境での例については、AGX Dynamics のドキュメントを参照してください。
UE4CMake による CMake 連携
UE4CMake プラグインは Build.cs の CMakeTarget.add() を提供し、CMake ライブラリを UBT の一部としてビルドできます。
CMakeTarget.add(Target, this, "TargetName",
Path.Combine(ModuleDirectory, "../Libs/Source"),
"-DCUSTOM_OPTION=ON", false);
CMake の出力から PublicIncludePaths と PublicAdditionalLibraries を自動的に設定し、変更検出のためにソースファイルを ExternalDependencies に登録します。また、PRAGMA_PUSH_PLATFORM_DEFAULT_PACKING / PRAGMA_POP_PLATFORM_DEFAULT_PACKING による構造体のパッキングにも対応します。
UnrealMacroNuke（包括的なマクロ除染）
check 以外にも多数の UE マクロと競合するライブラリでは、UnrealMacroNuke を使うと、競合するすべてのマクロを未定義にして再定義する、対になるヘッダーを生成できます。
#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 パッケージマネージャーとの連携
conan-ue4cli パッケージは、UE にバンドルされた依存関係に対するサードパーティライブラリのビルドを自動化します。Build.cs は conan install を実行し、conanbuildinfo.json を解析してインクルードパス、ライブラリパス、定義を抽出します。UE とサードパーティライブラリが同じライブラリの異なるバージョン（例：zlib、libpng）に依存している場合に発生するシンボルインターポジションの解決に不可欠です。
Android APL（Android パッケージングレイヤー）
Android のサードパーティライブラリをネイティブライブラリとしてデプロイし、Java と連携するには、APL XML ファイルが必要です。
// Build.cs -- Android
AdditionalPropertiesForReceipt.Add("AndroidPlugin",
Utils.MakePathRelativeTo(
Path.Combine(ThirdPartyPath, "LIBRARY_APL.xml"),
Target.RelativeEnginePath));
変更検出用の外部依存関係
変更時に再ビルドをトリガーする外部ファイルを登録します。
ExternalDependencies.Add(Path.Combine(ModuleDirectory, "include", "version.h"));
指定したファイルに変更があった場合、UBT がメイクファイルを再生成するようになります。ヘッダーファイルやライブラリバイナリの更新を追跡する場合に便利です。
AddEngineThirdPartyPrivateStaticDependencies
独自のコピーを管理せずに、エンジンに同梱されているライブラリを使用します。
AddEngineThirdPartyPrivateStaticDependencies(Target, "OpenSSL", "libWebSockets", "libcurl", "zlib");
エンジンにすでに同梱されているライブラリを使用する場合は、この方法が推奨されます。