※ UBAは UE5.4 でベータとして公開されている機能です
1. 概要
UE5.4 から導入された UnrealBuildAccelerator (以降、UBA) を使用して分散ビルドするためのセットアップ方法を記載します。以下は分散ビルドのイメージです。ローカルPCだけでビルドを行う際にはビルドに多くの時間を要していました。分散ビルドは別のPCにビルドタスクを分配して、ローカルPC以外でもビルドの処理を行うことによって、ビルド時間を短縮することができるものです。
UE5.4 においてUBA はベータとしてリリースされましたが、ソースコードのビルドおよびシェーダーコンパイルのビルド(実験的機能)において分散ビルドを実施し、簡単なセットアップで利用することができます。
2. ローカルネットワークにおける手動での分散ビルド
ここではローカルネットワーク環境において UnrealBuildAccelerator を使用して分散ビルドできていることをテストするための手順を示します。
※自動での分散ビルド環境構築を行いたい場合は、この手順をスキップして 3. に進んでください
2.1. ソースコードの分散ビルド
エンジンコードなど、ソースコードの分散ビルドが動作するためのセットアップ方法について示します。以下の構成においてローカルPCおよびリモートPCに対してUBAを配置して分散ビルドできるまでの方法を示します。前提として、ローカルPCにはエンジンコードを含むソースコードが存在しており、リモートPCは何もセットアップされていないPCであるとします。
- リモートPC に UBA を配置
リモートPCにはエンジンがインストールされていなくても問題ありませんが、分散ビルドを実行するために UBA のアプリケーションを配置しておきます。これはビルド済みの環境（たとえばソースコードをビルドするローカルPCなど）からあらかじめUBAを含むアプリケーションをコピーしておくことで問題ありません。
UBAはエンジンの以下の場所にあるので、x64 フォルダ以下をコピーしてリモートPCの任意の場所（どこでも可）に配置しておきます。
[EngineRoot]\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe
- リモートPC で UBA起動
リモートPCに UBA を配置した後は、UBAを起動してローカルPCからの分散ビルド開始待ち状態にしておくため、以下のようなバッチファイルを作成して実行します。UBAにホスト（ローカルPC）のアドレスを指定し、キャッシュ配置場所のディレクトリを指定して実行することで、UBAは接続待ちの状態となります。
- フォーマット
[EngineRoot]\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe -host=[HostPCIpAddress] -dir=[CacheDirPath]
- 実行例
C:\EPIC\Github\UnrealEngine\Engine\Binaries\Win64\UnrealBuildAccelerator\x64\UbaAgent.exe -host=-host=192.168.11.10 -dir=d:\cache
リモートPCでは UBA を起動するとホストとの接続待ち状態となります。
ローカルPC から分散タスクが投げられると自動的にビルドの出力を表示します。
- ローカルPC からUBTを使用してビルド実行
UBTを指定して UBA でエンジンのリビルドを実行します。以下はコマンド実行のフォーマット例で、実行例をその下に示します。引数の指定は以下の内容に準拠します。
“-UBA” はUBAを使用した分散ビルドを実施することを指定します。
“-UBAVisualizer” は分散ビルドのタスクを示すアプリケーション起動を指定します。
“-UBAForceRemote” はリモートPCのみでビルドを実行するかどうかを指定します。
- フォーマット
[EngineRoot]\Engine\Build\BatchFiles\RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA -UBAVisualizer
- 実行例
C:\EPIC\Github\UnrealEngine\Engine\Build\BatchFiles\RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA -UBAVisualizer
“-UBAForceRemote” なし時 ⇒ ローカル＋リモートでビルド実行
“-UBAForceRemote” 追加時 ⇒ リモートのみでビルド実行
2.2. 分散シェーダーコンパイル
ソースコードビルドと同様にシェーダーコンパイルの分散実行におけるテストを行うための設定について以下に示します。基本的なUBAの配置に関しては 2.1. で完了しているものとし、以下ではシェーダーコンパイルを実行するための設定および確認方法について記載しています。
-
プロジェクトのプラグインで UBAController を有効化
プロジェクトを立ち上げてから UBAController プラグインを有効にしておきます。 -
Engine.ini で UBAController を有効化
プロジェクトの DefaultEngine.ini に以下の定義を追加します。
[UbaController]
Enabled=True
- エディタ起動時に以下の引数を付けて起動
シェーダーコンパイルが分散できることを確認するために、以下の引数をつけてプロジェクトを起動します。このコマンドによってシェーダーコンパイルが強制的に実行されて分散される様子が確認できます。
-noshaderddc -noxgeshadercompiler
※注意： -noshaderddc -noxgeshadercompiler コマンドはシェーダーコンパイルを分かりやすく実行するためのコマンドで実際には使用しません、パッケージングなどを行いシェーダーコンパイルを実行することが実際の使われ方です
3. ローカルネットワークでの自動分散ビルド
ここまでで手動で分散ビルドを確認するための方法について述べてきましたが、ここからは自動で分散ビルドを実施するためのセットアップ方法について示します。実際に分散ビルドを行うにあたって、分散先や分散タスクを制御することが必要になってきます。UBA はビルドを実行するためのアプリケーションですが、そのUBAに対して自動的に分配する制御を行うのが HordeServer / HorderAgent です。
HordeServer はビルドマシンPCにインストールするアプリケーションで、ネットワーク上に存在しているHordeAgentを登録してUBAと連携して分散指示を行います。そのため分散ビルドを行うために HordeServer をインストールする必要があります。HordeAgent はリモートPCにインストールされるアプリケーションで、インストールされたPCに存在するUBAと連携して分散ビルドの処理を行います。
ここからの内容は以下のページに基づきます。
3.1. ビルドマシンPC のセットアップ
-
HordeServer のインストール
Engine/Extras/Horde/UnrealHordeServer.msi を実行してHordeServerのインストールを行います。Githubからエンジンを取得する場合、初期ダウンロードには Engine/Extras/Horde/ 以下の内容が含まれていませんが、Setup.bat を実行することによって ディレクトリが構築されてアクセスできるようになります。インストーラーを起動したら後は変更せずに全て[Next]を選択してOKです(変更の必要がある場合は必要に応じて内容を変更してください)。
-
ビルドマシンPC の IPアドレスを確認
PCでコマンドプロンプトを開き、ipconfig と入力してビルドマシンのIPアドレスを確認しておきます。図の場合、"10.7.101.8"がビルドマシンのIPアドレスで後で使用するためにメモしておきます。
3.2. ローカルPC のセットアップ
- UBA 利用の設定追加
ローカルPCでは、分散ビルドを実施するためにホスト(ビルドマシンPC)の指定を行います。ホストの指定は、Engine/Saved/UnrealBuildTool/BuildConfiguration.xml を開いてIPを指定します。以下の内容を BuildConfiguration.xml に追加(もしくはCopy&Paste)して、サーバー(の項目)を先ほど確認したビルドマシンのIPアドレスに書き換えます。
<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
<BuildConfiguration>
<!-- Enable support for UnrealBuildAccelerator -->
<bAllowUBAExecutor>true</bAllowUBAExecutor>
</BuildConfiguration>
<Horde>
<!-- Address of the Horde server -->
<!-- Server>http://{{ SERVER_HOST_NAME }}:13340</Server -->
<Server>http://10.7.101.8:13340</Server>
<!-- Pool of machines to offload work to. Horde configures Win-UE5 by default. -->
<WindowsPool>Win-UE5</WindowsPool>
</Horde>
<UnrealBuildAccelerator>
<!-- Enable for visualizing UBA progress (optional) -->
<bLaunchVisualizer>true</bLaunchVisualizer>
</UnrealBuildAccelerator>
</Configuration>
ビルドマシンPCのIPアドレスが、"10.7.101.8"の場合、"http://10.7.101.8:13340"と入力しておきます。
<Server>http://10.7.101.8:13340</Server>
3.3. リモートPC のセットアップ
リモートPCではHordeAgentをインストールしておきます。HordeAgentをインストールしたらPCを分散の対象とするために HordeServer へ登録します。これによってHordeServer は HordeAgent へタスクを分散できるようになり、自動的に分散対象のPCへ割り当てを行うことができるようになります。
- HordeAgent のインストール
HordeAgentのインストーラはHordeServerのPCにアクセスしてインストーラを入手します。リモートPC で WebBrowser を開いて http://[HostIp]:13340 と入力（例：http://10.7.101.8:13340 ）します。
[TOOLS] から HordeAgent のインストーラをダウンロードしてインストールします。
インストーラのセットアップは基本的に変更する必要なく[Next]を押して進めて良いですが、最後のHordeServer IP を指定する箇所では、メモしておいたHordeServer（ビルドマシンPC）のIP、 “http://[HostIp]:13340” と入力（例：http://10.7.101.8:13340 ）します。
- HordeAgent を HordeServer に登録
[SERVER]->[Agent Enrollments] から HordeAgent のPCを登録します。
HordeAgentのインストールされたPCが一覧に表示されるため、①→②→③の順番でハードウェアを選択して[Enroll Agents]ボタンを押して登録します。
登録が完了したら [SERVER]->[Agents] の一覧に表示が追加されます。
以上でセットアップが完了です。ローカルPCからビルドすることで分散ビルドをご利用頂けます。
4. トラブルシュート
- 分散ビルドされない
- ソースコードを数行変更した程度では分散されずにローカルのビルドだけで完了するので、分散されていることを確認したい場合はエンジンのリビルドでチェックした方が良いです。
RunUBT.bat UnrealEditor Win64 Development -Rebuild -UBA
- ローカルPCが無線LAN接続でも利用可能ですが、無線LAN接続でうまく動作しない場合は一度有線LANでご確認ください。ネットワーク接続がうまくいかないケースはポートが開いていない可能性があります。
- クラウドネットワーク環境のPCをビルドに参加させたい
- UE5.4時点では未サポートです。
- HordeServer と HordeAgent を同一PCにインストールしても大丈夫か？
- 効率的にビルドができなくなる可能性があるためおすすめしません。
