Arma 3: Functions Library

From Bohemia Interactive Community
Revision as of 23:10, 4 August 2021 by R3vo (talk | contribs) (See Also)
Jump to navigation Jump to search

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. arguments call (uiNamespace getVariable "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

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 {}; {{cc|file path will be %ROOT%\My\Category\Path\fn_myFunction.sqf";
		};

		class Data
		{
			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.

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

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 myOtherFunction
			{
				preInit = 1;
				postInit = 1;
				ext = ".fsm";
				preStart = 1;
				recompile = 1;
			};
		};
	};
};
Attributes
Attributes
Attribute Description
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).
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.
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.
ext the ext attribute can be used to set function file's type; it can be
    • ".sqf" (default)
    • ".fsm" (see FSM)
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

The following attributes only work with config.cpp (addon) usage:

config.cpp only
Attribute Description
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.
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)


See Also