unreal-enhanced-input

Unreal Enhanced Input

以现代 UE5 方式接入玩家输入，使用 Enhanced Input 系统：采用数据驱动的 Input Actions 和 Mapping Contexts，而非旧版 Project Settings 轴／动作映射。 面向 UE 5.8（Enhanced Input 为默认系统；旧版输入已弃用）。

适用场景

• 添加移动／视角／跳跃／开火输入，创建 Input Action (IA_) 和 Input Mapping Context (IMC_) 资源，应用修饰器／触发器，为玩家添加映射上下文，或在 C++ 或 Blueprints 中绑定动作时使用。
• 项目包含 IA_*/IMC_* 资源或引用了 EnhancedInput 时使用。

不适用场景： 与引擎无关的输入架构（重新绑定策略、缓冲、多设备设计）→ input-systems。这些绑定所在的 Pawn/Character C++ 类 → unreal-cpp-gameplay。

核心工作流

1. 启用模块／插件。 Enhanced Input 在 UE5 中默认启用；要在 C++ 中绑定输入，请将 "EnhancedInput" 添加到 *.Build.cs 中的 PublicDependencyModuleNames。
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 映射到一个 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 只有两个按键能移动／轴向错误 — Axis2D 需要 Modifiers：对负向按键（A、S）使用 Negate，对垂直方向（W/S）使用 Swizzle Input Axis Values，这样两条轴才能正确映射。未使用修饰器的原始绑定会导致异常。
• Get<FVector2D>() 返回零 — 值类型不匹配：Input Action 是 Digital／Axis1D，而非 Axis2D。让 Get<T>() 与动作的 Value Type 保持一致。
• 动作意外地每帧触发 — 对于 Down 触发器，按住时 Triggered 会重复触发；单次操作（按下／松开跳跃）请使用 Started／Completed，或使用 Pressed／Tap 触发器。
• 两个上下文相互冲突 — 多个映射上下文会按 Priority 叠加；优先级更高的上下文可能会消耗按键。请通过优先级和 RemoveMappingContext 进行管理。

参考资料

• 如需查看完整的第一／第三人称 C++ Character 与 Enhanced Input 示例（包含头文件和源文件、视角／跳跃，以及控制重新绑定说明），请阅读 references/cpp-setup.md。
• 主要文档："Enhanced Input in Unreal Engine" (https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine)。

相关技能

• input-systems — 与引擎无关的输入架构和重新绑定策略。
• unreal-cpp-gameplay — Character／Pawn 类和模块设置。
• fps-shooter — 将输入与 3D 控制器和射击功能结合。