Difference between revisions of "addAction"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (clarified example 2 variable name)
(changelog)
(9 intermediate revisions by 2 users not shown)
Line 25: Line 25:
 
{{!}}{{GVI|arma3|1.81}}
 
{{!}}{{GVI|arma3|1.81}}
 
{{!}}New param is available: ''memoryPoint'' & ''radius'' param is now always referencing distance between player eye position ([[eyePos]]) and object selection, memory point or [0,0,0]; in this order, depending on what params are supplied to the command.
 
{{!}}New param is available: ''memoryPoint'' & ''radius'' param is now always referencing distance between player eye position ([[eyePos]]) and object selection, memory point or [0,0,0]; in this order, depending on what params are supplied to the command.
 +
{{!}}-
 +
{{!}}{{GVI|arma3|1.85}}
 +
{{!}}New condition variable is available: ''_originalTarget'' is the original object to which the action is attached, regardless if the object/unit is in a vehicle or not.
 
{{!}}}
 
{{!}}}
 
|Description=
 
|Description=
Line 69: Line 72:
  
 
<dt>condition:</dt>
 
<dt>condition:</dt>
<dd>[[String]] - (Optional, default "true") script code that must return [[true]] for the action to be shown. Special variables passed to the script code are ''_target'' (object to which action is attached to) and ''_this'' (caller/executing person)
+
<dd>[[String]] - (Optional, default "true") script code that must return [[true]] for the action to be shown. Special variables passed to the script code are:
 +
<ul>
 +
<li>''_target'': [[Object]] - the object to which action is attached or, if the object is a unit inside of vehicle, the vehicle</li>
 +
<li>''_this'': [[Object]] - caller person to whom the action is shown (or not shown if condition returns [[false]])</li>
 +
<li>''_originalTarget'': [[Object]] - the original object to which the action is attached, regardless if the object/unit is in a vehicle or not (''since Arma 3 v1.85.144342'')</li>
 +
</ul>
 
{{Important|
 
{{Important|
 
* ''condition'' is evaluated on each frame in [[Scheduler#Unscheduled_Environment|non-scheduled environment]].
 
* ''condition'' is evaluated on each frame in [[Scheduler#Unscheduled_Environment|non-scheduled environment]].

Revision as of 13:42, 21 August 2018

Hover & click on the images for description

Description

Description:
Template:Feature arma3 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 (default 50m). 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. Template:Informative
Arma 3 logo black.png1.63 Two new params are available: radius and unconscious
Arma 3 logo black.png1.69 New param is available: selection
Arma 3 logo black.png1.81 New param is available: memoryPoint & radius param is now always referencing distance between player eye position (eyePos) and object selection, memory point or [0,0,0]; in this order, depending on what params are supplied to the command.
Arma 3 logo black.png1.85 New condition variable is available: _originalTarget is the original object to which the action is attached, regardless if the object/unit is in a vehicle or not.
Groups:
Uncategorised

Syntax

Syntax:
object addAction [title, script, arguments, priority, showWindow, hideOnUse, shortcut, condition, radius, unconscious, selection, memoryPoint]
Parameters:
object:
Object - unit, vehicle or static object
title:
String - The action name which is displayed in the action menu, may contain XML like syntax. Because of that < and > symbols will be interpreted as opening and closing XML tags. To avoid this use &lt; for < and &gt; for >. The title text can be changed with setUserActionText
script:
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.
  • Parameters array passed to the script upon activation in _this variable is:
    params ["_target", "_caller", "_actionId", "_arguments"];
    
  • target (_this select 0): Object - the object which the action is assigned to
  • caller (_this select 1): Object - the unit that activated the action
  • ID (_this select 2): Number - ID of the activated action (same as ID returned by addAction)
  • arguments (_this select 3): Anything - arguments given to the script if you are using the extended syntax
arguments:
Anything - (Optional, default nil) 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
priority:
Number - (Optional, default 1.5) 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')
showWindow:
Boolean - (Optional, default true) 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
hideOnUse:
Boolean - (Optional, default true) 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
shortcut:
String - (Optional, default "") one of the 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
condition:
String - (Optional, default "true") script code that must return true for the action to be shown. Special variables passed to the script code are:
  • _target: Object - the object to which action is attached or, if the object is a unit inside of vehicle, the vehicle
  • _this: Object - caller person to whom the action is shown (or not shown if condition returns false)
  • _originalTarget: Object - the original object to which the action is attached, regardless if the object/unit is in a vehicle or not (since Arma 3 v1.85.144342)
Template:Important
radius:
Number - (Optional, default 50) 3D distance in meters the unit activating the action must be within to activate it. -1 disables this radius
unconscious:
Boolean - (Optional, default false) if true will be shown to incapacitated player (see setUnconscious, lifeState)
selection:
String - (Optional, default "") named selection in Geometry LOD to which the action is attached
memoryPoint:
String - (Optional, default "") memory point on the object to which the action is attached. If selection is supplied, memoryPoint is not used
Return Value:
Number - The ID of the action is returned. Action can be removed with removeAction (see also removeAllActions. IDs are incrementing, the first given action to each unit has the ID 0, the second the ID 1, etc. IDs are also passed to the called script (see script parameter)

Examples

Example 1:
// short and sweet 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!", name player] }]; player addAction ["String Exec", "hint 'this is also compiled'"];
Example 2:
_actionID = player addAction ["Exec the file", "scriptFile.sqf"] scriptFile.sqf: hint str _this;
Example 3:
// create object on the server and add action to the object on every client if (isServer) then { _object = "some_obj_class" createVehicle [1234, 1234, 0]; [_object, ["Greetings!", {hint "Hello!"}]] remoteExec ["addAction"]; };
Example 4:
Default parameters:this addAction [ "<title>", { params ["_target", "_caller", "_actionId", "_arguments"]; }, [], 1.5, true, true, "", "true", // _target _this 50, false, "", "" ];

Additional Information

See also:
actionIDsactionParamssetUserActionTextinGameUISetEventHandlershowHUDinputActionremoveActionremoveAllActionsactionBIS_fnc_holdActionAdd

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note

Notes

Posted on May 02, 2018 - 13:44 (UTC)
Dedmen
If you want to replicate vanilla Actions like "Treat yourself" where the scroll menu only shows text and it displays the icon mid-screen you can use private _action = player addAction ["Heal", {}]; player setUserActionText [_action , "Heal", "<img size='2' image='\a3\ui_f\data\IGUI\Cfg\Actions\heal_ca'/>"];

Bottom Section