Function

A function is a special form of a script. The common extension for functions is .sqf.

A function is much like a regular scripting command, except that you can use functions to create something like a custom command. A function does something and can then return a value to the point which 'called' that function or it can simply return Nothing.

Introduction

Functions were first introduced into an OFP: Resistance patch.

Usage

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 scripts, where timing is important.

Syntax

Functions are strictly limited to SQF syntax.

Execution

Functions can be executed from several points in the game:

• Other scripts
• Other functions
• Scripting lines in the Mission Editor
• 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.

Example:

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

call myFunction1;
[1, 2] call myFunction2;

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.

Note: Due to this nature, the special variables and commands of scripts are not available in functions.

Limitations

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.

Return Value

The last value given in a function is returned to the calling instance. Note that there must not be a semicolon after this value.

return.sqf

COMMAND 1;
COMMAND 2;
RETURN_VALUE

test.sqf

value = call loadFile "return.sqf";
// value is now RETURN_VALUE

call loadFile "return.sqf";
// valid, but RETURN_VALUE is lost

Examples

Example 1: max.sqf

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

max.sqf

comment "Return maximum of first and second argument";
private ["_a","_b"];
_a = _this select 0;
_b = _this select 1;
if (_a>_b) then {_a} else {_b}

executing script:

fMax = loadFile "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.

comment "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

Notice that there are no brackets around the functions arguments which precede the call command.
In case the function doesn't require any arguments you can use empty brackets instead.

[] call FNC_helloall

See also

• Scripts
• SQF syntax
• call