{"name":"addAction","operator":null,"title":"addAction","type":"command","url":"https://community.bistudio.com/wiki/addAction","revid":378569,"updated":"2026-05-08T21:16:48Z","groups":["Interaction"],"status":"ok","replaced_by":[],"games":[{"game":"arma3","name":"Arma 3","version":"0.50"}],"since":{"game":"arma3","name":"Arma 3","version":"0.50"},"arma3_since":"0.50","branch":null,"locality":{"argument":"global","effect":"local","server_exec":false},"exec":null,"description":"Adds an entry to the action menu of an object. The action can only be activated when in proximity to the object **and** looking at it. Adding an action to the player makes that action available to the player at all times. For event handling of user interaction see inGameUISetEventHandler.","syntaxes":[{"syntax":"object addAction [title, script, arguments, priority, showWindow, hideOnUse, shortcut, condition, radius, unconscious, selection, memoryPoint]","since":null,"effect":null,"exec":null,"params":[{"name":"object","type":"Object","optional":false,"default":null,"description":"unit, vehicle or static object. **No agents and simple objects!**","types":["Object"],"since":null,"text":"**object**: Object - unit, vehicle or static object. **No agents and simple objects!**"},{"name":"title","type":"String","optional":false,"default":null,"description":"the action name displayed in the action menu, may contain Structured Text. Because of that **<** and **>** symbols will be interpreted as opening and closing XML tags. To avoid this use `<` for **<** and `>` for **>**. The title text appearance can be changed with setUserActionText","types":["String"],"since":null,"text":"**title**: String - the action name displayed in the action menu, may contain Structured Text. Because of that **<** and **>** symbols will be interpreted as opening and closing XML tags. To avoid this use `<` for **<** and `>` for **>**. The title text appearance can be changed with setUserActionText"},{"name":"script","type":"String or Code","optional":false,"default":null,"description":"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:\n\n```sqf\nparams [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"];\n```\n\n- **target**: Object - the object which the action is assigned to\n- **caller**: Object - the unit that activated the action\n- **actionID**: Number - activated action's ID (same as addAction's return value)\n- **arguments**: Anything - arguments given to the script if you are using the extended syntax","types":["String","Code"],"since":null,"text":"**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:\n\n```sqf\nparams [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"];\n```\n\n- **target**: Object - the object which the action is assigned to\n- **caller**: Object - the unit that activated the action\n- **actionID**: Number - activated action's ID (same as addAction's return value)\n- **arguments**: Anything - arguments given to the script if you are using the extended syntax"},{"name":"arguments","type":"Anything","optional":true,"default":"nil","description":"arguments to pass to the script. Accessible with `_this select 3` inside the script. If Array is used as an argument for example, its first element reference would be `_this select 3 select 0`","types":["Anything"],"since":null,"text":"**arguments**: Anything - (Optional, default nil) arguments to pass to the script. Accessible with `_this select 3` inside the script. If Array is used as an argument for example, its first element reference would be `_this select 3 select 0`"},{"name":"priority","type":"Number","optional":true,"default":"1.5","description":"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 to 6","types":["Number"],"since":null,"text":"**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 to 6"},{"name":"showWindow","type":"Boolean","optional":true,"default":"true","description":"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* set to true will be shown","types":["Boolean"],"since":null,"text":"**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* set to true will be shown"},{"name":"hideOnUse","type":"Boolean","optional":true,"default":"true","description":"if set to true, it will hide the action menu after selecting it. If set to false, it will leave the action menu open and visible after selecting the action, leaving the same action highlighted, for the purpose of allowing you to re-select that same action quickly, or to select another action","types":["Boolean"],"since":null,"text":"**hideOnUse**: Boolean - (Optional, default true) if set to true, it will hide the action menu after selecting it. If set to false, it will leave the action menu open and visible after selecting the action, leaving the same action highlighted, for the purpose of allowing you to re-select that same action quickly, or to select another action"},{"name":"shortcut","type":"String","optional":true,"default":"\"\"","description":"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","types":["String"],"since":null,"text":"**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"},{"name":"condition","type":"String","optional":true,"default":"\"true\"","description":"expression that must return true for the action to be shown. **Special variables** passed to the script code are:\n- *_target*: Object - The object to which action is attached or, if the object is a unit inside of vehicle, the vehicle\n- *_this*: Object - Caller person to whom the action is shown (or not shown if *condition* returns false)\n- *_originalTarget*: Object - The original object to which the action is attached, regardless if the object/unit is in a vehicle or not\n- *_actionId*: Number - checked action's ID (same as addAction's return value)\n\n> [!WARNING]\n> If the player is the group leader, has an action added to them, and selects a subordinate, `*_this*` alternatively switches between the player and this selected unit - RPT logging `Unknown attribute itemsCmd` in the process.\n\n> [!IMPORTANT]\n> - *condition* is evaluated on each frame in unscheduled environment.\n> - *condition* is **not** evaluated if a dialog is open.\n> - If action is added to an object and not to the player, *condition* will only get evaluated if the player is closer than ~50m to the object surface and is looking at the object.\n> - If action is added to player, *condition* is evaluated all the time.","types":["String"],"since":null,"text":"**condition**: String - (Optional, default \"true\") expression that must return true for the action to be shown. **Special variables** passed to the script code are:\n- *_target*: Object - The object to which action is attached or, if the object is a unit inside of vehicle, the vehicle\n- *_this*: Object - Caller person to whom the action is shown (or not shown if *condition* returns false)\n- *_originalTarget*: Object - The original object to which the action is attached, regardless if the object/unit is in a vehicle or not\n- *_actionId*: Number - checked action's ID (same as addAction's return value)\n\n> [!WARNING]\n> If the player is the group leader, has an action added to them, and selects a subordinate, `*_this*` alternatively switches between the player and this selected unit - RPT logging `Unknown attribute itemsCmd` in the process.\n\n> [!IMPORTANT]\n> - *condition* is evaluated on each frame in unscheduled environment.\n> - *condition* is **not** evaluated if a dialog is open.\n> - If action is added to an object and not to the player, *condition* will only get evaluated if the player is closer than ~50m to the object surface and is looking at the object.\n> - If action is added to player, *condition* is evaluated all the time."},{"name":"radius","type":"Number","optional":true,"default":"50","description":"maximum 3D distance in meters between the activating unit's eyePos and *object**s* memoryPoint*,* selection *or position. -1 disables the radius; hardcoded limit is** 50*'","types":["Number"],"since":"arma3 1.64","text":"**radius**: Number - (Optional, default 50) maximum 3D distance in meters between the activating unit's eyePos and *object**s* memoryPoint*,* selection *or position. -1 disables the radius; hardcoded limit is** 50*'"},{"name":"unconscious","type":"Boolean","optional":true,"default":"false","description":"if true will be shown to incapacitated player. See also setUnconscious and lifeState","types":["Boolean"],"since":"arma3 1.64","text":"**unconscious**: Boolean - (Optional, default false) if true will be shown to incapacitated player. See also setUnconscious and lifeState"},{"name":"selection","type":"String","optional":true,"default":"\"\"","description":"*object*'s geometry LOD's named selection","types":["String"],"since":"arma3 1.70","text":"**selection**: String - (Optional, default \"\") *object*'s geometry LOD's named selection"},{"name":"memoryPoint","type":"String","optional":true,"default":"\"\"","description":"*object*'s memory point. If *selection* is supplied, *memoryPoint* is not used","types":["String"],"since":"arma3 1.82","text":"**memoryPoint**: String - (Optional, default \"\") *object*'s memory point. If *selection* is supplied, *memoryPoint* is not used"}],"returns":{"type":"Number","types":["Number"],"description":"the added action's ID. 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 the script parameter)","text":"Number - the added action's ID. 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 the *script* parameter)"},"form":"binary","operator":null,"left":{"text":"object","types":["Object"]},"right":{"text":"[title, script, arguments, priority, showWindow, hideOnUse, shortcut, condition, radius, unconscious, selection, memoryPoint]","types":["Array"]}}],"examples":[{"text":"```sqf\n// short and sweet\nplayer addAction [\"a useless action that does nothing\", {}];\nplayer addAction [\"<t color='#FF0000'>This Useless Action Is RED</t>\", { hint \"RED\" }];\nplayer addAction [\"Hint Hello!\", { hint format [\"Hello %1!\", name player] }];\nplayer addAction [\"String Exec\", \"hint 'this is also compiled'\"];\n```","code":["// short and sweet\nplayer addAction [\"a useless action that does nothing\", {}];\nplayer addAction [\"<t color='#FF0000'>This Useless Action Is RED</t>\", { hint \"RED\" }];\nplayer addAction [\"Hint Hello!\", { hint format [\"Hello %1!\", name player] }];\nplayer addAction [\"String Exec\", \"hint 'this is also compiled'\"];"]},{"text":"```sqf\n_actionID = player addAction [\"Exec the file\", \"scriptFile.sqf\"];\n```\n\n**scriptFile.sqf:**\n\n```sqf\nhint str _this;\n```","code":["_actionID = player addAction [\"Exec the file\", \"scriptFile.sqf\"];","hint str _this;"]},{"text":"```sqf\n// create object on the server and add action to the object on every client\nif (isServer) then\n{\n    private _object = \"some_obj_class\" createVehicle [1234, 1234, 0];\n    [_object, [\"Greetings!\", { hint \"Hello!\"; }]] remoteExec [\"addAction\"]; // Note: does not return action id\n};\n```","code":["// create object on the server and add action to the object on every client\nif (isServer) then\n{\n\tprivate _object = \"some_obj_class\" createVehicle [1234, 1234, 0];\n\t[_object, [\"Greetings!\", { hint \"Hello!\"; }]] remoteExec [\"addAction\"]; // Note: does not return action id\n};"]},{"text":"Default parameters:\n\n```sqf\nthis addAction\n[\n    \"title\",\n    {\n        params [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"];\n    },\n    nil,\n    1.5,\n    true,\n    true,\n    \"\",\n    \"true\",\n    50,\n    false,\n    \"\",\n    \"\"\n];\n```","code":["this addAction\n[\n\t\"title\",\n\t{\n\t\tparams [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"];\n\t},\n\tnil,\n\t1.5,\n\ttrue,\n\ttrue,\n\t\"\",\n\t\"true\",\n\t50,\n\tfalse,\n\t\"\",\n\t\"\"\n];"]},{"text":"Default parameters with comments:\n\n```sqf\nthis addAction\n[\n    \"title\",    // title\n    {\n        params [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"]; // script\n    },\n    nil,        // arguments\n    1.5,        // priority\n    true,        // showWindow\n    true,        // hideOnUse\n    \"\",            // shortcut\n    \"true\",        // condition\n    50,            // radius\n    false,        // unconscious\n    \"\",            // selection\n    \"\"            // memoryPoint\n];\n```","code":["this addAction\n[\n\t\"title\",\t// title\n\t{\n\t\tparams [\"_target\", \"_caller\", \"_actionId\", \"_arguments\"]; // script\n\t},\n\tnil,\t\t// arguments\n\t1.5,\t\t// priority\n\ttrue,\t\t// showWindow\n\ttrue,\t\t// hideOnUse\n\t\"\",\t\t\t// shortcut\n\t\"true\",\t\t// condition\n\t50,\t\t\t// radius\n\tfalse,\t\t// unconscious\n\t\"\",\t\t\t// selection\n\t\"\"\t\t\t// memoryPoint\n];"]}],"multiplayer":"The command will be ignored on dedicated servers, probably because no UI exists.","problems":null,"aliases":[],"see_also":["actionIDs","actionParams","setUserActionText","inGameUISetEventHandler","showHUD","inputAction","removeAction","removeAllActions","action","shownAction","BIS_fnc_holdActionAdd"],"notes":[{"user":"Dedmen","date":"2018-05-02T13:44:00Z","text":"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\n\n```sqf\nprivate _actionId = player addAction [\"Heal\", {}];\nplayer setUserActionText [_actionId, \"Heal\", \"<img size='2' image='\\a3\\ui_f\\data\\IGUI\\Cfg\\Actions\\heal_ca'/>\"];\n```"},{"user":"PierreMGI","date":"2020-05-12T10:42:00Z","text":"addAction on unit or player stays on corpse after kill. So this action is lost for the new body after respawn. If you want a persistent addAction, you need to add it in the respawn script (onPlayerRespawn.sqf or addMissionEventHandler \"entityRespawned\" or addMPEventHandler \"MPrespawn\"...\nYou can use removeAllActions on corpse."},{"user":"Leopard20","date":"2022-08-28T21:52:00Z","text":"If the server blocks execVM in CfgRemoteExec, you can't use path to script:\n\n```sqf\n_obj addAction [\"Test\", \"path\\script.sqf\"]; // \"path\\script.sqf\" won't execute\n```\n\nYou can, however, do this:\n\n```sqf\n_obj addAction [\"Test\", { _this spawn compile preprocessFileLineNumbers \"path\\script.sqf\" }];\n```\n\nBut it's recommended to use functions if the script is called frequently."}],"categories":["ArmA: Armed Assault: Scripting Commands","Arma 2: Operation Arrowhead: Scripting Commands","Arma 2: Scripting Commands","Arma 3: New Scripting Commands","Arma 3: Scripting Commands","Command Group: Interaction","Introduced with Arma 3 version 0.50","Introduced with Operation Flashpoint version 1.10","Operation Flashpoint: New Scripting Commands","Operation Flashpoint: Scripting Commands","Scripting Commands","Scripting Commands: Local Effect","Take On Helicopters: Scripting Commands"]}