Magic Variables: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(added thisTrigger, _forEachIndex, _x for count)
m (Text replacement - "{{Feature|Warning|" to "{{Feature|warning|")
 
(40 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Stub}}
{{TOC|side}}
=== Introduction ===
__NOEDITSECTION__
Magic variables are engine-maintained [[Variables|variables]] that serve a specific purpose within a given scope and are often used by the engine to provide data to a [[Script File|script]] or [[Code|code]] fragment.<br>
They are usually no longer present after leaving the scope (e.g. after code execution or after a [[forEach]]-statement).


'''Magic variables''' are engine maintained [[Variables|variables]] that serve a specific purpose within a given scope and are often used by the engine to push data to a given [[Script (File)|script]] or [[Code|code]] fragment. They are usually no longer present after leaving the scope (e.g. after code execution, or after a [[forEach]] statement).


=== Uses ===
{{ConfigPage|start}}
{{ConfigPage|abc}}
==== _this ====
Used to make the arguments of a script call ([[call]], [[exec]], [[execVM]], [[spawn]]) visible and accessible to the script. Also used by [[:Category:Event Handlers|Event Handlers]] to provide parameters.


*The most frequently used magic variable probably is <tt>_[[this]]</tt>, which is used to make arguments of a script call ([[call]], [[exec]], [[execVM]], [[spawn]]) visible and accessible to the script.
 
*Other uses of magic variables can be seen in [[forEach]], where the current element can be accessed via <tt>_x</tt> and the current index with <tt>_forEachIndex</tt>.
==== _x ====
*In the condition of the extended syntax of [[count]] variable <tt>_x</tt> refers to the current tested element.
Represents the current element during iteration with [[apply]], [[count]], [[configClasses]], [[configProperties]], [[findIf]], [[forEach]] and [[select]].
*[[Triggers]] also define <tt>[[thisList]]</tt> and <tt>[[thisTrigger]]</tt>, which is however only accessible within the activation or deactivation script.
 
*[[Exception handling]] using a [[try]]..[[catch]] statement usually declare a magic variable named <tt>_exception</tt>, which contains details about the exception [[throw]]n in the try-block.
 
{{ArgTitle|4|_y|{{GVI|arma3|2.02}}}}
Iterating over a [[HashMap]] with [[forEach]] will return the key as [[#x|_x]] and the value as [[#y|_y]].
 
 
{{ArgTitle|4|_exception|{{GVI|arma1|1.00}}}}
[[Exception handling]] using a [[try]]-[[catch]]-statement declares this variable which contains details about the [[throw|thrown]] exception in the [[try]]-block.
 
 
{{ArgTitle|4|_fnc_scriptName|{{GVI|arma3|1.00}}}}
{{Feature|informative|Not engine-maintained, but added by {{hl|functions_f/initFunctions.sqf}} – see [[scriptName]].}}
Within a [[:Category:Functions|Function]], the {{hl|TAG_fnc_functionName}} function name (e.g. {{hl|"myTag_fnc_myFunction"}}).
 
 
{{ArgTitle|4|_fnc_scriptNameParent|{{GVI|arma3|1.00}}}}
{{Feature|informative|Not engine-maintained, but added by {{hl|functions_f/initFunctions.sqf}} – see [[scriptName]].}}
Within a [[:Category:Functions|Function]], the name of the function that called the current function (same as [[#fnc_scriptName|_fnc_scriptName]] if the function was not called by another function).
 
 
{{ArgTitle|4|_forEachIndex|{{GVI|arma2oa|1.55}}}}
Represents the (zero-based) index of a [[forEach]]- / [[forEachReversed]]-loop.
 
 
{{ArgTitle|4|_self|{{GVI|arma3|2.14}}}}
Available in HashMapObject methods. Contains the HashMapObject instance that the method was invoked on (see [[createHashMapObject]]).
 
 
{{ArgTitle|4|_thisArgs|{{GVI|arma3|2.04}}}}
Additional Event Handler arguments available with [[addMissionEventHandler]].
 
 
{{ArgTitle|4|_thisEvent|{{GVI|arma3|2.06}}}}
The name of the Event added with [[addEventHandler]], [[addMPEventHandler]], [[addMissionEventHandler]],[[addUserActionEventHandler]], [[ctrlAddEventHandler]] and [[displayAddEventHandler]], as well as for config types EHs.
 
 
{{ArgTitle|4|_thisEventHandler|{{GVI|arma3|1.64}}}}
The index for Event Handlers added with [[addEventHandler]], [[addMPEventHandler]], [[addMissionEventHandler]], [[addUserActionEventHandler]], [[ctrlAddEventHandler]] and [[displayAddEventHandler]].
 
 
{{ArgTitle|4|_thisFSM|{{GVI|arma3|1.54}}}}
The [[FSM]] ID for FSMs executed with [[execFSM]].
 
 
{{ArgTitle|4|_thisScript|{{GVI|arma3|1.54}}}}
The [[Script Handle]] of a script started with [[execVM]], [[call]] or [[spawn]].
 
 
{{ArgTitle|4|_thisScriptedEventHandler|{{GVI|arma3|1.68}}}}
The index for Scripted Event Handlers added with [[BIS_fnc_addScriptedEventHandler]].
 
 
==== _time ====
{{Feature|warning|[[SQS Syntax|SQS]] only.}}
The time elapsed since the script started running.
 
 
==== this ====
* '''Addon Config Files''' (e.g. UserActions, onInit, etc.)''':''' The object to which the entry belongs.
* '''Dialogs:''' The player unit that activated control (e.g. via mouseEnter). [[false]] if non-activated.
* '''Object Init Fields:''' The object to which the init field belongs.
* '''Triggers:'''
** ''Condition'': The [[Boolean]] return value of the [[Trigger]]'s condition (e.g. "East Not Present").
** ''On Activation'' and ''On Deactivation'': Seems to always return [[false]].
* '''Waypoints:'''
** ''Condition'', ''On Activation'' and ''On Deactivation'': The group leader that completed the waypoint (or the driver, if the waypoint is assigned to a vehicle).
 
 
==== thisList ====
* '''Triggers:'''
** Accessible in the ''Condition'', ''On Activation'' and ''On Deactivation'' code.
** Defines an array of objects that have been detected by the trigger (same as what is returned by the [[list]] command).
** Seems to be undefined in the ''On Deactivation'' expression and should not be used. It will either be an empty array, or possibly the contents of a different trigger.
* '''Waypoints:'''
** Accessible within the ''Condition'' or ''On Activation'' code.
** Defines an array containing all group members that completed the waypoint.
 
 
==== thisTrigger ====
Refers to the [[Triggers|trigger]] object itself - accessible within the ''Condition'', ''On Activation'' and ''On Deactivation'' code.
 
{{ConfigPage|end}}
 
 
[[Category: Scripting Topics]]

Latest revision as of 00:24, 2 February 2024

Magic variables are engine-maintained variables that serve a specific purpose within a given scope and are often used by the engine to provide data to a script or code fragment.
They are usually no longer present after leaving the scope (e.g. after code execution or after a forEach-statement).


_this

Used to make the arguments of a script call (call, exec, execVM, spawn) visible and accessible to the script. Also used by Event Handlers to provide parameters.


_x

Represents the current element during iteration with apply, count, configClasses, configProperties, findIf, forEach and select.


_y

Iterating over a HashMap with forEach will return the key as _x and the value as _y.


_exception

Exception handling using a try-catch-statement declares this variable which contains details about the thrown exception in the try-block.


_fnc_scriptName

Not engine-maintained, but added by functions_f/initFunctions.sqf – see scriptName.

Within a Function, the TAG_fnc_functionName function name (e.g. "myTag_fnc_myFunction").


_fnc_scriptNameParent

Not engine-maintained, but added by functions_f/initFunctions.sqf – see scriptName.

Within a Function, the name of the function that called the current function (same as _fnc_scriptName if the function was not called by another function).


_forEachIndex

Represents the (zero-based) index of a forEach- / forEachReversed-loop.


_self

Available in HashMapObject methods. Contains the HashMapObject instance that the method was invoked on (see createHashMapObject).


_thisArgs

Additional Event Handler arguments available with addMissionEventHandler.


_thisEvent

The name of the Event added with addEventHandler, addMPEventHandler, addMissionEventHandler,addUserActionEventHandler, ctrlAddEventHandler and displayAddEventHandler, as well as for config types EHs.


_thisEventHandler

The index for Event Handlers added with addEventHandler, addMPEventHandler, addMissionEventHandler, addUserActionEventHandler, ctrlAddEventHandler and displayAddEventHandler.


_thisFSM

The FSM ID for FSMs executed with execFSM.


_thisScript

The Script Handle of a script started with execVM, call or spawn.


_thisScriptedEventHandler

The index for Scripted Event Handlers added with BIS_fnc_addScriptedEventHandler.


_time

SQS only.

The time elapsed since the script started running.


this

  • Addon Config Files (e.g. UserActions, onInit, etc.): The object to which the entry belongs.
  • Dialogs: The player unit that activated control (e.g. via mouseEnter). false if non-activated.
  • Object Init Fields: The object to which the init field belongs.
  • Triggers:
    • Condition: The Boolean return value of the Trigger's condition (e.g. "East Not Present").
    • On Activation and On Deactivation: Seems to always return false.
  • Waypoints:
    • Condition, On Activation and On Deactivation: The group leader that completed the waypoint (or the driver, if the waypoint is assigned to a vehicle).


thisList

  • Triggers:
    • Accessible in the Condition, On Activation and On Deactivation code.
    • Defines an array of objects that have been detected by the trigger (same as what is returned by the list command).
    • Seems to be undefined in the On Deactivation expression and should not be used. It will either be an empty array, or possibly the contents of a different trigger.
  • Waypoints:
    • Accessible within the Condition or On Activation code.
    • Defines an array containing all group members that completed the waypoint.


thisTrigger

Refers to the trigger object itself - accessible within the Condition, On Activation and On Deactivation code.