unreal-enhanced-input

Unreal Enhanced Input

レガシーな Project Settings の軸／アクションマッピングの代わりに、データ駆動型の Input Actions と Mapping Contexts を使う Enhanced Input システムで、現代的な UE5 の方法でプレイヤー入力を接続します。 UE 5.8 を対象としています（Enhanced Input がデフォルトで、レガシー入力は非推奨です）。

使用する場面

• 移動／視点操作／ジャンプ／射撃の入力を追加するとき、Input Action（IA_）と Input Mapping Context（IMC_）のアセットを作成するとき、モディファイアー／トリガーを適用するとき、マッピングコンテキストをプレイヤーに追加するとき、または C++ や Blueprint でアクションをバインドするときに使用します。
• プロジェクトに IA_*／IMC_* アセットがある場合や、EnhancedInput を参照している場合に使用します。

使用しない場面： エンジンに依存しない入力 アーキテクチャ（再バインド戦略、バッファリング、マルチデバイス設計）には input-systems を使用します。これらのバインドを配置する Pawn／Character の C++ には unreal-cpp-gameplay を使用します。

基本的なワークフロー

1. モジュール／プラグインを有効にします。 Enhanced Input は UE5 でデフォルトで有効です。C++ でバインドするには、*.Build.cs の PublicDependencyModuleNames に "EnhancedInput" を追加します。
2. Input Actions（IA_）を作成します。 それぞれに Value Type があります。ボタンには Digital (bool)、トリガーには Axis1D (float)、移動／視点操作には Axis2D (Vector2D) を使用します。
3. Input Mapping Context（IMC_）を作成し、 キー／ボタンをそれらのアクションにマッピングします。 生の入力を調整するには Modifiers（Negate、Swizzle Input Axis Values、Dead Zone）を使用します。たとえば、WASD を 1 つの Axis2D にまとめるには、A/S に Negate、W/S に Swizzle が必要です。アクションが いつ 発生するかは Triggers（Pressed、Hold、Tap）で指定します。
4. プレイヤーにマッピングコンテキストを追加します。 EnhancedInputLocalPlayerSubsystem の AddMappingContext(IMC, Priority) を介して追加します。通常は BeginPlay／ポゼッション時に行います。
5. アクションをハンドラーにバインドします。 EnhancedInputComponent 上で ETriggerEvent（Triggered、Started、Completed など）を指定してバインドし、ハンドラー内で FInputActionValue を読み取ります。
6. PIE で検証します。 Enhanced Input のデバッグ用コンソールコマンド （showdebug enhancedinput）を使うと、どのアクションがトリガーされたか、その値を確認できます。

パターン

1. マッピングコンテキストを追加する（C++ Character）

void AMyCharacter::BeginPlay()
{
    Super::BeginPlay();
    if (APlayerController* PC = Cast<APlayerController>(GetController()))
        if (ULocalPlayer* LP = PC->GetLocalPlayer())
            if (auto* Subsystem = LP->GetSubsystem<UEnhancedInputLocalPlayerSubsystem>())
                Subsystem->AddMappingContext(DefaultMappingContext, /*Priority*/ 0);
}
// DefaultMappingContext is a UPROPERTY(EditAnywhere) TObjectPtr<UInputMappingContext>.

2. アクションをバインドして値を読み取る

void AMyCharacter::SetupPlayerInputComponent(UInputComponent* InputComponent)
{
    Super::SetupPlayerInputComponent(InputComponent);

    // The component is an Enhanced Input component when the plugin is active.
    if (UEnhancedInputComponent* EIC = Cast<UEnhancedInputComponent>(InputComponent))
    {
        EIC->BindAction(MoveAction, ETriggerEvent::Triggered, this, &AMyCharacter::Move);
        EIC->BindAction(LookAction, ETriggerEvent::Triggered, this, &AMyCharacter::Look);
        EIC->BindAction(JumpAction, ETriggerEvent::Started,   this, &ACharacter::Jump);
        EIC->BindAction(JumpAction, ETriggerEvent::Completed, this, &ACharacter::StopJumping);
    }
}

void AMyCharacter::Move(const FInputActionValue& Value)
{
    const FVector2D Axis = Value.Get<FVector2D>();          // Axis2D action
    AddMovementInput(GetActorForwardVector(), Axis.Y);
    AddMovementInput(GetActorRightVector(),   Axis.X);
}

3. Blueprint での同等の処理（ノードの流れ）

Event BeginPlay
  -> Get Controller -> Cast To PlayerController -> Get Local Player
  -> Get EnhancedInputLocalPlayerSubsystem -> Add Mapping Context (IMC_Default, Priority 0)

// IA_Move is exposed as its own event node in the Character's Event Graph:
EnhancedInputAction IA_Move (Triggered)
  -> Action Value (Vector2D) -> Add Movement Input (Forward * Y, Right * X)

注意点

• 入力がまったくない — マッピングコンテキストが追加されていない（AddMappingContext）、またはプレイヤーに Local Player がまだありません。ポゼッション後／BeginPlay 後に追加してください。
• C++ でのバインド時にリンク／コンパイルエラーが発生する — Build.cs の PublicDependencyModuleNames に "EnhancedInput" がありません。
• WASD の 2 つのキーでしか移動しない／軸が間違っている — Axis2D には Modifiers が必要です。負のキー（A、S）に Negate を設定し、縦方向（W/S）に Swizzle Input Axis Values を設定して、両方の軸が正しくマッピングされるようにします。モディファイアーなしの生のバインドでは正しく動作しません。
• Get<FVector2D>() がゼロを返す — 値の型が一致していません。Input Action が Axis2D ではなく Digital／Axis1D になっています。Get<T>() をアクションの Value Type に合わせてください。
• アクションが予期せず毎フレーム発生する — Down トリガーでは、押し続けている間 Triggered が繰り返されます。1 回だけ発生させる操作（ジャンプの押下／解放）には Started／Completed、または Pressed／Tap トリガーを使用してください。
• 2 つのコンテキストが競合する — 複数のマッピングコンテキストは Priority に従って重ねて適用されます。優先度の高いコンテキストがキーを消費することがあります。優先度を管理し、RemoveMappingContext を使用してください。

参考資料

• Enhanced Input を使った一人称／三人称 C++ Character の完全な例（ヘッダーとソース、視点操作／ジャンプ、および操作の再割り当てに関する注記を含む）については、references/cpp-setup.md を参照してください。
• 主要ドキュメント：「Unreal Engine の Enhanced Input」 （https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine）。

関連スキル

• input-systems — エンジンに依存しない入力アーキテクチャと再バインド戦略。
• unreal-cpp-gameplay — Character／Pawn クラスとモジュールの設定。
• fps-shooter — 3D コントローラーと射撃に入力を組み合わせます。