BLOGブログ

2019.11.20UE4/Cook

[UE4]BuildGraphってなんぞや?

執筆バージョン: 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に「プロジェクトのエディタのコンパイル」と「プロジェクトのゲームのコンパイル」の
2つのノード名を指定するとで、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は、今回紹介した内容以外にも色々と機能が提供されているので、
コマンドの追加、シェルスクリプト、手動等で対応していた部分を自動化にできそうです。