Control Structures

Control Structures are statements which are used to control execution flow in the scripts. They are sequences of scripting code which help to control complex procedures. You can use control structures to define code which is only executed under certain conditions or repeated for a couple of times.

Note for advanced readers: in the Virtual Reality scripting language control structures are normal scripting commands, with no special handling compared to other commands. This is different from most imperative programming languages (like C), where control statements are implemented in the core language grammar. The "controlling" done by them is implemented by accepting code as an argument. The complex control structures like "while ... do ..." are implemented using helper types, like While Type.

Requirements

To fully understand this article you should read the following articles:

Conditional Structures

Conditional structures help to define code which is only executed under certain circumstances. Often you will write code that depends on the game state, on other code or other conditions.

`if`-Statement

The if-statement defines code that is only executed if a certain condition is met. The syntax of it looks like that:

if (CONDITION) then // The round braces are optional { STATEMENT; ... };

CONDITION is a Boolean statement or variable which returns either true or false. The code nested in the following block is only executed if the condition is true, else ignored.
STATEMENT is a custom sequence of statements. That may be commands, assignments, control structures etc.

Example:

if (_temperature < 0) then
{
    hint "Snow!";
};

In this example, first the value of _temperature is checked:

If the value is 0 or greater than 0, the nested code is ignored.
If the value is less than 0, the command hint "Snow!"; is executed.

Alternative Code (else)

You can also define alternative code that is executed, when the condition is not true.

if (CONDITION) then { STATEMENT1; ... } else { STATEMENT2; ... };

Another way of specifying an alternative code is done by feeding a 2-dimensional Array of Code into the then like this (but this alternative is CPU-heavier):

if (CONDITION) then [{STATEMENT1; ...}, {STATEMENT2; ...}];

In fact the above syntax with the Array is the only possible syntax as else does nothing else than taking the code to its left and the one to its right and packs them both into an Array of Code which is then fed into the then operator. But using else is just as fine and in most cases better in case of readability of your code.

Here you have a second sequence of statements executed when CONDITION is false.

Conditional assignments

if..then structures can also be used to assign conditional values to variables:

_living = if (alive player) then { true } else { false };

SQS syntax (deprecated)

Warning
SQS Syntax is deprecated; SQF Syntax should be used instead.

Within SQS Syntax the use of goto labels is a way to execute more than one statement within if...then structures.

if (CONDITION) then { goto "label" } ... some other statements #label statement1 statement2 statement3

Example 1: (without else)

if (_temperature < 0) then { goto "Snow" }
; ... some other statements

#Snow
  hint "Snow!"
  echo "There is snow!"
  variable = text "Hey. Snow outside."

Example 2: (with else)

if (_temperature < 0) then { goto "Snow" } else { goto "Sunshine" }
; ... some other statements
goto "Continue"
#Snow
  hint "Snow!"
  echo "There is snow!"
  variable = text "Hey. Snow outside."
  goto "Continue"

#Sunshine
  hint "No Snow but sunshine!"
  echo "There is no snow!"
  variable = text "Hey. No snow outside."
  goto "Continue"

#Continue
; ...

Nested `if`-Statements

Since the if-statement is itself a statement, you can also create nested if-statements.

Example:

if (alive player) then
{
    if (someAmmo player) then
    {
        hint "The player is alive and has ammo!";
    }
    else
    {
        hint "The player is out of ammo!";
    };
}
else
{
    hint "The player is dead!";
};

`switch`-Statement (Armed Assault v1.00)

In some cases you may want to check a variable for several values and execute different code depending on the value. With the above knowledge you could just write a sequence of if-statements.

if (_color == "blue") then
{
    hint "What a nice color";
}
else
{
    if (_color == "red") then
    {
        hint "Don't you get aggressive?";
    }
};

The more values you want to compare, the longer gets this sequence. That is why the simplified switch-statement was introduced.

The switch-statement compares a variable against different values:

switch (VARIABLE) do { case VALUE1: { STATEMENT; ... }; case VALUE2: { STATEMENT; ... }; ... };

The structure compares VARIABLE against all given values (VALUE1, VALUE2, ...). If any of the values matches, the corresponding block of statements is executed.

Example:

[switch (_color) do
{
    case "blue":
    {
        hint "What a nice color";
    };
    case "red":
    {
        hint "Don't you get aggressive?";
    };
};

`default`-Block

In some cases you may want to define alternative code that is executed, when none of the values matches. You can write this code in a default-Block.

switch (VARIABLE) do { case VALUE1: { STATEMENT; ... }; case VALUE2: { STATEMENT; ... }; ... default // No colon behind **default** { STATEMENT; ... }; };

Variable Assignments

Switch can be used to assign different values to a variable:

private _color = switch (side player) do
{
    case west: { "ColorGreen" };
    case east: { "ColorRed" };
};

Loops

Loops are used to execute the same code block for a specific or unspecific number of times.

`while`-Loop

This loop repeats the same code block as long as a given Boolean condition is true.

while {CONDITION} do // Note the curly braces { STATEMENT; ... };

Description:

CONDITION is evaluated. If it is true, go on to 2., else skip the block and go on with the code following the loop.
Execution of all nested statements. Go back to 1.

If CONDITION is false from the beginning on, the statements within the block of the loop will never be executed.

Because the test of the while expression takes place before each execution of the loop, a while loop executes zero or more times.

Example:

private _counter = 0;

while { _counter < 10 } do
{
    _counter = _counter + 1;
};

`for`-Loop (Armed Assault v1.00)

The for-loop repeats the same code block for a specific number of times.

for [{BEGIN}, {CONDITION}, {STEP}] do { STATEMENT; ... };

BEGIN is a number of statements executed before the loop starts
CONDITION is a Boolean condition evaluated before each loop
STEP is a number of statements executed after each loop

The loop processes as follows:

BEGIN is executed
CONDITION is evaluated. If it is true, go on to 3., else skip the block and go on with the code following the loop.
The statements in the code block are executed
STEP is executed, go on to 2.

If CONDITION is false from the beginning on, the code block will never be executed.

Example:

for [{ _i = 0 }, { _i < 10 }, { _i = _i + 1 }] do // a loop repeating 10 times
{
    player globalChat format ["%1", _i];
};

will display "0" then "1" then "2" then "3" then "4" then "5" then "6" then "7" then "8" then "9".

Description:

The variable _i is set to 0
The condition _i < 10 is evaluated, which is true until _i surpasses 9.
The code player globalChat _i; is executed
The variable _i is incremented by 1, back to step 2.

`for`-`from`-`to`-Loop

There exists an alternate syntax of the for-loop, which simplifies the last example a bit.

for "VARNAME" from STARTVALUE to ENDVALUE do { STATEMENT; ... };

VARNAME is any name given to the variable used to count the loop
STARTVALUE is a Number value given to the counter variable before the loop starts
ENDVALUE is a Number value until which the counter is incremented

Important
Note: Unless using a custom step as seen below, ENDVALUE must be greater than STARTVALUE for the loop to execute

The loop processes as follows:

A variable with the name VARNAME is initialized with STARTVALUE
If VARNAME does not exceed ENDVALUE, the code block will be executed.
The variable VARNAME is incremented by 1
Go back to step 2

The following example is semantically equal to the last example.

Example:

for "_i" from 0 to 9 do // a loop repeating 10 times
{
    player globalChat format ["%1", _i];
};

Description:

_i is set to 0
player globalChat 0 is executed
_i is incremented by 1 => _i is now 1
Back to step 2

`for`-`from`-`to`-Loop with custom `step`

The default step to increment the variable in for-from-to-Loops is 1. You can set a custom step though using this syntax:

for "VARNAME" from STARTVALUE to ENDVALUE step STEP do { STATEMENT; ... };

STEP is a Number which defines the step by which the variable is incremented every loop

Important
Note: Utilizing this method, you can perform loops where VARNAME decrements by using a negative step value combined with a STARTVALUE that is greater than ENDVALUE

The rest is equal to the above section.

Example:

for "_i" from 0 to 9 step 2 do // a loop repeating 5 times
{
    player globalChat format ["%1", _i];
};

Description:

_i is set to 0
player globalChat 0 is executed
_i is incremented by 2 => _i is now 2
Back to step 2

`forEach`-Loop

You will often use the forEach-loop to increment over arrays. It repeats the same code block for every item in an array.

{ STATEMENT; ... } forEach ARRAY;

The code block is executed exactly (count ARRAY) times.

You may use the magic variable _x within the code block, which always references to the current item of the array. Magic variable _foreachindex contains current index of the _x element in ARRAY.

Example:

private _array = [unit1, unit2, unit3];

{
    _x setDamage 1;
}
forEach _array;

Description:

In the first loop, the statement unit1 setDamage 1; is executed
In the second loop, the statement unit2 setDamage 1; is executed
In the third loop, the statement unit3 setDamage 1; is executed

Warning
Each iteration will be executed within one frame, even if it consists of multiple instructions. So be aware of large and/or complex code blocks!

Return Values

Control structures always return the last expression evaluated within the structure.

Example:

if (myCondition) then { myValueA; } else { myValueB; }; // returns myValueA or myValueB

Requirements

Conditional Structures

if-Statement

Alternative Code (else)

Conditional assignments

SQS syntax (deprecated)

Nested if-Statements

switch-Statement (Armed Assault v1.00)

default-Block

Variable Assignments

Loops

while-Loop

for-Loop (Armed Assault v1.00)

for-from-to-Loop

for-from-to-Loop with custom step

forEach-Loop

Return Values

See Also

`if`-Statement

Nested `if`-Statements

`switch`-Statement (Armed Assault v1.00)

`default`-Block

`while`-Loop

`for`-Loop (Armed Assault v1.00)

`for`-`from`-`to`-Loop

`for`-`from`-`to`-Loop with custom `step`

`forEach`-Loop