Niagara のモジュールとエミッタのバージョン管理

概要

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

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

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

また、エミッタをアセットとして保存し、Niagara スクリプトと同じように、それらのエミッタに Niagara バージョン管理を適用することができます。

モジュールのバージョン管理

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

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

画像をクリックするとフルサイズで表示されます。

エミッタのバージョン管理

モジュールと同様に、複数のプロジェクトで再利用するためにエミッタのバージョン管理を行うことができます。この機能を使用するにはエミッタをアセットとして保存する必要があります。次の 2 種類の方法があります。

1. エミッタを新規作成する方法です。新しいエミッタを作成するには、コンテンツ ブラウザ内で右クリックし、 [FX] > [Niagara Emitter] を選択します。
2. 既存のエミッタを変換する方法です。Niagara システム内から、エミッタを右クリックして [Create Asset From This] を選択します。

エミッタ アセットから、上部のツールバーにある [Versioning (バージョン管理)] ボタンを見つけて、バージョン管理を有効にすることができます。Niagara スクリプト アセットから行う方法と同様に機能します。

画像をクリックするとフルサイズで表示されます。

バージョン管理を有効にする方法

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

画像をクリックするとフルサイズで表示されます。

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

バージョンの詳細

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

画像をクリックするとフルサイズで表示されます。

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

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

画像をクリックするとフルサイズで表示されます。

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

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

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

新しいバージョンを作成したら、ウィンドウを閉じて Niagara Script エディタに戻ることができます。ツールバーの [...] メニューからいつでも編集中のアクティブ バージョンを切り換えることができます。

画像をクリックするとフルサイズで表示されます。

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

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

画像をクリックするとフルサイズで表示されます。

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

画像をクリックするとフルサイズで表示されます。

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

画像をクリックするとフルサイズで表示されます。

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

画像をクリックするとフルサイズで表示されます。

At any time you can click on the version button in the Selection Panel to change from one version of the module to another.バージョン番号の上にマウスを移動させると、そのバージョンを説明するツールチップが表示されます。

画像をクリックするとフルサイズで表示されます。

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

画像をクリックするとフルサイズで表示されます。

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

新しいバージョンに切り替えるには、 [System Overview] で更新するカスタム モジュールを選択します。バージョン スイッチャーをクリックし、次に使用するバージョンを選択します。新しいバージョンがメジャー バージョンの場合、[Selection] パネルから [Fix Issue (問題を修正)] をクリックして直接このバージョンにアップグレードすることもできます。

画像をクリックするとフルサイズで表示されます。

Python の統合

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

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

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

画像をクリックするとフルサイズで表示されます。

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

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

テキストの直接入力

直接コピーして貼り付けるには、最初に [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")
	
	
Copy full snippet

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)
Copy full snippet

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);
	
	
Copy full snippet

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()
	
Copy full snippet

bool is_set()

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

	
		bool is_local_value()
	
Copy full snippet

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()
	
	
Copy full snippet

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()