View source for User:Matty Smith/Sandbox

[[Category:Sandbox]]
<!--
{{GameCategory|arma3|Editing}}
[[Category:Introduced with {{arma3}} version 2.06]]
-->
{{TOC|side}}

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

<syntaxhighlight lang="cpp">
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).
	};
};
</syntaxhighlight>

== Adding a new key ==
=== Defining a new action in CfgUserActions ===
<syntaxhighlight lang="cpp">
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).
	};
};
</syntaxhighlight>

=== Defining a default keybind in CfgDefaultKeysPresets ===
<syntaxhighlight lang="cpp">
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".
			};
		};
	};
};
</syntaxhighlight>
{{Feature|Warning|If the key code is large enough, for example {{ic|0x1D130023}} ({{Controls|Ctrl|H}}), then adding values may lead to a wrong result due to rounding errors (see {{HashLink|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 ===
<syntaxhighlight lang="cpp">
class UserActionGroups
{
	class ModSection // Unique classname of your category.
	{
		name = "Mod Section"; // Display name of your category.
		isAddon = 1;
		group[] = {"TAG_MyActionName"};
	};
};
</syntaxhighlight>

=== 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:
<syntaxhighlight lang="cpp">
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"};
	};
};
</syntaxhighlight>


== Scripted Event Handlers ==
<code>[[addUserActionEventHandler]] ["ReloadMagazine", "Activate", {
	[[systemChat]] "Reloading!";
	[[removeUserActionEventHandler]] ["ReloadMagazine", "Activate", [[Magic Variables#thisEventHandler|_thisEventHandler]]];
}];</code>
The persistence of these EHs is the same as that of [[Arma 3: Mission Event Handlers|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:

{| class="wikitable"
!{{ic|0x}}
!{{ic|aa}}
!{{ic|bb}}
!{{ic|cc}}
!{{ic|dd}}
|-
|Description
|Combo key
|Device types
|Main key additional info
|Main key
|-
!colspan="5"| Examples
!Result

|-
|1. {{Controls|A|2×B}}
|DIK_A ({{ic|0x1E}})
|INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_KB ({{ic|0x13}})
|DOUBLE TAP ({{ic|0x10}})
|DIK_B ({{ic|0x30}})
|{{ic|0x1E130130}}

|-
|2. {{Controls|A|MMB click}}
|DIK_A ({{ic|0x1E}})
|INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_MB ({{ic|0x11}})
|None ({{ic|0x00}})
|MOUSE_BUTTONS_MIDDLE + MOUSE_CLICK_OFFSET ({{ic|0x82}})
|{{ic|0x1E110002}}

|-
|3. {{Controls|A}} + Mouse Left (Move)
|DIK_A ({{ic|0x1E}})
|INPUT_DEVICE_COMBO_KB + INPUT_DEVICE_MAIN_MB ({{ic|0x11}})
|None ({{ic|0x00}})
|MOUSE_AXIS_LEFT ({{ic|0x00}})
|{{ic|0x1E110000}}

|-
|4. {{Controls|LMB click|MMB click}}
|MOUSE_BUTTONS_MIDDLE + MOUSE_CLICK_OFFSET ({{ic|0x82}})
|INPUT_DEVICE_COMBO_MB + INPUT_DEVICE_MAIN_MB ({{ic|0x31}})
|None ({{ic|0x00}})
|MOUSE_BUTTONS_LEFT + MOUSE_CLICK_OFFSET ({{ic|0x80}})
|{{ic|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 {{ic|0x00}}.

=== bb - Device types ===

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

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

<syntaxhighlight lang="cpp">
// 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
</syntaxhighlight>

=== 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.

<syntaxhighlight lang="cpp">
#define MAIN_INFO_NONE 0x00000000
#define MAIN_INFO_DOUBLE_TAP 0x00000100
</syntaxhighlight>

=== dd - Main key ===

==== Keyboard Input ====

For keyboard input, the main key is the [[DIK KeyCodes|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.

<syntaxhighlight lang="cpp">
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)
</syntaxhighlight>

==== Mouse Axis ====

<syntaxhighlight lang="cpp">
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
};
</syntaxhighlight>

==== Head Tracker ====

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

<syntaxhighlight lang="cpp">
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
};
</syntaxhighlight>

==== Joysticks ====

<syntaxhighlight lang="cpp">
#define N_JOYSTICK_AXES		8 // 3 normal, 3 rotate, 2 sliders
#define N_JOYSTICK_POV		8 // 8 directional stick
</syntaxhighlight>
There are up to 256 joystick buttons available.