Difference between revisions of "Arma 3: Functions Library"

From Bohemia Interactive Community
Jump to navigation Jump to search
m
m (Fix typo)
(112 intermediate revisions by 16 users not shown)
Line 1: Line 1:
[[Category:Arma 3: Editing]]
+
{{TOC|side||3}}
 +
{{arma3}}'s '''Functions Library''' is the way to declare mission, campaign or addon's [[Function]]s. The main difference from older [[:Category:Functions Library|Function Libraries]] is that it runs automatically and does not require a Functions module.
  
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.
+
The advantages of using the Functions Library over e.g [[execVM]] an [[SQF Syntax|SQF]] file are as follow:
 +
# '''Automatic compilation upon mission start''' into a global variable - no need to remember direct paths to files.
 +
# '''Anti-hack protection''' using [[compileFinal]] (see {{HashLink|#Recompiling}})
 +
# '''Listing in the [[Arma 3: Functions Viewer|Functions Viewer]]'''
 +
# '''Advanced debugging options'''
 +
# '''Optional immediate execution upon mission start''', without need for manual call
 +
# '''Potential performance improvements'''
  
  
== Preview ==
+
{{Feature|important|This page is about {{arma3}} Functions Library.
[[File:A3_functionwViewer.png|300px|thumb|right|In-game functions viewer]]
+
* For {{arma2}}/{{Name|arma2oa|short}}, see [[Arma 2: Functions Library]].
Use the following code to display function library anywhere in game:
+
* For {{tkoh}}, see [[Take On Helicopters: Functions Library]].
[] call [[BIS_fnc_help]];
+
}}
  
In 2D editor, press 'Ctrl + F' to display the viewer or click on icon: [[File:icon editor functions.png|20px]]
 
  
Features:
+
== Function Declaration ==
* Listing through all functions from config or [[Description.ext]] files.
 
* Displaying name, path, description and code of selected functions.
 
* Code can be easily copied to clipboard.
 
  
 +
Functions are configured within the <tt>CfgFunctions</tt> class.
 +
 +
Mission and campaign specific functions can be configured in [[Description.ext]]/[[Campaign Description.ext]], while addon functions are defined in [[Config.cpp]].
 +
Configuration structure is the same in both cases.
 +
 +
 +
{{Feature|informative|The root directory (noted as '''&lt;ROOT&gt;''' on this page) is the origin from which the game will try to load function files. It depends on <tt>CfgFunctions</tt>' location:
 +
* if [[Description.ext]], '''&lt;ROOT&gt;''' means the [[Mission Editor: External#Mission Folder|mission's root]] directory
 +
* if [[Campaign Description.ext]], '''&lt;ROOT&gt;''' means the campaign's root directory
 +
* if in config, '''&lt;ROOT&gt;''' means the '''game'''<nowiki/>'s root directory. The addon path needs to be set manually.
 +
}}
  
== Execution ==
 
=== Singleplayer ===
 
Functions can be launched in mission, intro and outro using this syntax:
 
_fnc = [params] call functionName;
 
or
 
_fnc = [params] spawn functionName;
 
  
=== Multiplayer ===
+
See a basic example config:
Functions replaces obsolete [[Multiplayer_framework|Multiplayer Framework]]. You can use [[BIS_fnc_MP]] to remotely call function on specific clients and set them to be persistent, so they'll be executed automatically for client upon JIP.
+
class '''CfgFunctions'''
[params,"functionName",target,isPersistent] call BIS_fnc_MP;
+
{
 +
class {{Color|purple|TAG}}
 +
{
 +
class {{Color|darkorange|Category}}
 +
{
 +
class {{Color|teal|functionName}} {};
 +
};
 +
};
 +
};
 +
* The function's name will be '''{{Color|purple|TAG}}'''_fnc_'''{{Color|teal|functionName}}'''
 +
* The function will be loaded:
 +
** from config: <tt>'''&lt;ROOT&gt;'''\{{Color|darkorange|Category}}\'''fn_'''{{Color|teal|functionName}}'''.sqf'''</tt>
 +
** from description.ext: <tt>'''&lt;ROOT&gt;'''\'''Functions'''\{{Color|darkorange|Category}}\'''fn_'''{{Color|teal|functionName}}'''.sqf'''</tt>
  
=== GUI ===
+
{{Feature|informative|'''config.cpp only''': Anywhere outside of running mission, refer to the functions stored in [[uiNamespace]]. e.g:
Anywhere outside running mission (user interface), refer to functions stored in UInamespace
+
<code>''arguments'' [[call]] ([[uiNamespace]] [[getVariable]] ''"{{Color|purple|TAG}}_fnc_{{Color|teal|functionName}}"'');</code>}}
_fnc = [params] call (uinamespace getvariable 'functionName');
 
or
 
_fnc = [params] spawn (uinamespace getvariable 'functionName');
 
  
 +
=== Config Levels ===
  
== Configuration ==
+
A '''CfgFunctions''' config is made of three levels: Tag, Category, and Function.
List of functions is defined in config under CfgFunctions container. New ones can be also added in description.ext file of mission or campaign.
 
  
 +
==== Tag ====
 +
To prevent duplicates, every author must create a subclass with a unique {{Color|purple|[[OFPEC tags|tag]]}} and create functions under it.
 +
The tag name will be used when composing a function name (e.g [[BIS_fnc_spawnGroup|'''BIS'''_fnc_spawnGroup]]).
 
  class CfgFunctions
 
  class CfgFunctions
 
  {
 
  {
  class A3
+
  class {{Color|purple|TAG}}
 +
{
 +
class Category
 +
{
 +
class myFunction {};
 +
};
 +
};
 +
 +
class TAG_WeaponManagement
 
  {
 
  {
  tag = "<span style="color:green;">BIS</span>";
+
  '''tag''' = {{Color|purple|"TAG"}}; {{cc|the function will be named '''{{Color|purple|TAG}}_fnc_myOtherFunction'''}}
requiredAddons[] = {"A3_Data_F"}; {{codecomment|// Optional requirements of CfgPatches classes}}
+
  class Category
  class <span style="color:crimson;">category</span>
 
 
  {
 
  {
file = "<span style="color:DarkOrange;">A3\functions_f\Misc</span>";
+
  class myOtherFunction {};
  class <span style="color:teal;">Test1</span> {description="Testing file 2";};
 
class <span style="color:teal;">Test2</span> {description="Testing file 3"; file="<span style="color:DarkOrange;">test.sqf</span>"};
 
class <span style="color:teal;">Test3</span> {description="Testing file 4 (FSM)"; ext="<span style="color:fuchsia;">.fsm</span>"};
 
 
  };
 
  };
 
  };
 
  };
 
  };
 
  };
  
* If ''file'' path is not set for the given function, system will search for file in
+
===== Attributes =====
**<code>'<span style="color:DarkOrange;">file</span>\<span style="color:crimson">category</span>\fn_<span style="color:teal">function</span>.sqf"</code> (if functions is defined in description.ext)
+
====== tag ======
* When ''file'' parameter is defined in category root, all functions in given category will be searched for in this directory.
+
The <tt>tag</tt> attribute can override the config {{Color|green|tag}} set differently.
  
Result of example code above is:
+
==== Category ====
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test1</span>''' - will load script <code><span style="color:DarkOrange;">A3\functions_f\Misc</span>\<span style="color:crimson;">category</span>\fn_<span style="color:teal;">Test1</span>.sqf</code>
+
The category name changes the function's category in the [[Arma 3: Functions Viewer|Functions Viewer]]. It does not change the function's name, only the loading path.
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test2</span>''' - will load script <code><span style="color:DarkOrange;">test.sqf</span></code> from mission directory
+
class CfgFunctions
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test3</span>''' - will load FSM <code><span style="color:DarkOrange;">A3\functions_f\Misc</span>\<span style="color:crimson;">category</span>\<span style="color:teal;">Test4</span><span style="color:fuchsia;">.fsm</span></code>
+
{
 +
class TAG
 +
{
 +
class {{Color|darkorange|Category}}
 +
{
 +
class myFunction {};
 +
};
 +
 +
class OtherCategory
 +
{
 +
'''file''' = "{{Color|darkorange|My}}\{{Color|darkorange|Category}}\{{Color|darkorange|Path}}";
 +
class myFunction {}; {{cc|file path will be '''&lt;ROOT&gt;'''\{{Color|darkorange|My}}\{{Color|darkorange|Category}}\{{Color|darkorange|Path}}\fn_myFunction.sqf";}}
 +
};
 +
 +
class DataCategory
 +
{
 +
'''requiredAddons[]''' = {{Color|darkorange|{ "A3_Data_F" }<nowiki/>}}; {{cc|Optional requirements of [[CfgPatches]] classes. If some addons are missing, category functions will not be compiled.}}
 +
class myDataFunction {};
 +
};
 +
};
 +
};
  
Optional function class params:
+
===== Attributes =====
* '''description''' - Short function description. Will be rendered obsolete in further revisions, with script headers serving as the main source of documentation.
+
====== file ======
* '''ext''' - file type, can be ".sqf" or ".fsm" (meaning scripted FSM). Default is ".sqf".
+
The <tt>file</tt> attribute can override the category's loading path segment.
* '''file''' - optional direct path to the file.
 
* '''recompile''' (new in Arma 3) - function will be recompile upon mission start.
 
* '''preInit''' (new in Arma 3) - function will be executed automatically upon mission start, before objects are loaded.
 
* '''postInit''' (new in Arma 3) - function will be executed automatically upon mission start, after objects are loaded.
 
  
== Debugging ==  
+
====== requiredAddons ======
 +
The category can skip loading if a required addon is missing by setting its dependency with the <tt>requiredAddons</tt> attribute.
  
=== Debug Functions ===
+
==== Function ====
Use debug functions to register params, display errors and log messages to [[RPT]] file. Printed output of these functions automatically contains name of function from which it was called.
+
{{Feature|informative|By convention, the function class should be named in '''camelCase''' and not have its first letter capitalised (e.g PascalCase):
 +
* {{Icon|checked}} TAG_fnc_{{Color|teal|myFunction}}
 +
* {{Icon|unchecked}} TAG_fnc_{{Color|teal|MyFunction}}
 +
* {{Icon|checked}} TAG_fnc_{{Color|teal|POWRescue}}
 +
}}
 +
class CfgFunctions
 +
{
 +
class TAG
 +
{
 +
class Category1
 +
{
 +
class {{Color|teal|myFunction}} {};
 +
};
 +
 +
class Category2
 +
{
 +
file = "Path\To\Category";
 +
class myFunction
 +
{
 +
'''file''' = "{{Color|teal|My}}\{{Color|teal|Function}}\{{Color|teal|Filepath.sqf}}"; {{cc|file path will be '''&lt;ROOT&gt;'''\{{Color|teal|My}}\{{Color|teal|Function}}\{{Color|teal|Filepath.sqf}}", ignoring "Path\To\Category"}}
 +
};
 +
 +
class {{Color|teal|myFSMFunction}}
 +
{
 +
'''preInit''' = 1;
 +
'''postInit''' = 1;
 +
'''ext''' = ".fsm";
 +
'''preStart''' = 1;
 +
'''recompile''' = 1;
 +
};
 +
};
 +
};
 +
};
  
To prevent RPT spam, logging is disabled by default. Enable it by placing the following parameter to your mission [[Description.ext]]:
+
===== Attributes =====
  allowFunctionsLog = 1;
+
{| class="wikitable sortable"
 +
! rowspan="2" | Attribute
 +
! rowspan="2" | Description
 +
! colspan="2" | Available in
 +
|- style="font-size: 0.9em"
 +
! [[Description.ext]]
 +
! [[config.cpp]]
 +
|-
 +
| file
 +
| the <tt>file</tt> attribute can be used to manually set the file path.
 +
{{Feature|important|The '''file''' entry '''overrides''' Category's set path and ignores it entirely (they are not merged).}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| preInit
 +
| the <tt>preInit</tt> attribute (formerly known as "forced") can be set to 1 to call the function upon mission start, before objects are initialized.<br>Passed arguments are {{ic|["preInit"]}}. The function is run in an '''[[Scheduler#Unscheduled Environment|unscheduled environment]]'''.
 +
| style="text-align: center" | {{Icon|checked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| postInit
 +
| the <tt>postInit</tt> attribute can be set to 1 to call the function upon mission start, after objects are initialized.<br>Passed arguments are {{ic|["postInit", [[didJIP]]]}}. The function is run in a '''[[Scheduler#Scheduled Environment|scheduled environment]]''' so suspension is allowed, but '''any long term suspension will halt the mission loading until suspension is done'''.
 +
| style="text-align: center" | {{Icon|checked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| ext
 +
| the <tt>ext</tt> attribute can be used to set function file's type; it can be one of:
 +
* ".sqf" (default)
 +
* ".fsm" (see [[FSM]])
 +
| style="text-align: center" | {{Icon|checked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| preStart
 +
| the <tt>preStart</tt> attribute can be set to 1 to call the function upon game start, before title screen, but after all addons are loaded.
 +
| style="text-align: center" | {{Icon|unchecked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| recompile
 +
| the <tt>recompile</tt> attribute can be set to 1 to recompile the function upon mission start (functions in [[Description.ext]] are always compiled upon mission (re)start)
 +
| style="text-align: center" | {{Icon|unchecked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|-
 +
| headerType
 +
| the <tt>headerType</tt> adds code to the beginning of functions that can:
 +
* Set up the [[#Meta Variables|Meta Variables]] _fnc_scriptParent and _fnc_scriptName
 +
* Name the current scope via the command [[scriptName]]
 +
* Adds debug information by saving the current execution order in the [[Array]] _fnc_scriptMap.<br/>
 +
Possible values are:
 +
* -1: No header - Adds nothing, literally adds a blank [[String]] to the beginning of functions. The functions will have no debug or {{HashLink|#Meta Variables}} assigned for it and the scope will not be named. Useful to reduce the performance overhead or if custom debug system is used.
 +
* 0: Default header - The default header changes based on the current [[#Debug Modes|Debug Mode]]
 +
* 1: System header - Incorporates the [[#Meta Variables|Meta Variables]] _fnc_scriptParent. Also names the current scope.
 +
  [[private]] _fnc_scriptNameParent = [[if]] ([[isNil]] '_fnc_scriptName') [[then]] { '%1' } [[else]] { _fnc_scriptName };
 +
[[scriptName]] '%1';
 +
See the following section for more information.
 +
| style="text-align: center" | {{Icon|checked}}
 +
| style="text-align: center" | {{Icon|checked}}
 +
|}
  
{{Important|Usage of following functions is strongly recommended:
+
{{Feature|important|Notes about <tt>preInit</tt> and <tt>postInit</tt> defined in '''config.cpp''':
* [[BIS_fnc_param]]
+
* these attributes will make the function run '''on each, every and any mission start'''
* [[BIS_fnc_log]]
+
* Any scripting error will prevent the mission from being loaded correctly
* [[BIS_fnc_error]]
+
* Server admins might blacklist the whole addon if they find out the function is used for hacking
* [[BIS_fnc_halt]]
 
 
}}
 
}}
  
Examples of debug outputs:
 
{{codecomment|"Config param 'splendid' not defined in CfgArma." call BIS_fnc_halt;}}
 
"Log: HALT: [BIS_fnc_isSplendid] Config param 'splendid' not defined in CfgArma."
 
  
{{codecomment|_mission <nowiki>=</nowiki> [BIS_Player] call [[BIS_fnc_endMission]];}}
+
== Advanced Knowledge ==
"Log: ERROR: [BIS_fnc_endMission] 0: BIS_Player is type OBJECT, must be STRING. "end1" used instead."
 
  
{{codecomment|["Persistent execution is not allowed when target is %1. Use %2 or %3 instead.",typename 0,typename objnull,typename false] call BIS_fnc_error;}}
+
=== Meta Variables ===
"Log: ERROR: Persistent execution is not allowed when target is SCALAR. Use OBJECT or BOOL instead."
 
  
{{codecomment|42 call BIS_fnc_log;}}
+
* '''_fnc_scriptName''': [[String]] - Name of the script
"BIS_fnc_log: [BIS_fnc_myFunction]: 42"
+
* '''_fnc_scriptNameParent''': [[String]] - Name of the parent script
 +
* '''_fnc_scriptMap''': [[Array]] - List of all parent scripts
  
{{codecomment|["Random number is %1",random 999] call BIS_fnc_log;}}
+
=== Debug Modes ===
"BIS_fnc_log: [BIS_fnc_myFunction] Random number is 808.768"
 
  
 +
Developers can access several debug modes using ''[[BIS_fnc_functionsDebug]]'' function. '''For this to work [[Description.ext#allowFunctionsRecompile|function recompiling]] has to be allowed!'''
  
=== Allow Recompile ===
+
==== Debug Mode 0 ====
For security reasons, all functions are compiled using [[compileFinal]] and cannot be rewritten afterwards). When writing and testing a function, this would require game restart after every single change.
+
default - incorporates the [[#Meta Variables|Meta Variables]] _fnc_scriptParent and _fnc_scriptName and names the current scope.
 +
[[private]] _fnc_scriptNameParent = [[if]] ([[isNil]] '_fnc_scriptName') [[then]] {'%1'} [[else]] {_fnc_scriptName};
 +
[[private]] _fnc_scriptName = '%1';
 +
[[scriptName]] _fnc_scriptName;
  
To allow recompiling [[missionNamespace]] functions, place following param into mission [[Description.ext]]:
+
==== Debug Mode 1 ====
  allowFunctionsRecompile = 1;
+
As per ''Debug Mode 0'' and also saves the current execution order in the [[Array]] _fnc_scriptMap.
 +
[[private]] _fnc_scriptNameParent = [[if]] ([[isNil]] '_fnc_scriptName') [[then]] { '%1' } [[else]] { _fnc_scriptName };
 +
  [[private]] _fnc_scriptName = '%1';
 +
[[scriptName]] _fnc_scriptName;
 +
[[private]] _fnc_scriptMap = [[if]] ([[isNil]] '_fnc_scriptMap') [[then]] {[_fnc_scriptName]} [[else]] {_fnc_scriptMap + [_fnc_scriptName]};
  
''Note: Unavailable in the 0.56.104778 default build, planned for the next one. Dev builds might receive the feature sooner. Use '''recompile = 1;''' function param for debugging your own functions meanwhile.''
+
==== Debug Mode 2 ====
 +
As per ''Debug Mode 1'' and also outputs execution order using [[textLogFormat]] ( textLogFormat is not available in the retail version of Arma3 ) is it available in Diagnostics exe?
 +
[[private]] _fnc_scriptNameParent = [[if]] ([[isNil]] '_fnc_scriptName') [[then]] { '%1' } [[else]] { _fnc_scriptName };
 +
[[private]] _fnc_scriptName = '%1';
 +
[[scriptName]] _fnc_scriptName;
 +
[[private]] _fnc_scriptMap = [[if]] ([[isNil]] '_fnc_scriptMap') [[then]] { [_fnc_scriptName] } [[else]] { _fnc_scriptMap + [_fnc_scriptName] };
 +
[[textLogFormat]] ['%1 : %2', _fnc_scriptMap [[joinString]] ' >> ', _this];
  
  
=== Debug Mode ===
+
== See Also ==
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!}}
 
 
 
 
 
=== Meta Variables ===
 
System is adding header with basic meta data to all functions. Following local variables are defined there:
 
* '''_fnc_scriptName''': STRING - Function name (<tag>_fnc_<name>)
 
* '''_fnc_scriptNameParent''': STRING - Name of function from which 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|Please do not modify these values!}}
 
  
 +
* [[Initialization Order]]
 +
* [[Arma 3: Functions Viewer]]
 +
* [[:Category:Arma 3: Functions|Arma 3 Functions]]
 +
* [[Arma 3: Writing a Function|Writing a Function Tutorial]]
  
=== Initialization Order ===
+
{{GameCategory|arma3|Editing}}
# '''Functions'''
+
[[Category: Functions Library]]
# Init [[ArmA_2:_Event_Handlers|Event Handlers]]
 
# [[Mission.sqm]]
 
# [[Event_Scripts|Init.sqf]]
 
# [[Event_Scripts|Init.sqs]]
 
# [[Triggers]]
 

Revision as of 22:41, 1 September 2021

Arma 3's Functions Library is the way to declare mission, campaign or addon's Functions. The main difference from older Function Libraries is that it runs automatically and does not require a Functions module.

The advantages of using the Functions Library over e.g execVM an SQF file are as follow:

  1. Automatic compilation upon mission start into a global variable - no need to remember direct paths to files.
  2. Anti-hack protection using compileFinal (see Recompiling)
  3. Listing in the Functions Viewer
  4. Advanced debugging options
  5. Optional immediate execution upon mission start, without need for manual call
  6. Potential performance improvements


This page is about Arma 3 Functions Library.


Function Declaration

Functions are configured within the CfgFunctions class.

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


The root directory (noted as <ROOT> on this page) is the origin from which the game will try to load function files. It depends on CfgFunctions' location:


See a basic example config:

class CfgFunctions
{
	class TAG
	{
		class Category
		{
			class functionName {};
		};
	};
};
  • The function's name will be TAG_fnc_functionName
  • The function will be loaded:
    • from config: <ROOT>\Category\fn_functionName.sqf
    • from description.ext: <ROOT>\Functions\Category\fn_functionName.sqf
config.cpp only: Anywhere outside of running mission, refer to the functions stored in uiNamespace. e.g: arguments call (uiNamespace getVariable "TAG_fnc_functionName");

Config Levels

A CfgFunctions config is made of three levels: Tag, Category, and Function.

Tag

To prevent duplicates, every author must create a subclass with a unique tag and create functions under it. The tag name will be used when composing a function name (e.g BIS_fnc_spawnGroup).

class CfgFunctions
{
	class TAG
	{
		class Category
		{
			class myFunction {};
		};
	};

	class TAG_WeaponManagement
	{
		tag = "TAG"; // the function will be named TAG_fnc_myOtherFunction
		class Category
		{
			class myOtherFunction {};
		};
	};
};
Attributes
tag

The tag attribute can override the config tag set differently.

Category

The category name changes the function's category in the Functions Viewer. It does not change the function's name, only the loading path.

class CfgFunctions
{
	class TAG
	{
		class Category
		{
			class myFunction {};
		};

		class OtherCategory
		{
			file = "My\Category\Path";
			class myFunction {}; // file path will be <ROOT>\My\Category\Path\fn_myFunction.sqf";
		};

		class DataCategory
		{
			requiredAddons[] = { "A3_Data_F" }; // Optional requirements of CfgPatches classes. If some addons are missing, category functions will not be compiled.
			class myDataFunction {};
		};
	};
};
Attributes
file

The file attribute can override the category's loading path segment.

requiredAddons

The category can skip loading if a required addon is missing by setting its dependency with the requiredAddons attribute.

Function

By convention, the function class should be named in camelCase and not have its first letter capitalised (e.g PascalCase):
  • Ico ok.png TAG_fnc_myFunction
  • Ico none.png TAG_fnc_MyFunction
  • Ico ok.png TAG_fnc_POWRescue
class CfgFunctions
{
	class TAG
	{
		class Category1
		{
			class myFunction {};
		};

		class Category2
		{
			file = "Path\To\Category";
			class myFunction
			{
				file = "My\Function\Filepath.sqf"; // file path will be <ROOT>\My\Function\Filepath.sqf", ignoring "Path\To\Category"
			};

			class myFSMFunction
			{
				preInit		= 1;
				postInit	= 1;
				ext			= ".fsm";
				preStart	= 1;
				recompile	= 1;
			};
		};
	};
};
Attributes
Attribute Description Available in
Description.ext config.cpp
file the file attribute can be used to manually set the file path.
The file entry overrides Category's set path and ignores it entirely (they are not merged).
Ico ok.png Ico ok.png
preInit the preInit attribute (formerly known as "forced") can be set to 1 to call the function upon mission start, before objects are initialized.
Passed arguments are ["preInit"]. The function is run in an unscheduled environment.
Ico ok.png Ico ok.png
postInit the postInit attribute can be set to 1 to call the function upon mission start, after objects are initialized.
Passed arguments are ["postInit", didJIP]. The function is run in a scheduled environment so suspension is allowed, but any long term suspension will halt the mission loading until suspension is done.
Ico ok.png Ico ok.png
ext the ext attribute can be used to set function file's type; it can be one of:
  • ".sqf" (default)
  • ".fsm" (see FSM)
Ico ok.png Ico ok.png
preStart the preStart attribute can be set to 1 to call the function upon game start, before title screen, but after all addons are loaded. Ico none.png Ico ok.png
recompile the recompile attribute can be set to 1 to recompile the function upon mission start (functions in Description.ext are always compiled upon mission (re)start) Ico none.png Ico ok.png
headerType the headerType adds code to the beginning of functions that can:
  • Set up the Meta Variables _fnc_scriptParent and _fnc_scriptName
  • Name the current scope via the command scriptName
  • Adds debug information by saving the current execution order in the Array _fnc_scriptMap.

Possible values are:

  • -1: No header - Adds nothing, literally adds a blank String to the beginning of functions. The functions will have no debug or Meta Variables assigned for it and the scope will not be named. Useful to reduce the performance overhead or if custom debug system is used.
  • 0: Default header - The default header changes based on the current Debug Mode
  • 1: System header - Incorporates the Meta Variables _fnc_scriptParent. Also names the current scope.
private _fnc_scriptNameParent = if (isNil '_fnc_scriptName') then { '%1' } else { _fnc_scriptName };
scriptName '%1';

See the following section for more information.

Ico ok.png Ico ok.png
Notes about preInit and postInit defined in config.cpp:
  • these attributes will make the function run on each, every and any mission start
  • Any scripting error will prevent the mission from being loaded correctly
  • Server admins might blacklist the whole addon if they find out the function is used for hacking


Advanced Knowledge

Meta Variables

  • _fnc_scriptName: String - Name of the script
  • _fnc_scriptNameParent: String - Name of the parent script
  • _fnc_scriptMap: Array - List of all parent scripts

Debug Modes

Developers can access several debug modes using BIS_fnc_functionsDebug function. For this to work function recompiling has to be allowed!

Debug Mode 0

default - incorporates the Meta Variables _fnc_scriptParent and _fnc_scriptName and names the current scope.

private _fnc_scriptNameParent = if (isNil '_fnc_scriptName') then {'%1'} else {_fnc_scriptName};
private _fnc_scriptName = '%1';
scriptName _fnc_scriptName;

Debug Mode 1

As per Debug Mode 0 and also saves the current execution order in the Array _fnc_scriptMap.

private _fnc_scriptNameParent = if (isNil '_fnc_scriptName') then { '%1' } else { _fnc_scriptName };
private _fnc_scriptName = '%1';
scriptName _fnc_scriptName;
private _fnc_scriptMap = if (isNil '_fnc_scriptMap') then {[_fnc_scriptName]} else {_fnc_scriptMap + [_fnc_scriptName]};

Debug Mode 2

As per Debug Mode 1 and also outputs execution order using textLogFormat ( textLogFormat is not available in the retail version of Arma3 ) is it available in Diagnostics exe?

private _fnc_scriptNameParent = if (isNil '_fnc_scriptName') then { '%1' } else { _fnc_scriptName };
private _fnc_scriptName = '%1';
scriptName _fnc_scriptName;
private _fnc_scriptMap = if (isNil '_fnc_scriptMap') then { [_fnc_scriptName] } else { _fnc_scriptMap + [_fnc_scriptName] };
textLogFormat ['%1 : %2', _fnc_scriptMap joinString ' >> ', _this];


See Also