Difference between revisions of "Functions Library 2.0"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "\[\[Arma 3 ([^ACHJKLMTZ|])([^|]+)\]\]" to "Arma 3: $1$2")
m (redirect)
(Tag: New redirect)
Line 1: Line 1:
#REDIRECT [[Take On Helicopters: Functions Library]]
{{Feature | important | This page is about {{tkoh}} Functions Library system.
* for {{arma2}}, see [[Functions Library]]
* for {{arma3}}, see [[Arma 3: Functions Library]]
[[Functions Library 2.0]] 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 is 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;
_fnc = [params] spawn functionName;
=== Multiplayer ===
Functions replaces obsolete [[Arma 2: Multiplayer Framework]]. You can use [[remoteExec]] or [[remoteExecCall]] to remotely execute function on specific clients and set them to be persistent, so they'll be executed automatically for client upon JIP.
[params] remoteExec ["functionName",target,isPersistent];
=== GUI ===
Anywhere outside running mission (user interface), refer to functions stored in UInamespace
_fnc = [params] call (uinamespace getvariable 'functionName');
_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 the 3D Editor, you can find the Function Viewer in the Tools category of the menustrip [[File:icon editor functions.png|20px]]
* 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 = "<span style="color:DarkOrange;">hsim\ModulesCore_H\modules\functions</span>";
class <span style="color:green;">BIS</span>
class <span style="color:crimson;">category1</span>
class <span style="color:teal;">Test1</span> {description="Testing file 1"};
class HSim
tag = "<span style="color:green;">BIS</span>";
class <span style="color:crimson;">category2</span>
file = "<span style="color:DarkOrange;">hsim\modules_h\functions</span>";
class <span style="color:teal;">Test2</span> {description="Testing file 2";};
class <span style="color:teal;">Test3</span> {description="Testing file 3"; file="<span style="color:DarkOrange;">test.sqf</span>"};
class <span style="color:teal;">Test4</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
**'' '<span style="color:DarkOrange;">file</span>\<span style="color:crimson">category</span>\fn_<span style="color:teal">function</span>.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.
* Default ''ext='' is .sqf. You can optionally use .fsm, but no other extensions are compatible. Define .fsm even when you're settings ''file='' leading directly to the file.
Result is:
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test1</span>''' - will load script ''<span style="color:DarkOrange;">hsim\ModulesCore_H\modules\functions</span>\<span style="color:crimson;">category1</span>\<span style="color:teal;">test1</span>.sqf'' from functions directory (see above)
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test2</span>''' - will load script ''<span style="color:DarkOrange;">hsim\modules_h\functions</span>\<span style="color:crimson;">category2</span>\<span style="color:teal;">Test2</span>.sqf''
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test3</span>''' - will load script ''<span style="color:DarkOrange;">test.sqf</span>'' from mission directory
* '''<span style="color:green;">BIS</span>_fnc_<span style="color:teal;">Test4</span>''' - will load FSM ''<span style="color:DarkOrange;">hsim\modules_h\functions</span>\<span style="color:crimson;">category2</span>\<span style="color:teal;">Test4</span><span style="color:fuchsia;">.fsm</span>''
== Debugging ==
=== Debug Functions ===
Use debug functions/commands to register params, display errors and log messages. Printed output of these functions automatically contains name of function from which it was called.
{{Feature|important|Usage of following functions/commands is mandatory:
* [[param]]
* [[params]]
* [[BIS_fnc_log]]
* [[BIS_fnc_error]]
* [[BIS_fnc_halt]]
Examples of debug outputs:
{{codecomment|"Helicopter class is empty." call bis_fnc_halt;}}
[3104] Log: HALT: [BIS_fnc_heliportHeliAddMission] Helicopter class is empty.
{{codecomment|_mission <nowiki>=</nowiki> [[param]] [0,worldName,[""]];}}
[3104] Log: ERROR: [BIS_fnc_endMission] 0: HSim_Player is type OBJECT, must be STRING. "United_States_H" used instead.
{{codecomment|["Helicopter '%1' not found.",_heliPlayer] call bis_fnc_error;}}
[3104] Log: ERROR: [BIS_fnc_heliportHeliAddMission] Helicopter 'MYHELICOPTER' not found.
{{codecomment|42 call bis_fnc_log;}}
[3104] array ["Log: [BIS_fnc_heliportInit] ",42]
{{codecomment|["Random number is %1",random 999] call bis_fnc_log;}}
[3104] Log: [BIS_fnc_heliportInit] Random number is 808.768
=== 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 is printed to debug log.
=== Debug Variables ===
Store following variables into profileNameSpace to toggle various debug options:
* '''BIS_fnc_initRecompileEditor''' - recompiles functions every time you click on 'Preview' button in editor ensuring changes made in functions are present on mission start.
=== 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]]).
{{Feature|important|Please do not modify these values!}}
=== Initialization Order ===
# '''Functions'''
# Init Event Handlers
# Mission.sqm
# Init.sqf
# Init.sqs
# Triggers

Latest revision as of 18:21, 4 May 2021