Page tree
Skip to end of metadata
Go to start of metadata


Introduced in

Version:1.20

Description

Description: Add an action to an object. The action is usable by the object itself, as well as anyone who is within proximity of the object and is looking at it.

If an action is added to a unit, the action will only be visible when the unit is on foot. If the unit enters a vehicle, the action will not be visible, not to the unit, or to anyone in / near his vehicle. To make the action stay visible even after the unit enters a vehicle, use fn vbs addActionEx.

The action will run a script, which will have the following parameters passed to it in the _this variable:

[target, caller, ID, data]

  • target: Object - the object which the action is assigned to
  • caller: Object - the unit that activated the action
  • index: Number - index of the activated action (used to remove action)
  • data: Anything - extra arguments passed to the addAction command (see syntax)

Syntax

Syntax: holder addAction [title, filename, arguments, priority, showWindow, hideOnUse, shortcut, condition]
Parameters:
  • holder: Object - Object to assign the action to
  • title: String - The action name which is displayed in the action menu.
  • filename: String - Path to the script that is called when the action is activated. Relative to the mission folder.
  • arguments: Anything - Extra data to pass to the script (will be (_this select 3) for the script) (optional)
  • priority: Number - Priority value of the action (determines how high it appears in the action menu). Actions will be arranged descending according to this. Every game action has a preset priority value. Value can be negative. Actions with same values will be arranged in order which they were made, newest at the bottom. (optional)
  • showWindow: Boolean - If set true, action menu will appear on screen as soon as action is available. If false, action will still be added to menu, but will not cause it to appear if hidden. (optional)
  • hideOnUse: Boolean - If set to true, the action menu will hide itself after action is used. If false, action menu will stay open and on selected action after use. (optional)
  • shortcut: String - VBS Key Actions that will activate action. DIK KeyCodes can also be used. Use empty string for no shortcut (""). (optional)
  • condition: String - (optional, default true) Code that must return true for action to be shown. Variables "_target" (object action is attached to) and "_this" (executing unit) can be used in the evaluation. (optional)
Return Value: Number - Index of the added action. Used to remove the action with removeAction

Alternative Syntax

Syntax:holder addAction [[aim, fov, los, tolerance], title, filename, ...] (V2.00+)
Parameters:
  • holder: Object - Object to assign the action to
  • aim: Boolean - If true, then the player's cursor must be aimed at the holder. (If the object is obstructed, "aim" will always be false, even when the player points at it, and the "los" check has been disabled.)
  • fov: Boolean - If true, then the holder must be within the player's field of view (somewhat in front of him). (Even if disabled, the action will disappear if the player's angle is about 90º away from the object.)
  • los: Boolean - If true, then the holder must be within the player's line of sight (not obstructed).
  • tolerance: Number - Distance (in meters) holder can be outside of the player's line of sight, and still be considered visible. (Some objects -even small ones- may need a tolerance>0 in order for "los" to return true - even if there are no external obstructions between the player and the object.)
  • title: String - The action name which is displayed in the action menu.
  • filename: String - Path to the script that is called when the action is activated. Relative to the mission folder.
  • ... all other arguments as in standard syntax described above ...
Return Value:Number - Index of the added action. Used to remove the action with removeAction

Examples

Examples: Adds "hello" to the player's action menu. On execution, passes an array of caller, target and index to "hello.sqf", see description above.
IDindex = player addAction ["Hello", "hello.sqf"];

hello.sqf:

_target = _this select 0;
_caller = _this select 1;

hint format ["%1 says hello to %2", name _caller, name _target];
Adds "hello" to the action menu of the player driving vic1. On execution, passes an array to "hello.sqf", see description above.
IDindex = vehicle vic1 addAction["Hello", "hello.sqf", [], 6, true, true, "", "driver _target == player"];

Additional Information

See also: removeAction, fn vbs addActionEx
Multiplayer:Multiplayer usage of this command can be complicated, because everything about the command is local. This has a number of implications. For example, a given object might have no actions on client A, 1 action on client B, and 2 actions on client C. Each client sees and uses separate actions; nothing is shared across the network. This means:

-The script run when the action is used only runs on the client that used the action.

-Actions are only visible on the computer where they were added. To make an action visible to all clients, the addAction command must be executed on all of them. When doing this, however, the index returned by the command can vary across all clients.

-Actions are only removed on the computer where the removeAction command was given.

This means, for example, that the self-removing action menu example, given above, would not work properly in a networked environment. If one client used the generator, he would no longer see the generator action; howoever, all other clients would still see the action until they themselves used it.
Problems: 

Notes