Core Redirects

クラス、列挙型変数、関数、パッケージ、プロパティ、構造体をロード時に再マップを可能にする Core Redirect の概要

Windows
MacOS
Linux

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

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

Core Redirect でクラスまたは構造体の名前を指定すると、Unreal Engine のリフレクション システムに表示される通りにその名前は書きだされます。つまり、プレフィックスは付きません。たとえば、AMyActorMyActorFMyStructMyStruct となります。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

    (オプション) 再マッピングが望ましい場合、古いまたは削除されたパッケージ名を指定します。これがない場合、Removedtrue に設定します。

    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;
    };

Original Values

これは 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 の影響を調べることができます。結果:

NoCoreRedirect.png

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

CoreRedirectWithoutMatchSubstring.png

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

CoreRedirectWithMatchSubstring.png

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

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

Select Skin
Light
Dark

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信