開発中は、既存のクラス、プロパティ、関数名や類似するコード メンバーの名前変更が必要になることがあります。
それらの変更によって大量のアセットが影響を受ける場合、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 システムは提供する最大もしくは最小の情報を使用します。次の表に、その特異性のレベルの例を示します。
形式の例 |
適用範囲 |
---|---|
|
|
|
クラスや関数が存在するモジュールに関係なく、 |
|
すべてのモジュール内のすべてのクラスにある「 |
バージョンが 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
アセットを作成して保存したらエディタを閉じ、.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
の影響を調べることができます。結果は次のとおりです。
MatchSubtring
は受け取るアセットをより詳細に確認する必要があるため、スタートアップ時間に影響を及ぼします。MatchSubstring
は大きな変更を行う場合の修正として一時的に使用するためのものです。これらの変更に関連するアセットはすぐに再保存し、関連するコードの変更をプロジェクトのソース コントロール データベースにチェックインし、ソース コントロールに入らずに Core Redirect を削除することをお勧めします。
Core Redirect をデバッグする
-DebugCoreRedirects
コマンドライン引数を使用すると、Core Redirect の問題をデバッグできます。このコマンドライン引数は UE ログに追加情報を追加し、誤字などの Core Redirect の問題を特定するのに役立ちます。