Matty Smith/Sandbox – User

As of 2.06, mods are able to define keys that can be bound by the user in the keybindings.

class CfgUserActions
{
	class TAG_MyActionName // This class name is used for internal representation and also for the inputAction command.
	{
		displayName = "";
		tooltip = "";
		onActivate = "['TAG_MyActionName', true] call TAG_fnc_MyHandler";		// _this is always true.
		onDeactivate = "['TAG_MyActionName', false] call TAG_fnc_MyHandler";	// _this is always false.
		onAnalog = "['TAG_MyActionName', _this] call TAG_fnc_MyAnalogHandler";	// _this is the scalar analog value.
		analogChangeThreshold = 0.01; // Minimum change required to trigger the onAnalog EH (default: 0.01).
	};
};

Adding a new key

Defining a new action in CfgUserActions

class CfgUserActions
{
	class TAG_MyActionName // This class name is used for internal representation and also for the inputAction command.
	{
		displayName = "My Test Action";
		tooltip = "This action is for testing.";
		onActivate = "_this call TAG_fnc_MyHandler";		// _this is always true.
		onDeactivate = "_this call TAG_fnc_MyHandler";		// _this is always false.
		onAnalog = "_this call TAG_fnc_MyAnalogHandler";	// _this is the scalar analog value.
		analogChangeThreshold = 0.1; // Minimum change required to trigger the onAnalog EH (default: 0.01).
	};
};

Defining a default keybind in CfgDefaultKeysPresets

class CfgDefaultKeysPresets
{
	class Arma2 // Arma2 is inherited by all other presets.
	{
		class Mappings
		{
			TAG_MyActionName[] = {
				0x25, // DIK_K
				"256 + 0x25", // 256 is the bitflag for "doubletap", 0x25 is the DIK code for K.
				"0x00010000 + 2" // 0x00010000 is the bitflag for "mouse button".
			};
		};
	};
};

⚠

If the key code is large enough, for example 0x1D130023 (Ctrl + H), then adding values may lead to a wrong result due to rounding errors (see Number - Floating-point Precision). As such, it is recommended to do the calculation manually and use that value instead.

Adding a keybind to the keybind options dialog

class UserActionGroups
{
	class ModSection // Unique classname of your category.
	{
		name = "Mod Section"; // Display name of your category.
		isAddon = 1;
		group[] = {"TAG_MyActionName"};
	};
};

Setting up a collision group (optional)

Class UserActionsConflictGroups provides the ability to configure checks for keybinding collisions. The following example demonstrates how to ensure that the input does not conflict with car movement keybindings:

class UserActionsConflictGroups
{
	class ActionGroups
	{
		TAG_MyActionGroup[] = {"TAG_MyActionName"};
	};

	class CollisionGroups
	{
		// Add your group to an existing collision group:
		carMove[] += {"TAG_MyActionGroup"};

		// Or alternatively add your own collision group (which is usually preferrable):
		TAG_MyActionGroupCollisions[] = {"basic", "vehBasic", "HeadMove", "TAG_MyActionGroup"};
	};
};

Scripted Event Handlers

addUserActionEventHandler ["ReloadMagazine", "Activate", { systemChat "Reloading!"; removeUserActionEventHandler ["ReloadMagazine", "Activate", _thisEventHandler]; }];

The persistence of these EHs is the same as that of Mission Event Handlers - they are scoped per mission and get removed when the mission ends.

See Also:

• addUserActionEventHandler
• removeUserActionEventHandler
• removeAllUserActionEventHandlers

Defining key codes

A key code is defined by 4 bytes (2 hexadecimal digits), each containing a different part of the keycode:

0x	aa	bb	cc	dd	Result
Description	Combo key	Device types	Main key additional info	Main key
Examples
1. A + 2×B	DIK_A (0x1E)	INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_KB (0x13)	DOUBLE TAP (0x10)	DIK_B (0x30)	0x1E130130
2. A + MMB click	DIK_A (0x1E)	INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_MB (0x11)	None (0x00)	MOUSE_BUTTONS_MIDDLE + MOUSE_CLICK_OFFSET (0x82)	0x1E110002
3. A + Mouse Left (Move)	DIK_A (0x1E)	INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_MB (0x11)	None (0x00)	MOUSE_AXIS_LEFT (0x00)	0x1E110000
4. LMB click + MMB click	MOUSE_BUTTONS_MIDDLE + MOUSE_CLICK_OFFSET (0x82)	INPUT_DEVICE_COMBO_MB + INPUT_DEVICE_MAIN_MB (0x31)	None (0x00)	MOUSE_BUTTONS_LEFT + MOUSE_CLICK_OFFSET (0x80)	0x02310000

aa - Combo key

This is the exact same as #dd - Main key, but for the combo key.

If there is not a combo key, use 0x00.

bb - Device types

This specifies the type of the main key, and optionally the combo key.

For a single keybind, use INPUT_DEVICE_SOLO_xx, but for a combo keybind add together the results of INPUT_DEVICE_COMBO_xx and INPUT_DEVICE_MAIN_xx.

// Secondary combo types:
#define INPUT_DEVICE_COMBO_KB 0x00100000 // Keyboard button (key)
#define INPUT_DEVICE_COMBO_MB 0x00300000 // Mouse button
#define INPUT_DEVICE_COMBO_JB 0x00500000 // Joystick button
#define INPUT_DEVICE_COMBO_JP 0x00600000 // Joystick POV
#define INPUT_DEVICE_COMBO_XI 0x00900000 // XBox controller (XInput)

// Main combo types:
#define INPUT_DEVICE_MAIN_MB 0x00010000 // Mouse button
#define INPUT_DEVICE_MAIN_MA 0x00020000 // Mouse axis
#define INPUT_DEVICE_MAIN_KB 0x00030000 // Keyboard button (key)
#define INPUT_DEVICE_MAIN_JB 0x00040000 // Joystick button
#define INPUT_DEVICE_MAIN_JA 0x00050000 // Joystick axis
#define INPUT_DEVICE_MAIN_JP 0x00060000 // Joystick POV
#define INPUT_DEVICE_MAIN_XI 0x00070000 // XBox controller (XInput)
#define INPUT_DEVICE_MAIN_TR 0x00080000 // Movement tracking device

// Device types:
#define INPUT_DEVICE_SOLO_KB 0x00000000 // Keyboard button (key)
#define INPUT_DEVICE_SOLO_MB 0x00010000 // Mouse button
#define INPUT_DEVICE_SOLO_JB 0x00020000 // Joystick button
#define INPUT_DEVICE_SOLO_JA 0x00030000 // Joystick axis
#define INPUT_DEVICE_SOLO_JP 0x00040000 // Joystick POV
#define INPUT_DEVICE_SOLO_XI 0x00050000 // XInput device
#define INPUT_DEVICE_SOLO_TR 0x00080000 // EyeXTracker, TrackIR, FreeTrack, ... exclusive, in this preference
#define INPUT_DEVICE_SOLO_MA 0x00100000 // Mouse axis

cc - Main key additional info

Depending on what the main key is, this can provide additional parameters to the main key

The most common is double tap.

#define MAIN_INFO_NONE 0x00000000
#define MAIN_INFO_DOUBLE_TAP 0x00000100

dd - Main key

Keyboard Input

For keyboard input, the main key is the DIK keycode of the corresponding key.

Mouse Button

For mouse button input, you use the following value, added to an offset depending on if you would like a click or a hold.

enum MouseButtons
{
	MOUSE_BUTTONS_LEFT		= 0,
	MOUSE_BUTTONS_RIGHT		= 1,
	MOUSE_BUTTONS_MIDDLE	= 2,
	MOUSE_BUTTONS_CUSTOM_1	= 3,
	MOUSE_BUTTONS_CUSTOM_2	= 4,
	MOUSE_BUTTONS_CUSTOM_3	= 5,
	MOUSE_BUTTONS_CUSTOM_4	= 6,
	MOUSE_BUTTONS_CUSTOM_5	= 7
};

#define MOUSE_HOLD_OFFSET	0x00
#define MOUSE_CLICK_OFFSET	0x80 // Offset for mouse button click (compared to hold)

Mouse Axis

enum MouseAxis
{
	MOUSE_AXIS_LEFT = 0,
	MOUSE_AXIS_RIGHT = 1,
	MOUSE_AXIS_UP = 2,
	MOUSE_AXIS_DOWN = 3, // Last actual mouse axis, change N_MOUSE_AXES if adding new axis
	MOUSE_AXIS_WHEEL_UP = 4,
	MOUSE_AXIS_WHEEL_DOWN = 5
};

Head Tracker

For head tracker or mouse axis input, the following constants are available:

enum MovementTrackerAxis
{
	TRACK_PITCH = 0,	// Up / down rotation
	TRACK_YAW = 1,		// Left / right rotation
	TRACK_ROLL = 2,		// Side roll
	TRACK_X = 3,		// Left / right move
	TRACK_Y = 4,		// Up / down move
	TRACK_Z = 5		 // Forward / backward move
};

Joysticks

#define N_JOYSTICK_AXES		8 // 3 normal, 3 rotate, 2 sliders
#define N_JOYSTICK_POV		8 // 8 directional stick

There are up to 256 joystick buttons available.