Core Redirects | Unreal Engine 4.27 ドキュメンテーション

開発中、既存クラス、プロパティ、関数名、似ているコードメンバの名前を変更が必要な場合があります。これらの変更による影響を多数のアセットが受ける場合、Unreal Engine は既存しているアセットを認識しなくなるため、コードメンバ名を変更してプロジェクトを再コンパイルするだけでは膨大なデータロスを引き起こします。 Unreal Engine は Core Redirects を使ってこの問題に対処しています。 Core Redirect はプロジェクトの「DefaultEngine.ini」ファイル、あるいはプラグインの場合は「そのプラグイン名 .ini]ファイル (たとえば Engine の Paper2D プラグインであれば BasePaper2D.ini、ゲームプラグインであれば Default<GamePluginName>.ini) で設定してください。いずれの場合も、Core Redirects は "[CoreRedirects]" セクションに置かれます。これらの Core Redirect はアセットをロードしながら古いデータを自動的に再マップして、名前変更によるデータロスを防ぎます。 Core Redirects が有効になっている例は、BaseEngine.ini ファイルで確認できます。

サポートしている Core Redirect の種類

Core Redirect でクラスまたは構造体の名前を指定すると、Unreal Engine のリフレクションシステムに表示される通りにその名前は書きだされます。つまり、プレフィックスは付きません。たとえば、AMyActor は MyActor、FMyStruct は MyStruct となります。Unreal Engine のリフレクションシステムは列挙型にプレフィックスを使わないので、コードで使うそのままの列挙型が Core Redirect に表示されます。たとえば、ESampleEnum は Core Redirect が参照すると ESampleEnum のままです。たとえば、ESampleEnum は Core Redirect が参照すると ESampleEnum のままです。

現在サポートされている Core Redirect の形式は以下の通りです。

ClassRedirects - 新しい UCLASS 参照するために、古い (または削除された) UCLASS を使っているオブジェクトとプロパティを変更します。

フィールド	型	目的
`OldName`	String	古い (または削除された) UCLASS の名前を指定します。
`NewName`	String	新しい UCLASS の名前を指定します。
`MatchSubstring`	Bool	(オプション) これが存在して `true` にセットされている場合、この Core Redirectは、完全一致を要求するというよりは、`OldName` の値が含まれているすべてのクラスに適用します。
`OverrideClassName`	String	(オプション) 変更を UCLASS の基底クラスに指定します。一般的に、Blueprint クラスをネイティブクラスに変更するために使用します (`/Script/CoreUObject.Class`)。
`InstanceOnly`	Bool	(オプション) `true` がセットされていると、もとのクラスがまだ存在し参照可能ですが、存在する古いクラスのインスタンス (レベルに配置されたアクタやコンポーネント) は新しいクラスに再マップされることを示します。プロジェクトにエンジンに存在するクラスを特定のバージョンにする場合、レベルはもとのクラスのインスタンスがたくさんあって、それらすべてをプロジェクト固有のバージョンに変更したい場合に特に便利です。
`ValueChanges`	String ペアのリスト	(オプション) ぺアの最初の文字列と一致する古いクラスのインスタンス名を変更します。新しい名前がペアの 2 番目の文字列になります。

		[CoreRedirects]
		+ClassRedirects=(OldName="Pawn",NewName="MyPawn",InstanceOnly=true)
		+ClassRedirects=(OldName="/Script/MyModule.MyOldClass",NewName="/Script/MyModule.MyNewClass")
		+ClassRedirects=(OldName="PointLightComponent",NewName="PointLightComponent",ValueChanges=(("PointLightComponent0","LightComponent0")))
		+ClassRedirects=(OldName="AnimNotify_PlayParticleEffect_C",NewName="/Script/Engine.AnimNotify_PlayParticleEffect",OverrideClassName="/Script/CoreUObject.Class")

EnumRedirects - 古い UENUM 型、または列挙型内の古い値を再マップします。

フィールド	型	目的
`OldName`	String	古い UENUM 名 (`NewName` が指定されている場合) または既存の UENM 名 (値のみを再マッピングする場合) を指定します。
`NewName`	String	(オプション) 古い UENUM から新しい UENUM へ再マッピングする場合、新しい UENUM を指定します。
`MatchSubstring`	Bool	(オプション) これが `true` にセットされていると、この Core Redirectは、完全一致を要求するというよりは、`OldName` の値が含まれているすべての列挙型に適用します。
`ValueChanges`	String ペアのリスト	ペアの最初の文字列は古い列挙型の値、2 番目の文字列は新しい値です。両方の値が同じクラスにある場合、古い値がコードに存在してはいけません。

		[CoreRedirects]
		+EnumRedirects=(OldName="ENumbers",NewName="ELetters",ValueChanges=(("NumberTwo","LetterB"),("NumberThree","LetterC")))

FunctionRedirects - 古い UENUM 型、または列挙型内の古い値を再マップします。

フィールド	型	目的
`OldName`	String	古い (または削除された) UFUNCTION の名前を指定します。関数名をピリオドで区切って、クラス名が含まれるようにします。
`NewName`	String	新しい UFUNCTION の名前を指定します。関数名をピリオドで区切ると、あるクラスから別のクラスへ関数を再マップすることができます。
`MatchSubstring`	Bool	(オプション) これが存在して `true` にセットされていると、この Core Redirect は、完全一致を要求するというよりは、`OldName` の値が含まれているすべての関数に適用します。

		[CoreRedirects]
		+FunctionRedirects=(OldName="MyOldActor.OldFunction",NewName="MyNewActor.NewFunction")
		+FunctionRedirects=(OldName="MyActor.OldFunction",NewName="NewFunction")

PackageRedirects - ひとつのパケットから別のパケットへ再マップ、または削除されたパッケージへの参照に関する警告を抑えます (参照はクリアまたはヌルに設定されます)。

フィールド	型	目的
`OldName`	String	古い、または削除されたパッケージ名を指定します。
`NewName`	String	(オプション) 再マッピングが望ましい場合、古いまたは削除されたパッケージ名を指定します。これがない場合、`Removed` を `true` に設定します。
`MatchSubstring`	Bool	(オプション) これが存在して `true` にセットされていると、この Core Redirectは、完全一致を要求するというよりは、`OldName` の値が含まれているすべての関数に適用します。
`Removed`	Bool	(オプション) これが存在して `true` にセットされていると、名前を指定されたパッケージが削除されます。削除されたコンテンツへのリファレンスは、警告またはエラーを出さずに null に設定されます。この場合、`NewName` 引数は存在しません。

		[CoreRedirects]
		+PackageRedirects=(OldName="OldPlugin",NewName="/NewPlugin/",MatchSubstring=true)
		+PackageRedirects=(OldName="/Game/DeletedContentPackage",Removed=true)

PropertyRedirects - 削除されたプロパティを新しいものへ再マップします。

フィールド	型	目的
`OldName`	String	削除されたプロパティの名前です。この名前はピリオドで区切って、クラス名とサブ変数名を含むようにします。 (たとえば、`MyActor.MyStruct.MyProperty` です)。
`NewName`	String	新しいプロパティの名前です。この名前は `OldName` のようにピリオドで区切ります。そうしないと、同じ名前空間に `OldName` として存在する単なる変数名になります。
`MatchSubstring`	Bool	(オプション) これが存在して `true` にセットされていると、この Core Redirectは、完全一致を要求するというよりは、`OldName` の値が含まれているすべてのプロパティに適用します。

		[CoreRedirects]
		+PropertyRedirects=(OldName="MyOldActor.OldIntProperty",NewName="MyNewActor.NewIntProperty")
		+PropertyRedirects=(OldName="MyActor.OldFloatProperty",NewName="NewFloatProperty")

StructRedirects - 削除された (または取り除かれた) USTRUCT を使ってプロパティが新しい USTRUCT を参照するように変更します。

フィールド	型	目的
`OldName`	String	古い (または削除された) USTRUCT の名前を指定します。
`NewName`	String	新しい USTRUCT の名前を指定します。
`MatchSubstring`	Bool	(オプション) これが存在して `true` にセットされていると、この Core Redirectは、完全一致を要求するというよりは、`OldName` の値が含まれているすべての構造体に適用します。

		[CoreRedirects]
		+StructRedirects=(OldName="MyStruct",NewName="MyNewStruct")

名前の柔軟性と特異性

名前は、クラス、構造体、プロパティ、関数を説明する時に使用し、特異性のレベルを変えて書くことができます。さらに、Core Redirect システムは提供する最大もしく最小の情報を使用します。以下の表は、その特異性のレベルの例です。

形式例	適用範囲
`/Script/MyModule.MyActor.MyFunctionOrProperty`	`MyModule` モジュールの `MyActor` クラス内の `MyFunctionOrProperty` という関数またはプロパティのみに適用されます。
`MyActor.MyFunctionOrProperty`	クラスおよび関数が存在するモジュールに関係なく、`MyActor` クラス内の `MyFunctionOrProperty` という関数またはプロパティに適用されます。
`MyFunctionOrProperty`	すべてのモジュールのすべてのクラスの `MyFunctionOrProperty` という関数またはプロパティに適用されます。

4.16 より前のバージョンのゲームおよびサンプルの .ini ファイルの中には、古い Core Redirect が含まれている場合があります。その中で使われている形式は後方互換性をサポートしていますが、独自の Core Redirect を書くためのテンプレートとしての使用は推奨しません。このページで指定されている形式のみを使用してください。

Substring Matching

MatchSubstring 引数は、すべての Core Redirect のタイプに使用することができます。true にセットすると、OldName および NewName のフィールドは完全一致ではなくサブストリングとして処理されます。これにより、単一の Core Redirect との複数一致が可能になります。以下の例では、構造体とクラスで開始しています。

オリジナルコードと値:

		USTRUCT()
		struct FMyStruct
		{
			GENERATED_BODY()

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestInt;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestIntFromStruct;
		};

		UCLASS()
		class REDIRECTORSTEST_API AMyActor : public AActor
		{
			GENERATED_BODY()

		public:
			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestInt;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 MainClassTestInt;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			FMyStruct TestStruct;
		};

これは AMyActor Asset に保存している元のコードと元の値です。

上記に示した値で AMyActor Asset を作成および保存したら、エディタを終了し、.h ファイルでコード、ゲームの .ini ファイルで Core Redirect を変更します。int32 プロパティの名前を変更して、コードを以下のようにします。

		USTRUCT()
		struct FMyStruct
		{
			GENERATED_BODY()

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestInteger;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestIntegerFromStruct;
		};

		UCLASS()
		class REDIRECTORSTEST_API AMyActor : public AActor
		{
			GENERATED_BODY()

		public:
			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 TestInteger;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			int32 MainClassTestInteger;

			UPROPERTY(EditAnywhere, Category = "Documentation")
			FMyStruct TestStruct;
		};

この変更により、Core Redirct の効果、特に MatchSubstring の影響を調べることができます。結果：

プロパティ名をコードで変更しましたが、Core Redirect はひとつも作成されませんでした。結果として、新しいプロパティにデータ値は何も移行されていません。

PropertyRedirects=(OldName="TestInt",NewName="TestInteger") causes only the two preoperties with exact name matches to migrate their data.

PropertyRedirects=(OldName="TestInt",NewName="TestInteger",MatchSubstring=true)サブストリングが一致するため、4 つすべてのプロパティが移行します。

MatchSubtring は受け取る Asset をより完全に確認する必要があるので、スタートアップ時間に影響します。 MatchSubstring は大きな変更を行う場合に一時的に使用するためのものです。これらの変更に関係する Asset をすぐに再保存し、プロジェクトのソースコントロールデータベースの関係するコードが変更されていること、および Core Redirect がソースコントロールを追加しなくても削除されていることの確認を推奨します。