Enhanced Input

An overview of the Enhanced Input Plugin.

Choose your operating system:

Windows

macOS

Linux

For Unreal Engine 5 (UE5) projects that require more advanced input features, like complex input handling or runtime control remapping, the Enhanced Input Plugin provides developers with an upgrade path and backward compatibility from the default input system from Unreal Engine 4 (UE4). This plugin implements features like radial dead zones, chorded actions, contextual input and prioritization, as well as the ability to extend your own filtering and processing of raw input data in an Asset-based environment.

Getting Started

To configure your project to use Enhanced Input, enable the Enhanced Input Plugin. You can do this by opening the Edit dropdown menu in the editor and selecting Plugins. Under the Input section of the Plugin List, find and enable the Enhanced Input Plugin, then restart the editor.

image alt text

The plugin will become active after you restart the editor.

Once the editor has restarted, you can set your project to use Enhanced Input Plugin classes instead of the default UE5 input handlers. Go to the Edit dropdown menu and choose Project Settings. From there, locate the Input section (under the Engine heading) and find the Default Classes settings. These will initially contain the standard PlayerInput and InputComponent classes.

image alt text

To use Enhanced Input, change these settings to EnhancedPlayerInput and EnhancedInputComponent, respectively.

image alt text

From the Editor, press the tilde key(~) to open the console command window and enter tREGhe following command:

showdebug enhancedinput

which will provide you with the next steps until everything is configured as required.

Core Concepts

The Enhanced Input system has four main concepts:

  • Input Actions are the communication link between the Enhanced Input system and your project's code. An Input Action can be anything that an interactive character might do, like jumping or opening a door. It can also be used to indicate user input states, like holding a button that changes a character's walking movement to running. Input Actions are separate from raw input; an Input Action is not concerned with the specific input that triggered it, but does know its current state and can report an input value on up to three independent floating-point axes.

As an example, a "pick up item" Action might only need an on/off state, indicating whether or not the user wants the character to pick something up, while a "walk" Action might require two axes to describe the direction and speed at which the user wants the character to walk.

  • Input Mapping Contexts map user inputs to Input Actions and can be dynamically added, removed, or prioritized for each user. You can apply one or more of these Contexts to a local player through its Enhanced Input Local Player Subsystem, and prioritize them to resolve collisions between multiple Actions trying to consume the same input.

For example, consider a single button that can either open doors while the character is walking around in the world, or select an item while the character is looking through a backpack.

Whenever the character is near a door, you add the "open door" Context. If the character opens the backpack, you add a "select item" Input Mapping Context that out-prioritizes the "open door" Context, so that characters looking through a backpack while standing near a door can still select backpack items. When the character closes the backpack, you remove the "select item" Context, enabling the "open door" Context to take effect.

This ensures that the user's inputs will be interpreted correctly based on the character's situation, and prevents the need to program code at the input-handling level with awareness of the door and backpack systems.

  • Modifiers adjust the value of raw input coming from the user's devices. An Input Mapping Context can have any number of modifiers associated with each raw input for an Input Action. Common Modifiers include dead zones, input smoothing over multiple frames, conversion of input vectors from local to world space, along with several others that are included in the plugin. Developers can also create their own Modifiers.

  • Triggers use post-Modifier input values, or the output magnitudes of other Input Actions, to determine whether or not an Input Action should activate. Any Input Action within an Input Mapping Context can have one or more Triggers for each input. For example, taking a photograph might require that the user hold down the Left Mouse Button for a quarter of a second while a separate Input Action for aiming the camera is active.

By combining these concepts, developers can quickly set up input systems ranging from simple to complex, and adjust these systems without having to change project code.

Input Actions

Input Actions are the connection between the system and your project's code. You can create an Input Action by right-clicking in the Context Browser, expanding the Input option, and choosing Input Action.

To trigger an Input Action, you must include it in an Input Mapping Context, and add that Input Mapping Context to the local player's Enhanced Input Local Player Subsystem.

image alt text

To make your Pawn class respond to a triggered Input Action, you must add an event to your Blueprint Graph. Each Input Action generates an event with its own Asset name; for example, if you created an Input Action and named the Asset "MyAction", then the Event name will be "MyAction".

Right-click any open space in your Blueprint Graph and choose the appropriate event from the Enhanced Action Events category in the context menu. You can enter the Asset name to narrow the context menu's results.

image alt text

Finding the MyAction event in the Blueprint Graph's right-click context menu.

If you have multiple Input Action Assets in different folders with the same name, you will see multiple events with that name in this list. Hover over them with the mouse to reveal their tooltip, which will reveal the full Asset name, including the folder path, to make sure you select the one you want.

When you add the event to your Blueprint, it will be collapsed. You can expand the node to see other execution pins and additional data.

image alt text

The fully expanded event node; this will execute the appropriate pin (or pins) on each tick based on the state of "MyAction".

Input Mapping Contexts

Input Mapping Contexts describe the rules for triggering one or more Input Actions. The basic structure of an Input Mapping Context is a hierarchy with a list of Input Actions at the top level. Under the Input Action level is a list of user inputs that can trigger each Input Action, such as keys, buttons, and movement axes.

The bottom level contains a list of Input Triggers and Input Modifiers for each user input, which you can use to determine how an input's raw value is filtered or processed, and what restrictions it must meet in order to drive the Input Action at the top of its hierarchy.

Any input can have multiple Input Modifiers and Input Triggers. These will be evaluated in the order in which they appear in the list you create; this is particularly important for Input Modifiers, which use the output of each step as the input for the next.

To create an Input Mapping Context, right-click the Context Browser, expand the Input option, and choose Input Mapping Context.

image alt text

You can populate your Input Mapping Context with all of the relevant Input Actions. For a simple project, you can put all of your Input Actions into a single Input Mapping Context. More complex projects work best with multiple Input Mapping Contexts, since a local player can have more than one active Input Mapping Context at a time.

As an example, you can give a Character who can swim, walk, and drive vehicles multiple Input Mapping Contexts: one for common actions that are always available and always mapped to the same user inputs; and another one for each individual mode of travel.

Developers can then place the vehicle-related Input Actions into a separate Input Mapping Context, which are added to the local player when entering a vehicle, and removed from the local player when exiting the vehicle.

Doing this helps to optimize and prevent bugs by ensuring that inappropriate Input Actions cannot run. Additionally, using mutually-exclusive Input Mapping Contexts will help avoid input collisions, therefore when a user input is used for different Input Actions the input will never accidentally trigger the wrong action.

See the sections on Modifiers and Triggers for more details.

image alt text

This Input Mapping Context shows an Input Action for running. This can be activated by multiple inputs, including a gamepad's left thumbstick deflection, which combine both axes into a single input. That input's raw value will go through a "dead zone" Input Modifier, and the resulting value will be sent to the "hold" Input Trigger to drive the "RunAction" Input Action.

image alt text

There are a large number of input bindings available in the dropdown menu. To select your input binding more quickly, click the small button to the left of the dropdown, and then press the key or button you want to bind.

image alt text

This simple Input Mapping Context supports Input Actions for running and jumping.

Once you have populated an Input Mapping Context, you can add it to the Local Player associated with the Pawn's Player Controller. You can achieve this by casting the Pawn's Controller to a Player Controller, getting its Enhanced Input Local Player Subsystem, and adding the Input Mapping Context to it with an integer priority value. The Enhanced Input Local Player Subsystem also supports querying or removing specific Input Mapping Contexts, or clearing all Input Mapping Contexts.

image alt text

Each Input Mapping Context that you add makes it possible to trigger the included Input Actions, running the appropriate events in the Pawn's Blueprint Graph. You can change the set of Input Mapping Contexts at any time during gameplay.

Input Modifiers

Input Modifiers are pre-processors that alter the raw input values that UE5 receives before sending them on to Input Triggers. The Enhanced Input Plugin ships with a variety of Input Modifiers to perform tasks like changing the order of axes, implementing "dead zones", converting axial input to world space, and several others.

Each input associated with an Input Action inside an Input Mapping Context goes through a user-defined series of Input Modifiers before proceeding to the Input Trigger (or Input Triggers) for that input. Input Modifiers are applied in the order they are listed, and the output value from each Input Modifier becomes the input value for the next.

  1. If you need to create an Input Modifier, then you can make your own by creating a new Blueprint Child Class using Input Modifier as the parent.

image alt text

Creating an Input Modifier child class.

  1. Next, navigate to My Blueprint > Functions > Override and from the dropdown menu select the Modify Raw function.

image alt text

The output parameter is an Input Action Value, which contains three float values, much like a Vector. The function's input parameters contain the Player Input object, the Current Value from the input hardware or the previous Input Modifier, and a Delta Time value.

image alt text

The Input Action Value that you return from Modify Raw will go to the next Input Modifier, if there is one, or to the first Input Trigger.

image alt text

Directional Input

A good example of Input Modifier usage is two-dimensional directional input using a single Input Action. With a mouse or a gamepad's analog stick, reading two-dimensional movement is a simple matter of creating an Input Action that supports at least two axes and adding the appropriate input to the Input Mapping Context.

Enhanced Input supports input from one-dimensional sources, such as a keyboard's directional arrows or the popular "WASD" key configuration; you can achieve this control scheme by applying the correct Input Modifiers. Specifically, by using Negate to make some keys register as negative, and using Swizzle Input Axis Values to make some keys register as Y-Axis instead of the default X-Axis:

Letter Key

Arrow Key

Desired Input Interpretation

Required Input Modifiers

W

Up

Positive Y-Axis

Swizzle Input Axis Values (YXZ or ZXY)

A

Left

Negative X-Axis

Negate

S

Down

Negative Y-Axis

Negate Swizzle Input Axis Values (YXZ or ZXY)

D

Right

Positive X-Axis

(none)

image alt text

This interpretation of the directional arrows or "WASD" keys enables one-dimensional inputs to map to a two-dimensional Input Action.

Since each key reports a positive, one-dimensional value, this value will always occupy the X-axis and will have a value of either 0.0 or 1.0 on any given tick.

By negating the value for left and down inputs, and switching the axis order so that the input's X-axis value moves to the Y-axis for up and down inputs, you can use Input Modifiers to interpret a set of one-dimensional inputs as a single two-dimensional input value.

Input Triggers

Input Triggers determine whether or not a user input, after passing through an optional list of Input Modifiers, should activate the corresponding Input Action within its Input Mapping Context. Most Input Triggers analyze the input itself, checking for minimum actuation values and validating patterns like short taps, prolonged holds, or the typical "press" or "release" events. The one exception to this rule is the "Chorded Action" Input Trigger, which is only triggered with another Input Action. By default, any user activity on an input will trigger on every tick.

There are three types of Input Triggers:

  • Explicit types cause the input to succeed if the Input Trigger succeeds.

  • Implicit types cause the input to succeed only if the Input Trigger and all other Implicit type Input Triggers succeed.

  • Blocker types cause the input to fail if the Input Trigger succeeds.

Below is a logical example of how each trigger type interacts in a situation against other trigger types:

Implicits == 0, Explicits == 0 - Always fires, unless the value is 0.

Implicits == 0, Explicits > 0 - At least one explicit has been fired.

Implicits > 0, Explicits == 0 - All implicits have been fired.

Implicits > 0, Explicits > 0 - All implicits and at least one explicit have been fired.

Blockers - Override all other triggers to force a trigger failure.

After processing user input, Input Triggers can return one of three states:

  • None indicates that the Input Trigger's conditions have not been met, so the Input Trigger fails.

  • Ongoing indicates that the Input Trigger's conditions are partially met, and the Input Trigger is processing but is not yet succeeding.

  • Triggered indicates that all of the Input Trigger's conditions have been met, and the Input Trigger succeeds.

You can create your own Input Trigger by extending the base Input Trigger class, or Input Trigger Timed Base. Input Trigger Timed Base checks that an input has been held down for a certain length of time before accepting it and returning the Ongoing state.

The provided Input Trigger Timed Base class does not ever return the Triggered state. Override the functions within your new Input Trigger child class to determine how it responds to user input. The function Get Trigger Type determines the Input Trigger's type. Update State takes the player's input object, current Input Action Value, Delta Time, and returns the None, Ongoing, or Triggered state.

image alt text

This page was written for a previous version of Unreal Engine and has not been updated for the current Unreal Engine 5.0 release.