Input Preprocessor
Overview
All input in Prysm goes through a fairly complicated process. It consists of rules and algorithms that propagate input forwarding through multiple Views, calculate coordinates and keep track of user focus, among other things. Although Prysm comes with many out-of-the-box settings or delegates that let you control how user input is handled, it’s impossible for the settings to cover all possible use-cases.
The Input Preprocessor
feature gives you absolute control over all facets of the input, by putting every part of the implementation in your hands to extend or override, at the cost of having a fairly complicated initial setup process and maintenance. It is basically a way for you to write your Prysm input handling from scratch, using the Unreal Engine IInputProcessor interface, with example code provided to start you off.
The IInputProcessor
implementation you receive when you activate the feature contains an outline of the processing needed to handle input in Prysm, which tries to resemble the current Prysm input behavior as closely as possible. You are required to “finish” the implementation, providing any and all details or unspecified behaviors, so that they match your desired functionality.
Input Preprocessor
is different from the out-of-the-box behavior of Prysm, especially when it comes to edge cases. This is mostly due to Prysm views in a HUD/UMG/Component being Actors
/Widgets
and thus relying on Unreal Engine to provide focus behavior, coordinate conversion, etc. The Input Preprocessor
is not even a UObject
, so these functionalities need to be provided externally.General setup
Here are the steps to set up the Input Preprocessor
:
- Prysm provides a default implementation of the
Input Preprocessor
. To override it, you need to subscribe to theICohtmlPlugin::OnGetCohtmlInputPreprocessor
delegate, which will be fired when the Prysm System gets created. - Remove any spawning of the
SCohtmlInputForward
Widget, whether from Blueprints, or C++. Its job will be taken over by theInput Preprocessor
. - Read over the provided
IInputProcessor
C++ implementation and provide, or override any relevant parts, as outlined here. - Activate the
Input Preprocessor
from the Prysm settings. - Verify all functionalities listed in the following chapter thoroughly.
Implementing and Overriding the Input Preprocessor
Firstly, you need to decide if your game will be using a HUD/Component setup, a UMG one, or both. The HUD/Component setup is the one activated by default in the Input Preprocessor
.
If you want to do some special handling for UMG input, set the bPropagateInputToUMG
variable to true
and then extend the relevant UMG methods as you see fit. Using both UMG and a HUD/Component setup is not defined behavior for Prysm. If you want to use such a setup, you should define and implement the particulars of how, and in what order input will be propagated yourself.
Other than that, here are the main things you would need to implement for the needs of your game:
- How does your
Input Preprocessor
detect/processKeyChar
events- They are usually received directly from the engine, but the
KeyChar
event callback is missing from theIInputProcessor
provided by Unreal Engine.
- They are usually received directly from the engine, but the
KeyChar
events manually with some custom solution.- FocusReceived/FocusLost mechanics
- These are usually handled by the engine. They come with a pre-implemented crude setup that calls focus events manually, based on when Prysm Views switch focus.
- When UI input is handled at all
- In a normal setup you can turn off any UI input processing by defocusing the
InputForwardWidget
, for example. To achieve a similar result, you would need to implement theShouldHandleInput
method.
- In a normal setup you can turn off any UI input processing by defocusing the
- When is input discarded
- In Unreal Engine the input is received on a per-object basis when the object is interacted with. However, all engine input goes through the
IInputProcessor
, so you would need to weed out the relevant UI events and discard all others.
- In Unreal Engine the input is received on a per-object basis when the object is interacted with. However, all engine input goes through the
PIE
.- How does the
Input Preprocessor
receive data about the world- Most input depends on the
Game world
,Player
,PlayerController
andGameViewportClient
. The provided implementation fetches the data in a crude way, for example just taking the first localPlayer Controller
. If you want to extend or customize that, override theGetWorldData
method.
- Most input depends on the
After implementing the points above, you can also check the various sub-features present in Prysm, such as whether or not the Gamepad will keep the state of pressed buttons when unfocused, will raycasting reach further objects than the first encountered, etc.
You can look at the Prysm settings, or the Prysm HUD/Component/UMG Blueprint-exposed parameters for ideas on sub-features that you can further implement if you will be using the Input Preprocessor
.
After getting the Input Preprocessor
up and running, here are some of the behaviors you can override:
- How and in what order does Prysm finds Views inside HUDs/Components in your game.
- How does Prysm raycast in the game world to find Views.
- How are mouse events and their coordinates processed before being sent to every View.
- How do we keep track of the currently focused component in order to send keyboard/gamepad events to them.