Input Handling Overview
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.
-
Input Factory - Implements the 'Abstract Factory Pattern' to create type-specific input factories:
InputFactory. -
Type-specific Input Factory - Creates input handlers of the matching input type, for example:
KeyboardInputFactory,TouchInputFactory. -
Input Handler - Components that can process given inputs, for example:
KeyboardPlayerInputComponent,TouchPlayerInputComponent. -
Input Service - Iterates through registered input handlers until the input is processed:
InputService.
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.
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.
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.
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.
The input type is set in InputService. This will determine the type of input factory created. The following is an example of setting the input type to KEYBOARD.
private static final InputFactory.InputType inputType = InputFactory.InputType.KEYBOARD;
Input handlers can be created using the Input Factory. The following is an example to create a type-agnostic input handler for the player:
InputComponent inputComponent = ServiceLocator.getInputService().getInputFactory().createForPlayer();
Create a new input handler which extends InputComponent. InputComponent registers itself with the InputService on creation with the default priority of 0. To set a custom priority level, the input handler's constructor should call super({ priority-level }).
This is an example of creating a new input handler for the tree with a priority level to 5.
public class NewInputComponent extends InputComponent {
public NewInputComponent() {
super(5);
}
...
}
InputComponent has methods to handle each type of input event (e.g. keyDown, scrolled, etc.) and by default these methods do not process the input. Therefore, input handlers should override all relevant input handling methods.
As an example, let's extend the input handler to handle typing the character a.
public class NewInputComponent extends InputComponent {
public NewInputComponent() {
super(5);
}
@Override
public boolean keyTyped(char character) {
if (character == 'a') {
// handle input here
return true;
}
return false;
}
}
Note: For games supporting multiple input types, you will need to create a type-specific input handler for each input type. For example, if your game supports KEYBOARD and TOUCH, you would need to create KeyboardNewInputComponent and TouchNewInputComponent.
To register the new input handlers with the input factories, add an abstract method for creating the input handler to InputFactory.
public abstract InputComponent createForPlayer();
Then implement these methods within the input type-specific factories.
Within KeyboardInputFactory :
@Override
public InputComponent createForExample() {
return new KeyboardNewInputComponent();
}
Within TouchInputFactory :
@Override
public InputComponent createForExample() {
return new TouchNewInputComponent();
}
InputComponent currently implements the libgdx InputProcessor and GestureDetector.GestureListener interfaces. This means that it can support any input handlers that use only keyboard, mouse and touch gesture input. If the input type you are looking to create is not supported by these two interfaces, first follow the steps in "Implementing a New Input Interface".
For the purpose of explaining how to add a new input type, we will look at how TOUCH was added into the game.
Within InputFactory:
Add the new input type to InputType.
public enum InputType {
KEYBOARD,
TOUCH
}
Add the option to create a Touch InputFactory in createFromInputType().
public static InputFactory createFromInputType(InputType inputType) {
...
if (inputType == InputType.KEYBOARD) {
return new KeyboardInputFactory();
} else if (inputType == InputType.TOUCH) {
return new TouchInputFactory();
}
...
}
Create a touch input factory which returns touch-specific input components. It should have methods for all the entity's within the game with custom input components, i.e. for the starting game this means the player and debug terminal.
Within TouchInputFactory :
@Override
public InputComponent createForPlayer() {
return new TouchPlayerInputComponent();
}
@Override
public InputComponent createForTerminal() {
return new TouchTerminalInputComponent();
}
Create touch-specific input components for all the entity's within the game with custom input components.
As an example we will look at how the KEYBOARD input component KeyboardPlayerInputComponent handles the player attack differently to the TOUCH input component TouchPlayerInputComponent.
For KEYBOARD, within KeyboardPlayerInputComponent the player attack is triggered by pressing space:
@Override
public boolean keyDown(int keycode) {
switch (keycode) {
...
case Keys.SPACE:
// player attack
entity.getEvents().trigger("attack");
return true;
...
}
}
For TOUCH, within TouchPlayerInputComponent the player attack is triggered by touching down on the game (with a mouse or via a touch device):
@Override
public boolean touchDown(int screenX, int screenY, int pointer, int button) {
// player attack
entity.getEvents().trigger("attack");
return true;
}
For the purpose of explaining how to support a new input interface, we will pretend that the game does not yet support Touch Gesture input and will thus will go through the steps of adding it.
Set InputComponent and InputService to implement the new input interface.
public abstract class InputComponent extends Component
implements InputProcessor, GestureDetector.GestureListener {
public class InputService implements InputProcessor, GestureDetector.GestureListener {
Add methods to InputComponent which return false for each new input methods. By default InputComponent will not handle any input, as these methods will be overridden by the actual input handlers.
@Override
public boolean fling(float velocityX, float velocityY, int button) {
return false;
}
@Override
public boolean longPress(float x, float y) {
return false;
}
...
Add methods to InputService which iterate through the registered input handlers for each of the new input methods.
@Override
public boolean fling(float velocityX, float velocityY, int button) {
for (InputComponent inputHandler : inputHandlers) {
if (inputHandler.fling(velocityX, velocityY, button)) {
return true;
}
}
return false;
}
@Override
public boolean longPress(float x, float y) {
for (InputComponent inputHandler : inputHandlers) {
if (inputHandler.longPress(x, y)) {
return true;
}
}
return false;
}
...
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 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.
The abstract factory pattern also means that when we can write any code interacting with input handler's to be type agnostic.
Let's consider the player as an example.
When adding an input handler ... TODO