[Unreal]#FInputMode

#1. 개념

 

1. Input Mode

Unreal Engine에서 PlayerController는 입력 모드를 통해 게임 내에서 입력이 어떻게 처리될지를 결정합니다. 주요 Input Mode는 3가지로, FInputModeGameOnly, FInputModeUIOnly, 그리고 FInputModeGameAndUI가 있습니다. 

 

2. FInputModeGameOnly

입력을 게임 월드에 전달하고, 마우스 커서를 기본적으로 숨기지만 별도의 설정을 통해 나타내는 것 또한 가능합니다. 주로 게임 플레이 중에 사용됩니다. 다만, FInputModeGameOnly의 경우, 마우스 커서를 나타내는 것은 가능하지만 기본적으로 UI 요소로서의 자동 입력 라우팅을 비활성화합니다. 따라서, FInputModeGameOnly를 Input Mode로 설정했을 경우, 마우스 커서와 UI요소의 상호작용은 직접 구현해야 합니다.

 

3. FInputModeUIOnly

사용자 입력은 UI 시스템으로 자동 라우팅되어 우선 처리되며, 기본적으로 게임 월드로 입력 전달은 차단됩니다. 이때, FInputModeUIOnly에서 제공하는 SetWidgetToFocus 함수를 통해 포커싱 된 위젯은 UI 시스템으로 자동 라우팅된 입력을 우선 처리할 수 있는 우선권을 가지며, 이를 UI 내비게이션 시스템이라고 합니다. 

 

4. FInputModeGameAndUI

게임 월드와 UI 요소 모두에 입력을 전달합니다. 다만, 입력이 UI 시스템으로 자동 라우팅 되어  우선적으로 전달되며, 이후 처리되지 않은 입력은 게임 월드에 전달됩니다. 주로, HUD나 화면에 항상 표시되는 Overlay UI가 있는 게임 플레이에서 할 용 됩니다.

 

5. EMouseLockMode

// Engine/Source/Runtime/ApplicationCore/Public/GenericPlatform/GenericApplicationMessageHandler.h

enum class EMouseLockMode
{
    DoNotLock,
    LockOnCapture,
    LockAlways,
    LockInFullscreen
};

// Usage example in a PlayerController
void AMyPlayerController::SetupInputMode()
{
    FInputModeGameAndUI InputMode;
    
    // Choose one of the following based on your game's needs:
    InputMode.SetMouseLockMode(EMouseLockMode::DoNotLock);
    // or
    InputMode.SetMouseLockMode(EMouseLockMode::LockOnCapture);
    // or
    InputMode.SetMouseLockMode(EMouseLockMode::LockAlways);
    // or
    InputMode.SetMouseLockMode(EMouseLockMode::LockInFullscreen);

    SetInputMode(InputMode);
}

EMouseLockMode 열거형은 주로 FInputModeGameAndUI에서 활용합니다. 주로, 게임 플레이 과정에서 키보드 입력을 처리하는 동시에, 마우스 커서를 나타내고 화면의 UI들과 상호작용하는 과정에서 그 규칙을 설정합니다. FInputModeGameOnly는 제한적이지만, 명시적으로 마우스 잠금 설정이 가능합니다.

 

1. EMouseLockMode::DoNotLock: 마우스를 잠그지 않고, 마우스 커서가 자유롭게 화면 전체를 움직일 수 있습니다.
2. EMouseLockMode::LockAlways: 항상 마우스를 잠급니다. 마우스 커서가 게임 화면 내 고정되며, 화면 밖으로 나갈 수 없습니다. 특히, FPS 등의 장르에서 마우스를 화면 중심에 고정하고 조준점 위치를 화면의 가운데에 고정하는데 활용됩니다.
3. EMouseLockMode::LockInFullScreen: 전체 화면 모드에서만 마우스를 잠급니다. 게임이 전체 화면일 때만 마우스를 잠그고, 창 모드에서는 잠그지 않습니다. 전체 화면에서는 게임에 집중하고, 창 모드에서는 다른 응용프로그램과의 전환을 쉽게 하고 싶을 때 활용합니다.

 

---

 

#2. FInputModeGameOnly

 

1. 코드

// Engine/Source/Runtime/Engine/Classes/GameFramework/PlayerController.h

struct FInputModeGameOnly : public FInputModeDataBase
{
    FInputModeGameOnly()
    {
        bCanConsumeCaptureMouseDown = true;
    }

    /** If true (default) will capture all mouse down events while in this input mode */
    FInputModeGameOnly& SetConsumeCaptureMouseDown(bool InCanConsumeCaptureMouseDown)
    {
        bCanConsumeCaptureMouseDown = InCanConsumeCaptureMouseDown;
        return *this;
    }

private:
    bool bCanConsumeCaptureMouseDown;

    friend class FSlateApplication;
};

// Usage example in a PlayerController or GameMode
void AMyPlayerController::SetupGameOnlyInputMode()
{
    FInputModeGameOnly InputMode;
    InputMode.SetConsumeCaptureMouseDown(true);
    SetInputMode(InputMode);

    // Optionally, hide the mouse cursor
    bShowMouseCursor = false;

    // If you want to lock the mouse to the viewport (common in FPS games)
    FViewport* Viewport = GetWorld()->GetGameViewport()->Viewport;
    if (Viewport)
    {
        Viewport->LockMouseToViewport(true);
        Viewport->CaptureMouse(true);
    }
}

"ConsumeMouseCaptureDown" 변수는 마우스 다운 이벤트를 소비할지 여부를 결정합니다. 마우스 다운 이벤트 소비는 해당 이벤트를 게임 내에서 처리하고, 다른 시스템으로 전파하지 않는다는 의미입니다. 따라서, 기본 값인 true로 설정할 경우, 게임 월드에서 모든 마우스 클릭을 캡처하고, 이는 게임 창 밖으로 마우스가 빠져나가는 것을 방지합니다. 반대로, 마우스 클릭이 게임을 통과하여 다른 애플리케이션이나 운영체제로 전달될 수 있습니다. 결과적으로, ConsumeMouseCaptureDown 멤버 변수는 전체 화면 게임에서 마우스를 게임 내 가둬둡니다. 특히 FPS 게임에서 마우스 커서는 숨기고, 마우스를 Viewport에 고정하는 등에 활용됩니다. 

 

---

 

#3. FInputModeUIOnly

 

1. 코드

// Engine/Source/Runtime/Engine/Classes/GameFramework/PlayerController.h

struct FInputModeUIOnly : public FInputModeDataBase
{
    FInputModeUIOnly()
    {
        bFocusWhileLocked = true;
    }

    /** Widget to focus when this input mode is set */
    FInputModeUIOnly& SetWidgetToFocus(const TSharedPtr<SWidget>& InWidgetToFocus)
    {
        WidgetToFocus = InWidgetToFocus;
        return *this;
    }

    /** Focus option to use when this input mode is set */
    FInputModeUIOnly& SetLockMouseToViewportBehavior(EMouseLockMode InMouseLockMode)
    {
        MouseLockMode = InMouseLockMode;
        return *this;
    }

    /** Whether to focus the user-specified widget when the viewport is locked */
    FInputModeUIOnly& SetFocusWidgetWhenLocked(bool bInFocusWhileLocked = true)
    {
        bFocusWhileLocked = bInFocusWhileLocked;
        return *this;
    }

private:
    TSharedPtr<SWidget> WidgetToFocus;
    EMouseLockMode MouseLockMode;
    bool bFocusWhileLocked;

    friend class FSlateApplication;
};

// Usage example
void AMyPlayerController::SetupUIOnlyInputMode()
{
    FInputModeUIOnly InputMode;
    InputMode.SetWidgetToFocus(MyUIWidget);
    InputMode.SetLockMouseToViewportBehavior(EMouseLockMode::DoNotLock);
    SetInputMode(InputMode);
}

FInputModeUIOnly는 SetLockMouseToViewportBehavior, SetFocusWidgetWhenLocked 등의 메서드를 활용해 입력 자동 라우팅의 우선권을 갖는 위젯을 설정하거나, 마우스 잠금 등 UI 관련 설정이 대부분입니다.

 

---

 

#4. FInputModeGameAndUI

 

1. 코드

// Engine/Source/Runtime/Engine/Classes/GameFramework/PlayerController.h

struct FInputModeGameAndUI : public FInputModeDataBase
{
    FInputModeGameAndUI()
    {
        bHideCursorDuringCapture = true;
        SetMouseLockMode(EMouseLockMode::DoNotLock);
    }

    /** Mouse lock mode for this input mode */
    FInputModeGameAndUI& SetMouseLockMode(EMouseLockMode InMouseLockMode)
    {
        MouseLockMode = InMouseLockMode;
        return *this;
    }

    /** Whether to hide the cursor during capture */
    FInputModeGameAndUI& SetHideCursorDuringCapture(bool bInHideCursorDuringCapture)
    {
        bHideCursorDuringCapture = bInHideCursorDuringCapture;
        return *this;
    }

private:
    EMouseLockMode MouseLockMode;
    bool bHideCursorDuringCapture;

    friend class FSlateApplication;
};

// Usage example
void AMyPlayerController::SetupGameAndUIInputMode()
{
    FInputModeGameAndUI InputMode;
    InputMode.SetMouseLockMode(EMouseLockMode::LockOnCapture);
    InputMode.SetHideCursorDuringCapture(false);
    SetInputMode(InputMode);
}

SetMouseLockMode를 통해 마우스 잠금 모드 설정, SetHideCursorDuringCapture를 통해 마우스 클릭 이벤트 발생 시 커서 숨김 여부 등의 설정이 가능합니다. 예를 들면, 로그 라이크 장르의 게임에서 키 입력을 통해 게임월드에서 로직을 처리하는 동시에, 마우스 커서를 화면에 나타내고 HUD와 상호작용하도록 설정할 수 있습니다. 

 

---