Scripting Topics
Index
Array assignment
Code strings
Event based scripts
Event handlers
Functions - SQF
Local variables
Script syntax
Triggers
Variables
Waypoints
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.
« To Menu
--------------------------------------------------------------------------------
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.
"Killed" Object: killer
"Hit" Object: causedBy, Scalar: howMuch
"Engine" Boolean: engineState
"GetIn" String: Position (1), Object: unit
"GetOut" String: Position (1), Object: unit
"Fired" String: weapon, String: muzzle, String: mode, String: ammo
"IncomingMissile" String: ammo, Object: whoFired
"Dammaged" String: selectionName, Scalar: howMuch
"Gear" Boolean: gearState
"Fuel" Boolean: fuelState
"Init" No arguments.
(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.
General Barron
Check here for more info on eventhandlers.
« To Menu
--------------------------------------------------------------------------------
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 to introduce variables at any given scope.
« To Menu
--------------------------------------------------------------------------------
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.
« To Menu
--------------------------------------------------------------------------------
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 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).
--------------------------------------------------------------------------------
« To Menu