Scripting Topics

Array assignment

Description

Assignment used on arrays only assigns a pointer to the same array to the target variable.
When b is an array, after executing a = b both a and b represent the same array.
When b is changed, a is changed as well.
One particular situation that can lead to this behaviour is:

aList = list sensor_name

You can force creation of a copy of the array by using unary operator + array.

General Barron

Wow. Never knew this before.
Glad I know it now.

But can someone explain how to use + array to me please?


Code strings

Description

Many languague constructs (including forEach, if, while) use the concept of "code strings".
Code is passed as a string to them and they interpret it as code if they wish.
Since version 1.85, string constants can be written in two ways:

Using double quotes (like "Hello") or
Curled braces (like {a=a+1}).

While both ways are currently equivalent and the string constant is created, we recommend the use of curled braces for code only, as this makes scripts easier to read - moreover future versions of scripting language may precompile code enclosed in curled braces.


Event based scripts

Description

There are some scripts in the game which are launched when some event occurs.
Some of them have names given by mission designer (scripted waypoint, particle scripts (since version 1.50), user action scripts).

Names of others are given by the program.

init.sqs - Launched when mission is started (before briefing screen).
- No arguments

initIntro.sqs - Launched when intro is started (since version 1.50).
- No arguments

exit.sqs - Launched when mission is finished (before debriefing screen, since version 1.50).
- Argument: end # - number of game end.

onFlare.sqs - Launched when illuminating shell is lit(since version 1.45).
- Arguments: [[r, g, b], gunner] - r, g, b is light color.

General Barron

There is also:

onPlayerKilled.sqs - Launched when the player is killed.
This script replaces the default death sequence.
Make sure you place the command enableEndDialog somewhere in your script, as this will then cause the dialog that allows you to load, retry, or quit to appear.


Event handlers

Description

Event handlers can be defined in unit config or by function addEventHandler.
Multiple handlers can be attached at one time.
Event handler types are defined below.
Each handler receives arguments in _this, argument types and meanings are defined below.

(1) Position can be "driver", "gunner", "commander" or "cargo".

MP notes

"Killed" and "Hit" eventhandlers are executed where given unit is local.
All other eventhandlers are executed on all computers.
Events added by addEventHandler may be different on each computer.


Functions - SQF

Description

While script syntax (see exec) is line based, functions (see call, then, do) are based on structured expressions and 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.

Note: Scripts can do some things that are not possible in functions.
Scripts can wait suspended until some condition is met, it can also use goto to change execution point at any time.

Main language contructs used in functions are:
if..then..else
while..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.


Example 1 (max.sqf)

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)

comment "Switch all infantry units to safe mode";
{
if (vehicle _x == _x) then
{
_x setBehaviour "safe"
}
} forEach _this

Due to line-based nature of 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).
Recommended file extension for functions is .SQF (as opposed to .SQS used for scripts).


Local variables

Description

A local variable is any variable which has a name that starts with an underscore.
All other variables are global.
Each of the commands then, do, while, forEach, count, exec and call defines a visibility scope for local variables.
All local variables from outer scopes are visible as well.
If assignment is made into a variable that does not exist in any visible scope, it is created in the innermost scope.
You can use function private or private to introduce variables at any given scope.


Script syntax

Description

Each script line may be one of the following:

Comment: Line starting with ';'.
Example: ;This is comment

Label: Line starting with '#'.
Example: #LabelName

Waiting for a condition: Line starting with '@'.
Example: @condition

Waiting for a time: Line starting with '&'.
Example: &endTime......is equivalent to @_time >= (endTime)

Delay: Line starting with '~'.
Example: ~delay......Is equivalent to __waitUntil = _time+(cas) ; &__waitUntil

Command: Any expression returning no value.
Example: _unit setBehaviour "safe"

Assignment: Assignment of any value to a variable.
Example: _a = 10

Conditional: ? condition......Command or assignment, command is executed only when condition is satisfied.
Example: ?_condVar > 10: _var = _var + 2


Note: Variable _time is reserved.
It is used to keep the time elapsed since script execution started.

Local variables can be used during script execution to avoid variable conflicts.
Local variable names start with an underscore ('_').
Variables starting with two underscores are reserved and should never be used.


Triggers

Description

Condition expression is used to determine when the trigger is activated.
Boolean variable this is set during evaluation of condition expression to primary sensor activation condition.
Array variable thisList is set to list of all vehicles that would satisfy primary sensor activation condition.
Condition must return a Boolean value.

On Activation and On Deactivation expressions define action that is peformed when trigger condition changes to true or false.
Expression must either be an assignment or return nothing (see type Nothing).
Variable denoting trigger can be created by filling in name field.


Variables

Description

Variables must be initialised before being used.

When any uninitialized variable is detected in any expression, the whole expression results in nil (undefined value).
When undefined value is encountered in field where boolean value is expected, it is converted to false.

Variable may be unitialised by assigning it nil value.
This effectively destroys variable as if it never existed.


Waypoints

Description

Condition expression is used to determine when the waypoint execution is terminated.
Boolean variable this is set during evaluation of condition expression to primary waypoint termination condition.
Array variable thisList is set to list of all units in the group that given waypoint is assigned to.
Condition must return Boolean value.

On Activation expression defines action that is peformed after the waypoint is terminated.
Expression must either be an assignment or return nothing (see type Nothing).

Search OFPEC COMREF