unreal-enhanced-input

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unreal Enhanced Input

Wire player input the modern UE5 way with the Enhanced Input system: data-driven Input Actions and Mapping Contexts instead of the legacy Project Settings axis/action mappings. Targets UE 5.4+ (Enhanced Input is the default; legacy input is deprecated).

使用Enhanced Input系统以UE5的现代方式配置玩家输入：采用数据驱动的Input Actions和Mapping Contexts，替代传统的项目设置轴/动作映射。适用于**UE 5.4+**版本（Enhanced Input为默认选项；传统输入已被弃用）。

When to use

使用场景

Use when adding movement/look/jump/fire input, creating Input Action (
```
IA_
```
) and Input Mapping Context (
```
IMC_
```
) assets, applying modifiers/triggers, adding a mapping context to a player, or binding actions in C++ or Blueprints.
Use when the project has
```
IA_*
```
/
```
IMC_*
```
assets or references
```
EnhancedInput
```
.

When not to use: engine-agnostic input architecture (rebinding strategy, buffering, multi-device design) →

input-systems

. The Pawn/Character C++ those bindings live in →

unreal-cpp-gameplay

适用于添加移动/视角/跳跃/射击输入、创建Input Action（
```
IA_
```
）和Input Mapping Context（
```
IMC_
```
）资源、应用修改器/触发器、为玩家添加映射上下文，或在C++或Blueprints中绑定动作的场景。
适用于项目包含
```
IA_*
```
/
```
IMC_*
```
资源或引用
```
EnhancedInput
```
的情况。

不适用于： 引擎无关的输入架构（重绑定策略、缓冲、多设备设计）→ 请参考

input-systems

。绑定所在的Pawn/Character C++类 → 请参考

unreal-cpp-gameplay

。

Core workflow

核心工作流程

Enable the module/plugin. Enhanced Input is on by default in UE5; for C++ binding add
```
"EnhancedInput"
```
to
```
PublicDependencyModuleNames
```
in
```
*.Build.cs
```
.
Create Input Actions (
IA_
). Each has a Value Type:
```
Digital (bool)
```
for buttons,
```
Axis1D (float)
```
for triggers,
```
Axis2D (Vector2D)
```
for movement/look.
Create an Input Mapping Context (
IMC_
) that maps keys/buttons to those actions. Use Modifiers to shape raw input (Negate, Swizzle Input Axis Values, Dead Zone) — e.g. WASD into one Axis2D needs Negate on A/S and a Swizzle on W/S. Use Triggers (Pressed, Hold, Tap) to decide when an action fires.

Add the mapping context to the player via the

EnhancedInputLocalPlayerSubsystem

(

AddMappingContext(IMC, Priority)

), usually in

BeginPlay

/possession.

Bind actions to handlers by

ETriggerEvent

(

Triggered

Started

Completed

, …) on the

EnhancedInputComponent

, and read the

FInputActionValue

in the handler.

Verify in PIE; the Enhanced Input debugging console commands (
```
showdebug enhancedinput
```
) show which actions trigger and their values.

启用模块/插件。Enhanced Input在UE5中默认开启；若要在C++中绑定，需在
```
*.Build.cs
```
的
```
PublicDependencyModuleNames
```
中添加
```
"EnhancedInput"
```
。
创建Input Actions（
IA_
）。每个动作都有一个值类型：
```
Digital (bool)
```
适用于按钮，
```
Axis1D (float)
```
适用于扳机键，
```
Axis2D (Vector2D)
```
适用于移动/视角控制。
创建Input Mapping Context（
IMC_
），将按键/按钮映射到这些动作。使用修改器调整原始输入（取反、交换输入轴值、死区）——例如，将WASD映射到单个Axis2D时，需要对A/S键取反，对W/S键交换输入轴值。使用触发器（按下、按住、点击）决定动作触发的时机。
通过
EnhancedInputLocalPlayerSubsystem
为玩家添加映射上下文（
```
AddMappingContext(IMC, Priority)
```
），通常在
```
BeginPlay
```
或角色拥有时执行。
在
EnhancedInputComponent
上通过
ETriggerEvent
（
Triggered
、
Started
、
Completed
等）将动作绑定到处理函数，并在处理函数中读取
```
FInputActionValue
```
。
在PIE（Play In Editor）中验证；Enhanced Input调试控制台命令（
```
showdebug enhancedinput
```
）可显示触发的动作及其数值。

Patterns

实现模式

1. Add the mapping context (C++ Character)

1. 添加映射上下文（C++ Character类）

cpp

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>.

cpp

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是UPROPERTY(EditAnywhere) TObjectPtr<UInputMappingContext>类型。

2. Bind actions and read values

2. 绑定动作并读取数值

cpp

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);
}

cpp

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

    // 当插件激活时，该组件为Enhanced Input组件。
    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类型的动作
    AddMovementInput(GetActorForwardVector(), Axis.Y);
    AddMovementInput(GetActorRightVector(),   Axis.X);
}

3. Blueprint equivalent (node flow)

3. 蓝图等效实现（节点流程）

text

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)

text

Event BeginPlay
  -> 获取控制器 -> 转换为PlayerController -> 获取本地玩家
  -> 获取EnhancedInputLocalPlayerSubsystem -> 添加映射上下文（IMC_Default，优先级0）

// IA_Move在Character的事件图表中作为独立事件节点暴露：
EnhancedInputAction IA_Move (Triggered)
  -> 动作数值（Vector2D） -> 添加移动输入（向前向量 * Y，向右向量 * X）

Pitfalls

常见陷阱

No input at all — the mapping context was never added (
```
AddMappingContext
```
), or the player has no Local Player yet. Add it after possession/
```
BeginPlay
```
.

Link/compile error binding in C++ —

"EnhancedInput"

isn't in

Build.cs

PublicDependencyModuleNames

WASD only moves on two keys / wrong axis — Axis2D needs Modifiers: Negate on the negative keys (A, S) and a Swizzle Input Axis Values on the vertical (W/S) so both axes map correctly. Raw bindings without modifiers misbehave.
Get<FVector2D>()
returns zero — value-type mismatch: the Input Action is Digital/Axis1D, not Axis2D. Match the
```
Get<T>()
```
to the action's Value Type.
Action fires every frame unexpectedly —
```
Triggered
```
repeats while held for a Down trigger; use
```
Started
```
/
```
Completed
```
for one-shots (jump press/release), or a Pressed/Tap trigger.
Two contexts fight — multiple mapping contexts stack by Priority; a higher-priority context can consume a key. Manage with priorities and
```
RemoveMappingContext
```
.

完全无输入——映射上下文从未添加（未调用
```
AddMappingContext
```
），或者玩家尚未拥有本地玩家。应在角色拥有后或
```
BeginPlay
```
时添加。
C++绑定时出现链接/编译错误——
```
Build.cs
```
的
```
PublicDependencyModuleNames
```
中未添加
```
"EnhancedInput"
```
。
WASD仅能通过两个按键移动/轴方向错误——Axis2D需要修改器：对负方向按键（A、S）取反，对垂直方向（W/S）交换输入轴值，这样两个轴才能正确映射。未使用修改器的原始绑定会出现异常行为。
Get<FVector2D>()
返回零值——值类型不匹配：Input Action是Digital/Axis1D类型，而非Axis2D。需确保
```
Get<T>()
```
与动作的值类型匹配。
动作意外每帧触发——对于按下触发器，
```
Triggered
```
会在按住期间重复触发；对于一次性操作（跳跃按下/释放），请使用
```
Started
```
/
```
Completed
```
，或使用Pressed/Tap触发器。
两个上下文冲突——多个映射上下文按优先级堆叠；高优先级上下文会占用按键。需通过优先级管理和
```
RemoveMappingContext
```
来处理。

References

参考资料

For a complete first-/third-person C++ Character with Enhanced Input (header + source, including look/jump and a control-rebind note), read
```
references/cpp-setup.md
```
.

Primary docs: "Enhanced Input in Unreal Engine" (

https://dev.epicgames.com/documentation/en-us/unreal-engine/enhanced-input-in-unreal-engine

如需完整的第一/第三人称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

）。

unreal-enhanced-input

Original

Translation

Unreal Enhanced Input

Unreal Enhanced Input

When to use

使用场景

Core workflow

核心工作流程

Patterns

实现模式

1. Add the mapping context (C++ Character)

1. 添加映射上下文（C++ Character类）

2. Bind actions and read values

2. 绑定动作并读取数值

3. Blueprint equivalent (node flow)

3. 蓝图等效实现（节点流程）

Pitfalls

常见陷阱

References

参考资料

Related skills

相关技能