Niagara のバージョン管理モジュール | Unreal Engine 4.27 ドキュメンテーション

概要

Niagara では、 Niagara スクリプト を使用して独自のカスタムモジュールを作成することができます。独自のモジュールを作成するときは、そのモジュールをチームに公開するか、多くのプロジェクトで使用することをお勧めします。モジュールを繰り返し使用して機能を追加したり改善したりする場合、それらのモジュールをすでに使用している既存のアセットを破壊することがないようにする必要があります。

バージョン管理を使用していないカスタムモジュールの場合、デフォルトではこのモジュールを使用しているアセットに直接変更がプッシュされます。一方、バージョン管理を有効にしていると、ユーザーはそのモジュールが利用可能になると新しいバージョンに手動でアップグレードする必要があります。

このことから、モジュールのバージョンを Niagara 内で直接作成できるようになりました。これは、Git や Perforce などのバージョン管理システムの置き換えを意図するものではなく、Niagara 内に直接ビルドされた内部バージョン管理システムです。

モジュールのバージョン管理を有効にする方法

バージョン管理を有効にするには、最初にスクリプトエディタのモジュールを開きます。どのモジュールも Niagara エディタ の [System Overview (システム概要)] からモジュールをダブルクリックするか、 コンテンツブラウザ から Niagara スクリプトをダブルクリックすると開くことができます。

ツールバーの [Versioning (バージョン管理)] ボタンをクリックします。

Niagara Versioning button in the Toolbar

初めてこのモジュールのバージョン管理を設定する場合は、ポップアップダイアログが表示されます。このダイアログでは、バージョン管理を有効にすると、モジュールのユーザーは変更を行うと手動で新しいバージョンにアップグレードする必要があることが通知されます。[Enable Versioning (バージョン管理を有効にする)] をクリックして承諾します。

Click on Enable Versioning in the dialog

これで、バージョンのプロパティを編集したり、新しいバージョンを作成したりできるようになりました。

バージョンの詳細

作成した各バージョンには、設定が必要なバージョンの詳細がいくつかあります。

パラメータ	説明
Is Exposed Version	されるときはいつでも、このバージョンがデフォルトになります。このモジュールを使用するユーザーは、バージョンセレクタにこのバージョンが表示されます。
Change Description	このバージョンの変更点についてユーザーに明確に知らせるためのテキストを入力します。
Is Visible in Version Select	有効にすると、ユーザーがバージョンセレクタでこのバージョンを選択できるようになります。モジュールの新しいバージョンを繰り返し処理してテストし、他のユーザーにはまだアクセスしてもらいたくない場合は、チェックボックスをオフにすることができます。

新しいバージョンを作成する

新しいバージョンを作成するには、 Niagara スクリプト ビューで [Versioning] ボタンをクリックしてパネルを開きます。[Add version (バージョンを追加)] をクリックします。

バージョンを作成する際は、最初に メジャーバージョン なのか マイナーバージョン なのかを指定する必要があります。マイナーバージョンは、重大な変更ではなく、小さな変更に対して使用する必要があります。メジャーバージョンは、そのバージョンに移行すると、すでに設定したプロパティを破壊することなしに古いバージョンに戻ることができない変更に対して使用します。

内部的にはマイナーバージョンとメジャーバージョンの違いはありません。

これは、単にユーザーにアップグレードに伴うリスクを認識してもらうための言語的な違いです。[New major version] または [New minor version] を選択したら、次に [Version Details (バージョンの詳細)] を設定することができます。新しいバージョンの設定中は、 [Is Exposed Version] のチェックボックスをオフにしておくことをお勧めします。また、新しいバージョンを作業していることに気付かれないためには、 [Is Visible in Version Selector] のチェックボックスもオフにしておくことをお勧めします。満足できる変更ができたら、これらのオプションを有効にして反映することができます。

別のバージョンを使用する

Niagara エディタ では、バージョン管理を使用しているスタックのモジュールを選択すると、 [Selection (選択)] パネルにバージョンセレクタのアイコンが表示されます。モジュールのバージョン管理が有効でも新しいバージョンがない場合は、バージョンアイコンはグレー表示されます。

Versioning enabled and no new version available

新しいマイナーバージョンが使用できるようになると、アイコンはオレンジ色になります。

Versioning enabled and new minor version available

新しいメジャーバージョンが利用可能になると、ユーザーに新しいバージョンを通知するメッセージも表示されます。

Versioning enabled and new major version available

いずれのバージョンの説明も、非表示にするまで [Selection] パネルに表示されます。

新しいメジャーバージョンが利用可能な場合は、エミッタスタックにも警告アイコンが表示されます。警告アイコンはモジュールの右側と、そのモジュールが属しているグループの右側にも表示されます。

A warning icon shows up in the stack when new major version is available

モジュールの新しいバージョンに切り替えると、毎回元に戻せるとは限りません。まずはプロジェクトを保存してから新しいバージョンに切り替え、すべてが適切に動作することを検証してください。

新しいバージョンに切り替えるには、 [System Overview] で更新するカスタムモジュールを選択します。バージョンスイッチャーをクリックし、次に使用するバージョンを選択します。バージョン番号の上にマウスを移動させると、そのバージョンを説明するツールチップが表示されます。

新しいバージョンがメジャーバージョンの場合、[Selection] パネルから [Fix Issue (問題を修正)] をクリックして直接このバージョンにアップグレードすることもできます。

Python の統合

これはまだ実験段階の機能なため、将来のリリースで変更される可能性があります。

モジュールをあるバージョンから別のバージョンへアップグレードすると、システムではできるだけ、古いバージョンのプロパティを新しいバージョンにマッピングしようとします。ただし、期待どおりの結果が不明な場合は、システムが適切にそのバージョンをアップグレードするように独自のアップグレードスクリプトを作成することをお勧めします。それにより、ユーザーはアップグレード後に作業をすべてやり直す必要がなくなります。

アップグレードスクリプトを提供するには、Niagara スクリプトツールバーの [Versioning] ボタンをクリックしてバージョン管理パネルを開きます。パネルには「Scripting」という名前のセクションがあります。デフォルトでは、 [Upgrade Script Execution (スクリプト実行ファイルをアップグレード)] はスクリプトを提供していないことを意味する [None] に設定されています。

スクリプトを入力するには、次の 2 つの方法があります。

テキストをコピーして [Versioning] パネルに直接貼り付ける。
外部アセットにリンクする。

テキストの直接入力

直接コピーして貼り付けるには、最初に [Upgrade Script Execution] をクリックしてから [Direct Text Entry (テキストの直接入力)] を選択します。これにより、 [Python Update Script (Python アップグレードスクリプト)] フィールドにスクリプトをコピーして貼り付けることができるようになります。

外部スクリプトを追加する

外部スクリプトにリンクするには、最初に [Upgrade Script Execution] をクリックしてから [Script Asset (スクリプトアセット)] を選択します。[Script Asset] フィールドの右側にある [...] のメニューをクリックすると、スクリプトファイルを参照できるようになります。

Python スクリプトを記述する

あるバージョンから別のバージョンに、それまでの Niagara スクリプトを新しいバージョンにどのようにマップするのかが明確ではない場合は、Python スクリプトを使用することができます。たとえば、古いバージョンは bool 型の入力を取得し、新しいバージョンでは 3 つ以上の値を持つ列挙型を代わりに使用する場合、アップグレードスクリプトは既存の bool 型の入力を 2 つの列挙型の値にマップすることができます。次にそのスクリプトの例を示します。

bool 型の入力を取得し、新しい入力を列挙型として設定する

	flying = upgrade_context.get_old_input("Is Flying")

	if not flying.is_local_value():

		print("Is Flying input used a dynamic input that could not be transferred to the new Movement Mode input")

	elif flying.as_bool():

		upgrade_context.set_enum_input("Movement Mode", "Flying")

	else:

		upgrade_context.set_enum_input("Movement Mode", "Walking")

upgrade_context 変数はスクリプトに提供され、古い入力と新しい入力を含みます。

「get_old_input(string input_name)」を呼び出すと、現在のスタックの値を取得するために使用できる入力オブジェクトが返されます。同様に、「set_XXX_input(string input_name, XXX value)」を使用して新しい入力の値を提供することができます。

実行する「print()」の呼び出しは、スクリプトの実行後にスタックに警告として表示されます。

Python を使用して Unreal で行えることに関するより詳細な内容については、「Python を使用したエディタのスクリプティング」を参照してください。

Python API のリスト

次に Niagara バージョン管理のオブジェクト API を示します。完全なリストは「Unreal Python API Documentation」のページを参照してください。

upgrade_context API

	get_old_input(string input_name)

これは UNiagaraPythonScriptModuleInput を返します (下記を参照してください)。入力が存在しない場合、これはエラーを返す代わりに空白のデフォルトオブジェクトを返します。

新しい入力を、次のようにタイプ別に設定します。

	set_float_input(string input_name, float value);

	set_int_input(string input_name, int value);

	set_bool_input(string input_name, bool value);

	set_vec2_input(string input_name, Vector2D value);

	set_vec3_input(string input_name, Vector value);

	set_vec4_input(string input_name, Vector4 value);

	set_color_input(string input_name, LinearColor value);

	set_quat_input(string input_name, Quat value);

	set_enum_input(string input_name, string value);

UNiagaraPythonScriptModuleInput API

	bool is_set()

これは、ユーザーが値を設定すると true を返します。

	bool is_local_value()

これは、入力がリンクされている属性や動的入力ではなく、ローカル値に設定されている場合に true を返します。

「bool is_local_value() 」が true を返す場合、次のように入力を Python 値に変換することができます。

	float as_float()

	int as_int()

	bool as_bool()

	Vector2D as_vec2()

	Vector as_vec3()

	Vector4 as_vec4()

	LinearColor as_color()

	Quat as_quat()

	string as_enum()