SQF Syntax
SQF stands for Status Quo Function - a successor of Status Quo Script, which is deprecated since Armed Assault but could still be used in Arma 3. SQF was first introduced in Operation Flashpoint: Resistance together with the call operator in update 1.85.
- "Status Quo" was a code name for Operation Flashpoint
- "Combined Arms" was a code name for Arma
- "Futura" was a code name for Arma 3.
Language Structure
The SQF Language is fairly simple in how it is built. In fact: there are barely any actual language structures at all.
The functionality is provided via so called operators (or more commonly known scripting commands). Those operators are one of the following types: Nularsic, Unary, or Binary.
Terminating an expression
An SQF expression has to be terminated via either ; (preferred by convention!) or ,.
Example
_num = 10; _num = _num + 20; systemChat str _num;
In the above example, there are three expressions.
_num = 10_num = _num + 20systemChat str _num
All get separated, not via a new line but the ;.
SQF also allows arrays and codeblocks to have expressions inside of them.
An array will always start with [ and ends with ]. The array may contain another value type including other arrays.
A codeblock is a separate value type containing numerous SQF expressions. It will be executed when used with eg. call and can be assigned to a variable just like any other value type. Codeblocks start with { and end with }
Whitespaces
Whitespace consists of tabs and/or space characters.
For the
purposes of the
engine
The 'line' begins at the first non whitespace character.
Similarly, trailing whitespace at the end of a line or statement is also ignored. In general whitespace is used for legibility, it is often optional in the syntax.
Blank Lines
Blank lines are lines containing nothing but whitespace and are therefore ignored by the engine.
Comments
A comment is additional text that gets ignored when a script is parsed. They serve as future reference and are often used to explain a specific part of the code.
In SQF, there are two kind of comments:
// In-line comment that ends on new line /* Block Comment that can span above multiple lines and ends on the following character combination: */
A comment can occur anywhere but inside a string. For example, the following would be valid:
1 + /* Some random comment in an expression. */ 1
It should be mentioned that there is a comment unary operator that should not be used as it will actually be executed (thus taking time to execute) but does nothing besides consuming a string.
There is no benefit in using it and the reason it exists is solely for backward compatibility.
Another way to make a comment that way, is to just place a string: [...]; "i can be considered as a comment but should not be used"; [...]
Comments are removed during the preprocessing phase. This is important to know as that prevents usage in e.g a string that gets compiled using the compile unary operator or when only using loadFile.
Nularsic Operators
A nularsic operator is more or less a computed variable. Each time accessed, it will return the current state of something. It is tempting to think of a nularsic operator as nothing more but a magic global variable, but it is important to differentiate!
Consider following example in a mission with e.g. 5 units:
// Put the result of allUnits into a variable. _unitsArray = allUnits; // Display the current array size using systemChat. systemChat str count _unitsArray; // Create a new unit in the player group. group player createUnit ["B_RangeMaster_F", position player, [], 0, "FORM"]; // Output the array size again systemChat str count _unitsArray; // Output the size of allUnits systemChat str count allUnits;
Now, what would the output of this look like?
System: 5 System: 5 System: 6
As you can see, _unitsArray was not automatically updated as it would have been if it was not generated each time. If allUnits was just a global variable with a reference to some internal managed array, our private variable should have had reflected the change as value types are passed by reference.
The reason for this is because allUnits and other nularsic operators just return the current state of something and do not return a reference to eg. an array containing all units.
It is generated each time, which is why some of theese operators are more expensive to run then just using a variable.
Unary Operators
The unary operators are operators that expect an argument on their right side (unary <argument>). They always will take the first argument that occurs.
A common mistake would be the following:
// Create some array containing three arrays. _arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]]; // Wrongly use the select operator to get the count of the third array. count _arr select 2; // Error
Now, what went wrong?
Let's put some brackets in the right places to make the mistake understandable:
(count _arr) select 2; // Error
Due to the nature of unary operators, count instantly consumes our variable _arr and returns the number 3. The 3 then is passed to select which does not knows what to do with a number as left argument and thus errors out.
To do it correctly, one would have to put the _arr select 2 in brackets.
The correct code thus would be:
// Create an array containing three arrays. _arr = [[1, 2, 3, 4, 5], [1, 2, 3, 4], [1, 2]]; // Use Brackets to correctly get count of the third array. count (_arr select 2); // Good :) will evaluate to 2
Binary Operators
Binary operators expect two arguments (<1st argument> binary <2nd argument>) and are executed according to their precedence. If their precedence is equal, they are executed left to right.
As example, we will look into the following expression:
// Create a nested array with 5 levels. _arr = [[[[[1]]]]]; // Receive the nested number with some random math expressions. _arr select 0 select 1 - 1 select 15 / 3 - 5 select 0 select 10 * 10 + 4 * 0 - 100 // Evaluates to 1.
Now, let us analyze why this is happening for the first few expressions:
- _arr is loaded
- 0 is loaded
- select is executed with the result of 1. & 2.
- 1 is loaded
- 1 is loaded
- - is executed with the result of 4. & 5.
- select is executed with the result of 3. & 6.
- ...
If we now would put brackets at the correct spots, the expression will get clearer:
((((_arr select 0) select (1 - 1)) select ((15 / 3) - 5)) select 0) select (((10 * 10) + (4 * 0)) - 100)
As you can see the * and / are executed first which matches their precedence. Afterward, the + and - operators will get executed followed by our select operator, which are executed from the left to the right.