開発中は、既存のクラス、プロパティ、関数名や類似するコード メンバーの名前変更が必要になることがあります。
それらの変更によって大量のアセットが影響を受ける場合、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") -
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"))) -
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") -
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) -
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") -
StructRedirects- 新しい USTRUCT を参照するように、古い (または削除された) USTRUCT を使用しているプロパティを変更します。フィールド 型 目的 OldName文字列値 古い (または削除された) USTRUCT の名前を指定します。 NewName文字列値 新しい USTRUCT の名前を指定します。 MatchSubstringブール型 (オプション) これを 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 アセットに保存しているオリジナル コードと値です。
上記の値を使って 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;
};
この変更によって 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 の問題を特定するのに役立ちます。