Back to Details

unreal-enhanced-input

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unreal Enhanced Input

Unreal Enhanced Input

Purpose

目的

Implement Unreal input with Enhanced Input — Input Actions, Mapping Contexts, triggers/modifiers, and runtime remapping.
使用Enhanced Input实现Unreal输入系统——涵盖Input Actions、Mapping Contexts、触发器/修改器以及运行时重映射。

Use When

适用场景

  • adding or unifying input handling for an Unreal project (UE5 Enhanced Input)
  • gameplay code binds raw keys/axes or legacy input names directly
  • input must change by context (gameplay, vehicles, menus, cinematics) or support rebinding
  • 为Unreal项目（UE5 Enhanced Input）添加或统一输入处理逻辑
  • 游戏玩法代码直接绑定原始按键/轴或旧版输入名称
  • 输入需根据场景（游戏玩法、载具、菜单、过场动画）变化，或支持重新绑定

Inputs

输入信息

  • list of gameplay actions and their value types (bool, Axis1D/2D/3D)
  • supported devices and platforms (keyboard/mouse, gamepad, touch)
  • gameplay contexts that change available input (on foot, vehicle, UI, spectator)
  • rebinding, accessibility, and local multiplayer requirements
  • 游戏玩法动作列表及其值类型（bool、Axis1D/2D/3D）
  • 支持的设备和平台（键盘/鼠标、游戏手柄、触控）
  • 会改变可用输入的游戏玩法场景（步行、载具、UI、spectator）
  • 重新绑定、无障碍功能及本地多人游戏需求

Process

实施流程

  1. model each action as an Input Action asset with an explicit value type; gameplay code binds to actions in 
    SetupPlayerInputComponent
    via 
    UEnhancedInputComponent
    , never to raw keys
  2. group bindings into Input Mapping Contexts per gameplay state and add/remove them on the local player's 
    UEnhancedInputLocalPlayerSubsystem
    with explicit priorities, instead of branching inside handlers
  3. put press semantics into Triggers (Pressed, Released, Hold, Tap, Combo) and stick/axis shaping into Modifiers (dead zone, swizzle, negate, scalar) on the action or mapping — not re-implemented in C++/Blueprint handlers
  4. route UI through CommonUI or input modes (
    SetInputMode*
    ) so menus consume input cleanly, and treat "UI open" as a context switch rather than per-handler checks
  5. implement rebinding with Player Mappable Keys (or 
    UEnhancedInputUserSettings
    in newer versions), persist per user, and update on-screen prompts from the active mappings
  6. for local multiplayer, keep contexts and rebinds per 
    ULocalPlayer
    and validate device assignment per player on each target platform
  7. test context transitions explicitly: entering/leaving vehicles, opening menus mid-hold, focus loss, and controller hot-plug
  1. 将每个动作建模为带有明确值类型的Input Action资源；游戏玩法代码在
    SetupPlayerInputComponent
    中通过
    UEnhancedInputComponent
    绑定到动作，绝不直接绑定到原始按键
  2. 按游戏玩法状态将绑定分组到Input Mapping Context中，并通过显式优先级在本地玩家的
    UEnhancedInputLocalPlayerSubsystem
    上添加/移除这些Context，而非在处理程序内分支判断
  3. 将按压语义放入Triggers（Pressed、Released、Hold、Tap、Combo），将摇杆/轴调整放入动作或映射上的Modifiers（死区、轴交换、取反、缩放）——不要在C++/Blueprint处理程序中重新实现这些逻辑
  4. 通过CommonUI或输入模式（
    SetInputMode*
    ）处理UI输入，确保菜单能干净地消费输入，并将“UI打开”视为场景切换，而非逐个处理程序检查
  5. 使用Player Mappable Keys（或新版本中的
    UEnhancedInputUserSettings
    ）实现重新绑定功能，按用户持久化设置，并根据当前激活的映射更新屏幕提示
  6. 对于本地多人游戏，为每个
    ULocalPlayer
    保留独立的Context和重新绑定设置，并在每个目标平台上验证每个玩家的设备分配
  7. 显式测试场景转换：进入/退出载具、按住按键时打开菜单、失去焦点、控制器热插拔

Outputs

输出成果

  • Input Action and Mapping Context asset inventory with priorities
  • trigger/modifier configuration per action
  • context-switch rules (which contexts exist and what adds/removes them)
  • rebinding and persistence design plus device test scenarios
  • 带有优先级的Input Action和Mapping Context资源清单
  • 每个动作的触发器/修改器配置
  • 场景切换规则（存在哪些场景，以及添加/移除它们的条件）
  • 重新绑定与持久化设计，以及设备测试场景

Quality Bar

质量标准

  • no gameplay code binds raw keys, legacy axis names, or 
    IsKeyDown
    checks outside the Enhanced Input setup
  • context switches are mapping-context adds/removes with priorities, not booleans inside input handlers
  • hold/tap/combo semantics live in Triggers so designers can tune them without code changes
  • rebinds persist per player, apply without restart, and drive the input prompts shown on screen
  • a held action that loses its context (menu opens, vehicle exited) cancels cleanly instead of sticking
  • 游戏玩法代码绝不绑定原始按键、旧版轴名称，或在Enhanced Input设置外使用
    IsKeyDown
    检查
  • 场景切换通过添加/移除带有优先级的映射Context实现，而非在输入处理程序内使用布尔值判断
  • 按住/点击/组合等语义存储在Triggers中，以便设计师无需修改代码即可调整
  • 重新绑定设置按玩家持久化，无需重启即可生效，并驱动屏幕上显示的输入提示
  • 当动作所在场景消失（如打开菜单、退出载具）时，按住的动作能干净地取消，而非保持激活状态

Common Failure Modes

常见失败模式

  • one giant mapping context with handler-side branching instead of per-state contexts
  • dead zones and sensitivity hardcoded in handlers, fighting the Modifiers configured on the mapping
  • UI and gameplay both receiving the same press because input modes/CommonUI routing was skipped
  • rebinding implemented against the legacy input ini, which Enhanced Input ignores
  • local multiplayer sharing one set of contexts so player two remaps player one
  • 使用一个巨型映射Context，在处理程序内分支判断，而非按状态拆分Context
  • 在处理程序中硬编码死区和灵敏度，与映射上配置的Modifiers冲突
  • UI和游戏玩法同时接收同一按键输入，因为跳过了输入模式/CommonUI路由
  • 针对旧版输入ini文件实现重新绑定，而Enhanced Input会忽略该文件
  • 本地多人游戏共享一组Context，导致玩家二的重新绑定会影响玩家一

Related Agents

相关Agent

  • unreal-reviewer
  • gameplay-programmer
  • ui-programmer
  • unreal-reviewer
  • gameplay-programmer
  • ui-programmer

Related Commands

相关命令

  • input-review
  • unreal-review
  • verify
  • input-review
  • unreal-review
  • verify

Related Skills

相关技能

  • unreal-gameplay-framework
  • unreal-blueprint-patterns
  • unreal-gameplay-framework
  • unreal-blueprint-patterns

Notes

注意事项

  • Keep this skill aligned with the relevant rules layer and current project documentation.
  • The engine-neutral action-abstraction policy lives in 
    engineering-common/input-abstraction
    ; this skill is the Unreal-specific implementation of it.
  • 保持本技能与相关规则层及当前项目文档一致
  • 引擎无关的动作抽象策略位于
    engineering-common/input-abstraction
    ；本技能是该策略在Unreal中的具体实现