ToyMaker: Input System

What is it?

The ToyMaker input system is responsible for translating raw input from the app's platform into abstract inputs, called actions, meaningful within a context of the application.

The process by which it does so is described below:

1. It receives input from the platform via ToyMaker::InputManager::queueInput() (through SDL, currently).
2. It decomposes the input into several simple normalized single-axis values. Each value corresponds to an ToyMaker::InputFilter, stored in ToyMaker::InputManager::mRawInputState.
3. It takes a set of 1-3 of the decomposed input and maps them to one input combo value. If the input combo value is considered triggered, it is added to a list of unmapped inputs generated this frame (ToyMaker::InputManager::mUnmappedInputs).
4. When the engine requests action inputs received this frame via ToyMaker::InputManager::getTriggeredActions(), input combos are sent to the action contexts they are valid for.
5. Each action context translates input combos received to actions that it knows, returns them to the input manager, which returns them to the engine.
6. The engine forwards the mapped actions to whichever objects need them, via ToyMaker::ActionDispatch::dispatchAction().

   W    ______
 A|S|D        \___.--> Character : Move (2 Axes) --> (Move handlers)
<keyboard>     /
              /
             /
 (( L ))----/
<controller>

Setup takes place via an input bindings file, pointed to by the project configuration's "input_map_path" property. This bindings file lists

• Action contexts valid for this project.
• Actions available in each context.
• The combination of input values (identified by their ToyMaker::InputFilter) that map to one axis of an action. Each combination is referred to as an input binding.

Important API

• ToyMaker::InputManager::registerActionContext() – Defines a namespace for actions (which are virtual inputs).
• ToyMaker::InputManager::registerAction() – Adds the definition of an action to an action context.
• ToyMaker::ActionContext – A namespace for a set of application-defined virtual inputs, called actions.
• ToyMaker::IActionHandler – The base class of an object wishing to handle actions generated by the input system.
• ToyMaker::ActionDispatch – A class whose instances are responsible for tracking subscribers of an action, and for routing actions triggered this frame to them.

Why does it exist?

The main purpose of the input system is to provide a layer of abstraction between application-specific code, and platform-generated input.

The application defines the form of each action it expects to receive. The action handler can safely expect that this is the only form its input will take, and doesn't have to reason about differences in platforms.

Adapting the application to a specific platform then becomes a much more trivial task of specifying which real platform inputs map to virtual actions, without touching any of the application's code.