Arma 3: Functions Library

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 Arma 3: Writing a Function#Recompiling and BIS_fnc_recompile)
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

Important

This page is about Arma 3 Functions Library.

• For Arma 2/Arma 2:OA, see Arma 2: Functions Library.
• For Take On Helicopters, see Take On Helicopters: 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.

Note

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:

• if Description.ext, <ROOT> means the mission's root directory
• if Campaign Description.ext, <ROOT> means the campaign's root directory
• if in config, <ROOT> means the game's root directory. The addon path needs to be set manually.

See a basic example config: class CfgFunctions { class TAG { class Category { class functionName {}; }; }; };

• The function's name will be TAGfncfunctionName
• The function will be loaded:
  • from config: **<ROOT>**\Category\**fn_**functionName**.sqf**
  • from description.ext: **<ROOT>**\**functions**\Category\**fn_**functionName**.sqf**

Important

config.cpp only:

• <ROOT> in mods is defined by the file mandatory attribute - see the #file section below.
• 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 - it is required for mods.

requiredAddons

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

Function

Note

By convention, the function class should be named in camelCase and not have its first letter capitalised (e.g PascalCase):

• ✓ TAG_fnc_myFunction
• ✗ TAG_fnc_MyFunction
• ✓ 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

Important

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

• Initialisation Order
• Arma 3: Functions Viewer
• Arma 3 Functions
• Writing a Function Tutorial

Arma 3 Editing