Difference between revisions of "Functions Library 2.0"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "{{SideTOC}}" to "{{TOC|side}}")
m (redirect)
(Tag: New redirect)
 
(3 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{TOC|side}}
+
#REDIRECT [[Take On Helicopters: Functions Library]]
{{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;
 
or
 
_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');
 
or
 
_fnc = [params] spawn (uinamespace getvariable 'functionName');
 
 
 
 
 
== In-game functions viewer ==
 
 
 
[[Image:Take_On_Helicopters_Functions_Viewer.jpg|300px|thumb|right]]
 
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]]
 
 
 
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 = "<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.
 
{{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]]).
 
{{Important|Please do not modify these values!}}
 
 
 
=== Initialization Order ===
 
 
 
# '''Functions'''
 
# Init Event Handlers
 
# Mission.sqm
 
# Init.sqf
 
# Init.sqs
 
# Triggers
 
 
 
 
 
[[Category:Take On Helicopters]]
 
[[Category:Take On Helicopters: Editing]]
 

Latest revision as of 18:21, 4 May 2021