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.
This section outlines the input commands that can be made in Allacrost.
Reading this section will tell you all you need to know in order to utilize this API.
Those that are interested in how the input engine works should refer to this section.
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|
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|
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()|
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.