--- name: "Control Structures" type: topic source: https://community.bistudio.com/wiki/Control_Structures revid: 363911 updated: 2024-04-25T21:29:06Z --- # 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](../topics/Code.md) as an argument. The complex control structures like "[while](../commands/while.md) ... [do](../commands/do.md) ..." are implemented using helper types, like [While Type](../topics/While_Type.md).* ### Requirements To fully understand this article you should read the following articles: - Introduction to Arma Scripting - [Variables](../topics/Variables.md) - [Operators](../topics/Operators.md) ### 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](../commands/if.md) (CONDITION) [then](../commands/then.md) `// The round braces are optional` { STATEMENT; ... }; - `CONDITION` is a [Boolean](../topics/Boolean.md) statement or [variable](../topics/Variables.md) which returns either `true` or `false`. The code nested in the following [block](../topics/Code.md) 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:** ```sqf 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](../commands/else.md)) You can also define *alternative* code that is executed, when the condition is *not* `true`. [if](../commands/if.md) (CONDITION) [then](../commands/then.md) { STATEMENT1; ... } [else](../commands/else.md) { STATEMENT2; ... }; Another way of specifying an alternative code is done by feeding a 2-dimensional [Array](../topics/Array.md) of [Code](../topics/Code.md) into the [then](../commands/then.md) like this (but this alternative is CPU-heavier): [if](../commands/if.md) (CONDITION) [then](../commands/then.md) [{STATEMENT1; ...}, {STATEMENT2; ...}]; In fact the above syntax with the Array is the only possible syntax as [else](../commands/else.md) does nothing else than taking the code to its left and the one to its right and packs them both into an [Array](../topics/Array.md) of [Code](../topics/Code.md) which is then fed into the [then](../commands/then.md) operator. But using [else](../commands/else.md) 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: ```sqf _living = if (alive player) then { true } else { false }; ``` ##### SQS syntax (deprecated) > [!WARNING] > SQS Syntax is deprecated; [SQF Syntax](../topics/SQF_Syntax.md) should be used instead. Within SQS Syntax the use of [goto](../commands/goto.md) labels is a way to execute more than one statement within if...then structures. [if](../commands/if.md) (CONDITION) [then](../commands/then.md) { [goto](../commands/goto.md) "label" } ... some other statements #label statement1 statement2 statement3 **Example 1: (without [else](../commands/else.md))** ```sqs 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](../commands/else.md))** ```sqs 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:** ```sqf 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](../topics/Variables.md) for several values and execute different code depending on the value. With the above knowledge you could just write a sequence of `if`-statements. ```sqf 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](../commands/switch.md) (VARIABLE) [do](../commands/do.md) { [case](../commands/case.md) VALUE1: { STATEMENT; ... }; [case](../commands/case.md) 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:** ```sqf [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](../commands/switch.md) (VARIABLE) [do](../commands/do.md) { [case](../commands/case.md) VALUE1: { STATEMENT; ... }; [case](../commands/case.md) VALUE2: { STATEMENT; ... }; ... [default](../commands/default.md) `// No colon behind **default**` { STATEMENT; ... }; }; ##### Variable Assignments Switch can be used to assign different values to a variable: ```sqf private _color = switch (side player) do { case west: { "ColorGreen" }; case east: { "ColorRed" }; }; ``` ### Loops **Loops** are used to execute the same [code block](../topics/Code.md) for a specific or unspecific number of times. #### `while`-Loop This loop repeats the same code block as long as a given [Boolean](../topics/Boolean.md) condition is `true`. [while](../commands/while.md) {CONDITION} [do](../commands/do.md) `// Note the curly braces` { STATEMENT; ... }; **Description:** 1. `CONDITION` is evaluated. If it is `true`, go on to 2., else skip the block and go on with the code following the loop. 1. 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:** ```sqf 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](../commands/for.md) [{BEGIN}, {CONDITION}, {STEP}] [do](../commands/do.md) { STATEMENT; ... }; - `BEGIN` is a number of statements executed *before* the loop starts - `CONDITION` is a [Boolean](../topics/Boolean.md) condition evaluated *before* each loop - `STEP` is a number of statements executed *after* each loop The loop processes as follows: 1. `BEGIN` is executed 1. `CONDITION` is evaluated. If it is `true`, go on to 3., else skip the block and go on with the code following the loop. 1. The statements in the code block are executed 1. `STEP` is executed, go on to 2. If `CONDITION` is `false` from the beginning on, the code block will never be executed. **Example:** ```sqf 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:** 1. The variable `_i` is set to 0 1. The condition `_i < 10` is evaluated, which is `true` until `_i` surpasses 9. 1. The code `player globalChat _i;` is executed 1. 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](../commands/for.md) "VARNAME" [from](../commands/from.md) STARTVALUE [to](../commands/to.md) ENDVALUE [do](../commands/do.md) { STATEMENT; ... }; - `VARNAME` is any name given to the variable used to count the loop - `STARTVALUE` is a [Number](../topics/Number.md) value given to the counter variable before the loop starts - `ENDVALUE` is a [Number](../topics/Number.md) value until which the counter is incremented > [!IMPORTANT] > Note: Unless using a custom [step](../commands/step.md) as seen below, ENDVALUE must be greater than STARTVALUE for the loop to execute The loop processes as follows: 1. A variable with the name `VARNAME` is initialized with `STARTVALUE` 1. If `VARNAME` does not exceed `ENDVALUE`, the code block will be executed. 1. The variable `VARNAME` is incremented by 1 1. Go back to step 2 The following example is semantically equal to the last example. **Example:** ```sqf for "_i" from 0 to 9 do // a loop repeating 10 times { player globalChat format ["%1", _i]; }; ``` **Description:** 1. `_i` is set to 0 1. `player globalChat 0` is executed 1. `_i` is incremented by 1 => `_i` is now 1 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](../commands/for.md) "VARNAME" [from](../commands/from.md) STARTVALUE [to](../commands/to.md) ENDVALUE [step](../commands/step.md) STEP [do](../commands/do.md) { STATEMENT; ... }; - `STEP` is a [Number](../topics/Number.md) 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](../commands/step.md) value combined with a STARTVALUE that is greater than ENDVALUE The rest is equal to the above section. **Example:** ```sqf for "_i" from 0 to 9 step 2 do // a loop repeating 5 times { player globalChat format ["%1", _i]; }; ``` **Description:** 1. `_i` is set to 0 1. `player globalChat 0` is executed 1. `_i` is incremented by 2 => `_i` is now 2 1. Back to step 2 #### `forEach`-Loop You will often use the `forEach`-loop to increment over [arrays](../topics/Array.md). It repeats the same code block for every item in an array. { STATEMENT; ... } [forEach](../commands/forEach.md) ARRAY; The code block is executed exactly `(count ARRAY)` times. You may use the [magic variable](../topics/Magic_Variables.md) `_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:** ```sqf private _array = [unit1, unit2, unit3]; { _x setDamage 1; } forEach _array; ``` **Description:** 1. In the first loop, the statement `unit1 setDamage 1;` is executed 1. In the second loop, the statement `unit2 setDamage 1;` is executed 1. 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](../topics/Expression.md) evaluated** within the structure. **Example:** ```sqf if (myCondition) then { myValueA; } else { myValueB; }; // returns myValueA or myValueB ``` ### See Also - Command Group: Program Flow - Statement - [Expression](../topics/Expression.md) Source: [BI Community Wiki — Control Structures](https://community.bistudio.com/wiki/Control_Structures) (revision 363911).