4-2. MVVM 플러그인 | UE5 UI Deep Dive

01

UMG ViewModel 플러그인 개요

Epic의 공식 MVVM 솔루션

UE 5.1에서 도입된 UMG ViewModel 플러그인은 Epic의 공식 MVVM 솔루션입니다. UI 코드를 View(UMG 위젯)와 ViewModel(데이터/로직)로 분리하여 관심사 분리(Separation of Concerns)를 달성합니다.

Model
게임 데이터
(Character, GameState)

↔

ViewModel
MVVMViewModelBase
(FieldNotify 속성)

↔

View
UMG Widget
(자동 바인딩)

플러그인 활성화

설정
// 1. Edit > Plugins > "UMG Viewmodel" 활성화
// 2. Build.cs에 모듈 추가
PublicDependencyModuleNames.AddRange(new string[]
{
    "ModelViewViewModel",    // MVVM 코어
    "ModelViewViewModelBlueprint", // BP 지원
    "UMG",
});

Beta 상태

UMG ViewModel 플러그인은 아직 Beta 상태입니다. API가 향후 버전에서 변경될 수 있으므로, 프로덕션 적용 시 버전 호환성에 주의하세요. 그러나 Lyra 등 Epic의 샘플 프로젝트에서도 활용되고 있어 안정성은 확보되어 있습니다.

02

MVVMViewModelBase

ViewModel 기본 클래스와 FieldNotify

C++ - ViewModel 정의
#include "MVVMViewModelBase.h"

UCLASS()
class UPlayerStatsViewModel : public UMVVMViewModelBase
{
    GENERATED_BODY()

public:
    // FieldNotify 프로퍼티: 값 변경 시 자동 브로드캐스트
    UPROPERTY(BlueprintReadWrite, FieldNotify,
        Getter, Setter,
        Category = "Stats")
    float HealthPercent = 1.0f;

    UPROPERTY(BlueprintReadWrite, FieldNotify,
        Getter, Setter,
        Category = "Stats")
    int32 PlayerLevel = 1;

    UPROPERTY(BlueprintReadWrite, FieldNotify,
        Getter, Setter,
        Category = "Stats")
    FText PlayerName;

    // Getter 함수
    float GetHealthPercent() const { return HealthPercent; }
    int32 GetPlayerLevel() const { return PlayerLevel; }
    FText GetPlayerName() const { return PlayerName; }

    // Setter 함수: UE_MVVM_SET_PROPERTY_VALUE 매크로 사용
    void SetHealthPercent(float NewValue)
    {
        // 값이 변경되면 자동으로 바인딩된 위젯에 통지
        UE_MVVM_SET_PROPERTY_VALUE(HealthPercent, NewValue);
    }

    void SetPlayerLevel(int32 NewValue)
    {
        UE_MVVM_SET_PROPERTY_VALUE(PlayerLevel, NewValue);
    }

    void SetPlayerName(FText NewValue)
    {
        UE_MVVM_SET_PROPERTY_VALUE(PlayerName, NewValue);
    }
};

UE_MVVM_SET_PROPERTY_VALUE 매크로

이 매크로는 값 비교 후 변경이 있을 때만 FieldNotify 이벤트를 브로드캐스트합니다. 수동으로 BroadcastFieldValueChanged()를 호출하는 것보다 안전하고 간결합니다. 내부적으로 INotifyFieldValueChanged 인터페이스를 통해 바인딩된 모든 위젯에 변경을 알립니다.

03

View 바인딩 설정

UMG 위젯에서 ViewModel 속성을 바인딩하는 방법

Widget Blueprint 에디터에서 MVVM 바인딩 패널을 통해 ViewModel의 FieldNotify 속성을 위젯 속성에 연결합니다.

C++ - View에서 ViewModel 연결
// Widget Blueprint에서 ViewModel 클래스 지정:
// Widget Designer > View Bindings 패널 > ViewModel 추가
// Class: UPlayerStatsViewModel
// Creation Type: Manual (코드에서 생성) 또는 Create Instance

// 바인딩 설정 (에디터):
// HealthBar.Percent <-> ViewModel.HealthPercent
// LevelText.Text <-> ViewModel.PlayerLevel (변환 함수 지정)
// NameText.Text <-> ViewModel.PlayerName

// C++에서 ViewModel 생성 및 연결
void UPlayerHUD::NativeConstruct()
{
    Super::NativeConstruct();

    // ViewModel 인스턴스 생성
    StatsVM = NewObject<UPlayerStatsViewModel>(this);

    // MVVM 서브시스템을 통해 View에 ViewModel 설정
    UMVVMView* View = UMVVMSubsystem::GetViewFromUserWidget(this);
    if (View)
    {
        View->SetViewModel("PlayerStats", StatsVM);
    }
}

// 게임플레이에서 ViewModel 업데이트
void UPlayerHUD::UpdateFromCharacter(AMyCharacter* Character)
{
    // ViewModel의 Setter가 FieldNotify를 트리거
    // → 바인딩된 위젯이 자동으로 업데이트됨
    StatsVM->SetHealthPercent(Character->GetHealthPercent());
    StatsVM->SetPlayerLevel(Character->GetLevel());
    StatsVM->SetPlayerName(Character->GetDisplayName());
}

04

블루프린트에서 ViewModel 사용

블루프린트 전용 ViewModel 생성과 바인딩

블루프린트에서도 MVVMViewModelBase를 상속하여 ViewModel을 생성할 수 있습니다. 블루프린트 에디터에서 변수에 FieldNotify 플래그를 설정하면 됩니다.

블루프린트 ViewModel 설정 단계
// 1. 새 Blueprint Class 생성: Parent = MVVMViewModelBase
// 2. 변수 추가 (예: HealthPercent, float)
// 3. 변수 디테일에서 "FieldNotify" 체크박스 활성화
// 4. Widget Blueprint > View Bindings 패널 열기
// 5. "Add ViewModel" > 생성한 BP ViewModel 클래스 선택
// 6. 위젯 속성과 ViewModel 속성 연결
//    예: ProgressBar의 Percent ↔ ViewModel의 HealthPercent
// 7. 변환 함수(Conversion Function)가 필요하면 지정
//    예: int32를 FText로 변환

변환 함수 (Conversion Function)

ViewModel의 속성 타입과 위젯 속성 타입이 다를 때 변환 함수를 지정합니다. 예를 들어, int32 PlayerLevel을 FText 타입의 TextBlock.Text에 바인딩할 때, FText::AsNumber()를 변환 함수로 지정합니다.

SUMMARY

핵심 요약

UMG ViewModel 플러그인은 UE 5.1에서 도입된 Epic의 공식 MVVM 솔루션으로, View와 ViewModel을 분리합니다
UMVVMViewModelBase를 상속하고 FieldNotify 속성을 정의하면 값 변경 시 자동으로 바인딩된 위젯에 통지됩니다
UE_MVVM_SET_PROPERTY_VALUE 매크로는 값 변경 감지와 FieldNotify 브로드캐스트를 자동으로 처리합니다
Widget Blueprint의 View Bindings 패널에서 ViewModel 속성을 위젯 속성에 시각적으로 연결합니다
타입이 다른 바인딩에는 변환 함수(Conversion Function)를 지정하여 자동 변환을 적용합니다

PRACTICE

도전 과제

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

실습 1: MVVMViewModelBase 서브클래스 생성

UMVVMViewModelBase를 상속한 PlayerStatsViewModel 클래스를 만들고, UE_MVVM_FIELD_NOTIFICATION_FRIENDS 매크로로 HP, MaxHP, Level 필드를 FieldNotify로 노출하세요. 블루프린트에서 바인딩 설정까지 완료합니다.

실습 2: FieldNotify 양방향 바인딩

Slider 위젯과 ViewModel의 float 프로퍼티를 양방향 바인딩하세요. Slider를 움직이면 ViewModel 값이 변경되고, 코드에서 ViewModel 값을 변경하면 Slider 위치가 업데이트되는 것을 확인합니다.

심화 과제

그래픽/오디오/게임플레이 설정을 관리하는 SettingsViewModel을 구현하고, Widget Blueprint에서 MVVM 바인딩으로 설정 UI를 구성하세요. 설정값 저장/로드(USaveGame)와 ViewModel 동기화를 포함합니다.