2-2. Input Routing | UE5 UI Deep Dive

01

입력 라우팅 기본 원리

CommonUI가 입력 이벤트를 처리하는 흐름

CommonUI의 입력 라우팅은 UCommonUIActionRouterBase가 중앙에서 관리합니다. 입력 이벤트는 노드 트리의 가장 깊은 활성 노드(leaf)에서 시작하여 루트를 향해 버블업(bubble up) 합니다.

하드웨어 입력

→

Slate Input Processor

→

CommonGameViewportClient

→

Action Router

→

Active Node

C++ - 입력 라우팅 흐름
// CommonGameViewportClient가 입력을 가로채서 ActionRouter에 전달
// ActionRouter는 현재 활성 노드 스택을 확인하고
// 가장 위(가장 최근 활성화된) 노드부터 입력을 전달

// 입력 처리 우선순위:
// 1. 현재 활성 Activatable Widget의 등록된 액션
// 2. 부모 Activatable Widget의 등록된 액션
// 3. 게임 레이어 (게임플레이 입력)

// 위젯에서 입력 액션 등록
void UMyMenuWidget::NativeOnActivated()
{
    Super::NativeOnActivated();

    // UI 액션 바인딩 - 이 위젯이 활성 상태일 때만 동작
    RegisterUIActionBinding(
        FBindUIActionArgs(
            BackInputActionData,    // UInputAction 또는 CommonUI InputActionDataTable
            false,                  // bDisplayInActionBar
            FSimpleDelegate::CreateUObject(this, &UMyMenuWidget::HandleBack)
        )
    );
}

입력 소비(Consumption) 규칙

활성 노드가 입력을 처리하면 해당 입력은 소비(consumed)되어 하위 노드나 게임 레이어로 전파되지 않습니다. 이것이 CommonUI가 "메뉴가 열려 있으면 게임 입력 차단" 로직을 자동으로 처리하는 방식입니다.

02

Action Router 설정

입력 라우팅의 중앙 관리자 구성

C++ - CommonUI Action Router 접근
// Action Router는 Local Player에 속한 서브시스템
UCommonUIActionRouterBase* ActionRouter =
    GetOwningLocalPlayer()->GetSubsystem<UCommonUIActionRouterBase>();

// 현재 활성 입력 모드 확인
ECommonInputMode CurrentMode = ActionRouter->GetActiveInputMode();
// ECommonInputMode::Menu  - UI 전용
// ECommonInputMode::Game  - 게임 전용
// ECommonInputMode::All   - 둘 다 허용

// 입력 모드 수동 설정 (일반적으로 Activatable Widget이 자동 관리)
ActionRouter->SetActiveUIInputConfig(
    FUIInputConfig(ECommonInputMode::Menu, EMouseCaptureMode::NoCapture)
);

Input Action Data Table

CommonUI는 UCommonInputActionDataBase를 통해 입력 액션을 데이터 기반으로 관리합니다. 각 플랫폼/디바이스에 맞는 아이콘과 키 매핑을 자동 제공합니다.

C++ - Input Action Data 정의
// CommonInputActionDataBase 에셋에서 정의하는 내용:
// - 액션 이름 (예: "Back", "Confirm", "Cancel")
// - 키보드/마우스 매핑 (예: Escape, Enter)
// - 게임패드 매핑 (예: B 버튼, A 버튼)
// - 플랫폼별 아이콘 텍스처

// 프로젝트 설정에서 CommonInput 설정:
// Project Settings > Game > Common Input Settings
//   > Input Data 에셋 지정
//   > Platform Input Data 설정

UPROPERTY(EditDefaultsOnly, Category = "Input")
UCommonInputActionDataBase* BackActionData;

UPROPERTY(EditDefaultsOnly, Category = "Input")
UCommonInputActionDataBase* ConfirmActionData;

03

Enhanced Input 통합

CommonUI와 Enhanced Input 시스템의 연동

UE 5.1+부터 CommonUI는 Enhanced Input과의 실험적 통합을 지원합니다. 기존 CommonInput 데이터 대신 UInputAction을 직접 사용할 수 있습니다.

C++ - Enhanced Input과 CommonUI 연동
// 프로젝트 설정에서 Enhanced Input 통합 활성화
// Project Settings > Game > Common Input Settings
//   > "Enable Enhanced Input Support" = true

// Activatable Widget에서 Enhanced Input Action 사용
UPROPERTY(EditDefaultsOnly, Category = "Input")
UInputAction* IA_Back;

void UMyActivatableMenu::NativeOnActivated()
{
    Super::NativeOnActivated();

    // Enhanced Input Action을 CommonUI 액션으로 등록
    FBindUIActionArgs BindArgs(IA_Back, false,
        FSimpleDelegate::CreateUObject(this, &UMyActivatableMenu::GoBack));
    RegisterUIActionBinding(BindArgs);
}

void UMyActivatableMenu::GoBack()
{
    // 이 위젯을 비활성화하여 이전 메뉴로 돌아감
    DeactivateWidget();
}

Enhanced Input 통합 주의사항

Enhanced Input 통합은 아직 실험적(Experimental) 기능입니다. CommonUI의 플랫폼별 아이콘 자동 전환을 완전히 활용하려면 여전히 CommonInputActionDataBase 에셋 설정이 필요합니다. Enhanced Input Action만 단독으로 사용하면 아이콘 전환 기능이 제한될 수 있습니다.

04

입력 디바이스 전환 감지

마우스/키보드와 게임패드 전환을 감지하고 UI를 적응시키는 방법

C++ - 입력 디바이스 변경 감지
// CommonUI는 입력 디바이스 변경을 자동 감지
// UCommonInputSubsystem을 통해 접근 가능

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

    // 입력 타입 변경 델리게이트 바인딩
    UCommonInputSubsystem* InputSubsystem =
        GetOwningLocalPlayer()->GetSubsystem<UCommonInputSubsystem>();

    if (InputSubsystem)
    {
        InputSubsystem->OnInputMethodChangedNative.AddUObject(
            this, &UMyHUD::OnInputMethodChanged);
    }
}

void UMyHUD::OnInputMethodChanged(ECommonInputType NewInputType)
{
    switch (NewInputType)
    {
    case ECommonInputType::MouseAndKeyboard:
        // 마우스 커서 표시, 키보드 프롬프트로 전환
        ShowMousePrompts();
        break;

    case ECommonInputType::Gamepad:
        // 게임패드 아이콘 표시, 포커스 네비게이션 활성화
        ShowGamepadPrompts();
        break;

    case ECommonInputType::Touch:
        // 터치 최적화 UI 전환
        ShowTouchPrompts();
        break;
    }
}

UCommonActionWidget 활용

UCommonActionWidget은 입력 디바이스 변경을 자동으로 감지하여 해당 디바이스의 아이콘으로 전환합니다. 수동으로 디바이스 전환 로직을 구현하는 대신 이 위젯을 사용하면 코드량을 크게 줄일 수 있습니다.

SUMMARY

핵심 요약

CommonUI 입력 라우팅은 Action Router가 중앙에서 관리하며, 입력은 가장 깊은 활성 노드에서 루트로 버블업됩니다
활성 노드가 입력을 소비하면 하위 노드/게임 레이어로 전파되지 않아 자동 입력 차단이 구현됩니다
RegisterUIActionBinding()으로 위젯별 입력 액션을 등록하며, 위젯 활성화 상태에 따라 자동 관리됩니다
Enhanced Input 통합은 UE 5.1+에서 실험적으로 지원되며, UInputAction을 직접 사용할 수 있습니다
UCommonInputSubsystem의 OnInputMethodChanged로 마우스/게임패드/터치 전환을 감지합니다

PRACTICE

도전 과제

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

실습 1: Action Router 입력 라우팅 설정

CommonUI Action Router를 통해 메뉴가 열렸을 때 게임 입력을 차단하고, 메뉴를 닫으면 게임 입력이 복원되는 시스템을 구현하세요. RegisterUIActionBinding으로 ESC 키에 메뉴 닫기를 바인딩합니다.

실습 2: 입력 디바이스 전환 감지

UCommonInputSubsystem을 사용하여 키보드/마우스와 게임패드 간 전환을 감지하고, UI에 표시되는 입력 아이콘(키보드 아이콘 vs 게임패드 아이콘)을 자동으로 교체하는 시스템을 구현하세요.

심화 과제

게임 HUD, 인벤토리, 확인 팝업 등 3개 이상의 UI 레이어가 중첩될 때 올바른 입력 라우팅이 작동하도록 CommonUI 노드 트리를 설계하고, 각 레이어의 활성/비활성 전환을 검증하세요.