View source for Arma 3: Functions Library

[[Category:Arma 3: Editing]]

Arma 3 '''Functions Library''' is pack of routine script functions available from anywhere in game. Main difference from older [[Functions Library]] is that it runs automatically and doesn't require Functions manager to be present.

== Finding a Function ==
[[File:A3_functionwViewer.png|300px|thumb|right|Functions Viewer]]
Before you can use a function, you first need to find it. The easiest way is to access the '''Functions Viewer''':

* In editor, click on [[File:icon editor functions.png|20px]] icon or press Ctrl + F
* In mission, access the [[Mission_Editor:_Debug_Console|debug console]] (automatically visible in pause menu of an editor mission) and click on '''FUNCTIONS''' button.

Once in the '''Functions Viewer''', you can filter all available functions by location, projects and categories.

When you find the desired function, look at the code preview on the right. Every function has a header where you can find basic description of its functionality including required arguments, returned values and sometimes examples of use.

{{note|Some functions, especially the older ones, may have missing or incomplete headers.<br />We do our best to update them, but if you find some issues, feel free to report them in the [http://feedback.arma3.com/ Feedback Tracker].}}


Selected functions have also detailed description here on Community Wiki, see [[:Category:Arma_3:_Functions|Arma 3 Functions]] category.

== Calling a Function ==
Functions can be launched in mission, intro and outro using this [[call]] or [[spawn]] commands:
 _returnedValue = ''arguments'' [[call]] ''functionName'';
 ''arguments'' [[spawn]] ''functionName'';

=== Arguments ===
Arguments are data sent into the function, affecting its behavior.

They can be '''mandatory''' or '''optional'''.
* Mandatory arguments are required for function to run. When missing, the function usually stops and throws an error.
* Optional arguments allows more detailed configuration. If you dont send them, the function will use pre-defined default values.

{{note|Within the function, '''arguments''' are called '''parameters''', or simply params.}}


For example, let's take a look at [[BIS_fnc_endMission]], a function which ends a mission with animated closing shot. This is what the header says:
 /*
 	Author: Karel Moricky
 
 	Description:
 	Ends mission with specific ending.
 
 	<span style="color:DarkCyan;">Parameter(s):
 		0 (Optional):
 			STRING - end name (default: "end1")
 			ARRAY in format [endName,ID], will be composed to "endName_ID" string
 		1 (Optional): BOOL - true to end mission, false to fail mission (default: true)
 		2 (Optional):
 			BOOL - true for signature closing shot (default: true)
 			NUMBER - duration of a simple fade out to black</span>
 
 	Returns:
 	BOOL
 */

As you can see, all arguments are marked optional and you can call the function without them.

 [] call BIS_fnc_endMission;
:This will result in successfull ending of type "end1", preceeded with the signature [[Debriefing|closing shot]].

 ["end2"] call BIS_fnc_endMission;
:Set the ending type to "end2", while keeping the other arguments intact.

 ["end2",false,false] call BIS_fnc_endMission;
:Fail the mission without any effect, using "end2" type.


However, what should you do if you want to set the '''only''' last argument without affecting the previous ones? The solution is simple - put an empty variable [[nil]] on their place.

 <nowiki>[</nowiki>[[nil]],[[nil]],false] call BIS_fnc_endMission;
:Disable the closing effects, but keep the other aguments intact (successful "end1").

{{note|Some older functions are incompatible with this syntax and using nil would break them. See their header for more information.}}

=== Returned Value ===
Functions executed by [[call]] command can return back a value. Let's take a look at [[BIS_fnc_sideName]]:

 /*
 	Author: Karel Moricky
 
 	Description:
 	Returns side name
 
 	Parameter(s):
 	0: SIDE or NUMBER - either side or side ID
 
 	<span style="color:DarkCyan;">Returns:
 	STRING</span>
 */
The function returns a [[String]] - localized name of a side.
 _westName = [[west]] call BIS_fnc_sideName;
:Variable _westName will now be "BLUFOR" (or other name, based on selected language)

=== Multiplayer ===
Functions executed using [[call]] or [[spawn]] command will run only on the computer which triggered them. If you'd wish to execute a function remotely on specific clients, use [[BIS_fnc_MP]] function.
 [arguments,''"functionName"'',''target'',''isPersistent''] call [[BIS_fnc_MP]];

=== User Interface ===
Anywhere outside of running mission, refer to the functions stored in [[uiNamespace]].
 ''arguments'' [[call]] ([[uiNamespace]] [[getVariable]] ''"functionName"'');

== Adding a Function ==
When writing a script, consider registering it into the Functions Library.

Main benefits uncludes:
# '''Automatic compilation upon mission start''' into a global variable - no need to remember direct paths to files.
# '''Anti-hack protection''' using [[compileFinal]]
# '''Listing in the Functions Viewer'''
# '''Advanced debugging options'''
# '''Optional immediate execution upon mission start''', without need for manual call


Mission and campaign specific functions can be configured in [[Description.ext]], while addon functions are defined in [[Config.cpp]]. Configuration structure is the same in both cases.

=== Tag ===
Functions are configured within CfgFunctions class. To prevent duplicities, every author must create a subclass with unique ''tag'' and place functions inside it. The tag name will be used when composing a function name.
 class CfgFunctions
 {
 	class <span style="color:green;">myTag</span>
 	{
 	};
 	class Anything
 	{
 		tag = "<span style="color:green;">myTag</span>"; {{codecomment|// Custom tag name}}
 		requiredAddons[] = {"A3_Data_F"}; {{codecomment|// Optional requirements of CfgPatches classes. When some addons are missing, functions won't be compiled.}}
 	};
 };

=== Path ===
==== File Path ====
The easiest and the most transparent way is to set path for each function.
 class CfgFunctions
 {
 	class <span style="color:green;">myTag</span>
 	{
 		class myCategory
 		{
 			class <span style="color:teal;">myFunction</span> {file = "<span style="color:DarkOrange;">myFile.sqf</span>";};
 		};
 	};
 };
This will try to compile function '''<big><span style="color:green;">myTag</span>_fnc_<span style="color:teal;">myFunction</span></big>''' from the following file:
 ''%ROOT%''\<span style="color:DarkOrange;">myFile.sqf</span>
Where ''%ROOT%'' is either '''[[Mission_Editor:_External#Mission_Folder|mission root]]''' (where mission.sqm file is), or the '''game root''' (path to an addon is not included and has to be part of the file path, e.g., <span style="color:DarkOrange;">myAddon\myFile.sqf</span>).

==== Folder Path ====
You can set folder path and leave the function paths undefined. The functions will then be loaded from the folder.
 class CfgFunctions
 {
 	class <span style="color:green;">myTag</span>
 	{
 		class myCategory
 		{
 			file = "<span style="color:DarkOrange;">myPath</span>";
 			class <span style="color:teal;">myFunction</span> {};
 		};
 	};
 };
Compile function '''<big><span style="color:green;">myTag</span>_fnc_<span style="color:teal;">myFunction</span></big>''' from the following file:
 ''%ROOT%''\<span style="color:DarkOrange;">myPath</span>\fn_<span style="color:teal;">myFunction</span>.sqf
<span style="color:DarkOrange;">myPath</span> can be a folder or multiple folders, e.g., <span style="color:DarkOrange;">myFolder\mySubfolder</span>

==== Default Path (Mission Only) ====
In a mission, you can leave also the folder path undefine and let functions be loaded from the default directory.
 class CfgFunctions
 {
 	class <span style="color:green;">myTag</span>
 	{
 		class <span style="color:crimson;">myCategory</span>
 		{
 			class <span style="color:teal;">myFunction</span> {};
 		};
 	};
 };
Compile function '''<big><span style="color:green;">myTag</span>_fnc_<span style="color:teal;">myFunction</span></big>''' from the following file:
 ''%ROOT%''\functions\<span style="color:crimson;">myCategory</span>\fn_<span style="color:teal;">myFunction</span>.sqf

=== Attributes ===
Apart from already mentioned ''file'', function class can have additional attributes:
 class CfgFunctions
 {
 	class myTag
 	{
 		class myCategory
 		{
 			class <span style="color:teal;">myFunction</span>
 			{
 				preInit = 1; {{codecomment|// 1 to call the function upon mission start, <u>before</u> objects are initialized}}
 				postInit = 1; {{codecomment|// 1 to call the function upon mission start, <u>after</u> objects are initialized}}
 				recompile = 1; {{codecomment|// 1 to recompile the function upon mission start}}
 				ext = ".fsm"; {{codecomment|// Set file type, can be ".sqf" or ".fsm" (meaning scripted FSM). Default is ".sqf".}}
 			};
 		};
 	};
 };
''preInit'' and ''postInit'' atrributes are truly powerful ones, as they let you execute your function at the beginning of '''every''' mission. Use them with caution!
* Any scripting error will prevent the mission from being loaded correctly
* Server admins might blacklist your addon if they find out you're using the function for hacking.

=== Initialization Order ===
When mission is starting, its components are initialized in the following order:
# Functions with ''recompile'' param set to 1 are recompiled
# Functions with ''preInit'' param set to 1 are called
# Object ''Init'' [[Arma_3:_Event_Handlers|Event Handlers]] are called
# Object initialization fields are called
# ''init.sqs'' is executed in singleplayer
# ''init.sqf'' is executed in singleplayer
# Persistent [[#Multiplayer|multiplayer functions]] are called (client only)
# [[Arma_3_Modules|Modules]] are initialized
# ''initServer.sqf'' is executed (server only)
# ''initPlayerLocal.sqf'' is executed
# ''initPlayerServer.sqf'' is executed (server only)
# Functions with ''postInit'' param set to 1 are called
# ''BIS_fnc_init" variable is set to true
# ''init.sqs'' is executed in multiplayer
# ''init.sqf'' is executed in multiplayer

== Writing a Function ==
The most important thing to remember when writing a function is that other people than you are going to use it. Most of them won't understand how does it work, expecting it to do its job without problems.

Your function must be '''robust'''. It shouldn't allow passing arguments of incorrect [[Data Types]] in. When some values are incorrect, it should throw an error explaining what went wrong and how to fix it. And above all, its header must provide complete explanation of usage.
{{Important|What is not documented, does not exist!}}

=== Loading Parameters ===
Arguments are the only way how to interact with your function. Let's now see how to make sure they are loaded properly.

We have this very simple function which will let a unit watch a position:
 _unit = <span style="color:green;">_this</span> [[select]] <span style="color:darkorange;">0</span>;
 _target = <span style="color:green;">_this</span> select <span style="color:darkorange;">1</span>;
 _unit [[doWatch]] _target;

Expected way how to call the function is by correctly defining all arguments:
{|
| [[File:Ico_ok.png]]
|
 [player,position myCar] call myTag_fnc_myFunction;
|}

However, the function will break down when you try to send only one argument in:
{|
| [[File:Ico_none.png]]
|
 [player] call myTag_fnc_myFunction;
|}

Furthermore, using wrong data type will also lead to a problem:
{|
| [[File:Ico_none.png]]
|
 [player,0] call myTag_fnc_myFunction;
|}

Variabe ''_target'' expects position array in format [x,y,z]. Scripting error will appear when different number of elements is used:
{|
| [[File:Ico_none.png]]
|
 [player,[1,2,3,4]] call myTag_fnc_myFunction;
|}


As you can see there, the most common problems are:
# '''Param of wrong data type is sent'''
# '''Param is missing'''
# '''Param is an array expecting specific number of elements, but different number is sent'''

Rather than check for these exceptions yourself, you can use existing function [[BIS_fnc_param]] which will do it for you:
 _unit = [<span style="color:green;">_this</span>, <span style="color:darkorange;">0</span>, <span style="color:teal;">objNull</span>, <span style="color:crimson;">[objNull]</span>] call BIS_fnc_param;
 _target = [<span style="color:green;">_this</span>, <span style="color:darkorange;">1</span>, <span style="color:teal;">[0,0,0]</span>, <span style="color:crimson;">[[],objNull]</span>, <span style="color:indigo;">[2,3]</span>] call BIS_fnc_param;
 _unit doWatch _target;
* First two arguments are the same as you used when selecting the param manually - <span style="color:green;">'''source array'''</span> and <span style="color:darkorange;">'''index'''</span> number.
* Third argument is the <span style="color:teal;">'''default value'''</span>. It will be used when the argument is missing, is [[nil]] or when wrong data type is used.
* Next is optional <span style="color:crimson;">'''array of compatible data types'''</span>. They are defined by an example of the type, e.g. [[objNull]] will mean an object is allowed. When wrong data type is sent into your function, BIS_fnc_param will log an error message explaining what went wrong and use the default value.
* The last, also optional argument is an <span style="color:indigo;">'''array of required array sizes'''</span>. [2,3] means only array with 2 or 3 elements are allowed. When incorrectly large array is sent into your function, BIS_fnc_param will log an error message explaining what went wrong and use the default value.


Let's see what will happen when you try to use the wrong examples now:
{|
| [[File:Ico_ok.png]]
|
 [player] call myTag_fnc_myFunction;
|}
: ''_target'' is undefined. Default <span style="color:teal;">[0,0,0]</span> is used instead. No error message is logged.

{|
| [[File:Ico_ok.png]]
|
 [nil,position myCar] call myTag_fnc_myFunction;
|}
: ''_unit'' is undefined (nil is passed instead). Default <span style="color:teal;">objNull</span> is used instead. No error message is logged.

{|
| [[File:Ico_warning.png]]
|
 [player,0] call myTag_fnc_myFunction;
|}
: ''_target'' has wrong <span style="color:crimson;">type</span>. Default <span style="color:teal;">[0,0,0]</span> is used instead. Error message is logged.

{|
| [[File:Ico_warning.png]]
|
 [player,[1,2,3,4]] call myTag_fnc_myFunction;
|}
: ''_target'' has wrong <span style="color:indigo;">size</span>. Default <span style="color:teal;">[0,0,0]</span> is used instead. Error message is logged.


Additionally, when only one argument is used, you can send it into the function directly without need to have it in an array.
{|
| [[File:Ico_ok.png]]
|
 player call myTag_fnc_myFunction;
|}

=== Returning Value ===
Users will often save result of your function to a variable. If no value is returned, the variable would be [[nil]] and could lead to script errors.
 _myVar = [player,position myCar] call myTag_fnc_myFunction;

It's good practice to '''always''' return a value, even if it would be simple [[true]] marking the function as completed. Let's use the example function from above:
 _unit = [_this, 0, objNull, [objNull]] call BIS_fnc_param;
 _target = [_this, 1, [0,0,0], [[],objNull], [2,3]] call BIS_fnc_param;
 _unit doWatch _target;
 '''true'''

=== Showing Errors ===
While BIS_fnc_param can filter out the most common issues, sometimes your function will have special rules which will need to be handled. Let's return back to our example function, where we'd want to terminate the function with error when ''_unit'' is dead:
 _unit = [_this, 0, objNull, [objNull]] call BIS_fnc_param;
 _target = [_this, 1, [0,0,0], [[],objNull], [2,3]] call BIS_fnc_param;
 '''if !(alive _unit) exitwith {["Unit %1 must be alive.",_unit] call [[BIS_fnc_error]]; false};'''
 _unit doWatch _target;
 true
Notice that we're returning [[false]] at the end of [[exitWith]] code.
{{Important|Error states must always return value of the same type as when everything is fine ([[Boolean]] in this case).}}


BIS_fnc_error accepts [[String]] and [[Array]] of [[format]]ted ext. The error is logged into [[RPT]] and if the mission is previewd from the editor, it will also appear on screen.
{|
| [[RPT]]
| 
 "User1/log: ERROR: [BIS_fnc_respawnTickets] #0: 0 is type SCALAR, must be NAMESPACE, SIDE, GROUP, OBJECT, BOOL. true used instead."
|-
| In-game
| [[File:A3 functions error.jpg|800px|On-screen error]]
|}

=== Logging ===
Apart from errors, you can print any debug message you need. Use one of the following functions:
* [[BIS_fnc_log]] - log a data of any type (e.g., [[String]], [[Number]], [[Object]], ...)
* [[BIS_fnc_logFormat]] - log [[format]]ted text
Profile name and function name will automatically appear in the output text, helping you identify the source.


Usage examples:
{| class="wikitable"
! Expression
! [[RPT]] Output
|-
|
 <span style="color:green;">"Hello World"</span> call BIS_fnc_log;
|
 "User1/BIS_fnc_log: [myTag_fnc_myFunction] <span style="color:green;">Hello World</span>"
|-
|
 <span style="color:green;">42</span> call BIS_fnc_log;
|
 "User1/BIS_fnc_log: [myTag_fnc_myFunction] <span style="color:green;">42</span>"
|-
|
 [<span style="color:green;">"I'm playing %1"</span>,[[missionName]]] call BIS_fnc_logFormat;
|
 "User1/BIS_fnc_log: [myTag_fnc_myFunction] <span style="color:green;">I'm playing FalconWing</span>"
|}


To prevent RPT spam, logging is by default enabled only when previewing a mission from the editor. To force it in the mission everywhere, use the following [[Description.ext]] attribute:
 allowFunctionsLog = 1;


=== Recompiling ===
Once compiled, functions remain unchanged and editing their file won't have any effect in the game. To adjust functions on the fly, you can manually triger their recompilation.
 1 call [[BIS_fnc_recompile]];
:Recompiles all functions. Can be also achieved by clicking on RECOMPILE button in the Functions Viewer
 "''functionName''" call [[BIS_fnc_recompile]];
:Recompile the given function

As a security measure, functions are by default protected against rewriting during the mission. This restriction does not apply in missions previewed from the editor and in missions with the following attribute in [[Description.ext]]:
 allowFunctionsRecompile = 1;

=== Meta Variables ===
System is adding header with basic meta data to all functions. Following local variables are declared there:
* '''_fnc_scriptName''': [[String]] - Function name (e.g., myTag_fnc_myFunction)
* '''_fnc_scriptNameParent''': [[String]] - Name of q function from which the current one was called (_fnc_scriptName used when not defined)
<!--* '''_fnc_scriptMap''': ARRAY - List of all parent scripts (available only in debug mode 1 and higher, see [[#Debug_Mode|above]]).-->
{{Important|Do not modify these values!}}

<!--
=== Debug Mode ===
Developers can access several debug modes using ''[[BIS_fnc_functionsDebug]]'' function.
# '''No debug'''
#* Default
# '''Save script map'''
#* Variable ''_fnc_scriptMap'' tracking script execution progress is stored in function header
# '''Save and log script map'''
#* Variable ''_fnc_scriptMap'' tracking script execution progress is stored in functions header and it's printed to debug log.
{{Important|Function recompiling has to be allowed!}}
-->