11-7. 마이그레이션 가이드 | UE5 대규모 오픈월드 RPG

01

업그레이드 전 체크리스트

마이그레이션 준비 사항

UE 5.7은 "최근 Unreal 업그레이드 중 가장 안정적"이라는 평가를 받고 있습니다. 그러나 안전한 마이그레이션을 위해 다음 체크리스트를 확인하세요.

프로젝트 백업 완료

소스 컨트롤에 커밋하고 별도 백업 생성

플러그인 호환성 확인

사용 중인 모든 플러그인의 5.7 지원 여부 확인

Deprecated API 사용 여부 확인

커스텀 C++ 코드에서 deprecated API 검색

Linux 사용 시 SDL3 마이그레이션 준비

SDL2에서 SDL3로 전환됨

릴리즈 일정 확인

출시가 임박하지 않은 프로젝트에서 업그레이드 권장

알려진 호환성 이슈

Bink Media 플러그인: 5.6 비호환
FMOD: 5.6 업데이트 후 빌드 뱅크 크래시 보고
메모리 사용량: 5.4 대비 최대 1GB 추가 사용

02

Deprecation 및 Breaking Changes

5.6/5.7에서 변경된 API

항목	버전	상태	대안
Swarm Manager	5.6	Deprecated	동적 라이팅 사용
Lumen SWRT Detail Traces	5.6	Deprecated	HWRT 사용
Profiler 모듈	5.6	Deprecated	UnrealInsights 사용
Virtual Scouting (레거시)	5.6	Removed	새 VP 도구 사용
UUMGSequencePlayer	5.6	Removed	Runner 구조체 사용
UReplicationBridge	5.7	Removed	직접 구현
BeginReplication	5.7	이름 변경	OnBeginReplication

C++
// UE 5.6 주요 API 변경 대응

// Transform Constraint 노드 deprecated
// Before (5.5)
// TransformConstraint 노드 사용

// After (5.6+)
// Point, Rotation, Parent Constraint 개별 노드 사용

// ControlRigHierarchyModifier (Python) 제거
// Before (5.5)
// modifier = ControlRigHierarchyModifier()

// After (5.6+)
// hierarchy = RigHierarchy()  # 쿼리용
// controller = RigHierarchyController()  # 작성용

// ControlRigBlueprint.controller 속성 제거
// Before (5.5)
// controller = blueprint.controller

// After (5.6+)
// controller = blueprint.get_controller()

// TSoftObjectPtr 생성자 변경 (5.5부터)
// 경고: "Constructing TSoftObjectPtr from an incompatible pointer type has been deprecated"
// 새 API로 업데이트 필요

03

C++ 코드 마이그레이션

Breaking Changes 대응 방법

C++
// MigrationHelper.h - 마이그레이션 헬퍼 유틸리티
#pragma once

#include "CoreMinimal.h"

/**
 * UE 5.6/5.7 마이그레이션 헬퍼
 * 버전별 호환성 처리
 */
class FMigrationHelper
{
public:
    // 엔진 버전 체크
    static bool IsUE57OrLater()
    {
        return ENGINE_MAJOR_VERSION >= 5 && ENGINE_MINOR_VERSION >= 7;
    }

    static bool IsUE56OrLater()
    {
        return ENGINE_MAJOR_VERSION >= 5 && ENGINE_MINOR_VERSION >= 6;
    }
};

// ===== Iris Replication 마이그레이션 =====

// UE 5.7에서 BeginReplication -> OnBeginReplication 변경
#if ENGINE_MINOR_VERSION >= 7
    // UE 5.7+ 방식
    virtual void OnBeginReplication() override
    {
        // 복제 시작 로직
    }
#else
    // UE 5.6 이하 방식
    virtual void BeginReplication() override
    {
        // 복제 시작 로직
    }
#endif

// ===== State Tree 마이그레이션 =====

// StateTree Re-Enter State Behavior: UE 5.7에서 opt-in 필요
UCLASS()
class UMyStateTreeConfig : public UStateTreeComponentSchema
{
    GENERATED_BODY()

public:
    UMyStateTreeConfig()
    {
#if ENGINE_MINOR_VERSION >= 7
        // UE 5.7: Re-Enter State Behavior 명시적 활성화
        bEnableReEnterStateBehavior = true;

        // Instance Data Refactor: scoped data 사용 시 opt-in
        bUseScopedInstanceData = true;
#endif
    }
};

C++
// Linux SDL3 마이그레이션 (UE 5.7)

// SDL 함수 반환값 변경
// 기존 (SDL2): 음수 값 반환
// 신규 (SDL3): success/failure 불리언 반환

#if PLATFORM_LINUX

#if ENGINE_MINOR_VERSION >= 7
// UE 5.7+ SDL3 방식
bool InitializeSDL()
{
    // SDL3는 불리언 반환
    if (!SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO))
    {
        UE_LOG(LogInit, Error, TEXT("SDL3 초기화 실패: %s"), SDL_GetError());
        return false;
    }
    return true;
}
#else
// UE 5.6 이하 SDL2 방식
bool InitializeSDL()
{
    // SDL2는 음수 값 반환
    if (SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO) < 0)
    {
        UE_LOG(LogInit, Error, TEXT("SDL2 초기화 실패: %s"), SDL_GetError());
        return false;
    }
    return true;
}
#endif

// DPI/스케일링 처리 변경
// SDL3는 SDL_HINT_VIDEO_X11_SCALING_FACTOR 힌트 사용
void SetupDPIScaling()
{
#if ENGINE_MINOR_VERSION >= 7
    SDL_SetHint(SDL_HINT_VIDEO_X11_SCALING_FACTOR, "1");
#endif
}

#endif // PLATFORM_LINUX

// ===== MSVC 컴파일러 업데이트 (UE 5.7) =====
// 기본 Microsoft Visual C++ 컴파일러: MSVC 14.44
// Visual Studio 2022 17.x 이상 필요

04

일반적인 마이그레이션 이슈

자주 발생하는 문제와 해결 방법

렌더링 파이프라인 이슈

C++
// PSO(Pipeline State Object) 처리 변경
// UE 5.7에서 셰이더 순열이 온디맨드로 컴파일됨
// 다중 머티리얼 에셋이 점진적으로 렌더링될 수 있음

// 해결책: PSO 캐싱 사전 워밍
void PrewarmPSOCache()
{
    // 자주 사용하는 머티리얼의 PSO를 미리 컴파일
    TArray<UMaterialInterface*> MaterialsToPrewarm;

    // 캐릭터 머티리얼
    MaterialsToPrewarm.Add(CharacterMaterial);
    // 무기 머티리얼
    MaterialsToPrewarm.Add(WeaponMaterial);
    // 이펙트 머티리얼
    MaterialsToPrewarm.Add(EffectMaterial);

    for (UMaterialInterface* Material : MaterialsToPrewarm)
    {
        if (Material)
        {
            Material->WarmupShaderPipelines();
        }
    }
}

// Forward Rendering 이슈
// 일부 레이 트레이싱 기능이 Forward 모드 제대로 인식 안 함
// 해결책: Deferred 렌더링 사용 또는 특정 기능 비활성화
void ConfigureForwardRendering()
{
    static IConsoleVariable* CVarForwardShading =
        IConsoleManager::Get().FindConsoleVariable(TEXT("r.ForwardShading"));

    if (CVarForwardShading && CVarForwardShading->GetInt() > 0)
    {
        // Forward 모드에서 레이 트레이싱 반사 비활성화
        IConsoleManager::Get().FindConsoleVariable(
            TEXT("r.RayTracing.Reflections"))->Set(0);
    }
}

MetaHuman 마이그레이션

C++
// MetaHuman 5.5 -> 5.6+ 마이그레이션
// 이전 버전 MetaHuman을 5.6으로 가져올 때 업데이트 필요

void MigrateMetaHumanAssets()
{
    // 1. MetaHuman 블루프린트 재컴파일
    TArray<UBlueprint*> MetaHumanBlueprints;
    FindAllMetaHumanBlueprints(MetaHumanBlueprints);

    for (UBlueprint* BP : MetaHumanBlueprints)
    {
        FKismetEditorUtilities::CompileBlueprint(BP);
    }

    // 2. Groom 에셋 업데이트
    TArray<UGroomAsset*> GroomAssets;
    FindAllGroomAssets(GroomAssets);

    for (UGroomAsset* Groom : GroomAssets)
    {
        // Groom 데이터 재빌드
        Groom->RebuildData();
    }

    // 3. Control Rig 에셋 마이그레이션
    // ControlRigBlueprint.controller -> get_controller() 변경 대응
}

SUMMARY

핵심 요약

UE 5.7은 "최근 업그레이드 중 가장 안정적" 평가
마이그레이션 전 백업, 플러그인 호환성, deprecated API 확인 필수
주요 변경: Swarm Manager deprecated, UReplicationBridge 제거
Linux 사용 시 SDL3 마이그레이션 필요
MSVC 14.44 (Visual Studio 2022 17.x+) 필요
메모리 사용량이 5.4 대비 최대 1GB 증가

마이그레이션 권장 사항

개발 브랜치에서 먼저 테스트
점진적 마이그레이션 수행
핵심 기능 테스트 자동화
롤백 계획 수립

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: UE5 버전 업그레이드 실습

RPG 프로젝트를 최신 UE5 버전으로 업그레이드하세요. 프로젝트 복사본으로 테스트하고, 마이그레이션 로그에서 Deprecated API와 Breaking Change를 식별하세요.

실습 2: Deprecated API 교체

UE_LOG 경고에서 Deprecated로 표시되는 API를 새 API로 교체하세요. 예: MarkPendingKill() -> MarkAsGarbage(), Cast<> nullptr 체크 패턴 업데이트 등을 수행하세요.

심화 과제: 마이그레이션 자동화 도구 구축

프로젝트 전체에서 Deprecated API를 검색하고 자동 교체하는 스크립트를 작성하세요. Build.cs 의존성 변경, 헤더 include 경로 업데이트도 자동화하세요. 마이그레이션 전후 자동 테스트를 실행하여 안정성을 검증하세요.