Unreal Engine でマルチプロセスクックを使用する | Unreal Engine 5.3 ドキュメンテーション

マルチプロセスクック は、利用可能な CPU コアとメモリリソースを活用することで、クック済みビルドの生成にかかる時間を短縮します。これを実行する際、クックは次のように分割されます。

複数の ワーカー のサブプロセスがアセットのグループをクックします。
ディレクター プロセスがアセットのセットを分割してワーカーに割り当て、その結果を照合し、必要に応じて出力を結合します。

このページでは次の項目について説明します。

マルチプロセスクックの現在の制限事項に関する情報
マルチプロセスクックを設定する手順
自分のプロジェクトでマルチプロセスクックを最大限に活用するためのガイドライン

メリットおよび制限事項

マルチプロセスクックでは、基本的にメモリと引き換えにして、並列処理を実現します。つまり、マルチプロセスクックを効果的に行うには、シングルプロセスでのクックよりも多くの RAM を使用する必要があります。

大量のアセットを含むプロジェクトでは、マルチプロセスクックにより、クック済みビルドを完了するのに必要な時間が大幅に短縮されます。Epic Games では、大規模なプロジェクトを 4 つのサブプロセスでクックするテストを社内で実施しました。このテストでは、同じプロジェクトをシングルプロセスでクックした場合と比較して、ビルド時間が約 40% 短縮されました。

Lyra などの小規模なプロジェクトでは、マルチプロセスクックでビルド時間が短縮される可能性はほとんどありません。これは、複数のワーカーの処理またはメモリのオーバーヘッドの方が、少数のアセットをクックすることで得られるメリットを上回るためです。

システムリソースのボトルネック

マルチプロセスクックは、現在、ディレクタープロセスが実行されているマシン上でしかワーカープロセスを実行しません。マシンリソースの共有により、効果的に使用できるプロセス数に上限が課されます。

マルチプロセスクックは、今後のリリースでリモートワーカーが使用できるように更新される予定です。

以下が、2 つの主要なボトルネックになります。

マシンに搭載されている RAM の容量
処理に利用できるコアの数

利用可能な RAM がなくなると、ディレクターとワーカープロセスはより頻繁にガベージコレクションを開始します。ガベージコレクションの負荷により、ワーカーの追加による向上が打ち消され、クック速度が低下します。

利用可能なコア数がなくなると、各ワーカーはシングルスレッドで動作します。通常ワーカースレッドで発生する長時間の非同期タスクはメインスレッドをブロックし、ワーカーを追加することで得られる迅速化を打ち消し、クック速度が低下します。

デバッグ

また、複数のプロセスで複雑化が増すことで、システム固有のクッカのデバッグがさらに困難になります。各ワーカーのログとアーティファクトはディレクターにレプリケートされます。これは、Epic Games の社内では、ログステートメントおよびアーティファクトから診断できるバグには特に有効でした。ただし、デバッガでアタッチする必要がある問題では、複数のプロセスにより問題がさらに複雑になります。

マルチプロセスクックは、一部の高度なプラグインの制作者にさらに負担をかけます。複数のパッケージに対するクックプロセスでデータを集約するプラグインは、収集したデータをディレクターにレプリケートするティック関数をワーカーで作成するために IMPCollector API を使用する必要があります。

マルチプロセスクックを有効にする

マルチプロセスクックを有効にするには、プロジェクトのコンフィギュレーションファイルまたはクッカの起動引数を使用して、CookProcessCount 変数を 1 より大きな値に設定します。

最良の結果を得るためには、CookProcessCount に対するさまざまな値をテストしてみましょう。CookProcessCount の最適な値は、プロジェクトやマシンの利用可能なリソースによって異なる場合があります。

コンフィギュレーションファイルでマルチプロセスクックを有効にする

マルチプロセスクックを有効にするには、プロジェクトの *Editor.ini の [CookSettings]:CookProcessCount でエントリを追加し、このエントリを 1 より大きな整数に設定します。以下に例を示します。


	[CookSettings]

	CookProcessCount=4

起動パラメータでマルチプロセスクックを有効にする

クッカの起動パラメータでマルチプロセスクックを有効にするには、-cookprocesscount=N を使用して CookProcessCount を設定します。ここで、N は使用したいプロセス数です。以下に例を示します。


	-cookprocesscount=4.

ビルドのパッケージ化に UnrealAutomationTool (UAT) を使用している場合、AdditionalCookerOptions を使用して、この引数を AutomationTool を介してクッカプロセスに渡すことができます。


	-AdditionalCookerOptions="<YourOtherOptions> -cookprocesscount=4"

Project Launcher を使用して Unreal Editor から自動化ツールを起動する場合は、Project Launcher の設定に、AdditionalCookerOptions 引数を指定する [AdditionalCookerOptions] フィールドがあります。

コンフィギュレーションおよび調整

マルチプロセスクックの主な調整パラメータは、使用するプロセス数 (CookProcessCount) です。プロジェクトでは、オーバーヘッドによってクックプロセスの速度が低下し始める直前まで、この値を大きい値に設定する必要があります。負荷が増大し始めたら、変更できる追加パラメータがあります。これにより、ボトルネックに影響を及ぼしたり、より多くのワーカーを使用できる可能性があります。

クッカのメモリ設定

クッカにはメモリ使用を制御するオプションセットが 1 つだけあり、どの時点でガベージを収集するかを指定します。Engine\Config\BaseEngine.ini の [CookSettings] セクションのコメントを参照し、マシンがメモリ不足に陥っている場合は、オプションセットを調整してみてください。

DefaultEditor.ini


	[CookSettings]
	MemoryMinFreePhysical=
	MemoryMaxUsedPhysical=
	SoftGCStartNumerator=
	SoftGCDenominator=

トラブルシューティング

マルチプロセスクック中に表示される可能性のあるエラーと、推奨される対処法について、以下に説明します。

Package %s can only be cooked by a now-disconnected CookWorker.The package can not be cooked. (パッケージ %s は現在接続が解除されている CookWorker によってのみクックできます。このパッケージをクックすることはできません)

このエラーは CookWorker がクラッシュしたときに表示されます。CookWorker のクラッシュをデバッグする必要があります。また、この後続のエラーは無視してください。クラッシュは以前のエラーとしてログに記録されている必要があります。
Retraction results message received from %s; no packages were available for retraction. (退避結果メッセージを %s から受信しました。退避できるパッケージはありませんでした)

ある CookWorker が他の CookWorker より先に終了すると、クッカはビジー状態のワーカーからその CookWorker に処理をオフロードしようとします。World Partition レベルでは、このオフロードはまだ可能ではありません。クッカは何度も退避しようとして失敗し続け、ログスパムと同様にパフォーマンスの問題を引き起こします。UE の現在のバージョンでは、これに対する修正は行われていません。World Partition のケースを修正し、レベルの生成済みのパッケージを複数の CookWorker に分割できるようにする修正が予定されています。
%s has not responded to a RetractionRequest message for %.1f seconds.Continuing to wait… (%s は %.1f 秒間 RetractionRequest メッセージに応答しませんでした。引き続き待機しています…)

報告された持続時間が 1000 秒を超えた場合、これは、通常、CookWorker のデッドロックを示しています。デバッガで CookWorker にアタッチして、その動作を確認してください。

メリットおよび制限事項

システム リソースのボトルネック