UE5 Common UI — 플랫폼 통합 UI 시스템

개요

Common UI는 Epic Games가 Fortnite에서 추출한 멀티플랫폼 UI 프레임워크입니다. PC/콘솔/모바일에서 동일한 위젯 코드로 플랫폼별 입력(마우스, 게임패드, 터치)을 처리하고 포커스 내비게이션, 백 버튼, 액션 버튼을 일관되게 관리합니다.

1. 플러그인 활성화

Edit → Plugins → UI → Common UI Plugin → Enable
Project Settings → Game → Common UI Framework 설정

2. CommonActivatableWidget — 화면 스택

일반 UUserWidget 대신 UCommonActivatableWidget을 사용하면 화면 스택이 자동 관리됩니다.

#pragma once
#include "CommonActivatableWidget.h"
#include "MainMenuWidget.generated.h"

UCLASS()
class UMainMenuWidget : public UCommonActivatableWidget
{
    GENERATED_BODY()
protected:
    // 위젯이 활성화될 때 호출
    virtual void NativeOnActivated() override;

    // 위젯이 비활성화될 때 호출
    virtual void NativeOnDeactivated() override;

    // 뒤로 가기 입력 처리
    virtual void NativeOnBackAction() override;

    // 포커스 대상 지정
    virtual UWidget* NativeGetDesiredFocusTarget() const override;
};

void UMainMenuWidget::NativeOnActivated()
{
    Super::NativeOnActivated();
    // 배경음악 재생, 애니메이션 시작 등
    PlayAnimation(OpenAnimation);
}

void UMainMenuWidget::NativeOnBackAction()
{
    // ESC / 게임패드 B버튼 처리
    DeactivateWidget(); // 스택에서 팝
}

// PlayerController에서 위젯 스택 관리
#include "CommonUIExtensions.h"

void AMyPlayerController::OpenPauseMenu()
{
    // 위젯 스택에 푸시 (이전 위젯 위에 표시)
    UCommonUIExtensions::PushContentToLayer_ForPlayer(
        GetLocalPlayer(),
        FGameplayTag::RequestGameplayTag("UI.Layer.Menu"),
        UPauseMenuWidget::StaticClass());
}

4. CommonButton — 플랫폼별 스타일

// CommonButtonBase를 상속한 커스텀 버튼
#include "CommonButtonBase.h"

UCLASS()
class UMyButton : public UCommonButtonBase
{
    GENERATED_BODY()
protected:
    // 버튼 클릭 처리
    virtual void NativeOnClicked() override;

    // 선택(게임패드 포커스) 처리
    virtual void NativeOnSelected(bool bBroadcast) override;

    // 버튼 스타일 업데이트
    virtual void UpdateInputActionWidget() override;
};

버튼 스타일 테이블:

Content Browser → 우클릭 → User Interface → Common Button Style
→ 플랫폼별 스타일(PC, Console, Mobile) 각각 설정

5. 입력 액션 바인딩

// 위젯에 게임패드 액션 바인딩
void UInventoryWidget::NativeConstruct()
{
    Super::NativeConstruct();

    // 게임패드 Y버튼 → 정렬
    RegisterBinding(
        FCommonInputActionDataBase::GetActionDataChecked(
            FGameplayTag::RequestGameplayTag("CommonInput.Menu.Sort")),
        FCommonActionCommittedDelegate::CreateUObject(
            this, &UInventoryWidget::SortItems));

    // 게임패드 X버튮 → 버리기
    RegisterBinding(
        FCommonInputActionDataBase::GetActionDataChecked(
            FGameplayTag::RequestGameplayTag("CommonInput.Menu.Drop")),
        FCommonActionCommittedDelegate::CreateUObject(
            this, &UInventoryWidget::DropItem));
}

6. CommonTextBlock — 자동 텍스트 스타일

// 스타일 에셋 기반 텍스트 (폰트, 크기, 색상 일괄 관리)
UPROPERTY(meta = (BindWidget))
UCommonTextBlock* TitleText;

void UMyWidget::NativeConstruct()
{
    Super::NativeConstruct();

    // 스타일 에셋 할당
    TitleText->SetStyle(TitleTextStyle); // UCommonTextStyle 에셋
    TitleText->SetText(FText::FromString("메인 메뉴"));
}

7. 플랫폼 감지 및 UI 분기

#include "CommonInputSubsystem.h"

void UMyWidget::NativeConstruct()
{
    Super::NativeConstruct();

    auto* InputSubsystem = UCommonInputSubsystem::Get(GetOwningLocalPlayer());
    if (InputSubsystem)
    {
        // 입력 방식 변경 감지 (마우스 ↔ 게임패드)
        InputSubsystem->OnInputMethodChangedNative.AddUObject(
            this, &UMyWidget::OnInputMethodChanged);
    }
}

void UMyWidget::OnInputMethodChanged(ECommonInputType NewInputType)
{
    bool bIsGamepad = (NewInputType == ECommonInputType::Gamepad);
    GamepadHintPanel->SetVisibility(
        bIsGamepad ? ESlateVisibility::Visible : ESlateVisibility::Collapsed);
}

8. UI 레이어 구조 권장 설계

HUD Layer         ← 체력바, 미니맵 (항상 표시)
Menu Layer        ← 일시정지, 인벤토리 (스택)
Modal Layer       ← 확인 다이얼로그 (최상단)

// GameplayTag 기반 레이어 정의
// Project Settings → Common UI → Registered UI Layers
"UI.Layer.HUD"
"UI.Layer.Menu"
"UI.Layer.Modal"

정리

Common UI는 플랫폼별 입력 처리와 포커스 내비게이션을 추상화해 PC/콘솔/모바일에서 하나의 위젯 코드로 동작하는 UI를 만들 수 있게 합니다. CommonActivatableWidget 스택으로 화면 전환을 관리하고, CommonButton과 스타일 에셋으로 디자인 일관성을 유지하세요.