Difference between revisions of "Function"

From Bohemia Interactive Community
Jump to navigation Jump to search
m
m (Text replacement - "\[\[SQF[ _]syntax" to "[[SQF Syntax")
 
(89 intermediate revisions by 18 users not shown)
Line 1: Line 1:
A '''function''' is a chunk of code grouped together. This code does a specific task and ''can be'' written in a seperate file parsed by the game engine. The common extensions for functions is '''.sqf'''.
+
{{TOC|side}}
  
A function is much like a regular scripting command, except that you can use functions to create something like a custom command. A '''function''' is simply a chunk of code that does something, the function can then return a value to the point which 'called' that function or it can simply return [[Nothing]].
+
A '''function''' contains [[Code|code]] which usually consists of an ''input'', ''processing'' and ''output'' part. Functions were first introduced in the [[Operation Flashpoint: Resistance Version History|{{ofpr}}]] patch.
 +
The main advantages of functions are:
 +
; Improved legibility
 +
: By writing the code once and re-using it by calling the function
 +
; Easier debugging
 +
: If your function contains an error, you only have to fix it in one place
  
== Introduction ==
+
== Types of function ==
 +
=== Functions-as-files ===
 +
:''See [[Function#Call|calling functions]] for how a function-as-file is called.
 +
Functions as files are functions stored within a file. These are usually used for larger and more complex functions. The code is evaluated in the same way, however, there are additional commands which must include the file before the function itself can be called.
  
Functions were first introduced into an OFP: Resistance patch.  
+
{{cc|[[Code]] inside fn_showHint.sqf}}
 +
  hint "Function was executed!"; {{cc|Function will show a hint when executed}}
  
== Usage ==
+
=== Inline functions ===
 +
Inline functions are functions are technically [[Code|code]] which is often stored within a variable or declared as a function parameter. Inline functions operate the same way as functions-as-files as both are evaluated in the same way, but the difference is that inline functions are stored within parentheses <tt>{}</tt>, whereas functions-as-files do not require these.
  
Functions should be used for any processes where the '''result''' or '''calculation''' done in the function is important. This result or calculation should be made in the '''least time possible'''. They are different to [[Script (File)|scripts]], where ''timing'' is important.
+
{{cc|Inline function as [[Variables|variable]]}}
 +
TAG_fnc_showHint =
 +
{
 +
    [[hint]] "Function was executed!"; {{cc|Function will show a hint when executed}}
 +
};
 +
[[call]] TAG_fnc_showHint;
  
== Syntax ==
+
== Anatomy of a function ==
 +
When scripting, there are two types of functions: functions-as-files and inline functions. Functions-as-files are instances where the a whole file itself is used to house a function, whereas inline functions are either contained within a variable or as a parameter of a function. Some built-in functions require functions-as-files, whereas most will support both.
  
Functions are strictly limited to [[SQF syntax]].
+
=== Parameters (input) ===
 +
Parameters for functions are available to the function via the [[Magic Variables|magic variable]] [[Magic Variables#this|_this]]. Declaration of parameters can be done using the [[params]] command. Common practice for defining parameters is done via the use of [[private]] variables and defined variables.
  
== Execution ==
+
{{cc|[[Code]] inside fn_showHint.sqf}}
 +
[[params]] ["_text"];
 +
[[hint]] _text;
  
Functions can be executed from several points in the game:
+
{{cc|Inline function as [[Variables|variable]]}}
 +
TAG_fnc_showHint =
 +
{
 +
    [[params]] ["_text"];
 +
    [[hint]] _text;
 +
};
 +
"Function was executed!" [[call]] TAG_fnc_showHint;
 +
 
 +
Parameters passed to functions are passed '''before''' the function, rather than after (such as the mathematical or c-like syntax ''f(x)'').
  
* Other scripts
+
//Array variable as parameter
* Other [[Function|functions]]
+
_myTempParams = [_parameterOne, _parameterTwo];
* Scripting lines in the [[Mission Editor]]
+
_myTempVariableTwo = _myTempParams call myInlineFunction;
* [[Event Handlers]] in addon config files
 
  
Functions are first compiled via [[preprocessFile]] command or loaded dynamically via the [[loadFile]] command. They are then executed via the [[call]] command.
+
//Array as parameter
 +
_myTempVariable = [_parameterOne,_parameterTwo] call myInlineFunction;
  
Functions are running ''within'' the executing instance, which waits for the result of the function. Different to scripts, functions halt all other game engine processes until the function has completed its instructions. This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes.  When creating a functions you want the function to be short and sweet to achieve the best results.
+
=== Return Values (output)===
 +
The value of the last executed statement in a function is returned to the calling instance.
  
Functions have a limitation of 10,000 loops before they are forced to exit by the game engine in order to maintain some level of stability.
+
my_fnc = {
 +
    [[if]] (_this > 0) [[exitWith]] {
 +
        _this + 1
 +
    };
 +
    _this - 1
 +
};
 +
 +
[[hint]] [[str]] (5 [[call]] my_fnc); //6
 +
[[hint]] [[str]] (-5 [[call]] my_fnc); //-6
  
[[Image:Function_Execution_Diagram.jpg]]
+
In the first example "_this + 1" is the last executed statement in my_fnc, in the second example it is "_this - 1". Traditionally the returning statement is written without ";" after it. Have it or don't have it, it is up to you, doesn't make a blind bit of difference:
  
== Return Value ==
+
my_fnc = {
 +
    a = 1;
 +
    b = 2;
 +
    c = a + b;
 +
    c //<- fine
 +
};
 +
 +
my_fnc = {
 +
    a = 1;
 +
    b = 2;
 +
    c = a + b;
 +
    c; //<- also fine
 +
};
 +
 
 +
More examples:
 +
//myCode.sqf
 +
private _myName = _this select 0;
 +
 +
private _returnMe = "FAIL";
 +
 +
if (_myName == "Test") then {
 +
    _returnMe = "PASS";
 +
};
 +
_returnMe
  
The '''last value given''' in a function is returned to the calling instance. Note that there ''must not'' be a semicolon after this value.
+
//myCodeInline
 +
myCodeReturnValue ={
 +
    private _myName = _this select 0;
 +
    private _returnMe = "FAIL";
 +
 +
    if (_myName == "Kaboom") then {
 +
          _returnMe = "PASS";
 +
    };
 +
 +
    _returnMe
 +
};
 +
 +
_myCalledVariable = ["Kaboom"] call myCodeReturnValue; // "PASS"
 +
_myCalledVariableFail = ["Blah"] call myCodeReturnValue; // "FAIL"
  
return.sqf
+
//return.sqf
  COMMAND 1;
+
  STATEMENT 1;
  COMMAND 2;
+
  STATEMENT 2;
 
  RETURN_VALUE
 
  RETURN_VALUE
  
test.sqf
+
//test.sqf
  value = [[call]] [[loadFile]] "return.sqf";
+
  value = [[call]] [[compile]] [[preprocessFile]] "return.sqf";
 
  // value is now RETURN_VALUE
 
  // value is now RETURN_VALUE
 
   
 
   
  [[call]] [[loadFile]] "return.sqf";
+
  [[call]] [[compile]] [[preprocessFile]] "return.sqf";
  // valid, but RETURN_VALUE is lost
+
  // valid, but RETURN_VALUE is not saved anywhere
 +
 
 +
=== Execution ===
 +
 
 +
[[Image: Function_Execution.png|frame|right||Function Execution Diagram in [[Scheduler#Scheduled_Environment|scheduled environment]]<br><br>'''Executing Instance :''' [[Script (File)|script]], function or game engine]]
 +
 
 +
Functions can be executed from several points in the game:
 +
 
 +
* Other [[Script (File)|scripts]]
 +
* Other functions
 +
* Scripting lines in the [[ArmA:_Mission_Editor|Mission Editor]]
 +
* [[:Category:Event Handlers|Event Handlers]] in addon config files
 +
 
 +
Functions are first loaded as [[String]] from a file via [[preprocessFile]] or [[loadFile]]. They are then executed via the [[call]] or [[spawn]] command. Since Armed Assault the loaded [[String]] needs to be [[compile|compiled]] in order to convert it to [[Code]], which is required for [[call]] or [[spawn]].
 +
 
 +
==== Call ====
 +
 
 +
Example (Operation Flashpoint):
 +
 
 +
myFunction1 = [[loadFile]] "myFunction1.sqf";
 +
myFunction2 = [[preprocessFile]] "myFunction2.sqf";
 +
 +
[[call]] myFunction1;
 +
[1, 2] [[call]] myFunction2;
 +
 
 +
Example (Armed Assault):
 +
 
 +
myFunction1 = [[compile]] [[loadFile]] "myFunction1.sqf";
 +
myFunction2 = [[compile]] [[preprocessFile]] "myFunction2.sqf";
 +
 +
_result1 = [[call]] myFunction1;
 +
_result2 = [1, 2] [[call]] myFunction2;
 +
 
 +
Functions executed using [[call]] are run ''within'' the executing instance, which waits for the result of the function. Unlike scripts, functions halt all other game engine processes until the function has completed its instructions. This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes.  When creating a functions you want the function to be short and sweet to achieve the best results.
 +
 
 +
'''Note:''' You can still use the special variables and commands of [[Script (File)|scripts]] in functions (Armed Assault only)!
 +
 
 +
==== Spawn ====
 +
 
 +
Functions may also be executed using [[spawn]], but then the function result is not accessible, making it behave more like a procedure. Spawned functions will run asynchronously or ''alongside'' the executing instance. This helps prevent large CPU intensive functions from seizing up the game.
 +
 
 +
Example (Armed Assault):
 +
 
 +
myFunction1 = [[compile]] [[loadFile]] "myFunction1.sqf";
 +
myFunction2 = [[compile]] [[preprocessFile]] "myFunction2.sqf";
 +
 +
_param [[spawn]] myFunction1;
 +
[1, 2] [[spawn]] myFunction2;
  
 
== Examples ==
 
== Examples ==
Line 54: Line 173:
 
In this example the function returns maximum of first and second argument.
 
In this example the function returns maximum of first and second argument.
  
  [[comment]] "Return maximum of first and second argument";
+
max.sqf
  [[private variableNameList|private]] ["_a","_b"];
+
  //"Return maximum of first and second argument";
  _a = _this [[select]] 0;
+
  [[params]] ["_a", "_b"];
_b = _this [[select]] 1;
+
  [_b, _a] [[select]] (_a > _b)
  [[if]] (_a>_b) [[then]] {_a} [[else]] {_b}
+
 
 +
alternative max.sqf (big boys code :))
 +
(_this [[select]] 0) [[max]] (_this [[select]] 1)
 +
 
 +
executing script:
 +
  fMax = [[compile]] [[preprocessFile]] "max.sqf";
 +
maxValue = [3,5] [[call]] fMax;
 +
 +
//maxValue is now 5
  
 
=== Example 2: infantrySafe.sqf ===
 
=== Example 2: infantrySafe.sqf ===
Line 64: Line 191:
 
In this example the function returns no value and switches all units to safe mode.
 
In this example the function returns no value and switches all units to safe mode.
  
  [[comment]] "Switch all infantry units to safe mode";
+
  //"Switch all infantry units to safe mode";
 
  {
 
  {
     [[if]] ([[vehicle]] _x == _x) [[then]]
+
     [[if]] ([[vehicle]] _x == _x) [[then]] {
    {
 
 
         _x [[setBehaviour]] "safe"
 
         _x [[setBehaviour]] "safe"
 
     }
 
     }
Line 76: Line 202:
 
An inline-function can be created in any script:
 
An inline-function can be created in any script:
  
  FNC_sayhello = {hint format["hello %1",_this]};
+
  FNC_sayhello = {[[hint]] [[format]] ["hello %1", _this]};
  
 
This function can then be called (in other scripts, functions, unit's init lines, trigger activation fields, etc.) via:
 
This function can then be called (in other scripts, functions, unit's init lines, trigger activation fields, etc.) via:
  
  name player call FNC_sayhello
+
  [[name]] [[player]] [[call]] FNC_sayhello
 +
 
 +
In case the function doesn't require any arguments you can just call the function.
  
Notice that there are '''no''' brackets around the functions arguments which precede the call command.<br>In case the function doesn't require any arguments you can use empty brackets instead <code>[] call FNC_helloall</code>.
+
[[call]] FNC_helloall
  
 
== See also ==
 
== See also ==
  
 +
* [[Script (File)|Scripts]]
 +
* [[SQF Syntax]]
 
* [[call]]
 
* [[call]]
  
 
[[Category: Scripting_Topics]]
 
[[Category: Scripting_Topics]]
[[Category: ArmA: Scripting]]
 

Latest revision as of 23:58, 24 March 2021

A function contains code which usually consists of an input, processing and output part. Functions were first introduced in the Operation Flashpoint: Resistance patch. The main advantages of functions are:

Improved legibility
By writing the code once and re-using it by calling the function
Easier debugging
If your function contains an error, you only have to fix it in one place

Types of function

Functions-as-files

See calling functions for how a function-as-file is called.

Functions as files are functions stored within a file. These are usually used for larger and more complex functions. The code is evaluated in the same way, however, there are additional commands which must include the file before the function itself can be called.

// Code inside fn_showHint.sqf
 hint "Function was executed!"; // Function will show a hint when executed

Inline functions

Inline functions are functions are technically code which is often stored within a variable or declared as a function parameter. Inline functions operate the same way as functions-as-files as both are evaluated in the same way, but the difference is that inline functions are stored within parentheses {}, whereas functions-as-files do not require these.

// Inline function as variable
TAG_fnc_showHint = 
{
   hint "Function was executed!"; // Function will show a hint when executed
};
call TAG_fnc_showHint;

Anatomy of a function

When scripting, there are two types of functions: functions-as-files and inline functions. Functions-as-files are instances where the a whole file itself is used to house a function, whereas inline functions are either contained within a variable or as a parameter of a function. Some built-in functions require functions-as-files, whereas most will support both.

Parameters (input)

Parameters for functions are available to the function via the magic variable _this. Declaration of parameters can be done using the params command. Common practice for defining parameters is done via the use of private variables and defined variables.

// Code inside fn_showHint.sqf
params ["_text"];
hint _text;
// Inline function as variable
TAG_fnc_showHint = 
{
   params ["_text"];
   hint _text;
};

"Function was executed!" call TAG_fnc_showHint;

Parameters passed to functions are passed before the function, rather than after (such as the mathematical or c-like syntax f(x)).

//Array variable as parameter
_myTempParams = [_parameterOne, _parameterTwo];
_myTempVariableTwo = _myTempParams call myInlineFunction;
//Array as parameter
_myTempVariable = [_parameterOne,_parameterTwo] call myInlineFunction;

Return Values (output)

The value of the last executed statement in a function is returned to the calling instance.

my_fnc = {
    if (_this > 0) exitWith {
        _this + 1
    };
    _this - 1
};

hint str (5 call my_fnc); //6
hint str (-5 call my_fnc); //-6

In the first example "_this + 1" is the last executed statement in my_fnc, in the second example it is "_this - 1". Traditionally the returning statement is written without ";" after it. Have it or don't have it, it is up to you, doesn't make a blind bit of difference:

my_fnc = {
    a = 1;
    b = 2;
    c = a + b;
    c //<- fine
};

my_fnc = {
    a = 1;
    b = 2;
    c = a + b;
    c; //<- also fine
};

More examples:

//myCode.sqf
private _myName = _this select 0;

private _returnMe = "FAIL";

if (_myName == "Test") then {
    _returnMe = "PASS";
};
_returnMe
//myCodeInline
myCodeReturnValue ={
    private _myName = _this select 0;
    private _returnMe = "FAIL";

    if (_myName == "Kaboom") then {
         _returnMe = "PASS";
    };

    _returnMe
};

_myCalledVariable = ["Kaboom"] call myCodeReturnValue; // "PASS"
_myCalledVariableFail = ["Blah"] call myCodeReturnValue; // "FAIL"
//return.sqf
STATEMENT 1;
STATEMENT 2;
RETURN_VALUE
//test.sqf
value = call compile preprocessFile "return.sqf";
// value is now RETURN_VALUE

call compile preprocessFile "return.sqf";
// valid, but RETURN_VALUE is not saved anywhere

Execution

Function Execution Diagram in scheduled environment

Executing Instance : script, function or game engine

Functions can be executed from several points in the game:

Functions are first loaded as String from a file via preprocessFile or loadFile. They are then executed via the call or spawn command. Since Armed Assault the loaded String needs to be compiled in order to convert it to Code, which is required for call or spawn.

Call

Example (Operation Flashpoint):

myFunction1 = loadFile "myFunction1.sqf";
myFunction2 = preprocessFile "myFunction2.sqf";

call myFunction1;
[1, 2] call myFunction2;

Example (Armed Assault):

myFunction1 = compile loadFile "myFunction1.sqf";
myFunction2 = compile preprocessFile "myFunction2.sqf";

_result1 = call myFunction1;
_result2 = [1, 2] call myFunction2;

Functions executed using call are run within the executing instance, which waits for the result of the function. Unlike scripts, functions halt all other game engine processes until the function has completed its instructions. This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes. When creating a functions you want the function to be short and sweet to achieve the best results.

Note: You can still use the special variables and commands of scripts in functions (Armed Assault only)!

Spawn

Functions may also be executed using spawn, but then the function result is not accessible, making it behave more like a procedure. Spawned functions will run asynchronously or alongside the executing instance. This helps prevent large CPU intensive functions from seizing up the game.

Example (Armed Assault):

myFunction1 = compile loadFile "myFunction1.sqf";
myFunction2 = compile preprocessFile "myFunction2.sqf";

_param spawn myFunction1;
[1, 2] spawn myFunction2;

Examples

Example 1: max.sqf

In this example the function returns maximum of first and second argument.

max.sqf

//"Return maximum of first and second argument";
params ["_a", "_b"];
[_b, _a] select (_a > _b)

alternative max.sqf (big boys code :))

(_this select 0) max (_this select 1)

executing script:

fMax = compile preprocessFile "max.sqf";
maxValue = [3,5] call fMax;

//maxValue is now 5

Example 2: infantrySafe.sqf

In this example the function returns no value and switches all units to safe mode.

//"Switch all infantry units to safe mode";
{
    if (vehicle _x == _x) then  {
        _x setBehaviour "safe"
    }
} forEach _this

Example 3: Inline Function

An inline-function can be created in any script:

FNC_sayhello = {hint format ["hello %1", _this]};

This function can then be called (in other scripts, functions, unit's init lines, trigger activation fields, etc.) via:

name player call FNC_sayhello

In case the function doesn't require any arguments you can just call the function.

call FNC_helloall

See also