Functions Library – Arma 3

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.

Usage

params are parameters required by given function.

⚠

If you wish to skip a param (e.g. leave it's default value), use nil on its index (valid only if BIS_fnc_param is used by the function).

Singleplayer

Functions can be launched in mission, intro and outro using this syntax:

_fnc = [params] call functionName;

or

_fnc = [params] spawn functionName;

Multiplayer

Functions replaces obsolete 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.

[params,"functionName",target,isSpawn,isPersistent] call BIS_fnc_MP;

GUI

Anywhere outside running mission (user interface), refer to functions stored in UInamespace

_fnc = [params] call (uinamespace getvariable 'functionName');

or

_fnc = [params] spawn (uinamespace getvariable 'functionName');

In-game functions viewer

Use following code to display function library anywhere in game:

[] call BIS_fnc_help;

In 2D editor, press 'Ctrl + F' to display the viewer or click on icon:

Features:

• 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.

Adding new functions

List of functions is defined in config under CfgFunctions container. New ones can be also added in description.ext file of mission or campaign.

class CfgFunctions
{
	file = "A3\functions_f\initFunctions.sqf";
	class A3
	{
		tag = "BIS";
		requiredAddons[] = {"A3_Data_F"}; // Optional requirements of CfgPatches classes
		class category
		{
			file = "A3\functions_f\Misc";
			class Test1 		{description="Testing file 2";};
			class Test2 		{description="Testing file 3"; file="test.sqf"};
			class Test3 		{description="Testing file 4 (FSM)"; ext=".fsm"};
		};
	};
};

• If file path is not set for the given function, system will search for file in
  • 'file\category\fn_function.sqf" (if functions is defined in description.ext)
• When file parameter is defined in category root, all functions in given category will be searched for in this directory.

Result of example code above is:

• BIS_fnc_Test1 - will load script A3\functions_f\Misc\category\fn_Test1.sqf
• BIS_fnc_Test2 - will load script test.sqf from mission directory
• BIS_fnc_Test3 - will load FSM A3\functions_f\Misc\category\Test4.fsm

Optional function class params:

• description - Short function description. Will be rendered obsolete in further revisions, with script headers serving as the main source of documentation.
• ext - file type, can be ".sqf" or ".fsm" (meaning scripted FSM). Default is ".sqf".
• file - optional direct path to the file.
• recompile (new in Arma 3) - function will be recompile upon mission start.
• forced (new in Arma 3) - function will be executed automatically upon mission start.

Debugging

Debug Functions

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.

⚠

Usage of following functions is strongly recommended:

• BIS_fnc_param
• BIS_fnc_log
• BIS_fnc_error
• BIS_fnc_halt

Examples of debug outputs:

"Config param 'splendid' not defined in CfgArma." call BIS_fnc_halt;
"Log: HALT: [BIS_fnc_isSplendid] Config param 'splendid' not defined in CfgArma."

_mission = [BIS_Player] call BIS_fnc_endMission;
"Log: ERROR: [BIS_fnc_endMission] 0: BIS_Player is type OBJECT, must be STRING. "end1" used instead."

["Persistent execution is not allowed when target is %1. Use %2 or %3 instead.",typename 0,typename objnull,typename false] call BIS_fnc_error;
"Log: ERROR: Persistent execution is not allowed when target is SCALAR. Use OBJECT or BOOL instead."

42 call BIS_fnc_log;
"BIS_fnc_log: [BIS_fnc_myFunction]: 42"

["Random number is %1",random 999] call BIS_fnc_log;
"BIS_fnc_log: [BIS_fnc_myFunction] Random number is 808.768"

Allow Recompile

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.

To allow recompiling missionNamespace functions, place following param into mission Description.ext:

allowFunctionsRecompile = 1;

Debug Mode

Developers can access several debug modes using BIS_fnc_functionsDebug function.

1. No debug
   • Default
2. Save script map
   • Variable _fnc_scriptMap tracking script execution progress is stored in function header
3. Save and log script map
   • Variable _fnc_scriptMap tracking script execution progress is stored in functions header and it's printed to debug log.

⚠

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 above).

⚠

Please do not modify these values!

Initialization Order

1. Functions
2. Init Event Handlers
3. Mission.sqm
4. Init.sqf
5. Init.sqs
6. Triggers