Input Engine

From Hero of Allacrost Wiki
Jump to: navigation, search


This document describes the use and operation of the input component of the Allacrost game engine. Allacrost's input engine uses the Simple Directmedia Layer (SDL) library for both keyboard and gamepad/joystick input, which the game supports. Mouse input is not supported due to the nature of the game. The goals of the input engine is to provide an easy-to-use interface for the API developer, a configurable interface for the player, and to support as many peripheri as possible. The rest of this document is divided into the following sections.

Input Commands
This section outlines the input commands that can be made in Allacrost.
API Usage
Reading this section will tell you all you need to know in order to utilize this API.
Event Processing
Those that are interested in how the input engine works should refer to this section.

Input Commands[edit]

The table below lists the standard set of user input commands, their default keyboard mappings, and their general purpose. The way in which each key is used is completely dependant on the game mode in question, so the general purpose is just a suggestion to the developer, but not a requirement.

Command Name Default Key Map General Purpose
Up 'up arrow' Move sprite or cursor upwards<
Down 'down arrow' Move sprite or cursor downwards
Left 'left arrow' Move sprite or cursor to the left
Right 'right arrow' Move sprite or cursor to the right
Confirm 'f' Confirm an action or menu command
Cancel 'd' Cancel an action or menu command
Menu 's' Display a central menu
Swap 'a' Swap the character being displayed
Left Select 'w' Select multiple targets or page scroll up
Right Select 'e' Select multiple targets or page scroll down
Pause 'spacebar' Pause/unpause the game
Table 1. Allacrost Standard Input Commands

There are also several meta-key commands (Ctrl+key) to perform various application-related functions. The two that a player are most likely to use are the Ctrl+f, Ctrl+q, and Ctrl+s meta-commands, which toggle full-screen mode, quit the game, and take a screenshot, respectively. Unlike the standard command set, meta-command keys cannot be re-mapped by the user. The table below lists all the possible meta-commands and their purpose.

Command Name Meta-Key Map General Purpose
Fullscreen Ctrl + f Toggles between full-screen and windowed mode
Quit Ctrl + q Registers a quit event to the game
FPS Display Ctrl + r Toggles the display of the frames per second in the upper-right hand corner
Screenshot Ctrl + s Takes a screenshot and saves it to a file
Texture Sheets Ctrl + t Displays and cycles through the texture sheets
Table 2. Allacrost Meta Input Commands

API Usage[edit]

The GameInput singleton manages all of the keyboard and joystick key/button mappings so they are completely transparent to the user of the API. In other words, you can only detect that the user requested a certain command, not whether that event came from the keyboard or a joystick, or what specific key/button was used to generate the event. Input can be checked at anytime from the GameInput singleton via a number of member access functions.

Each standard input command has three booleans registered to it: press, release, and state. Press is true when the user presses a command down, and it is cleared on the next iteration through the game loop. Release becomes true when the user releases a command, and it too becomes clearend on the next iteration through the game loop. State is true while the command is active (ie, the key or button is being held down). Using these three pieces of information, you can design your game mode to check and act on any combination of commands. The booleans can be accessed via member access functions in the GameInput singleton class. The table below enumerates each of those function names, which all return boolean values.

State Functions Press Functions Release Functions
bool UpState() bool UpPress() bool UpRelease()
bool DownState() bool DownPress() bool DownRelease()
bool LeftState() bool LeftPress() bool LeftRelease()
bool RightState() bool RightPress() bool RightRelease()
bool ConfirmState() bool ConfirmPress() bool ConfirmRelease()
bool CancelState() bool CancelPress() bool CancelRelease()
bool MenuState() bool MenuPress() bool MenuRelease()
bool SwapState() bool SwapPress() bool SwapRelease()
bool LeftSelectState() bool LeftSelectPress() bool LeftSelectRelease()
bool RightSelectState() bool RightSelectPress() bool RightSelectRelease()
Table 3. GameInput Member Access Functions

Note that there is no member access function for the pause or quit commands. This is because those commands are handled internally by the GameInput class (since they are always processed in the same manner). None of the meta-commands are available for access either.

Event Processing[edit]