Function

Introduction

Functions were first introduced into a OFP: Resistance patch.

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.

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.

Function files are denoted with the file extension .SQF (as opposed to .SQS used for scripts)

Example:

myfunctionname.sqf

While Sqs script syntax is line based, functions (see call, execVM, compile, then, do) are based on structured expressions. End-of-line has no special meaning - it is considered to be equivalent to space or semicolon, and is therefore required, even when ending line.

Functions in ArmA

Starting with Armed Assault there exist scripts which use the same structured expression syntax as functions, but can wait suspended, using sleep or waitUntil. While SQS scripts still work, they are considered deprecated and wherever possible, structured syntax scripts should be used instead. OFP-like Functions are still important in Armed Assault, as the calling script waits until they are executed, while the new type scripts are running parallel.

Functions in OFP

In Operation Flashpoint .sqs scripts could do some things that are not possible in functions. Scripts can wait suspended until some condition is met, they can also use goto to change execution point at any time.

Language Constructs

Main language contructs used in functions are:

• if..then..else
• while..do
• since ArmA: for ... from ... to ... step
• since ArmA: switch ... do
• Curled braces { }
• Multiple commands (including assigment commands) are delimited with a semicolon.

Result of the last expression evaluated is returned as a function result.

This can be Nothing when a function returns no value.

Examples

Example 1 (max.sqf) In this example the function returns maximum of first and second argument.

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}

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 (e.g init.sqs):

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).

Notes

Due to line-based nature of Sqs scripts it is not possible to create multiline string constants in them.
To overcome this limitation you can store multiline in separate files, and load them using loadFile or preprocessFile functions (the second uses C-like preprocessor with // or /* */ comments and #define macros).

See also

call