Scripting 101

DUE TO LENGTH, FORMATTING IS TAKING SOMETIME. I APOLOGIZE FOR ANY ERRORS. I WILL BE FIXING IT WITHIN THE NEXT WEEK OR SO.
Foundations of Scripting
This tutorial was made to help people new to the scripting community a grasp on basic concepts.
Please note that this will be subject to change as my knowledge base grows.
Also, if you see any errors or would like to contribute, feel free to send a PM.
My PM box is also open to any suggestions for other tutorials you would like for me to do.

Table of Contents
Basic Terms
Syntax
Variables
Data Types
Operators
Functions
Control Structures
Good Coding Practices
Basic Terms
Throughout this tutorial, I will be making references to various terms. In order to get you guys up to speed on the technical lingo, I ask that you know what each of the following mean and/or refer to.

Basic Terms

Script-When speaking about a script, we usually mean a .sqs or .sqf file. Both file types can be edited as a plain text file using a program like Notepad or Geany. I prefer notepad++ or Brackets.

Game Engine-The core program of the game which reads and executes your scripting commands at run time.

Function-A Piece of code which performs a specific task. A function may return a value. The mission author often writes complicated functions in .sqf files and then executes them in-game. Functions can be considered a kind of script. Usually, however, a "script" means a .sqs or .sqf file that runs over a period of time and directs gameplay, while a "function" is usually meant to run instantaneously and return a value.

Identifier-A name given to a variable that the scripter can choose: It is the name that identifies the variable.

Block-A block is a chunk of scripting code grouped together. A block is started and ended with curly braces { }. Blocks are either independent and executable with call or belong to a control structure.

Syntax
Every code has to follow a syntax. The syntax is the "grammar" of the scripting language. It makes sure that the game engine can read and understand the code.

Syntax

The primary syntax used in Armed Assault and ArmA 2 is SQF syntax. Read the corresponding article to inform yourself about the exact details. There are some crucial points which you must know about:
Every statement of SQF code except for the last one should end with a semicolon. Otherwise, the engine doesn't know when one statement ends and the next begins. In SQF, line breaks made with the ENTER key are only visible to the script writer. Spaces between lines are completely ignored by the engine.

There is an exception to this rule. When using commands such as |if () then {}, the final statement of code inside the parentheses and {} brackets can go without a semicolon. If this confuses you, just put a semicolon after all statements except for the last one.

Variables
Most if not all languages use variables. When creating scripts, variables are useful in “patching” detected code

Variables

What is a variable?

A variable or scalar is a storage location paired with an associated symbolic name (an identifier), which contains some known or unknown quantity or information referred to as a value. Since this variable is simply a storage location associated with a name, you can assign a variable basically any type of value.

Naming Variables

Variables can essentially have any name, with a few reserved strings such as the team names like west, east, or Civilian.

Using Variables

To use a variable, first it must be initialized. You can do this like so:

Code:

myVariable = 0;

Now, this variable has a value of 0. You can also initialize a variable to take a string value.

Code:

myVariable = “Hello World!”;

This variable has a string that says “Hello World!”, a common test value. Variables can also be assigned ‘nil’. ‘nil’ will essentially undefine and delete the variable, this is especially useful in projects with a large number of big variables.

Local and Global Variables

The previously initialized variables were global. Global variables are visible on the entire computer. Thus, it is good coding practice to make local variables. If I wanted to initialize “myVariable” locally, I would add an underscore before it.

Code:

_myVariable= 0;

Additionally, you can apply the “private” command to mark the variables as local.

Code:

 private “_myvariable”;
_myVariable = 0;

Note that if a local variable is initialized within a Control Structures (i.e. if, for, switch, while) its scope will stay within this structure (i.e. outside of the structure it will still be seen as undefined). This does not apply to global or public variables.

Code:

//Assume that the player is alive.
if (alive player) then {_living=true}; hint format["%1",_living];

This code would have an invalid output as variable “_living” was not previously initialized.

Code:

_dead=true; if (alive player) then {_dead=false}; hint format["%1",_dead];

This would properly return false since “_dead” was initialized before being used.

Functions and Variables

Variables can also be assigned to functions. This is especially useful when attempting to defeat anti-hacks. The reason behind this is that variables are easily changed and so when one gets blacklisted another can take its place.

Data Types
A data type refers to the type of content that can be assigned to a variable. Previously, we assigned our variables the Number and String data types. However, there are many more data types that exist within the Arma series.

Data Types

We have the:

Array

An array is a matrix of data. If you have taken an entry level algebra course in secondary school you should know what a matrix is. Arrays can contain any data type and is not restricted to only one. Additionally, an array can have more than one dimension. For example, this is a 1x3, uni-dimensional array. Using ”count” we find that there are two units in the array. Following that is a 2x4 multi-dimensional array.

Code:

//Single Dimension
_myVariable = ["Weapon1","Weapon2"];
_count = count _myVariable; // Output: 2

// Multi-Dimension
_multiArray1 = [["Item1",1,2,3],["Item2",4,5,6]];
_count = count _multiArray1; // Output: 2
_count = count _multiArray1 select 0; // Output: 4

Boolean

Booleans are a binary data type can be true or false.

Number

A standard number variable is an integer or floating point number.
The largest real positive number that can be entered via script is: 3.4028235e38
The largest real negative number that can be entered via script is: -3.4028235e38
Numbers larger or smaller than the above are represented as:
Positive infinity 1e39 = "1.#INF"
Negative infinity -1e39 = "-1.#INF"

Object

An object in the scripting language is a generic reference for a soldier, vehicle or building. Such an object can be animated (a house, a tank), can have ai associated with it (a soldier), or, simply be a 'Rock'. Various commands in the scripting language can refer as equally to generic (eg Object) types, as much as specific subtypes.

String

A string may consist of any number of ASCII characters.

Code:

_string = "here is my string"
_string2 = 'It may contain a lot of characters #@$'

Code

Code represents data consisting of commands and their parameters. Think a script within a script.

Script (Handle)

Script handle, used to identify scripts in script operations called using spawn or execVM.

Note that although more data types exist, most are used only when making custom missions, and thus not covered.
Operators

Operators

Operators are a very important part of scripting. Using operators, you can assign values, perform arithmetic, compare values, and execute logic functions.

Assigning Values
The most basic function of an operator is to assign a value to a variable.

Code:

 a = b

Arithmetic Operations
There are two types of arithmetic operations, unary and binary arithmetic operations. Arithmetic operations will always return a number.

Unary Arithmetic

Unary Arithmetic

Unary Arithmetic operators only use one input.

“-”

This operator will negate a value.

Code:

-a;

+-a;

-+a;

“+”

This operator will make a value positive. It is somewhat redundant.

Code:

+a;

“(“ and “)”

These operators used in conjunction form an expression.

Code:

(expression)

Binary Arithmetic

Binary arithmetic operators can use two inputs.

“+”

This operator adds.

Code:

a + b

“-”

This operator subtracts.

[CODE]a - b[CODE]

“*”

This operator multiplies.

[CODE]a*b[CODE]

“/”

This operator divides.

[CODE]a / b[CODE]

“%” or “mod”

These operators return the remainder of a / b.

Code:

a % b

a mod b

“^”

This operator raises a to the value of b.

Code:

a ^ b

The “+” and “-” operators can also be used with Strings and Arrays.

Logic Operators

What are logic operators?

Logic operations return a boolean. There are 8 types logic gates: buffers, NOT, AND, OR, NAND, NOR, XOR, XNOR. However, only 3 of them have usable operators(NOT, AND, OR). All others, with the exception of buffers which are redundant since input loss is not simulated, can be created using a combination of these three.

“!” and “not”

These operators return the inverse of input.

Code:

!a;

not a;

“&&” and “and”

These operators only return true if both inputs are true.

Code:

a && b;

a and b

“||” and “or”

These operators return true if one or both inputs are true.

Code:

a || b;

a or b;

Comparison Operators

Comparison operators compare two values and return a boolean, true if the comparison matches and false if not.

“==”

This operator compares whether or not inputs are equal.

[CODE]a == b;[CODE]

“!=”

This operator compares whether or not inputs are not equal.

Code:

a != b;

“<”

This operator compares whether or not input a is less than b.

Code:

a < b;

“>”

This operator compares whether or not input a is greater than b.

Code:

a > b;

“<=”

This operator compares whether or not input a is less than or equal to b.

Code:

a <= b;

“>=”

This operator compares whether or not input a is greater than or equal to b.

Code:

a >= b;

Usage of Operators

Operators are used heavily in functions and are a vital part of control structures, both of which will be explained in the next sections.

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.

Types of Control Structures

There are two types of control structures. They are conditional structures and loops.

Conditional Structures

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

“if -statements”

if- statements

if- statements define code that is only executed if a certain condition is met.

Code:

 if (condition) then {

STATEMENT;

…

};

CONDITION is a Boolean statement or variable that must return either true or false. The code that is nested in the if- statement is only executed if the condition is true, else it is ignored.

STATEMENT is a custom sequence of statements. This can include simple commands, variable assignments, and/or other control structures.

“if/else -statements”

if/else- statements

if/else- statements use the same rule of execution if a certain condition is met, but also implements alternative code that is set to execute whenever the condition is not true.

[CODE]if (condition) then {

STATEMENT;

…

} else {

STATEMENT;

…

};

If… then structures can also be used to assign conditional values to variables:

Code:

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

You can also nest an if- statement within another if- statement.

Code:

 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!";

};

This if- statement first checks if the player is alive. Then it uses a nested if- statement to check as to whether or not the player has ammo, providing output according to the conditions of the players ammo. However, if the player is dead, the statements within the first block of code is ignored and output returns “The player is dead!”.

“switch -statement”

switch- statement

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.

Code:

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:

Code:

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.

The previous block of code, but written using a switch statement.

Code:

switch (_color) do {

case "blue": {

hint "What a nice color";

};

case "red": {

hint "Don't you get aggressive?";

};

};

Looks much better right?

Default Blocks

Like the if- statement, the switch- statement can also have a block of code when none of the values matches. You can write this code in a default-Block. Note that there is no colon after the default tag!

Code:

switch (VARIABLE) do {

case VALUE1: {

STATEMENT;

...

};

case VALUE2: {

STATEMENT;

…

};

…

default {

STATEMENT;

…

};

};

Variable Assignments

Variable Assignment

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

Code:

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

Code:

while {CONDITION} do {

STATEMENT;

...

};

Note the curled braces for the condition. The loop processes as follow:

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. This differs from the for loop, which executes one or more times.

The following loop uses the local variable counter. Each time the block is executed the counter is incremented by plus 1. This will make the block run 10 times before stopping.

Code:

_counter = 0;

while {_counter < 10} do {

_counter = _counter + 1;

};

“for -Loop”

for -Loop

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

Code:

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.

Code:

// a loop repeating 10 times
for [{_i=0}, {_i<10}, {_i=_i+1}] do {

player globalChat format["%1",_i];
};

/*Will display

0

1

2

3

4

5

6

7

8

9

*/

This loop processes as follows:

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.
There are 2 variations of this loop, both of which can be found here:Click me!

Functions

A function is something defined in code which carries out an instruction or set of instructions and may or may not have inputs and outputs. The builtin functions which are provided by the various games themselves are referred to as commands, and are called in a different manner to functions which are defined within scripts.

Functions can also be used to reuse code. You can write some code once in the function and then include it in many different scripts. When the code is updated, it is updated for all scripts. When you only copy and paste the code to the other scripts, you have to update every script on any change.

Types of functions

Functions-as-files

Functions as files are functions stored within a file. These are usually used for larger and more complex functions. The code is evaluated in the same way, however, there are additional commands which must include the file before the function itself can be called.

Code:

//MyFile.sqf


// Code here..

Inline Functions

Inline functions are functions are technically code which is often stored within a variable or declared as a function parameter. Inline functions operate the same way as functions-as-files as both are evaluated in the same way, but the difference is that inline functions are stored within parentheses{}, whereas functions-as-files do not require these.

Code:

//InlineFunction as Variable

MyVariableName ={

// Code here..

};

// InlineFunction as command/function parameter

_myTemporaryVariable =player addEventHandler ["killed", { diag_log("I am providing an inline function (code) to this builtin command! Hurray for science!") }];

Anatomy of a Function

When scripting, there are two types of functions: functions-as-files and inline functions. Functions-as-files are instances where the a whole file itself is used to house a function, whereas inline functions are either contained within a variable or as a parameter of a function. Some built-in functions require functions-as-files, whereas most will support both.

Parameters

Parameters for functions are available to the function via the magic variable _this. There is no implicit declaration of function parameters in scripting, nor variable typing. Common practice for defining parameters is done via the use of private variables and defined variables.

Code:

//MyCode.sqf

private ["_parameterOne","_parameterTwo"];


_parameterOne = _this select 0;

_parameterTwo = _this select 1;

Code:

// Inline Function

MyInlineFunction ={

private ["_parameterOne","_parameterTwo"];


_parameterOne = _this select 0;

_parameterTwo = _this select 1;

};

Parameters passed to functions are passed before the function, rather than after (such as the mathematical or c-like syntax f(x)).

Code:

// Array variable as parameter

_myTempParams = [_parameterOne,_parameterTwo];

_myTempVariableTwo = _myTempParams call MyInlineFunction;

Code:

// Array as parameter

_myTempVariable = [_parameterOne,_parameterTwo] call MyInlineFunction;

Return Values

The value of the last executed statement in a function is returned to the calling instance.

Code:

my_fnc = {

    if (_this > 0) exitWith {

        _this + 1

    };

    _this - 1

};

Code:

hint str (5 call my_fnc); //6

hint str (-5 call my_fnc); //-6

In the first example "_this + 1" is the last executed statement in my_fnc, in the second example it is "_this - 1". Traditionally the returning statement is written without ";" after it. Have it or don't have it, it is up to you, doesn't make a difference:

Code:

my_fnc = {

    a = 1;

    b = 2;

    c = a + b;

    c //<- fine

};

Code:

my_fnc = {

    a = 1;

    b = 2;

    c = a + b;

    c; //<- also fine

};

More examples:

Code:

//MyCode.sqf

private ["_myName","_returnMe"];

_myName = _this select 0;


_returnMe = "FAIL";


if(_myName == "Test") then

{

_returnMe = "PASS";

};

_returnMe

Code:

// myCodeInline

MyCodeReturnValue ={

private ["_myName","_returnMe"];

_myName = _this select 0;

_returnMe = "FAIL";


if(_myName == "Kaboom") then

{

_returnMe = "PASS";

};


_returnMe


};


_myCalledVariable = ["Kaboom"] call MyCodeReturnValue; // "PASS"

_myCalledVariableFail = ["Blah"] call MyCodeReturnValue; // "FAIL"

Code:

//return.sqf

STATEMENT 1;

STATEMENT 2;

RETURN_VALUE

Code:

//test.sqf

value = call compile preprocessFile "return.sqf";

// value is now RETURN_VALUE


call compile preprocessFile "return.sqf";

// valid, but RETURN_VALUE is not saved anywhere

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 loaded as String from a file via preprocessFile or loadFile. They are then executed via the call or spawn command. Since Armed Assault the loaded String needs to be compiled in order to convert it to Code, which is required for call or spawn.

Call

Functions executed using call are run within the executing instance, which waits for the result of the function. Unlike 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.

Example:

Code:

myFunction1 = compile loadFile "myFunction1.sqf";

myFunction2 = compile preprocessFile "myFunction2.sqf";


_result1 = call myFunction1;

_result2 = [1, 2] call myFunction2;

Note: You can still use the special variables and commands of scripts in functions!

Spawn

Functions may also be executed using spawn, but then the function result is not accessible, making it behave more like a procedure. Spawned functions will run asynchronously or alongside the executing instance. This helps prevent large CPU intensive functions from seizing up the game.

Example:

Code:

myFunction1 = compile loadFile "myFunction1.sqf";

myFunction2 = compile preprocessFile "myFunction2.sqf";


_param spawn myFunction1;

[1, 2] spawn myFunction2;

Examples

Example 1: max.sqf

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

max.sqf

Code:

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}

alternative max.sqf (big boys code :))


(_this select 0) max (_this select 1)

executing script:


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

Code:

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:

Code:

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:

Code:

name player call FNC_sayhello

In case the function doesn't require any arguments you can just call the function.

Code:

call FNC_helloall

Good Coding Practices

There are many things you can do to make your code better. I highly recommend this powerpoint to try and improve your coding practices and formatting.

Credits to: Bohemia Interactive Studio: Community Wiki

FIN
Happy Hacking,
techfox3010

Scripting 101

Post a Reply

Similar Threads

Tags for this Thread