Core Redirect

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

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

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

現在サポートされている Core Redirect 形式は次のとおりです。

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

  フィールド	型	目的
  OldName	文字列値	古い (または削除された) UCLASS の名前を指定します。
  NewName	文字列値	新しい UCLASS の名前を指定します。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべてのクラスに適用されます。
  OverrideClassName	文字列値	(オプション) 変更を UCLASS の基底クラスに指定します。これは一般的に、ブループリント クラスをネイティブ クラスに変更するために使用されます (/Script/CoreUObject.Class)。
  InstanceOnly	ブール型	(オプション) これを true に設定すると、元のクラスはまだ存在し、参照することもできますが、古いクラスのインスタンス (レベルに配置されているアクタやコンポーネントなど) は新しいクラスに再マップされていることを示します。プロジェクトでエンジン内のクラスを特定のバージョンにするときに、レベルには元のクラスのインスタンスが大量にあり、それらをすべてプロジェクト固有のバージョンに変更する場合に、これはとても便利です。
  ValueChanges	文字列ペアのリスト	(オプション) ペアの最初の文字列と一致する古いクラスのインスタンス名を変更します。ペアの 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")
  
  Copy full snippet

  [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	文字列値	古い UENUM の名前 (NewName が指定されている場合)、または既存の UENUM の名前 (値のみを再マップする場合) を指定します。
  NewName	文字列値	(オプション) 古い UENUM から新しいものに再マップする場合、新しい UENUM の名前を指定します。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべての列挙型に適用されます。
  ValueChanges	文字列ペアのリスト	ペアの最初の文字列は古い列挙型の値で、2 番目の文字列は新しい値です。両方の値が同じクラスにある場合、古い値はコード内に存在してはいけません。

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

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

• FunctionRedirects - 古い UFUNCTION を新しいものに再マップします。

  フィールド	型	目的
  OldName	文字列値	古い (または削除された) UFUNCTION の名前を指定します。関数名をピリオドで区切ってクラス名を含めます。
  NewName	文字列値	新しい UFUNCTION の名前を指定します。関数名をピリオドで区切ると、あるクラスから別のクラスへ関数を再マップできます。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべての関数に適用されます。

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

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

• PackageRedirects - あるパッケージから別のパッケージへ再マップしたり、削除されたパッケージへの参照についての警告を抑制したりします (参照はクリアされるか、Null に設定されます)。

  フィールド	型	目的
  OldName	文字列値	古い、または削除されたパッケージの名前を指定します。
  NewName	文字列値	(オプション) 再マッピングが望ましい場合、古い、または削除されたパッケージを置き換えるパッケージの名前を指定します。これを指定しない場合は、Removed を true に設定します。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべてのパッケージに適用されます。
  Removed	ブール型	(オプション) これを true に設定すると、指定されたパッケージが削除されます。削除されたコンテンツへの参照は Null に設定され、警告やエラーは発生しません。この場合、NewName 引数は使用しないでください。

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

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

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

  フィールド	型	目的
  OldName	文字列値	削除されたプロパティの名前です。この名前はピリオドで区切ってクラス名とサブ変数名を含めます。たとえば MyActor.MyStruct.MyProperty とします。
  NewName	文字列値	新しいプロパティの名前です。この名前は OldName のようにピリオドで区切ります。OldName と同じ名前空間に存在する場合は、変数の名前にすることもできます。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべてのプロパティに適用されます。

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

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

• StructRedirects - 新しい USTRUCT を参照するように、古い (または削除された) USTRUCT を使用しているプロパティを変更します。

  フィールド	型	目的
  OldName	文字列値	古い (または削除された) USTRUCT の名前を指定します。
  NewName	文字列値	新しい USTRUCT の名前を指定します。
  MatchSubstring	ブール型	(オプション) これを true に設定すると、この Core Redirect は完全一致を必要とせず、OldName の値を含むすべての構造体に適用されます。

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

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

名前の柔軟性と特異性

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

バージョンが 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;
};
Copy full snippet

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 アセットに保存しているオリジナル コードと値です。

上記の値を使って AMyActor アセットを作成して保存したらエディタを閉じ、.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;
};
Copy full snippet

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 Redirect の効果を、特に MatchSubstring の影響を調べることができます。結果は次のとおりです。

プロパティの名前をコードで変更しましたが、Core Redirect は作成されませんでした。その結果、新しいプロパティに移行したデータ値はありません。

PropertyRedirects=(OldName="TestInt",NewName="TestInteger") では、名前が完全に一致する 2 つのプロパティのみ、データが移行しました。

PropertyRedirects=(OldName="TestInt",NewName="TestInteger",MatchSubstring=true) では、部分文字列の一致により、4 つすべてのプロパティが移行しています。

MatchSubtring は受け取るアセットをより詳細に確認する必要があるため、スタートアップ時間に影響を及ぼします。MatchSubstring は大きな変更を行う場合の修正として一時的に使用するためのものです。これらの変更に関連するアセットはすぐに再保存し、関連するコードの変更をプロジェクトのソース コントロール データベースにチェックインし、ソース コントロールに入らずに Core Redirect を削除することをお勧めします。

Core Redirect をデバッグする

-DebugCoreRedirects コマンドライン引数を使用すると、Core Redirect の問題をデバッグできます。このコマンドライン引数は UE ログに追加情報を追加し、誤字などの Core Redirect の問題を特定するのに役立ちます。