If you take a closer look at the defaultprofile.xml, you will notice that there are several Action Maps contained within the file, each with a different name. This is no mistake; there is a very good reason for this.

In every game or simulation, the same key or button is commonly used for multiple actions. During gameplay, the A button on a controller might, for example, trigger a jump, but in a menu it would select an option on the interface. If the game has an inventory for the player, pressing A while it is open might select an item. And if the player is inside a vehicle, the A button could trigger the handbrake. Similar multiple assignments can be found for lots of other input events, especially since the number of buttons on a game controller is fairly limited.

To accommodate this, the defaultprofile.xml contains several entries that map the same button to various Action events. One example is the A button on the Xbox controller, which is represented by the keyword xi_a. This is mapped to the jump event as well as the vehicle brake v_brake and a range of menu actions. When this button is pressed, all these Action events might be triggered. Creating individual Action event entries for each of these actions is sensible, as it allows the player to customize their controls individually. The player might choose to keep the default assignment for jumping, but prefer the B button to be the handbrake inside vehicles. Splitting the actions up into separate events allows this kind of freedom.

But how can we prevent the code responsible for jumping from making the player jump while they are in a vehicle or while they are navigating their inventory or an in-game menu? Of course, the code could perform checks and only trigger the jump when none of these conditions apply. However, this would require an unnecessary amount of overhead as the code that should only be concerned with the player jumping now also needs to know about menus, inventories, and the vehicle system. The overhead code would get larger with each new system that reacted to inputs.

Instead, CryENGINE separates all Actions into multiple, separate Action Maps that can be individually activated or deactivated. Action events from an Action Map will only trigger if that map is currently active. For example, one Action Map would only handle the player inside a vehicle. It contains the mappings for all vehicle controls, such as acceleration and brakes. This Action Map is only activated once the player enters a vehicle (as a driver). The rest of the time it is disabled and none of the vehicle control Action events will trigger. The code handling the vehicle Actions would not need to perform any unnecessary checks. Accordingly, when a vehicle is entered, Action Maps to control swimming or player locomotion are disabled.

The CryENGINE SDK uses different Action Maps for various game modes, UI menus, different camera modes, singleplayer/multiplayer, and debug actions that are used only during project development. Some of Crytek's previously released games even used special Action Maps for some boss fights to change the controls as per the specific needs of the fight. Of course, more than one Action Map can be active at a time.

If you write a completely new system for your game project that comes with its own set of controls, you might consider creating an entirely new Action Map inside defaultprofile.xml. To do so, create a new actionmap tag node inside the XML file and then place your mapped actions inside as follows:

<actionmap name="newName">
  <action … />
  <action … />
  <action … />
</actionmap>

All maps will be automatically loaded, so you won't need to add any extra managing code for it. You can enable and disable your Action Map via the ActionMapManager inside your system, as shown in the following code:

#include <IActionMapManager.h>

// retrieve a pointer to the Action Map Manager
IActionMapManager* pActionMapMan = g_pGame->GetIGameFramework()->GetIActionMapManager();

// enable an Action Map
pActionMapMan->EnableActionMap("vehicle_general", true);

// disable an Action Map
pActionMapMan->EnableActionMap("player ", false);

The preceding sample code is written for use inside the CryGameSDK DLL, where the global variable g_pGame is defined. When working with ActionMaps, this is the DLL in which you will spend most of your time. If you are working with a full source code and want to access the ActionMapManager from there, use gEnv->pGame instead. Inside the CryAction DLL, you may also use CCryAction::GetCryAction()->GetIActionMapManager(); to retrieve the pointer to the ActionMapManager.

To create a new Action event, you will need to create a new ActionId for it. This is basically just a string containing the name of the event and it is how Actions are referenced inside the codebase. To simplify the process for this, all Action events are listed in one file: GameActions.actions. This file is located inside the GameDll folder under GameSDK and is also included in the Visual Studio CryGameSDK project. This is an excerpt from this file:

DECL_ACTION(moveleft)
DECL_ACTION(moveright)
DECL_ACTION(moveforward)
DECL_ACTION(moveback)
DECL_ACTION(jump)
DECL_ACTION(crouch)
DECL_ACTION(sprint)

To add your own Action events, first choose an appropriate and descriptive name for your Action. It cannot contain whitespaces. Then, simply add it to the bottom of the file and surround your Action event with the DECL_ACTION() macro. This is defined in GameActions.h and the CGameActions class in this file creates ActionIds for all events listed in the GameActions.actions file. The new entry in the files could look something like this:

DECL_ACTION(your_new_action_name)

After you have added your Action in this file, you will need to recompile the CryGameSDK for both 64- and 32-bit before you can start using your new Action. But first you will need to map input events to it, which will be explained in the next section.

Once the Action event setup is done, you can add a mapping for your Action into one of the ActionMaps in the defaultprofile.xml file. You can create your own ActionMap of course, but keep in mind that you will also need to take care of activating and deactivating it. In most cases, you will be adding to the existing player ActionMap. This map is activated automatically at game start, so you will not need to add any extra managing code.

To add a new Action, open the defaultprofile.xml file from Game/Libs/config in a text editor. An editor that has syntax highlighting for a XML file is preferable, but not required. Since the file will be a few hundred lines long, the fastest way to find the ActionMap you want to modify is to do a quick search for its name, for example, player.

New Actions have to be added inside the tags for the ActionMap. Each ActionMap has an opening and a closing tag as shown in the following code snippet:

<actionmap name="player ">
...
<!-- New Actions go here, in between the actionmap tags -->
...
</action>

Each Action mapping gets its own XML entry, which has to be the tag action. There are a number of attributes that can be set on the node. Most are optional, but at the very least an entry has to have a name for the Action event it is supposed to trigger, one input event that is associated with it, and a trigger option.

<!-- Minimalistic Action mapping -->
<action name="jump" keyboard="space" onPress="1" />

To specify which input events will trigger the Action, you need to specify the device and the name of the input event. There are three devices: xboxpad, ps3pad, and keyboard. While the Xbox and PS3 controller are obvious, the keyboard attribute is used to access both the keyboard and the mouse input, although these are technically two devices. The distinction is made internally based upon the name of the events.

You can specify one, two, or all three devices inside the action node. You will need to decide which are relevant for the platform you are developing. The devices and their events can be set either as attributes or as children of the action node:

<action name="jump" keyboard="space" onPress="1" />
// The above entry creates the same mapping as the one below
<action name="jump" >
  <keyboard input="space" />
</action>

Using individual children rather than attributes inside the main action node allows you to bind more than one input event from the same device to an Action. This is especially useful for the Enter key that exists at two places on most standard keyboards (once on the main block, and once on the numeric keypad). Each of these keys generates an input event with a different name, yet it is expected that both keys work the same way, that is, they trigger the same Action. For example, if the Enter key would cause a dialog line to be skipped in your game, your players will most likely expect that the Enter key on the numeric keypad will have the same effect.

<action name="skip_dialogfragment" onPress="1" xboxpad="xi_b" >
  <keyboard>
    <inputdata input="enter"/>
    <inputdata input="np_enter"/>
  </keyboard>
</action>

The preceding action mapping example would link the Action of skipping of a dialog line to both Enter keys. Note that it also maps it to the B button on the Xbox controller. This is done inside the main action node. You can combine different input devices as attributes or children of the main action node.

In order to set up the appropriate input events inside the Action Map, you need to know their names. These are very straightforward for most keyboard keys, but not so for special keys such as the numeric keypad and function keys as well as the mouse and controller input events. You can find a table listing the most important input event names at the end of this chapter in the The input event names reference section.

Optional parameters

There are a number of optional attributes that can be set on an action node to further specify when and how the Action event is supposed to be triggered. These options will be explained in this section.

Trigger options

A trigger option defines when the Action event should be sent out if one of the mapped input events is received. In all the examples listed so far, the trigger option was set to onPress="1", which will send the Action event once when the button or key is pressed down.

Keyboard keys and buttons on a mouse or a controller can trigger Actions when being pressed down, when they are released, and/or repeatedly while they are being held down. This is useful for many game mechanics. In a fighting game, for example, a player might have to press a key or button to enter a defensive block stance and then hold it to stay in that stance. He exits the stance as soon as he releases it again. In such a case, the Action would have the trigger options onPress and onRelease set up.

The preceding table lists the three available trigger options and describes their effects. You can set up more than one trigger option for an Action mapping. An entry in your Action Map could look like the following code:

<action name="jump" onPress="1" onRelease="1" keyboard="space"/>

You can also specify different trigger options for each device and input. For example, have the Action immediately triggered when the mapped key on the keyboard is pressed, but only trigger it on release of the mapped button on the Xbox controller. This is done using the following code snippet:

<action name="menu_open" >
  <keyboard input="x" onPress="1" />
  <xboxpad input="xi_back" onRelease="1" />
</action>

Each of the three trigger options onPress, onHold, and onRelease allow further parameters to be specified. All of these are optional and are not required for the option to work.

OnPress parameters

By default, the onPress option will trigger the Action event immediately when the input event is received. However, this behavior can be altered and the event can be delayed. The following table lists the additional attributes you can specify. These must be set on the same node as the onPress attribute:

Tip

If the onPress trigger is delayed, then onRelease will be delayed as well automatically. It will not trigger until the onPress has triggered. This ensures that the onPress and the onRelease events are always triggered in their logical order.

OnHold parameters

When the option onHold is specified, the Game Action system will repeatedly trigger the mapped Action event while the key or button is being held down. This option allows further parameters to set the frequency of the events and an initial delay.

A delay is a length of time between the initial key press and before the repeated Action events are being triggered. You can easily visualize what this means by opening a text editor and holding down a letter key on your keyboard. After typing the letter once, there will be a short delay before your screen will start filling up.

The onHold parameters are specified as attributes in the same XML node where the onHold attribute is set. Here is an example setup:

<action name="menu_up" onHold="1" holdTriggerDelay="0.5" holdRepeatDelay="0.15" >
  <keyboard input="up" />
</action>

When specifying onHold inside an action tag, you will usually want to also specify one or more parameters to configure the trigger option. The following table lists the available parameters:

Tip

The onHold trigger is commonly specified together with the onPress trigger option.

OnRelease parameters

Unlike the other two trigger options, onRelease does not have its own delay parameter. However, as mentioned in the description of the onPress trigger option, the onRelease trigger will be delayed automatically in case the onPress trigger is delayed.

This ensures that the events are always being triggered in order. However, it is possible to prevent onRelease to trigger the Action event altogether if a certain amount of time has passed since the key or button was pressed, or in other words, a trigger timeout.

This is done with the releaseTriggerThreshold attribute. Like the other parameters, it needs to be set in the same node as the onRelease option. The following is an example of how to use this parameter:

<action name="detonate" onRelease="1" releaseTriggerThreshold="3">
  <keyboard input="h" />
</action>

With the preceding setup, the detonate Action will only trigger if the h key was pressed and released, but only if the key was not held down for more than 3 seconds.

Analog input

A key on a keyboard or a button on a mouse only has two states it can be in, either up or down. The Xbox and PS3 game controllers, however, also have analog controls such as the thumb sticks and the trigger buttons. These controls have no distinct pressed/released states, but instead deliver a value that represents how far they are pressed or how far they have been moved from the center.

You can access the analog value of these inputs in the code that will react to the Action event and use them to modify the game mechanics. The mapping in the ActionMaps also allows us to do some preprocessing of these values.

By using the parameters for analog input handling, you can prevent the Action event from being triggered unless the thumb stick or trigger button are moved above a specified threshold. The following table explains the three attributes required for this. All three need to be specified if analog preprocessing is to be used.

Modifiers

By default, holding Shift, Alt, Ctrl, or the Windows key while pressing any key on the keyboard will be ignored. For example, an Action linked to the input event h will trigger even if the Shift key is held, making the input into a capital letter H.

By specifying noModifiers="1" as an attribute, the Action requires that neither of these modifier keys must be pressed for the event to trigger. In the preceding example, the Action would not trigger when H is typed.

Tip

The keyboard input events are case-insensitive. Specifying the input event h in an Action mapping has the same result as specifying H in the mapping.

<action consoleCmd="1" keyboard="f5" name="save" onPress="1" />

When reacting to Actions, you can either set up your own class to receive the Action events, or you can extend the main existing Action event handler inside PlayerInput.cpp. The next section will cover how to set up a new Action event listener from scratch. This can be useful if, for example, you are implementing a new FlowGraph node that is supposed to trigger when receiving specific Action events. In most cases, however, adding handler code for new Actions inside the PlayerInput class is sufficient. Also, it is both faster and more convenient than setting up an entirely new listener. So, feel free to skip ahead to the Extending PlayerInput section at this time.

Setting up a new Action listener

The Game Action system is implemented like a regular event system. This means it has a list of listener classes that it manages internally whenever an event is triggered, a callback function is called in every class in that list with the event name and some parameters. In order for any class to receive the events it sends out, it needs to derive from a listener interface base class and register itself with the system as a listener.

Classes need to derive from the IActionListener interface to receive Action events

Note that the preceding diagram is only for demonstration. In fact, most classes are actually not derived from the IActionListener interface directly. They either receive their triggers via the PlayerInput class or are implemented as GameObject, which is in turn derived from the IActionListener interface.

For the Game Action system, the interface class that you will need to derive your system from is called IActionListener. This is defined in the file IActionMapManager.h, which you will need to include in your own header file as follows:

#include <IActionMapManager.h>

class CMyOwnClass : public IActionListener
{
public: 
  // ...
};

After deriving from the interface, you will need to implement the callback function to receive the Action events. This function is called OnAction and should be declared as follows:

virtual void OnAction(const ActionId& action, int activationMode, float value) {}

You can leave the body of the function empty for now. Before you can start catching the event, you will need to register your class as a listener with the ActionMapManager. Inside your classes initialization function, add the following lines of code:

IGameFramework* pGameFrmWk = gEnv->pGame->GetIGameFramework();
IActionMapManager* pActMan = pGameFrmWk->GetIActionMapManager();
pActMan->AddExtraActionListener(this);

Now, your OnAction() function will be called whenever an Action event is being triggered. The parameters of this function are practically the same as they were for the handler functions when extending the PlayerInput class, so please see the next section for a detailed description.

Extending PlayerInput

The class CPlayerInput inside PlayerInput.cpp in the Game DLL handles almost all Action events that are related to the player. The player class CPlayer itself is implemented as a GameObject (meaning it has a GameObject proxy), which is derived from the IActionListener interface. The CPlayerInput class registers itself with the player's GameObject as the main Action handler class. This means the GameObject will forward all received Action events to this class.

Classes need to derive from the IActionListener interface to receive Action events

The CPlayerInput class links a list of handler functions to specific Action events. If the class receives a certain Action event, it will call the linked function automatically.

It is very easy to add your own handler code in this class. For one, it is good practice to keep all code related to input inside one class, as it makes debugging simpler. But it also requires the least amount of work, since you don't need to write any management code to register or deregister yourself from the ActionMapManager. All you need to add is one function to handle the specific Action event that you are interested in and a single line to register it inside CPlayerInput.

Creating a new handler function

To add a handler for your newly created Action, implement a new function inside the CPlayerInput class. The function needs to follow a specific declaration:

bool NewHandlerFunction(EntityId entityId, const ActionId& actionId, int activationMode, float value);

Let's take a look at the parameters of this function. The first parameter is the entity ID of the player character. The second parameter is the name of the Action event. As your handler function will be linked directly to just one Action, this is irrelevant at this point. If you are implementing an Action listener from scratch or are using the same handler function for more than one Action event, you can use this variable to distinguish between different Actions.

The third parameter, activationMode, contains the trigger options that spawned the event. This will correspond to the trigger options set up in the mapping, and the values are either eAAM_OnPress, eAAM_OnRelease, or eAAM_OnHold.

The last parameter, value, contains an analog value. What this value represents depends on the input device. For keyboard keys and mouse buttons, this value will either be 0 or 1. However, for game controllers' thumb sticks or trigger buttons, this represents how far the trigger or stick is pushed. For mouse movements and the mouse wheel, this contains a delta value.

You can use these values to modify your response to the Action event. The intensity with which a trigger button is pressed determines how fast a vehicle is accelerates. Otherwise, the distance of the thumb stick from the center determines whether the player is walking or running.

When working with these values, consider that due to the nature of analog sticks these hardly ever return to an exact 0.0 value when they are released. It might make sense to work with a so-called "dead zone", which is a small range around 0.0 in which your function simply ignores the Action and pretends the stick was at the center. This way you will prevent things like camera or player movement when the user is not even touching the thumb stick.

When you implement your handler function inside the source file, be sure to return true to indicate that you have handled the event.

Registering your handler function

Before your handler function will be called, you will need to link it to the Action event you want it to handle. This is done in a single line in the CPlayerInput's constructor. All handler functions are registered here. This is an excerpt from the constructor:

ADD_HANDLER(moveforward, OnActionMoveForward);
ADD_HANDLER(moveback, OnActionMoveBack);
ADD_HANDLER(moveleft, OnActionMoveLeft);
ADD_HANDLER(moveright, OnActionMoveRight);

The ADD_HANDLER function has two parameters: the name of the Action event you intend to handle and the function that handles it. At the bottom of the constructor, add your own function and Action event.

ADD_HANDLER(NewAction, NewHandlerFunction);

Now, you are all set to receive Action events and respond to them.

IGameFramework* pGameFrmWk = gEnv->pGame->GetIGameFramework();
IActionMapManager* pActMan = pGameFrmWk->GetIActionMapManager();
IActionMap* pActnMap = pActMan->GetActionMap("NewActionMap");
pActnMap->SetActionListener( m_pPlayer->GetEntityId() );

You don't need to meddle with the source code to react to Action events. The FlowGraph node Input:Action offers easy access to the Game Actions system. To use this node, you will only need to know the name of the Action you want to respond to and the ActionMap it is defined in.

Inside your FlowGraph, add the node Input:Action. The node can only react to onPress and onRelease triggers; the onHold trigger will be ignored. The node looks like the following:

Before you can use this node, you will need to set up your Action event and ActionMap name. The node also requires the local player's entity to be assigned on it. You will also need to call the Enable port once to start listening to events. A possible setup can look like the following:

Generally, it is recommended that you don't use this FlowGraph node to listen to Action events, because the current implementation does not make use of the Game Actions system properly. It neither checks whether an ActionMap is active or not, nor does it respect the trigger options. If you need a proper Action event listening FlowGraph node for your project, you can use the information in this chapter to implement your own.

Action Filters are created in code, and they need to be registered with the ActionMapManager. The best place to do this is inside the CGameActions class in GameActions.h/GameActions.cpp. This class has direct access to all registered Action events and it is accessible from the CryGameSDK DLL. If you register your filter from another place, you should include GameActions.h and refer to the Action events by using CGameAction::ActionEventName. This section will take you through the process of creating a new Action Filter.

First, you need to retrieve a pointer to the ActionMapManager. Then you can create a new Action Filter. You will need to provide a name for the filter to access it again later and a filtering mode. There are two modes available:

Then, you can start adding Actions to the newly created filter. Here is some example code that creates a simple filter to block player movement:

IGameFramework* pGameFrmWk = gEnv->pGame->GetIGameFramework();
IActionMapManager* pActMan = pGameFrmWk->GetIActionMapManager();

IActionFilter* pNewFilter; 
pNewFilter = pActMan ->CreateActionFilter("no_move", eAFT_ActionFail);
pNewFilter->Filter(jump);
pNewFilter->Filter(moveleft);
pNewFilter->Filter(moveright);
pNewFilter->Filter(moveforward);
pNewFilter->Filter(moveback);

Once the Action Filter has been created, it can be activated or deactivated either from code or from FlowGraph. Both mechanics are explained as follows:

Like the Game Actions system, the input system is an event system. It sends out the input events to all classes that have registered themselves as listeners. To become a listener, a class needs to derive from the interface IInputEventListener.

#include <IInput.h>

class CMyOwnClass : public IInputEventListener
{
public: 
  // ...
};

To compile this without error, the class needs to implement the callback function that the input system will call with the input events. This function should return false to allow other listeners to also receive the event. If true is returned, the rest of the listeners will not be called.

virtual bool OnInputEvent( const SInputEvent &event );

This function will receive all input events dispatched by the input system, coming from all supported devices. The parameter event contains all information about the input event needed to process it. These are the members of the SInputEvent struct and their descriptions:

Most key and button presses will trigger at least two input events: once when the key is pressed down and once again when it is released. A common implementation of the OnInputEvent() function compares the keyName to all input event names it wants to react to, and then it checks the state of the input control before it reacts to the input. The state check is necessary so that the code doesn't respond to the same key pressed twice. This is not necessary of course for the non-button events, such as the mouse wheel or mouse movement for example.

You can either check the keyName directly by using a string compare or check the keyId against the enum value of your input event. A table listing the most common input event names can be found at the end of this chapter in the section The input event names reference.

The FlowGraph also provides the option to react to input events, making it easy for level designers to prototype new ideas. The node for this is called Debug:InputKey (note that this was called Input:Key in the previous CryENGINE releases).

Having many of these nodes in a level will cause a lot of string compare operations in nearly every frame, which can take a bite out of performance. In addition to that, input events are not filtered (like Action events), nor can they be remapped easily at runtime. Therefore, it is advised that all functionality prototyped with this node should be converted into a code-based solution. Instead of input events, it would also make sense to use Actions in this implementation.

To encourage implementing Actions properly, this node has been moved into the Debug category by Crytek. This means it is not intended to be used in a shipped product, but only for development and debugging purposes. By default, it will not work outside of the Sandbox editor.

To make this node work in launcher, it must have the local player's entity assigned to it, the NonDevMode checkbox must be checked, and the Enable port has to be triggered. Depending on your system configuration, you might also need to set the console variable g_disableInputKeyFlowNodeInDevMode to 0 inside your system.cfg file.

The preceding example shows how to receive left and right mouse movements by using the Debug:InputKey FlowGraph node. To catch input events with this node, you need to provide the name of the input event in the Key port of the node. A table listing the most common input event names can be found at the end of this chapter in the section The input event names reference.