Unreal Engine as a Library (UELibrary) は、 Unreal Engine 4 (UE4) の機能をライブラリにパッケージし直すことで、他のアプリケーションが独自の UE4 インスタンスを生成して制御することができます。UELibrary は、UE4 を制御するためのシンプルでプラットフォームに依存しない API を提供します。UE4 では、UELibrary のソース コードとサンプル アプリケーションを提供しているため、デベロッパーはプロセスを確認して、独自のエンジン、プラグイン、またはプロジェクト レベルの API 関数を追加することもできます。
この機能は、Unreal Engine End User License Agreement (「EULA」) で定義された「Engine Tools」を含むライブラリを作成します。EULA で定義されている Engine Tools に関する権利について一読し理解してください (特に、Engine Tools を含む製品の配布に関する制限について)。詳細については、「よくある質問 (FAQ)」および「その他のライセンス オプション」を参照してください。
UELibrary をビルドする
UELibrary は、Win64 でのモノリシック エディタ ビルド用にビルドできます。UELibrary はエンジンとともにビルドされ、選択したビルド コンフィギュレーションに従って、「/Engine/Intermediate/Build/」の任意の場所に名前とパスを持つ .lib ファイルを生成します。たとえば、Win64 の Development Editor コンフィギュレーションでは、 /Engine/Intermediate/Build/Win64/UE4Editor/Development/UELibrary/UE4Editor-UELibrary.dll が出力されます。UELibrary をプロジェクトの一部としてビルドするには、次のコードをプロジェクトの *.Target.cs ファイルに追加する必要があります。
GlobalDefinitions.Add("UE_LIBRARY_ENABLED=1");
LinkType = TargetLinkType.Monolithic;
bShouldCompileAsDLL = true;
UELibrary は、以下に説明するビルトイン API を使用して操作できます。また、アプリケーションのニーズに合わせて API を拡張することもできます。
ビルトイン API
ビルトイン API は、エンジンの起動、Windows メッセージの引き渡し、エンジンのティック、エンジンのシャットダウンという 4 つの基本機能を制御します。
| 公開済みの関数シグネチャ | 目的 |
|---|---|
int UELibrary_Init(HINSTANCE hInst, HWND hWnd, const char* CmdLine) |
コマンドラインで UE4 を起動して、指定した所有アプリケーションとウィンドウに UE4 を登録します。コマンドラインでロードする .uproject ファイルとマップを必ず指定してください。0 でない戻り値は、エラーであることを示します。これは 1 セッションあたり 1 回のみ呼び出すことができるため、複数の UE4 インスタンスの実行 (または複数のウィンドウへのレンダリング) には対応していません。 |
int UELibrary_Tick() |
エンジンをティックします。この関数は頻繁に呼び出すことをお勧めします。ほとんどの UE4 アプリケーションでは、1 秒あたり 30 ～ 60 回、VR アプリケーションでは、それ以上の頻度でティックすることが想定されるためです。0 でない戻り値は、エラーであることを示します。 エンジンは、このティックとその直前のティックとの時間差を特定します。この関数を呼び出す頻度があまり高くない場合、次にこの関数を呼び出す際にエンジンがより長い期間を 1 回のティックでシミュレートすることになります。エンジンには、1 ティックの時間拡張および最大デルタ時間などのルールがビルトインされているため、この関数を頻繁に呼び出さない場合は、頻度について再検討する必要があります。VR アプリケーションやハードウェアは、ユーザーを乗り物酔いから保護するために、低いティック レートではレンダリングを停止することがあります。 |
LRESULT UELibrary_WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam) |
Windows メッセージをエンジンに渡します。これは、 WndProc へのパススルーであり、WndProc が返す値はどのような値でも返します。 |
int UELibrary_Shutdown() |
UE4 をシャットダウンします。これは永続的なシャットダウンであるため、シャットダウン後、UE4 を再起動することはできません。0 でない戻り値は、エラーであることを示します。 |
このシンプルな API は、デフォルトで公開されており、UE4 を外部から操作するために必要なツールを提供します。追加機能が必要な場合は、この API を拡張することができます。
API を拡張する
また、ニーズに合わせて API を拡張し、追加の既存の機能または新規の機能を外部使用向けに公開することもできます。このためには、まずプロジェクトの「*.Target.cs」ファイルを上記の説明に従って、変更する必要があります。アプリケーションが必要とする追加の関数を記述し、 UELIBRARYAPI マクロを使用してそれらの関数を公開します。
新しい機能をエンジンに直接実装したいと考えるかもしれませんが、それはお勧めしません。説明に従って、プロジェクト レベルの実装を行ってください。