UE5 Common UI 플러그인 완전 가이드

개요

Common UI는 UE5의 공식 UI 플러그인으로, Lyra 샘플 게임에서 사용되는 멀티플랫폼 UI 프레임워크입니다. 게임패드/키보드/마우스 입력을 통합하고, 포커스 관리, 입력 라우팅, 플랫폼별 버튼 아이콘 자동화를 제공합니다.

플러그인: CommonUI 활성화 필요

1. 핵심 개념

CommonActivatableWidget: 활성화/비활성화 상태를 가진 위젯
  - Activate()  → 입력 포커스 받음
  - Deactivate() → 이전 포커스 반환

CommonButtonBase: 플랫폼별 버튼 아이콘 자동화
  - PC: E키 / Xbox: A버튼 / PlayStation: ×버튼 자동 표시

CommonTabListWidget: 탭 기반 네비게이션

2. CommonActivatableWidget 구현

// C++ 기반 팝업 위젯
UCLASS()
class UInventoryWidget : public UCommonActivatableWidget
{
    GENERATED_BODY()

public:
    // 활성화 시 호출
    virtual void NativeOnActivated() override
    {
        Super::NativeOnActivated();

        // 일시정지 등 처리
        UGameplayStatics::SetGamePaused(this, true);

        // 초기 포커스 설정
        if (UWidget* FirstFocusable = GetDesiredFocusTarget())
        {
            FirstFocusable->SetFocus();
        }
    }

    // 비활성화 시 호출 (Deactivate() 또는 Back 입력)
    virtual void NativeOnDeactivated() override
    {
        Super::NativeOnDeactivated();
        UGameplayStatics::SetGamePaused(this, false);
    }

    // 초기 포커스 대상 지정
    virtual UWidget* NativeGetDesiredFocusTarget() const override
    {
        return ItemListView; // 첫 포커스를 리스트뷰로
    }

protected:
    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UCommonListView> ItemListView;
};

3. CommonButtonBase — 플랫폼 아이콘

// 게임패드/키보드 입력에 따라 아이콘 자동 전환
UCLASS()
class UInteractButton : public UCommonButtonBase
{
    GENERATED_BODY()

protected:
    void NativePreConstruct() override
    {
        Super::NativePreConstruct();

        // 버튼에 트리거 입력 액션 연결
        // 에디터에서 설정: TriggeringInputAction = IA_Interact
    }

    // 버튼 클릭 시 처리
    void NativeOnClicked() override
    {
        Super::NativeOnClicked();
        OnInteractPressed.Broadcast();
    }

public:
    DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnInteractPressed);
    UPROPERTY(BlueprintAssignable)
    FOnInteractPressed OnInteractPressed;
};

에디터 설정:
UCommonButtonBase → Triggering Input Action: IA_Interact
Common UI가 자동으로:
  - PC 키보드: E 아이콘 표시
  - Xbox: A 버튼 아이콘 표시
  - PlayStation: X 버튼 아이콘 표시

// 팝업 스택 관리
UCLASS()
class UMainHUD : public UUserWidget
{
    GENERATED_BODY()

    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UCommonActivatableWidgetStack> ModalStack;

    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UCommonActivatableWidgetStack> MenuStack;

public:
    // 팝업 열기
    void OpenInventory()
    {
        ModalStack->AddWidget<UInventoryWidget>(UInventoryWidget::StaticClass());
    }

    // 메뉴 열기 (이전 메뉴 위에 쌓임)
    void OpenSettings()
    {
        auto* SettingsWidget = MenuStack->AddWidget<USettingsWidget>(
            USettingsWidget::StaticClass());
        // SettingsWidget은 자동으로 활성화됨
    }

    // 최상위 위젯 닫기 (Back 입력과 동일)
    void CloseTopWidget()
    {
        MenuStack->GetActiveWidget()->DeactivateWidget();
    }
};

5. CommonTabListWidget — 탭 네비게이션

UCLASS()
class UMainMenu : public UCommonActivatableWidget
{
    GENERATED_BODY()

    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UCommonTabListWidgetBase> TabList;

    UPROPERTY(meta = (BindWidget))
    TObjectPtr<UCommonAnimatedSwitcher> TabContentSwitcher;

protected:
    void NativeConstruct() override
    {
        Super::NativeConstruct();

        // 탭 등록
        TabList->RegisterTab(FName("Play"),     PlayTabWidget);
        TabList->RegisterTab(FName("Store"),    StoreTabWidget);
        TabList->RegisterTab(FName("Settings"), SettingsTabWidget);

        // 탭 변경 이벤트
        TabList->OnTabSelected.AddDynamic(this, &UMainMenu::OnTabChanged);

        // 첫 탭 활성화
        TabList->SelectTabByID(FName("Play"));
    }

    UFUNCTION()
    void OnTabChanged(FName TabId)
    {
        // 탭에 맞는 콘텐츠 전환
        if (TabId == FName("Play"))
            TabContentSwitcher->SetActiveWidgetIndex(0);
        else if (TabId == FName("Store"))
            TabContentSwitcher->SetActiveWidgetIndex(1);
    }
};

6. 입력 라우팅

// Common UI는 입력을 계층적으로 라우팅
// 최상위 활성화된 ActivatableWidget이 입력을 먼저 처리

// 게임패드 Back 버튼 처리
UCLASS()
class UPopupWidget : public UCommonActivatableWidget
{
    GENERATED_BODY()

protected:
    // Back 입력 핸들링
    FReply NativeOnFocusReceived(const FGeometry& InGeometry,
        const FFocusEvent& InFocusEvent) override
    {
        return FReply::Handled();
    }

    // 위젯이 Back 입력으로 닫힐 수 있는지
    bool NativeSupportedActivationInputActions(
        TArray<FDataTableRowHandle>& OutActions) override
    {
        // Back 입력 시 자동 Deactivate
        return true;
    }
};

7. 플랫폼 입력 데이터

// CommonInputSettings에서 플랫폼별 아이콘 매핑 설정
// 프로젝트 설정 → Common Input → Input Data

// 런타임 플랫폼 감지
ECommonInputType InputType = UCommonInputSubsystem::Get(GetPlayerController())
    ->GetCurrentInputType();

if (InputType == ECommonInputType::Gamepad)
{
    // 게임패드 UI 표시
}
else
{
    // 키보드/마우스 UI 표시
}

정리

CommonActivatableWidget: 포커스/입력 관리, Activate/Deactivate 상태
UCommonActivatableWidgetStack: 팝업 스택 관리
CommonButtonBase: 플랫폼별 버튼 아이콘 자동화
CommonTabListWidgetBase: 탭 네비게이션
Back 입력 자동 처리, 게임패드 포커스 관리 내장

UE5 Common UI 플러그인 완전 가이드

개요

1. 핵심 개념

2. CommonActivatableWidget 구현

3. CommonButtonBase — 플랫폼 아이콘

4. 위젯 스택 (Activatable Widget Stack)

5. CommonTabListWidget — 탭 네비게이션

6. 입력 라우팅

7. 플랫폼 입력 데이터

정리

참고 자료