1. Epic GamesDeveloper
  3. 코어 리디렉트

코어 리디렉트

코어 리디렉트는 로드 타임에 클래스, 열거형, 함수, 패키지, 프로퍼티, 구조체를 리매핑할 수 있습니다.

코어 리디렉트

개발 도중 기존 클래스, 프로퍼티, 함수 이름 또는 비슷한 코드 멤버의 이름을 변경해야 하는 경우가 있습니다. 그러나 이 변경에 영향을 받는 에셋 수가 많을 경우, 코드 멤버 이름만 변경하고 프로젝트를 리컴파일한다고 하더라도 언리얼 엔진(UE) 이 더 이상 기존 에셋을 인식하지 못해 엄청난 데이터가 손실됩니다. 이 문제를 해결하기 위해 엔진에서는 코어 리디렉트(Core Redirect) 를 사용합니다. 코어 리디렉트는 프로젝트의 DefaultEngine.ini 파일에 구성하거나, 플러그인의 경우 해당 플러그인 이름에 접두사가 붙은 .ini 파일(예를 들어 엔진의 Paper2D 플러그인이라면 BasePaper2D.ini , 게임 플러그인이라면 Default<GamePluginName>.ini )에 구성해야 합니다. 어느 경우든, 코어 리디렉트는 "[CoreRedirects]" 섹션에 배치됩니다. 이 코어 리디렉트는 에셋을 로드하는 동안 구버전 데이터를 자동으로 리매핑하여 이름 변경 프로세스로 인한 데이터 손실을 방지합니다. 현재 사용되는 코어 리디렉트 실제 예시는 BaseEngine.ini 파일을 확인하세요.

지원하는 코어 리디렉트 타입

코어 리디렉트에 클래스 또는 구조체 이름을 지정할 때, 해당 이름은 언리얼 엔진의 리플렉션 시스템에 나타난 그대로, 즉 접두사 글자를 떼고 작성해야 합니다. 예를 들어 AMyActor 는 MyActor 로, FMyStruct 는 MyStruct 로 작성합니다. 언리얼 엔진의 리플렉션 시스템이 열거형 타입에 접두사를 사용하지 않기 때문에, 열거형 타입은 코어 리디렉트에 코드와 똑같이 나타납니다. 예를 들어, ESampleEnum 을 코어 리디렉트가 참조하면 똑같이 ESampleEnum 으로 표시됩니다.

현재 지원하는 코어 리디렉트 포맷은 다음과 같습니다.

  • ClassRedirects - 구버전 (또는 제거된) UCLASS를 사용하여 오브젝트와 프로퍼티가 새 UCLASS를 가리키도록 변경합니다.
필드 타입 용도
OldName 스트링 구버전 (또는 제거된) UCLASS 이름을 지정합니다.
NewName 스트링 새 UCLASS 이름을 지정합니다.
MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 OldName 값이 들어 있는 클래스에 적용됩니다.
OverrideClassName 스트링 (선택 사항) UCLASS의 기저 클래스에 대한 변경을 지정합니다. 일반적으로 블루프린트 클래스를 네이티브 클래스( /Script/CoreUObject.Class )로 변경하는 데 사용됩니다.
InstanceOnly 부울 (선택 사항) 존재하고 true 로 설정된 경우 원본 클래스가 아직 존재하고 참조될 수 있지만, (레벨에 배치한 액터 또는 컴포넌트와 같은) 이전 클래스의 기존 인스턴스는 새 클래스로 리매핑해야 합니다. 프로젝트의 엔진에 특수 버전 클래스가 있지만 레벨이 원본 클래스 인스턴스로 가득 차 있는 경우, 이 원본 클래스 인스턴스를 모두 프로젝트 전용 버전으로 변경하고자 할 때 특히 유용합니다.
ValueChanges 스트링 쌍 목록 (선택 사항) 한 쌍의 첫 스트링에 일치하는 이전 클래스의 인스턴스 이름을 변경합니다. 새 이름은 그 쌍의 두 번째 스트링이 됩니다. 
		[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 스트링 (NewName 이 지정된 경우) 구버전 UENUM 이름 또는 (값만 리매핑하는 경우) 기존 UENUM의 이름을 지정합니다.
    NewName 스트링 (선택 사항) 구버전 UENUM에서 새 UENUM으로 리매핑하는 경우 새 UENUM 이름을 지정합니다.
    MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 OldName 값이 들어 있는 열거형 타입에 적용됩니다.
    ValueChanges 스트링 쌍 목록 쌍의 첫 스트링은 이전 열거형 값이고 두 번째 스트링은 새 값입니다. 두 값이 같은 클래스에 있는 경우, 이전 값은 더 이상 코드에 없어야 합니다. 
        [CoreRedirects]
    +EnumRedirects=(OldName="ENumbers",NewName="ELetters",ValueChanges=(("NumberTwo","LetterB"),("NumberThree","LetterC")))

  • FunctionRedirects - 구버전 UFUNCTION을 새 UFUNCTION으로 리매핑합니다.

    필드 타입 용도
    OldName 스트링 구버전 (또는 제거된) UFUNCTION 이름을 지정합니다. 함수 이름은 클래스 이름을 포함하도록 온점으로 구분합니다.
    NewName 스트링 새 UFUNCTION 이름을 지정합니다. 함수 이름을 온점으로 구분하면 한 클래스에서 다른 클래스로 함수를 리매핑할 수 있습니다.
    MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 OldName 값이 들어 있는 함수에 적용됩니다. 
        [CoreRedirects]
    +FunctionRedirects=(OldName="MyOldActor.OldFunction",NewName="MyNewActor.NewFunction")
    +FunctionRedirects=(OldName="MyActor.OldFunction",NewName="NewFunction")

  • PackageRedirects - 한 패키지에서 다른 패키지로 리매핑하거나, 삭제된 패키지로의 레퍼런스 경고를 표시하지 않습니다(레퍼런스를 지우거나 null로 설정합니다).

    필드 타입 용도
    OldName 스트링 구버전 (또는 제거된) 패키지 이름을 지정합니다.
    NewName 스트링 (선택 사항) 리매핑을 원하는 경우, 구버전 패키지 또는 제거된 패키지를 대체하는 패키지 이름을 지정합니다. 이 옵션이 존재하지 않는 경우 Removed 가 존재하고 true 로 설정됩니다.
    MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 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 처럼 완전히 온점으로 구분할 수도 있고, 같은 네임스페이스에 존재한다면 변수 이름만이 될 수도 있습니다.
    MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 OldName 값이 들어 있는 프로퍼티에 적용됩니다. 
        [CoreRedirects]
    +PropertyRedirects=(OldName="MyOldActor.OldIntProperty",NewName="MyNewActor.NewIntProperty")
    +PropertyRedirects=(OldName="MyActor.OldFloatProperty",NewName="NewFloatProperty")

  • StructRedirects - 구버전(또는 제거된) USTRUCT를 사용하는 프로퍼티가 새 USTRUCT를 가리키도록 변경합니다.

    필드 타입 용도
    OldName 스트링 구버전 (또는 제거된) USTRUCT 이름을 지정합니다.
    NewName 스트링 새 USTRUCT 이름을 지정합니다.
    MatchSubstring 부울 (선택 사항) 존재하고 true 로 설정된 경우, 이 코어 리디렉트는 정확히 일치하기보다는 OldName 값이 들어 있는 구조체에 적용됩니다. 
        [CoreRedirects]
    +StructRedirects=(OldName="MyStruct",NewName="MyNewStruct")

이름 유연성 및 특이성

클래스, 구조체, 프로퍼티, 함수를 설명하는 이름은 다양한 정도의 특이성으로 작성할 수 있습니다. 추가적으로, 코어 리디렉트 시스템은 딱 제공한 만큼의 정보를 사용합니다. 이러한 특이성 정도의 예시는 다음 표와 같습니다.

예시 포맷 적용 범위  
/Script/MyModule.MyActor.MyFunctionOrProperty MyModule 모듈의 MyActor 클래스 내 MyFunctionOrProperty 라는 함수 또는 프로퍼티에만 적용됩니다.  
MyActor.MyFunctionOrProperty 클래스 및 함수가 존재하는 모듈과는 관계없이 MyActor 클래스 내 MyFunctionOrProperty 라는 함수 또는 프로퍼티에 적용됩니다.  
  MyFunctionOrProperty 어떤 모듈 내에서든 모든 클래스의 MyFunctionOrProperty 라는 함수 또는 프로퍼티에 적용됩니다.

일부 구버전 코어 리디렉트는 4.16 버전 이전 게임 및 샘플의 특정 .ini 파일에서 찾을 수 있습니다. 해당 포맷이 아직 지원되는 것은 이전 버전과의 호환성 때문이므로, 코어 리디렉트를 직접 작성할 때는 해당 파일을 템플릿으로 사용하지 않는 것이 좋습니다. 대신 이 페이지에 지정된 포맷만 사용해 주시기 바랍니다.

서브스트링 일치

어떤 코어 리디렉트 타입이든 MatchSubstring 실행인자를 사용할 수 있습니다. 존재하고 true 로 설정된 경우, OldName 및 NewName 필드는 정확한 일치가 아닌 서브스트링으로 간주합니다. 이로써 하나의 코어 리디렉트로 다수의 일치가 가능합니다. 다음 예시에서는 구조체와 클래스로 시작하겠습니다.

원본 코드 및 값:

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 에셋에 저장하려는 원본 코드와 원본 값 세트입니다.

위에 표시된 값으로 AMyActor 에셋을 생성 및 저장한 후, 에디터를 닫고 .h 파일의 코드와 게임의 .ini 파일 코어 리디렉트를 변경할 수 있습니다. 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;
};

이 변경으로 코어 리디렉트의 효과, 구체적으로 MatchSubstring 의 영향을 확인할 수 있습니다. 결과는 다음과 같습니다.

코드의 프로퍼티 이름을 변경했지만, 코어 리디렉트는 생성하지 않았습니다. 그 결과 새 프로퍼티로 이주된 데이터 값이 없습니다.

PropertyRedirects=(OldName="TestInt",NewName="TestInteger") 는 이름이 정확히 일치하는 두 프로퍼티만 데이터를 이주하도록 합니다.

PropertyRedirects=(OldName="TestInt",NewName="TestInteger",MatchSubstring=true) 는 서브스트링 일치로 인해 네 개의 프로퍼티가 전부 이주하도록 합니다.

MatchSubtring 은 입력 에셋을 훨씬 더 철저히 검사하므로 시작 시간에 영향을 줄 수 있습니다. MatchSubstring 은 전면적으로 변경 사항을 적용할 때의 임시 수정 용도입니다. 이 변경에 관련된 에셋은 즉시 다시 저장하고, 관련된 코드 변경 사항과 함께 프로젝트의 소스 컨트롤 데이터베이스를 검사할 것을, 코어 리디렉트는 소스 컨트롤 입력 없이 삭제할 것을 권장합니다.

디버그 코어 리디렉트

-DebugCoreRedirects 명령줄 실행인자를 사용하면 코어 리디렉트 문제 디버그에 도움을 받을 수 있습니다. 이 명령줄 실행인자는 UE 로그에 정보를 추가하여 오타를 포함한 코어 리디렉트 문제를 식별하도록 돕습니다.

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page