Introduction

Note: This page only includes the Introduction and Behind the Scenes for input Handling. The 'Usage' section can be viewed in Using the Input System.

The Input System is used to process inputs from the user, e.g. mouse movements, keyboard presses, touch interactions, etc.

Currently there are two input types recognised within the game: KEYBOARD and TOUCH. Both use keyboard and mouse input, however, if you'd like to also support more input types, for example touch gestures or remote controller input, then this should provide a good foundation.

Key System Components

1. Input Factory - Implements the 'Abstract Factory Pattern' to create type-specific input factories: InputFactory.
2. Type-specific Input Factory - Creates input handlers of the matching input type, for example: KeyboardInputFactory, TouchInputFactory.
3. Input Handler - Components that can process given inputs, for example: KeyboardPlayerInputComponent, TouchPlayerInputComponent.
4. Input Service - Iterates through registered input handlers until the input is processed: InputService.

Creating Input Handlers

The Input System uses the Abstract Factory pattern to create input handlers that can process the received input. For example, if the user is using a keyboard and mouse, then the active input handlers should be able to process keyboard and mouse input; or, if the user is using a game controller, then the active input handlers should be able to process game controller input. The Abstract Factory pattern is quite a complex pattern, but is necessary for ensuring our code remains modular each time a new input-type is added.

Architecture

Processing Input

The Input Service is set as the game's input processer which means it will receive all user input. All active input handlers must register themselves with the Input Service and provide a priority level. The Input Service maintains a list of the registered input handlers, sorted by descending priority. When input is received, the input service iterates through the list of input handlers until the input is processed.

Example

There are three input handlers 1, 2 and 3, with priority orders 10, 5 and 1, respectively. The input can be handled by input handlers 2 and 3.

The user has pressed down a key. The Input Service sends the input to the input handlers ascending priority order.

Input handler 1 cannot process the input, so it is passed to input handler 2. The input is processed by input handler 2, and therefore is not passed on to input handler 3.

Why do we want this?

It is important that we are able to control the order in which input handlers are called in and stop calling input handlers when the input is handled.

Let's consider the case where we have our input type set to KEYBAORD and we press the 'w' key within our game. The 'w' key currently has two uses, firstly it can be typed into the terminal, and secondly it can be used to move our player up.

If the terminal is open, we want 'w' to be typed into the terminal, and if the terminal is closed, we want 'w' to control the player movement. Based on this logic, we want the terminal to have a higher priority than the player so that it gets to choose whether it handles the input or not based on its state, and if it doesn't then the player can attempt to.

This explains why we need input handler ordering, but why do we need a way to stop passing the input to input handlers?

Consider the case where we've just typed 'w' and it's appeared in the terminal. If this input was then also handled by the player, as we typed, we'd see the player in the background moving around too. This is not intended behaviour, so we need a way to prevent handled input from being passed to any other input handlers.

To do this, we make each input handler return a boolean: true, if the input has been handled, and false if it hasn't. Now the InputService which is passing the input to the input handlers, knows when to stop.

Behind the Scenes

Why the Abstract Factory pattern?

To understand why this pattern is necessary, let's consider some the most basic way we could write code for moving the player up and down with a keyboard:

if (keycode == Input.Keys.W) {
  player.moveUp();
} else if (keycode == Input.Keys.S) {
  player.moveDown();
} 

If we now want to support a game controller, we would have to extend it like so:

if (inputType == KEYBOARD) {
  if (input == 'W') {
    player.moveUp();
  } else if (input == 'S') {
    player.moveDown();
  }
} else if (inputType == GAME_CONTROLLER) {
  if (input == 'Y') {
    player.moveUp();
  } else if (input == 'A') {
    player.moveDown();
  }
}

You can see how the code will grow very quickly as soon as we try to add more functionality or more input types.

The Abstract Factory pattern allows us to abstract away input-specific code into the different type-specific InputComponent files. This means for every input handler we write we only have to worry about one input type, making each input handler's code much simpler.

Another benefit of the Abstract Factory pattern is that it allows us to write any code interacting with input handler's to be input type agnostic. Let's consider the player as an example.

As an example, when we create the player's input component, we use the InputFactory stored within the InputService.

 InputComponent inputComponent = ServiceLocator.getInputService().getInputFactory().createForPlayer();

Notice that we don't need to declare whether we want the KeyboardPlayerInputComponent or the TouchPlayerInputComponent. This is already done for us behind the scenes.