Input Handlers
Input Handlers are responsible for handling Player Inputs. They are mapped to Input Actions, bundled into an Input Setup and then triggered by the Input Manager.
Input Handler Design
Input Handlers extend from NinjaInputHandler, which grants them the following default properties. You can also extend any other handler provided by the framework, to modify its default behavior.
Property | Description |
|---|---|
Input Actions | Input Actions compatible with the Input Handler. |
Trigger Events | For each provided action, which Trigger Events will be detected. |
Can Be Buffered | Allows the Input Handler to be buffered . |
Input Handlers also contain the following relevant functions.
Function | Description |
|---|---|
Can Handle | Determines if the Handler is compatible with an Input Action and Input Trigger. |
Handle | Multiple |
The CanHandle check is purely a compatibility check and should not include temporary states. As for the Handle functions, you only need to implement the ones that are actually used by your handler.
Both functions are marked as const, since the Input Handler is not supposed to have a state. If a state is required, then it should be persisted somewhere else, such as the Player Controller or Character.
Creating Input Handlers
Input Handlers can be created from the NinjaInputHandler class, or any other Handler class available in the system that better suits your needs. Handlers can be created in Blueprints or in C++.
Creating an Input Handler
In your Content Browser, create a new Input Handler, by selecting this option in the Ninja Bear Studio context menu.
Name your Handler and navigate to the Class Defaults panel.
Set the Input Actions and Trigger Events that are compatible with the new Input Handler.
Navigate to the Class Settings panel and provide the correct Blueprint Display Name.
In the list of Functions, select the functions that are relevant to your Handler and implement them as needed.
Overrideable Functions
Input Handlers have multiple Handle functions, relative to each one of the main input events triggered by the Enhanced Input framework.
Started: An input action has started but have not yet triggered. "Started" and "Triggered" may happen during the same frame.
Triggered: An input action was triggered. The moment when this happens depends on the type of trigger set in the Input Action. For example, the " Pressed " trigger will send this event as soon as the actuation happens.
Ongoing: An input action has been triggered, and it is still ongoing. For example, the " Down " trigger will send this event while the tracked button is pressed.
Completed: An input action has been fully handled. "Completed" and "Triggered" may happen during the same frame.
Cancelled: An input action has started, but was interrupted before reaching the "Triggered" event.
You can determine whether a key was pressed or released with the appropriate Pressed and Released Input Action Triggers. They provide appropriate true and false values that you can use. You can convert the value provided by the Handler to a boolean, using the conversion functions provided by the Enhanced Input library.
The following image shows a custom Input Handler and some strategies to access contextual data from it, like the player, controller and input values.
Here is a breakdown of each input parameter available in the function's signature:
Manager: The Actor Component assigned to the owning character invoking this handler. You can access your Player Pawn, Controller and Ability System Component from this component.
Value: Final Action value to be applied to the owning character. Make sure to access the value in a way that is coherent with the Input Action value type.
Input Action: Additional information about the Input Action that triggered this handler.
Elapsed Time: Total time the action has been evaluating triggering. Only relevant/available for Ongoing and Triggered events.
Compatibility Checks
Handlers need to determine if they are compatible with an action or not. This can be done via the CanHandle function.
The default handler already provides a behavior that checks if the Input Handler is compatible with the Input Action and Trigger Event, which are defined by the Handler's default properties, InputActions and TriggerEvents.
The following image shows an additional check for a custom Input Action Data Asset that may contain project-specific information, that could even be used in the test itself.
Input Handler Examples
Here are some examples of Input Handlers, written in both Blueprints and C++ with some common use-cases.
Movement Handler
To move a pawn (or character), you just need to add the incoming input value to the proper world directions. This is meant to be used only as a reference, since the framework already provides a more robust Move Input Handler.
Look Handler
To control the camera assigned to a pawn, you can add the incoming input to the Controller's Pitch and Yaw inputs. Once again, this is meant to be used only as a reference, since the framework provides a more robust Look Input Handler.
Crouch Handler
This example makes a character crouch and stand up, using Pressed and Released triggers. It's an interesting example since it requires a cast, and routing the boolean input value depending on whether it's true (Pressed) or false (Released).
Such approach can be used for many other things, like jumping and activating abilities.
The framework provides more robust implementations not only for the Crouch Input Handler, but also for the Jump Input Handler, and multiple Ability Handlers.
