Overview

Input events come from the OS, are translated in the platform layer and then posted to the game. By default the game then checks the input event against a global action map (which supercedes all other action handlers). If there is no action specified for the event, it is passed on to the GUI system. If the GUI does not handle the input event it is passed to the currently active (non-global) action map stack.

Example: the user presses the ~ (tilde) key, which is bound in the global action map (in example/client/scripts/default.bind.cs) to toggleConsole. This causes the console function associated with the bind to be executed, which in this case is toggleConsole, resulting in the console output window being shown. If the key had not been bound in the global map, it would have passed to the first gui that could have handled it, and if none did, it would pass to any game actions that were bound to that key.

Platform Input

Platform specific code translates OS-specific events into uniform Torque input events. These events are posted into the main application event queue via a call to GameInterface::processEvent() (remember, Game points to a subclass of GameInterface). The default behavior for the GameInterface class is to pass all input events to GameInterface::processInputEvent(), which in the example DemoGame calls ActionMap::handleEventGlobal, followed by Canvas->processInputEvent (if not handled by the global map), and if neither of those handles it, passes it to ActionMap::handleEvent.

Action Maps

Action maps map platform input events to console commands. Any platform input event can be bound in a single generic way - so in theory the game doesn't need to know if the event came from the keyboard, mouse, joystick or some other input device. This allows users of the game to map keys and actions according to their own preferences.

There is one defined ActionMap object that is processed first for all events called GlobalActionMap.

Game action maps are arranged in a stack for processing - so individual parts of the game can define specific actions - for example when the player jumps into a vehicle it could push a vehicle action map and pop the default player action map.

Modifier Keys

The inputName of an action can be modified by one of the three modifier keys - alt, shift and control. For example, the fullscreen/window toggle is bound to "alt enter". If an action is called with a modifier, releasing the modifier key(s) will not cause the break event to fire - only when the key itself is released.

Keyboard Setup

Most of the input for keyboards are controled through the defaultProfile.cs found within ~/client/scripts/; Keyboard commands are also found in config.cs found in ~/client/.

Here's an example of a few inputs:

moveMap.bindCmd(keyboard, "escape", "", "escapeFromGame();");
moveMap.bind(keyboard, "f2", showPlayerList);
moveMap.bind(keyboard, "a", moveleft);
moveMap.bind(keyboard, "d", moveright);

Keyboard Map

Below you will find the text keys for all the keys on the keyboard.

Key: a to z
Function Keys: Fx; x = 1-12 - example: F5, F6, F10
Arrow Keys: left, right, up, down
Special: 
~ : tilde
Esc : escape
Tab : tab
Alt : alt, alt x; x = Any key from a to z
Ctrl : ctrl, ctrl x; x = Any key from a to z

Backing up Keymaps

Torque provides the capability to back up your keymaps with object.save(string filename, bool append).

Example

Setup: We have the default keymap defined in default.bind.cs and it is stored in an object called moveMap We allow the user to remap the keys in the options panel of the interface

Problem: We would like to save these remapped controls so the user will have their personal mappings each time the game is started.

Solution: Save the user's custom keymap to a file and load it each time they start the game.

This is the code to save the moveMap in its current state.

if (isObject(moveMap))
{
    moveMap.save("./config.cs", false);
}

First we make sure moveMap exists as an object to avoid runtime errors. Then we call its save function with two arguments. The filepath argument is the file where the map will be saved. The boolean argument specifies whether to append to the file or overwrite it. False is for overwriting it which is appropriate in this situation.

Then you merely need to load the new config.cs after loading default.bind.cs.

exec("./default.bind.cs");
exec("./config.cs");

This will overwrite the default setting with the client settings.

Developer Warning: A key reason this works is because Torque places commands at the beginning of config.cs to delete any existing moveMap and rebuild it. This has the effect of preventing you from adding any new controls to default.bind.cs without first deleting config.cs. This is desirable to prevent double mappings. For instance, if you had one control in your game and it is triggered with the 'D' key and the user remaps it to 'E', failing to delete the moveMap when loading would result in 'D' and 'E' both being bound to that function.