Menu
Lumberyard
Developer Guide (Version 1.11)

CryInput

The main purpose of CryInput is to provide an abstraction that obtains input and status from various input devices such as a keyboard, mouse, joystick, and so on.

It also supports sending feedback events back to input devices—for example, in the form of force feedback events.

The common interfaces for the input system can be found in IInput.h, in the CryCommon project.

IInput

IInput is the main interface of the input system. An instance implementing this interface is created automatically during system initialization in the InitInput function (InitSystem.cpp in CrySystem, see also CryInput.cpp in CryInput).

Only one instance of this interface is created. CrySystem also manages the update and shutdown of the input system.

This IInput instance is stored in the SSystemGlobalEnvironment structure gEnv. You can access it through gEnv->pInput or, alternatively, through the system interface by GetISystem()->GetIInput(). Access through the gEnv variable is the most commonly used method.

IInputEventListener

A common use case within the input system is to create listener classes in other modules (for example, CryGame) by inheriting from IInputEventListener and registering/unregistering the listener class with the input system for notifications of input events.

For example, the Action Map System registers itself as an input listener and forwards game events only for the keys defined in the profile configuration files to further abstract the player input from device to the game.

SInputEvent

SInputEvent encapsulates information that is created by any input device and received by all input event listeners.

IInputDevice

Input devices normally relate directly to physical input devices such as a joypad, mouse, keyboard, and so on. To create a new input device, you must implement all functions in the IInputDevice interface and register an instance of it with the Input System using the AddInputDevice function.

The Init function is called when registering the IInputDevice with the Input System; it is not necessary to manually call it when creating the input devices.

The Update function is called at every update of the Input System—this is generally where the state of the device should be checked/updated and the Input Events generated and forwarded to the Input System.

It is common for input devices to create and store a list in SInputSymbol of each symbol the input device is able to generate in the Init function. Then, in the update function, the symbols for the buttons/axes that changed are looked up and used (via their AssignTo function) to fill in most of the information needed for the events, which are then forwarded to the input system.

Example:

Copy
// function from CInputDevice (accessible only within CryInput) MapSymbol(...) { SInputSymbol* pSymbol = new SInputSymbol( deviceSpecificId, keyId, name, type ); pSymbol->user = user; pSymbol->deviceId = m_deviceId; m_idToInfo[ keyId ] = pSymbol; m_devSpecIdToSymbol[ deviceSpecificId ] = pSymbol; m_nameToId[ name ] = deviceSpecificId; m_nameToInfo[ name ] = pSymbol; return pSymbol; } bool CMyKeyboardInputDevice::Init() { ... //CreateDeviceEtc(); ... m_symbols[ DIK_1 ] = MapSymbol( DIK_1, eKI_1, "1" ); m_symbols[ DIK_2 ] = MapSymbol( DIK_2, eKI_2, "2" ); ... } void CMyKeyboardInputDevice::Update( ... ) { // Acquire device if necessary ... // Will probably want to check for all keys, so the following section might be part of a loop SInputSymbol* pSymbol = m_symbols[ deviceKeyId ]; ... // check if state changed ... // This is an example for, when pressed, see ChangeEvent function for axis type symbols pSymbol->PressEvent( true ); SInputEvent event; pSymbol->AssignTo( event, modifiers ); gEnv->pInput->PostInputEvent( event ); }

To forward events to the input system so that event listeners can receive them, use the PostInputEvent function from IInput.

If adding your input device to CryInput, it may be useful to inherit directly from CInputDevice, as it already provides a generic implementation for most functions in IInputDevice.

Note

This file is included with the full source of CryEngine and is not available in the FreeSDK or GameCodeOnly solutions. For these licenses please derive from IInputDevice directly.