執筆バージョン: Unreal Engine 4.23

今回はBuildGraphについてです。

UE4がカバーしきれていない作業（例えば、パッケージ後に必要なファイルのコピー等）がある場合
バッチファイルやシェルスクリプトになれたエンジニアであれば、スクリプトを自前で書いて解決するかと思います。
ですが、BuildGrapghの機能を利用するとXMLで手順を記述し自動で作業を行ってくれます。

バッチファイルでいいんじゃないかと思うかもしれませんが…
BuildGraphがよくわからんという理由で使わないのも負けた気がするのでちょっと調べてみました。

BuildGraphとは？

UnrealBuildTool,AutomationToolやエディタから実行可能な処理を利用し、独自にカスタマイズしたビルドを実行することができます。
XML形式で以下のように記述します。

BuildGraphの使用方法

書式

{プロジェクトパス}/Engine/Build/BatchFiles/RunUAT.bat BuildGraph -Script=[ビルドグラフXMLファイルパス] （option）

オプション引数

-Target=[開始する]
開始するノードを指定します。
※ノードについては後で解説します。
-Set:[option名]=[パラメータ]
オプションの設定
-Clean
過去のビルドをクリーニング処理する
-ListOnly
ノードを表示する
ノードの処理は行われないので、どのノードが実行されるか確認を行いたい場合に使えます。

サンプルの場所は以下の階層にあります。
\Engine\Build\Graph\Examples
まず、XMLを自作する前にどのようなことが出来るか、サンプルを動かしてみると良いかもしれません。

各エレメントについて解説

BuildGraphで使用される各エレメントを紹介します。

<Agent>

複数のノードをグループ化することができます。
ローカルPCでビルドする場合、この定義は無視されますが、指定しなければなりません。

パラメータ

Name	必須	グループの名前
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

<Node>

ビルドで行う処理をひとまとめに管理するものです。

パラメータ

Name	必須	ノード名
Requires	オプション	このノードの前に実行する必要があるノード名 複数ある場合はセミコロンで区切られます。
Produces	オプション	このノードが他のノードに対して利用可能にするタグ付けされたファイルセット 複数ある場合はセミコロンで区切られます このパラメータで指定されたタグは、他のノードからタグ付けされたファイルリストを参照出来るようになります。
NotifyOnWarnings	オプション	false の場合、このノードはWariningの通知を出しません。デフォルトはtrueです。
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

いきなり独自のBuildGraphを作る場合、ノード動作のイメージが湧きにくいかと思いますので例を挙げます。

以下のビルド処理があるとします。
・プロジェクトのエディタのコンパイル
・プロジェクトのゲームのコンパイル
・パッケージ化
できれば、パッケージ化前に以下の作業は済ませておきたいとします。
・最新のプログラムでゲーム側のビルドは済ませる必要がある
・アセットのクックするにはエディタのビルドを済ませる必要がある

この場合「パッケージ化」のパラメータRequiresに「プロジェクトのエディタのコンパイル」と「プロジェクトのゲームのコンパイル」の
２つのノード名を指定するとで、Requiresのノードの処理が終了後、「パッケージ化」の処理が走ります。
そのため、古いエディタやゲームのexeを使用せずに最新の状態のパッケージが作成できます。

このような作りにしておけば、エディタビルドだけ必要な場合は「プロジェクトのエディタのコンパイル」のノード名を指定すれば
エディタビルドのみを行うこともできます。
このように、一つのXMLを作成し一部を流用することがBuildGrapghの特徴でもあります。

<Aggregate>

ノードのグループを単一の名前で指定することができます。
Nodeは関連付けと処理がセットなのですが、関連したノードだけ実行したい場合はこちらを使ってください。

パラメータ

Name	必須	BuildGrapghのTargetオプションで指定する際に使用します。
Requires	必須	依存関係のリスト。ノード、タグ付けしたファイル セット、agent のグループなどがあります。
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

<Property>

プロパティを指定してパラメータを管理することができます。

パラメータ

Name	必須	設定するプロパティの名前。
Value	必須	プロパティの値
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

<Option>

<Property>と同様にパラメータを管理することができますが、
こちらはコマンドラインから-Set:[option名]で指定ができます。

パラメータ

Name	必須	設定するオプション名。
Description	必須	-ListOnly 引数で BuildGraph を実行する場合に表示するオプションの説明。
Restrict	オプション	有効な値と判定する正規表現 (例、 [a-zA-Z]+, true | false)。
DefaultValue	必須	ユーザーが指定しない場合のデフォルト値
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

<Include>

別の XMLファイルのスクリプトをこのファイル内で使用できるようにします。
汎用的なBuildGraphをまとめたりする場合に使うと良いでしょう。

パラメータ

Script	必須	インクルードしたいスクリプトへのパス (カレント スクリプトに相対的)。
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

タスク

ビルド プロセスの一部として実行されるアクション (コンパイル、クックなど) です。
デフォルトで定義済みのタスクが定義されています。
結構あるため、今回は知ってて得する定義済みタスクの一部を紹介したいとおもいます。

<Compile>

UnrealBuildToolsを利用しコンパイルを行います。
アンリアルのプロジェクトで管理するEditorやゲームのコンパイルを行います。

パラメータ

Target	必須	コンパイルするターゲット（例 UE4Editor,UE4Game,UE4Clinet,UE4Server)
Configuration	必須	コンパイルするビルドコンフィギュレーション (例 Development,Shipping)
Platform	必須	コンパイルするプラットフォーム（例 Win64）
Arguments	オプション	追加で UnrealBuildToolにわたす引数
Clean	オプション	Cleanオプションを許可するかどうか 指定しないと、コマンド行で -Clean 引数が渡されると、ターゲットはクリーンアップされます。
Tag	オプション	コンパイルで生成されたファイルに指定したタグ付けされます。
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

書式

<Command>

AutomationTool.exe（/Engine/Build/BatchFiles/RunUAT.batを利用している処理）を引数指定で利用することができます。
※極端な話、BuildGraphも実行できます。

パラメータ

Name	必須	実行するコマンド名
Arguments	オプション	コマンドの引数
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

使用例：パッケージビルド
参考ページ

[UE4] 4.9におけるパッケージングまとめ ～ProjectLauncher & Console編～

※UnrealEngine4が提供する必要なビルド処理を把握していない場合は、独自に実装するよりこちらを使ったほうが安心です。
書式

※Arguments 内部で「”」を利用できないので利用したい場合は&quot;を使用してください。

<Comandlet>

UE4Editor-Cmd.exeを引数指定で利用できます。

パラメータ

Name	必須	-runで指定するコマンド名（例：resavepackages）
Project	オプション	実行するプロジェクト名
Arguments	オプション	コマンドの引数
EditorExe	オプション	使用するUE4Editorのexeファイル名
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

使用例：ライトビルド
参考ページ

[UE4] ライトビルドをコマンドから実行しよう！

書式

<Spawn>

外部のプログラムを実行することができます。

パラメータ

Exe	必須	実行するExeファイル名
Arguments	オプション	実行するExeの引数
ErrorLevel	オプション	エラーレベル
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

仕様例：コマンドプロンプトのechoを利用
書式

<Log>

メッセージをログに表示させます。

パラメータ

Message	必須	表示するメッセージ
Files	オプション	指定した場合、指定されたメッセージの後に、指定されたファイルのリストが表示されます。
IncludeContents	オプション	trueを指定した場合、Filesで指定したファイルの内容が出力されます。
If	オプション	動作の条件式 条件式の結果が true でなければ、このエレメントは無視されます。

まとめ

BuildGrapghは、今回紹介した内容以外にも色々と機能が提供されているので、
コマンドの追加、シェルスクリプト、手動等で対応していた部分を自動化にできそうです。