View source for addAction

{{Command|= Comments
____________________________________________________________________________________________

| ofp |= Game name

|1.1|= Game version

|arg= global |= Arguments in MP

|eff= local |= Effects in MP
____________________________________________________________________________________________

| {{Feature arma3| This command syntax is for Arma 3 only. For TKOH and older versions see [[addAction TKOH]]}}
Adds an entry to the action menu of an object (scroll wheel menu). The action can only be activated when in proximity to the object (eg: building). Adding an action to the player obviously makes that action available to the player at all times. The appearance of onscreen text could be further tweaked with [[setUserActionText]]. For event handling of user interaction see [[inGameUISetEventHandler]]<br><br>

This command has [[local]] effect. Created action is only available on the computer where command was executed. To make action available to all players, command must be executed on all connected clients (see [[remoteExec]]). [[addAction]] is also ignored on dedicated server, because of no user interface. In Arma 3 [[addAction]] does not work on animals. This is intended behavior.  <br><br>

Since Arma 3 v1.63.136787, two new params are available: ''radius'' and ''unconscious''.
|= Description
____________________________________________________________________________________________

| unit '''addAction''' [title, script, arguments, priority, showWindow, hideOnUse, shortcut, condition, radius, unconscious] |= Syntax

|p1= <dl>
<dt style="clear:none;">unit:</dt>
<dd>[[Object]] - unit, vehicle or static object</dd>               
<dt>title:</dt>
<dd>[[String]] - The action name which is displayed in the action menu, may contain [[Structured Text|XML like syntax]]. Because of that '''<''' and '''>''' symbols will be interpreted as opening and closing XML tags. To avoid this use '''&amp;lt;''' for '''<''' and '''&amp;gt;''' for '''>'''. The title text can be changed with [[setUserActionText]]</dd>
<dt>script:</dt>
<dd>[[String]] or [[Code]] - Either path to the script file, relative to the mission folder or string with code or the actual script code. If the string is a path to script file, the script file *must* have extension .[[SQS]] or .[[SQF]]. The script, whether it is a file or a code, will run in scheduled environment, i.e. it is ok to use [[sleep]]. 
<ul><li>Parameters array passed to the script upon activation in ''[[_this]]'' variable are: [''target'', ''caller'', ''ID'', ''arguments'']</li>
<li>''target'' (''_this select 0''): [[Object]] - the object which the action is assigned to</li>
<li>''caller'' (''_this select 1''): [[Object]] - the unit that activated the action</li>
<li>''ID'' (''_this select 2''): [[Number]] - ID of the activated action (same as ID returned by [[addAction]])</li>
<li>''arguments'' (''_this select 3''): [[Anything]] - arguments given to the script if you are using the extended syntax</li>
</ul></dd>
<dt>arguments:</dt>
<dd>''(Optional)'': [[Anything]] - Arguments to pass to the script (will be ''_this select 3'' inside the script). If [[Array]] is used as an argument for example, its 1st element reference would be ''_this select 3 select 0''. Default value: [[nil]]</dd>
<dt>priority:</dt>
<dd>''(Optional)'': [[Number]] - Priority value of the action. Actions will be arranged in descending order according to this value. Every game action has a preset priority value. Value can be negative or decimal fraction. Actions with same values will be arranged in order which they were made, newest at the bottom. The bigger the number the higher the action will be positioned on the menu. Typical range is 0 (low priority. Eg: 'Get out') to 6 (high priority. Eg: 'Auto-hover on'). Default value: 1.5</dd>
<dt>showWindow:</dt>
<dd>''(Optional)'': [[Boolean]] - If set to [[true]], players see "Titletext" at mid-lower screen, as they approach the object. Only the title text for the action with highest priority and 'showWindow true' will be shown. Setting it to [[false]] disables the feature. Default value: [[true]]</dd>
<dt>hideOnUse:</dt>
<dd>''(Optional)'': [[Boolean]] - If set to [[true]], it will hide the action menu after selecting that action. If set to [[false]], it will leave the action menu open and visible after selecting that action, leaving the same action highlighted, for the purpose of allowing you to reselect that same action quickly, or to select another action. Default value: [[true]]</dd>
<dt>shortcut:</dt>
<dd>''(Optional)'': [[String]] - One of the [[:Category:Key Actions|key names]] defined in bin.pbo (e.g. "moveForward"). Adding available shortcut will bind corresponding keyboard key to this action. Shortcut availability can be tested with [[inputAction]] command. Default value: ""</dd>
<dt>condition:</dt>
<dd>''(Optional)'': [[String]] - script code that must return [[true]] for the action to be shown. Special variables passed to the script code are ''_target'' (unit to which action is attached to) and ''_this'' (caller/executing unit). Default value: "true"
<div style="margin-left:2em;">'''NOTE:''' <u>condition</u> is evaluated on each frame in non-scheduled environment. If action is added to some object and not to [[player]], <u>condition</u> will only get evaluated IF player is closer than 15m to the object AND is looking at the object. If action is added to [[player]], the <u>condition</u> is evaluated all the time.</div></dd>
<dt>radius:</dt>
<dd>''(Optional)'': [[Number]] - Distance in meters the unit activating the action must be within to activate it. -1 disables this radius. Default (and max) value: 15</dd>
<dt>unconscious:</dt>
<dd>''(Optional)'': [[Boolean]] - if [[true]] will be shown to incapacitated player (see [[setUnconscious]], [[lifeState]]). Default value: [[false]]</dd></dl>|=

| [[Number]]

The ID of the action is returned. IDs are incrementing. The first given action to each unit has got the ID 0, the second the ID 1 etc. ID's are also passed to the called script and used to remove an action with [[removeAction]] |= Return value
____________________________________________________________________________________________
		  
|x1= Short and sweet:<code>[[player]] [[addAction]] ["A Useless Action That Does Nothing", {}];
[[player]] [[addAction]] ["<t color='#FF0000'>This Useless Action Is RED</t>", {[[hint]] "RED"}];
[[player]] [[addAction]] ["Hint Hello!", {[[hint]] [[format]] ["Hello %1!", [[_this]] [[select]] 3]}, [[name]] [[player]]];
[[player]] [[addAction]] ["String Exec", "[[hint]] 'this is also compiled'"];</code> |= Example 1

|x2= [[SQF]] file example: <code>_act = [[player]] [[addAction]] ["Exec the file", "somescript.sqf"]</code>
somescript.sqf:
<code>[[hint]] [[str]] _this;</code> |= Example 2

|x3= [[SQS]] file example: <code>_genAct = generator [[addAction]] ["Switch on generator", "activate_generator.sqs"]</code>
activate_generator.sqs:
<code>_gen = [[_this]] [[select]] 0
_caller = [[_this]] [[select]] 1
_id = [[_this]] [[select]] 2
<nowiki>;</nowiki> remove the action once it is activated
_gen [[removeAction]] _id</code>

This example shows an action called "Switch on generator" added to an object with the name 'generator'. As soon as the player gets close to this object, he can execute the given action via the action menu. Then the script 'activate_generator.sqs' is executed, which in our example only removes the action from the generator. |= Example 3

|x4=Create object on dedicated server and add action to the object on every client:<code>[[if]] ([[isDedicated]]) [[then]]
{
	_obj = "some_obj_class" [[createVehicle]] [1234, 1234, 0];
	[_obj, ["Greetings!", {[[hint]] "Hello!"}]] [[remoteExec]] ["addAction", -2, _obj];
};</code>|= Example 4

____________________________________________________________________________________________

| [[removeAction]], [[removeAllActions]], [[setUserActionText]], [[inputAction]], [[action]], [[inGameUISetEventHandler]] |= See also

}}

<h3 style="display:none">Notes</h3>
<dl class="command_description">
<!-- Note Section BEGIN -->
<dd class="notedate">Posted on August 2, 2006 - 10:10
<dt class="note">'''[[User:Hardrock|hardrock]]'''<dd class="note">
An easy way to keep track of and remove actions is to store the IDs of the actions in variables.
This can be accomplished by doing the following: 
<code>_myaction = [[player]] [[addAction]] ["Hello", "hello.sqs"];</code>
This stores the action's ID in the local variable "_myaction" and assists in keeping track of the action ID.
To remove the above action, you would use the following line: 
<code>[[player]] [[removeAction]] _myaction;</code>
<!-- Note Section END -->
</dd>
</dl>

<h3 style="display:none">Bottom Section</h3>

[[Category:Scripting Commands|ADDACTION]]
[[Category:Scripting Commands Arma 3|{{uc:{{PAGENAME}}}}]]
[[Category:Command_Group:_Activators|{{uc:{{PAGENAME}}}}]]
[[Category:Command_Group:_Interaction|{{uc:{{PAGENAME}}}}]]
[[Category:Command_Group:_Unit_Control|{{uc:{{PAGENAME}}}}]]

<!-- CONTINUE Notes -->
<dl class="command_description">
<dd class="notedate">Posted on June 19, 2014 - 15:01 (UTC)</dd>
<dt class="note">'''[[User:Krzmbrzl00|Krzmbrzl00]]'''</dt>
<dd class="note">If executing ''actual script code'' like this:
<code>_unit [[addAction]] [ "yourAction", { [[hint]] "A line of code" } ];</code>
:you can have a user action that uses and/or affects variables used elsewhere in the script that adds the action.
'''But beware!'''<br>
The variable(s) must be global otherwise it won't work! ''i.e.''
;Fail:<code>_variable = [[false]];<br>_unit [[addAction]] [ "action", { _variable = [[true]] } ];</code>
;Succeed:<code>variable = [[false]];<br>_unit [[addAction]] [ "action", { variable = [[true]] } ];</code>
</dd>
</dl>
<!-- DISCONTINUE Notes -->

<!-- CONTINUE Notes -->
<dl class="command_description">
<dd class="notedate">Posted on March 10, 2015 - 09:55 (UTC)</dd>
<dt class="note">[[User:Killzone Kid|Killzone Kid]]</dt>
<dd class="note">
 Actionception:<code>actions = [];
actions [[set]] [0, [[player]] [[addAction]] ["Actionception", {
	[[if]] ([[count]] actions == 1) [[then]] {
		actions [[set]] [1, [[player]] [[addAction]] [" Actionception ", {
			[[if]] ([[count]] actions == 2) [[then]] {
				actions [[set]] [2, [[player]] [[addAction]] ["  Actionception  ", {
					[[if]] ([[count]] actions == 3) [[then]] {
						actions [[set]] [3, [[player]] [[addAction]] ["   Actionception   ", {
							{
								[[player]] [[removeAction]] [[Magic Variables|_x]];
							} [[forEach]] actions;
						}, [], 10, [[false]], [[true]]]];
					};
				}, [], 10, [[false]], [[false]]]];
			};
		}, [], 10, [[false]], [[false]]]];
	};
}, [], 10, [[false]], [[false]]]];</code>

Function to remove user actions with unknown ids:
<code>KK_fnc_removeUnknownUserActions <nowiki>=</nowiki> {
	[[for]] "_i" [[from]] 0 [[to]] ([[player]] [[addAction]] ["",""]) [[do]] {
		[[if]] !(_i [[in]] [[_this]]) [[then]] {
			[[player]] [[removeAction]] _i;
		};
	};
};</code>
To test:
<code>[[for]] "_i" [[from]] 0 [[to]] 9 [[do]] {
	[[player]] [[addAction]] ["Action #" + [[str]] _i, {
		[0,5,6] [[call]] KK_fnc_removeUnknownUserActions; 
	}];
};
</code>
Removes all user actions but 0, 5 and 6.
</dd>
</dl>
<!-- DISCONTINUE Notes -->

<!-- CONTINUE Notes -->
<dl class="command_description">
<dd class="notedate">Posted on July 18, 2016 - 01:13 (UTC)</dd>
<dt class="note">'''[[User:longbow|longbow]]'''</dt>
<dd class="note">
'''A3 v1.62.137494''': Condition is not evaluated when map is opened (and probably also true for other displays or opened dialog)
</dd>
</dl>
<!-- DISCONTINUE Notes -->