Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "{{Link|:Category:" to "{{Link|Category:")
 
(89 intermediate revisions by 15 users not shown)
Line 1: Line 1:
{{Stub}}
{{TOC|side}}
Scripting is one of the most powerful and most versatile tools available in the Arma sandbox. Unfortunately, it is also one of the most complex and unforgiving aspects of addon (i.e. mod) and mission creation.


During [[ArmA: Mission Editing|mission editing]] and [[ArmA: Addon Editing|addon editing]] you may come across situations where actions or features you would like to have to have in your mission or addon cannot be accomplished using the basic (or even the more advanced) capabilities of the [[ArmA: Mission Editor|mission editor]] or within config files (in the case of addons). Some examples of this might be really cinematic cutscenes in missions or special animations for an addon.
All {{arma}} games from {{arma0}} to {{arma3}} use a scripting language called [[SQF Syntax|SQF]]. Its predecessor [[SQS Syntax|SQS]] has been considered deprecated since {{arma1}} (2006) and is no longer used.
As of {{armaR}} (2022), SQF has been succeeded by {{GameCategory|armaR|Modding|Guidelines|Scripting|text= Enforce Script}}. This document only considers SQF.




The '''solution''' to this is to take advantage of the game-engines ability to call on an even more advanced feature known as [[Scripting|scripting]]. [[Armed Assault|Armed Assault's]] '''scripting language''' gives you more direct control of core game commands. With any combination of these [[:Category:ArmA: Scripting Commands|scripting commands]] you can then create custom processes that meet the specific needs of your mission or addon.
== Scripting Topics ==


== Terms ==
There is a plethora of topics to learn about in the context of {{arma}} scripting (see the table below).
Fortunately, there is no need to acquire detailed knowledge about all of these things in order to get started with scripting.
To aid with prioritisation, this page provides three selections of topics, each relevant to beginner, intermediate and advanced scripters respectively.
{{Table/RVScripting}}


Before getting started, you should understand the meaning of some of these terms.


; Script
== Beginner Scripting ==
: When speaking about a [[Script (File)|script]], it is generally considered a '''.sqs''' file, the same can be said for [[Function|functions]], since functions are a kind of script as well, the file ends with a '''.sqf'''. Both file types can be edited as a plain '''text''' file.


; Game Engine
{{Wiki|TODO|
: The core program of the game which reads and executes your scripting commands at run time.
* Using existing functions
}}
 
=== Variables ===
 
[[Variables]] are a fundamental building block of scripting (and programming in general). Like in mathematics, they serve as placeholders for values. A few examples:
* <sqf inline>A = 1;</sqf> The variable <var>A</var> now has the value 1.
* <sqf inline>B = 2;</sqf> The variable <var>B</var> now has the value 2.
* <sqf inline>C = "Hello World!";</sqf> The variable <var>C</var> now has the value "Hello World!".
A variable always has a [[Data Types|Data Type]]. In the example above, the variables <var>A</var> and <var>B</var> both have the data type [[Number]], while <var>C</var> has the data type [[String]]. The data type of a variable is not fixed and changes automatically based on the current value of the variable.
 
=== Commands and Operators ===
 
Two other basic tools of scripting are commands and [[Operators]]. In fact, they are so basic that the examples in the {{Link|#Variables}} section above already had to make use of an operator: The equals sign (<sqf inline>=</sqf>) serves as the assignment operator, assigning values to variables. Similarly, symbols such as <sqf inline>+</sqf>, <sqf inline>-</sqf>, <sqf inline>*</sqf> and <sqf inline>/</sqf> are also operators. Using operators is quite simple:
<sqf>
A = 1.5;
B = -2 * A;
C = A + B + 3.5; // Result: C is 2
</sqf>
Commands are often more versatile and complex than operators and can sometimes be used to interact with the game in some way. For instance, the [[setPosATL]] command can be used to change the position of an object in the game world, the [[damage]] command returns the amount of damage an object has suffered and the [[systemChat]] command can be used to display a message in the system chat.
 
While operators are usually fairly intuitive to use, commands are often more complicated. As such, every single command (and every single operator) has a dedicated [[Main Page|Community Wiki]] page documenting it. This makes the Community Wiki an essential resource for scripting as it can be consulted whenever an unfamiliar command is encountered or needs to be used. The documentation commonly includes information about the behaviour and effect of the command, its return value and the purpose and data types of its parameters.
 
{{Feature|informative|Commands List can be found here: [[:Category:Scripting Commands|Scripting Commands]].}}
 
=== Control Structures, Conditions and Booleans ===
 
[[Control Structures]] allow scripts to accomplish complex tasks. See the following:
<sqf>
if (damage player > 0.5) then
{
player setDamage 0;
systemChat "The player has been healed.";
}
else
{
systemChat "The player is fine.";
};
</sqf>
This code behaves differently depending on the damage status of the player. The [[systemChat]] output and whether or not the player is healed changes dynamically based on how much health the player has when the code is executed.
 
==== Conditions ====
In the example above, the condition is <sqf inline>damage player > 0.5</sqf>. Like all conditions, it results in a [[Boolean]] value when evaluated:
# First, <sqf inline>damage player</sqf> is evaluated and returns a number.
# Then, the <sqf inline>></sqf> operator compares that number to 0.5:
#* If the number is greater than 0.5, the <sqf inline>></sqf> operator returns [[true]].
#* If the number is less than or equal to 0.5, the <sqf inline>></sqf> operator returns [[false]].
 
==== Booleans ====
The data type [[Boolean]] only has two possible values: [[true]] and [[false]].
 
===== Boolean Operations =====
There are three basic operations that can be performed on Boolean values:
 
{| class="wikitable align-center-col-3 align-center-col-4" style="margin: auto"
|-
! Operation !! Description !! SQF Operator !! SQF Command
|-
| NOT (Negation) || Inverts the input value. || <sqf inline>!</sqf> || [[not]]
|-
| AND (Conjunction) || Combines two Booleans into one. Only returns [[true]] if both input values are [[true]]. || <sqf inline>&&</sqf> || [[and]]
|-
| OR (Disjunction) || Combines two Booleans into one. Returns [[true]] if at least one of the input values is [[true]]. || <sqf inline>||</sqf> || [[or]]
|}
 
Both the input and the output of these operations are Boolean values. Their behaviour is defined as follows:
 
{| class="align-center valign-top" style="margin: auto"
|
 
{| class="wikitable align-center"
! colspan="2" style="font-size: 1.25em" | NOT
|-
! Expression !! Result
|-
| <sqf inline>!true</sqf> || [[false]]
|-
| <sqf inline>!false</sqf> || [[true]]
|}
 
|
 
{| class="wikitable align-center"
! colspan="2" style="font-size: 1.25em" | AND
|-
! Expression !! Result
|-
| <sqf inline>true && true</sqf> || [[true]]
|-
| <sqf inline>true && false</sqf> || [[false]]
|-
| <sqf inline>false && true</sqf> || [[false]]
|-
| <sqf inline>false && false</sqf> || [[false]]
|}


== When Do I Need Scripting? ==
|


'''Be careful:''' Scripting isn't a solution to everything.
{| class="wikitable align-center"
! colspan="2" style="font-size: 1.25em" | OR
|-
! Expression !! Result
|-
| <sqf inline>true || true</sqf> || [[true]]
|-
| <sqf inline>true || false</sqf> || [[true]]
|-
| <sqf inline>false || true</sqf> || [[true]]
|-
| <sqf inline>false || false</sqf> || [[false]]
|}


|}


The first thing to ask yourself is "Am I absolutely, positively sure this cannot be done using just the editor?" The goal with scripting is to create processes that can't be done otherwise. Scripting does use system resources, poorly written scripts can effect game play and/or performance. So, it pays to be sure you have learned as much as you can about how the editor works and you understand its capabilities and limitations.
==== Complex Conditions ====
Boolean operations can be used to create complex conditions by combining multiple conditions into one.
<sqf>
if ((alive VIP_1 && triggerActivated VIP_1_Task_Complete) || (alive VIP_2 && triggerActivated VIP_2_Task_Complete)) then
{
systemChat "At least one VIP has been rescued.";
};
</sqf>


The second thing to ask before you start scripting away is "Will players even notice and/or use the action or feature I would like to implement?". It may seem silly, but just because it can be done does not always mean it should be.  
{{Feature|informative|Beginners sometimes write conditions such as <sqf inline>if (Condition == true)</sqf> or <sqf inline>if (Condition == false)</sqf>.<br>
While doing so is not a real error, it is unnecessary because [[Control Structures]] (and [[Trigger]]s) always implicitly compare the condition to [[true]].<br>
The correct (as in faster, more common and more readable) way to write such conditions is <sqf inline>if (Condition)</sqf> and <sqf inline>if (!Condition)</sqf> respectively.
}}


The third step (and after the first two are out of the way just may be the hardest step, especially for people new to scripting)is to try and determine if what you want to do can be implemented with the scripting language.
=== Arrays ===


If you aren't sure even after working out the preliminaries - just ask in the [http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi official forums]or at [http://www.ofpec.com OFPEC](these would also be good places to ask other players for their feedback on question number two (and if they bite you've got some possible beta testers on the hook!).
An [[Array]] is a [[:Category:Data Types|Data Type]] that can be seen as a list of items. This list can hold none to multiple elements of different types:
<sqf>
[] // an empty array
[true] // an array of 1 element (Boolean)
[0, 10, 20, 30, 40, 50] // an array of 6 elements of Number type
["John Doe", 32, true] // an array of 3 elements of different types (String, Number, Boolean)
</sqf>
An array is a useful way to keep data together and is used for example to store positions.


==== Positions ====
[[Position]]s are represented as 2D or 3D [[Array]]s of [[Number]]s (usually in the format <sqf inline>[X, Y]</sqf> or <sqf inline>[X, Y, Z]</sqf>) where X represents West-East, Y represents South-North and Z represents altitude.
However, there are some important caveats and distinctions one should be aware of - for instance, the positions <sqf inline>[0, 0, 0]</sqf> ASL ('''A'''bove '''S'''ea '''L'''evel) and <sqf inline>[0, 0, 0]</sqf> AGL ('''A'''bove '''G'''round '''L'''evel) are not necessarily equivalent.
It is therefore highly recommended to read the [[Position]]s page before working with positions.


=== Script Files ===


=== Checklist ===
Scripts are usually placed in [[Script File]]s. It is of course possible and sometimes even necessary to use short pieces of code in the Editor (e.g. in the ''On Activation'' expression of a [[Trigger]]), but scripts can become long and complex, and then working with them is far easier when they are properly placed in script files. Additionally, some features are only accessible through the use of script files ([[Event Scripts]] for example).


In summary:
Script files are basically just text files with a certain filename extension. For script files, that file extension is {{hl|.sqf}} (or {{hl|.sqs}}), but in the broader context of Arma scripting, modification, configuration and mission design, more file extensions can be encountered: {{hl|.ext}}, {{hl|.hpp}}, {{hl|.cpp}} and {{hl|.cfg}} to mention the most common ones.


# Can I do it with the ([[ArmA: Mission Editor|mission editor]], [[ArmA: Addon Configuration|addon ]] config files etc.).
==== File Creation ====
# Will players notice and/or use it?
Unfortunately, Windows does not make the creation of blank files with a desired file extension easily accessible.
# Is it possible?


If all of the three points are answered with "Yes", go on and script it! But be warned: It won't always be easy. ;-)
For instance, a common pitfall when trying to use [[Description.ext]] (a file that is used to configure certain mission features such as the respawn settings) for the first time is (unknowingly) creating {{hl|Description.ext.txt}} instead of {{hl|Description.ext}} because the Windows File Explorer hides file extensions by default.
Obviously, {{hl|Description.ext.txt}} will not work and will not have any of the desired effects on the mission because the game does not recognize it as {{hl|Description.ext}}, but identifying a wrong file extension as the root cause of an issue when troubleshooting is notoriously difficult as one is usually looking for errors in the code and not in the filename.


== Scripting Code ==
While there are many different ways to create a blank text file with a specific file extension, the easiest method using native Windows tools is probably this:
* Preparation (only needs to be done once):
# Open the File Explorer
# Open the ''View'' tab at the top
# Tick the ''File name extensions'' checkbox
* File Creation:
# Navigate to the location where you want to create a new script file
# Right-click
# Go to ''New''
# Click on ''Text Document''
# Rename {{hl|New Text Document.txt}} to what you need


The core of scripting is '''scripting code'''. The code consists of [[:Category:ArmA: Scripting Commands|scripting commands]] that tell the game engine what to do. These commands are executed one after another.
{{Feature|informative|It is also possible to bypass Notepad's automatic addition of the {{hl|.txt}} extension by wrapping the file name in quote, e.g {{hl|"description.ext"}}.}}


The code is written into special fields of the [[ArmA: Mission Editor|mission editor]] (see below) or into separate files that are executed at some defined point (f.i. through [[Triggers|triggers]]) during the running mission.
==== File Locations ====
In the context of mission creation, script files generally need to be placed in the corresponding ''scenario folder'' (often also called the ''mission root folder''). Every mission has its own scenario folder, it is created by the Editor when saving the scenario for the first time.
By default it only contains a single file called [[Mission.sqm|{{hl|mission.sqm}}]]; this file mostly stores data regarding Editor-placed entities and does not need to be touched when scripting.


=== Syntax ===
[[Description.ext]] and [[Event Scripts]] have to be placed directly in the root of the scenario folder (i.e. next to {{hl|mission.sqm}}), but all other files can be placed in subfolders of the scenario folder.
A well-structured scenario folder could look like this:


Every code has to follow a '''syntax'''. The syntax makes sure that the ''game engine'' can read and understand the code.
{{Color|green|Apex%20Protocol.Tanoa}}/
{{Color|lightgrey|├──}} functions/
{{Color|lightgrey|│  ├──}} fn_myFirstFunction.sqf
{{Color|lightgrey|│  └──}} fn_mySecondFunction.sqf
{{Color|lightgrey|├──}} scripts/
{{Color|lightgrey|│  ├──}} myFirstScript.sqf
{{Color|lightgrey|│  └──}} mySecondScript.sqf
{{Color|lightgrey|├──}} description.ext
{{Color|lightgrey|├──}} initPlayerLocal.sqf
{{Color|lightgrey|├──}} initServer.sqf
{{Color|lightgrey|└──}} mission.sqm


The primary syntax used in [[Armed Assault]] is [[SQF syntax]]. Read the corresponding article to inform yourself about it.
Each scenario folder is stored in either the {{hl|missions}} or the {{hl|mpmissions}} subfolder of the folder containing the [[Profile|Arma Profile]] that was used to create the scenario.
For instance, the path to the scenario folder from the example above could be:
C:\Users\Scott Miller\Documents\Arma 3 - Other Profiles\Keystone\missions\{{Color|green|Apex%20Protocol.Tanoa}}
The Editor uses {{Link|https://en.wikipedia.org/wiki/Percent-encoding|percent-encoding}} for scenario folder names, that is why whitespaces in the scenario name are replaced with {{hl|%20}}.


At some point you may also find scripts written in the deprecated [[SQS syntax]]. This syntax was the primary syntax in [[Operation Flashpoint]], but is considered deprecated since Armed Assault.
{{Feature|informative|
The [[:Category:Eden Editor|Eden Editor]] provides a useful shortcut to quickly open a mission's scenario folder in the Windows File Explorer:
With the mission open in the Editor, go to ''Scenario'' in the top left and then click on ''Open Scenario Folder''.
}}


All scripting pages about Armed Assault will focus on [[SQF syntax]].
'''See Also:'''
* [[2D Editor: External]]
* [[Eden Editor: Scenario Folder]]
* [[Profile]] (the possible profile folder paths are listed there)


=== Layout ===
==== Editing Script Files ====
Because script files are essentially plain text files, they can be edited with just about any text editor. For instance, the native Windows Notepad can be used, but working with it is not very comfortable. As such, regular scripters typically use more versatile applications such as {{Link|https://notepad-plus-plus.org|Notepad++}} or {{Link|https://code.visualstudio.com|Visual Studio Code}}, usually in combination with plugins that add additional support for SQF. One feature commonly provided by these plugins is ''syntax highlighting'', and for good reason: Syntax highlighting makes code significantly more readable and helps recognizing and avoiding basic syntax errors. Consequently, it is highly recommended to use syntax highlighting.


Code should be written in a specific '''layout'''. Complementary to the syntax, the layout assures that ''you and other coders'' can easily read the code. This is especially important when you haven't looked at your code for a long time and want to improve or change this code.
See [[:Category:Community Tools#Code Edition|Community Tools - Code Edition]] for a selection of community-made applications and plugins for Arma Scripting.


* There should be '''only one [[Statement|statement]] per line''' in [[Script (File)|scripts]]. This doesn't concern script lines in the mission editor, since there all the code has to be written within a single line.
==== Script Execution ====
* Use '''spaces or tabs''' to indent code in [[Block|blocks]]. This way you can easily tell to which block some code belongs.
The [[execVM]] command is used to execute script files.


Example:
For instance, {{hl|myFirstScript.sqf}} from the {{Link|#File Locations}} example above can simply be executed like so:
<sqf>execVM "scripts\myFirstScript.sqf";</sqf>
This can be done anywhere: Within another script, from the [[Arma 3: Debug Console|Debug Console]], in the ''On Activation'' or ''On Deactivation'' expression of a [[Trigger]] or in the init field of an [[Eden Editor: Object|Object]] in the Editor.


Statement 1;
Block
{
    Statement 2;
    Nested block
    {
        Statement 3;
        Statement 4;
    };
};


=== Comments ===
== Intermediate Scripting ==


You can and should write comments into your [[Script (File)|scripts]] that describe the purpose of your code. These comments are written in free text and completely ignored by the game engine.
{{Wiki|TODO|
* [[:Category:Functions|Functions]]
* [[Namespace]]s, {{Link|Variables#Scopes|Scopes}}
* {{Link|Category:Event Handlers|Event Handlers}}
* [[HashMap]]s
}}


Check out [[SQF syntax]] for information about the notation of comments.


'''Important:''' Don't write down what the code does, but rather what ''you'' want to do with the code. This is not as easy, but maybe the following example explains it a bit better:
== Advanced Scripting ==


Bad comment:
{{Wiki|TODO|
* [[Multiplayer Scripting]]
* [[GUI Tutorial|GUIs]]
* [[Code Optimisation]]
* [[Debugging Techniques]]
}}


// the variable i gets the value 1
i = 1;


Good comment:
== Miscellaneous ==


// reset the counter to start with 1 again
{{Feature|informative|This section contains content from an old version of this page which is due to be updated.}}
i = 1;


== Code Execution ==


how can I execute code? (external files vs. mission editor)
== Before anything ==<!-- "General Considerations" perhaps? -->


=== Mission Editor ===
; Is your idea necessary?
: Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!


how to execute code in the editor, listing of mission editor fields to start scripts
; Is it possible to do this in the editor?
: The [[:Category:Eden Editor|Eden Editor]] is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.
: Poorly written scripts are a frequent cause of poor performance, both in singleplayer and multiplayer scenarios.


=== External Files ===
; Can it be scripted using SQF?
: This question might be hard to answer. Try to get as much information about what you want to do and what [[:Category: Scripting Commands|commands]] and [[:Category: Functions|functions]] there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.


how to execute code in external files, scripts & functions
{{Feature|informative|Scripting is <u>not</u> the solution for everything!}}


== Developing a Script ==
=== Terms ===


script in this case: code in external files (scripts/functions). how to develop a script?
The following is a collection of terms frequently encountered when talking or reading about scripting.


* Requirements
; Game Engine
* Concept
: The core program of the game which executes your scripting commands at run time.
* Implementation
* Test


usually in your head, for complex scripts on paper and drafts
; Script / Script File
: Scripts are usually placed in [[Script File|script files]]. Script files contain code.


=== Requirements ===
; Syntax <!-- TODO: Explanation -->
: See [[SQF Syntax]] ({{arma}}, {{arma2}}, {{arma3}}).
: See [[SQS Syntax]] ({{ofp}}, {{arma}}).


what shall the script do?
; Variables
: A [[Variables|Variable]] is a named storage container for data.
: The name of a variable is called its [[Identifier]].


=== Concept ===
; Data Types
: The [[:Category: Data Types|Data Type]] of a variable specifies which kind of data that variable can contain.


How shall the script do it?
; Operators <!-- TODO: Explanation -->
: See [[Operators]]


=== Implementation ===
; Control Structures <!-- TODO: Explanation -->
: See [[Control Structures]]


Writing the code
; Functions <!-- TODO: Explanation -->
: See [[Function]]


=== Test ===
=== Must-Read Articles ===


Testing the code
==== Best Practices ====<!-- Bad section title, should be changed -->
See [[Code Best Practices]]


== Further Reading ==
==== Debugging ====
* [[Debugging Techniques]]
* [[:Category:Community_Tools#Debug_Console.2FSystem|Community Tools - Debug Console/System]]


If you want to learn more about [[Scripting]], read the following articles:
==== Optimisation ====
* [[Code Optimisation]]
* [[Mission Optimisation]]


* [[Variables]]
=== Useful Links ===
* [[Data Types]]
 
* [[Operators]]
These pages cover further aspects of scripting:
* [[:Category:Example Code|Example Code]]
* [[Control Structures]]
* [[Control Structures]]
* [[Exception Handling]]
* [[Multiplayer Scripting]]
* [[Exception handling]]
* [[Script File]]
* [[Function]]
* [[SQS to SQF conversion]]


== See also ==
Consider the following resources for more general learning:
* [[6thSense.eu/EG|6thSense.eu Editing Guide]]
* {{Link|link= https://www.armaholic.com/page.php?id=20465|text= Fockers Arma 3 Scripting Guide}}
* {{Link|link= https://www.armaholic.com/page.php?id=4847|text= Mr-Murray's Armed Assault Editing Guide - Deluxe Edition}}
* {{Link|https://youtu.be/WmEBN-RbK44|Excellent German SQF tutorial (YouTube)}}


* [[Script (File)]]
* [[Function]]
* [[SQF syntax]]


[[Category: Scripting Topics|Introduction to Scripting]]
[[Category:Arma Scripting Tutorials]]

Latest revision as of 14:51, 16 October 2024

Scripting is one of the most powerful and most versatile tools available in the Arma sandbox. Unfortunately, it is also one of the most complex and unforgiving aspects of addon (i.e. mod) and mission creation.

All Arma games from Arma: Cold War Assault to Arma 3 use a scripting language called SQF. Its predecessor SQS has been considered deprecated since Armed Assault (2006) and is no longer used. As of Arma Reforger (2022), SQF has been succeeded by Enforce Script. This document only considers SQF.


Scripting Topics

There is a plethora of topics to learn about in the context of Arma scripting (see the table below). Fortunately, there is no need to acquire detailed knowledge about all of these things in order to get started with scripting. To aid with prioritisation, this page provides three selections of topics, each relevant to beginner, intermediate and advanced scripters respectively.

Real Virtuality Scripting
Terminology ArgumentIdentifierExpressionOperandOperatorsParameterStatementVariablesMagic VariablesFunction
Syntax SQF SyntaxSQS SyntaxOrder of PrecedenceControl Structures
Tutorials Introduction to Arma ScriptingCode Best PracticesExample CodeCode OptimisationMission OptimisationMultiplayer ScriptingSQS → SQF
Data Types General ArrayBooleanCodeConfigControlDiary RecordDisplayEden EntityEden IDEditor ObjectGroupHashMapLocationNamespaceNumberObjectScript Handle
SideStringStructured TextTaskTeamTeam MemberNaNAnythingNothingVoidSwitch TypeWhile TypeWith TypeFor TypeIf Type
Special Arrays Array of Eden EntitiesColorDateParticleArrayPositionUnit Loadout ArrayVector3DWaypoint
Scripting Commands Scripting CommandsScripting Commands by Functionality
Scripting Functions Scripting FunctionsFunctions by Functionality
Debugging Common Scripting ErrorsDebugging TechniquesException handling
Advanced Event ScriptsEvent HandlersPreProcessor CommandsInitialisation OrderPerformance Profiling


Beginner Scripting

🚧
TODO:
  • Using existing functions

Variables

Variables are a fundamental building block of scripting (and programming in general). Like in mathematics, they serve as placeholders for values. A few examples:

  • A = 1; The variable A now has the value 1.
  • B = 2; The variable B now has the value 2.
  • C = "Hello World!"; The variable C now has the value "Hello World!".

A variable always has a Data Type. In the example above, the variables A and B both have the data type Number, while C has the data type String. The data type of a variable is not fixed and changes automatically based on the current value of the variable.

Commands and Operators

Two other basic tools of scripting are commands and Operators. In fact, they are so basic that the examples in the Variables section above already had to make use of an operator: The equals sign (=) serves as the assignment operator, assigning values to variables. Similarly, symbols such as +, -, * and / are also operators. Using operators is quite simple:

A = 1.5; B = -2 * A; C = A + B + 3.5; // Result: C is 2

Commands are often more versatile and complex than operators and can sometimes be used to interact with the game in some way. For instance, the setPosATL command can be used to change the position of an object in the game world, the damage command returns the amount of damage an object has suffered and the systemChat command can be used to display a message in the system chat.

While operators are usually fairly intuitive to use, commands are often more complicated. As such, every single command (and every single operator) has a dedicated Community Wiki page documenting it. This makes the Community Wiki an essential resource for scripting as it can be consulted whenever an unfamiliar command is encountered or needs to be used. The documentation commonly includes information about the behaviour and effect of the command, its return value and the purpose and data types of its parameters.

Commands List can be found here: Scripting Commands.

Control Structures, Conditions and Booleans

Control Structures allow scripts to accomplish complex tasks. See the following:

if (damage player > 0.5) then { player setDamage 0; systemChat "The player has been healed."; } else { systemChat "The player is fine."; };

This code behaves differently depending on the damage status of the player. The systemChat output and whether or not the player is healed changes dynamically based on how much health the player has when the code is executed.

Conditions

In the example above, the condition is damage player > 0.5. Like all conditions, it results in a Boolean value when evaluated:

  1. First, damage player is evaluated and returns a number.
  2. Then, the > operator compares that number to 0.5:
    • If the number is greater than 0.5, the > operator returns true.
    • If the number is less than or equal to 0.5, the > operator returns false.

Booleans

The data type Boolean only has two possible values: true and false.

Boolean Operations

There are three basic operations that can be performed on Boolean values:

Operation Description SQF Operator SQF Command
NOT (Negation) Inverts the input value. ! not
AND (Conjunction) Combines two Booleans into one. Only returns true if both input values are true. && and
OR (Disjunction) Combines two Booleans into one. Returns true if at least one of the input values is true. || or

Both the input and the output of these operations are Boolean values. Their behaviour is defined as follows:

NOT
Expression Result
!true false
!false true
AND
Expression Result
true && true true
true && false false
false && true false
false && false false
OR
Expression Result
true || true true
true || false true
false || true true
false || false false

Complex Conditions

Boolean operations can be used to create complex conditions by combining multiple conditions into one.

if ((alive VIP_1 && triggerActivated VIP_1_Task_Complete) || (alive VIP_2 && triggerActivated VIP_2_Task_Complete)) then { systemChat "At least one VIP has been rescued."; };

Beginners sometimes write conditions such as if (Condition == true) or if (Condition == false).

While doing so is not a real error, it is unnecessary because Control Structures (and Triggers) always implicitly compare the condition to true.

The correct (as in faster, more common and more readable) way to write such conditions is if (Condition) and if (!Condition) respectively.

Arrays

An Array is a Data Type that can be seen as a list of items. This list can hold none to multiple elements of different types:

[] // an empty array [true] // an array of 1 element (Boolean) [0, 10, 20, 30, 40, 50] // an array of 6 elements of Number type ["John Doe", 32, true] // an array of 3 elements of different types (String, Number, Boolean)

An array is a useful way to keep data together and is used for example to store positions.

Positions

Positions are represented as 2D or 3D Arrays of Numbers (usually in the format [X, Y] or [X, Y, Z]) where X represents West-East, Y represents South-North and Z represents altitude. However, there are some important caveats and distinctions one should be aware of - for instance, the positions [0, 0, 0] ASL (Above Sea Level) and [0, 0, 0] AGL (Above Ground Level) are not necessarily equivalent. It is therefore highly recommended to read the Positions page before working with positions.

Script Files

Scripts are usually placed in Script Files. It is of course possible and sometimes even necessary to use short pieces of code in the Editor (e.g. in the On Activation expression of a Trigger), but scripts can become long and complex, and then working with them is far easier when they are properly placed in script files. Additionally, some features are only accessible through the use of script files (Event Scripts for example).

Script files are basically just text files with a certain filename extension. For script files, that file extension is .sqf (or .sqs), but in the broader context of Arma scripting, modification, configuration and mission design, more file extensions can be encountered: .ext, .hpp, .cpp and .cfg to mention the most common ones.

File Creation

Unfortunately, Windows does not make the creation of blank files with a desired file extension easily accessible.

For instance, a common pitfall when trying to use Description.ext (a file that is used to configure certain mission features such as the respawn settings) for the first time is (unknowingly) creating Description.ext.txt instead of Description.ext because the Windows File Explorer hides file extensions by default. Obviously, Description.ext.txt will not work and will not have any of the desired effects on the mission because the game does not recognize it as Description.ext, but identifying a wrong file extension as the root cause of an issue when troubleshooting is notoriously difficult as one is usually looking for errors in the code and not in the filename.

While there are many different ways to create a blank text file with a specific file extension, the easiest method using native Windows tools is probably this:

  • Preparation (only needs to be done once):
  1. Open the File Explorer
  2. Open the View tab at the top
  3. Tick the File name extensions checkbox
  • File Creation:
  1. Navigate to the location where you want to create a new script file
  2. Right-click
  3. Go to New
  4. Click on Text Document
  5. Rename New Text Document.txt to what you need
It is also possible to bypass Notepad's automatic addition of the .txt extension by wrapping the file name in quote, e.g "description.ext".

File Locations

In the context of mission creation, script files generally need to be placed in the corresponding scenario folder (often also called the mission root folder). Every mission has its own scenario folder, it is created by the Editor when saving the scenario for the first time. By default it only contains a single file called mission.sqm; this file mostly stores data regarding Editor-placed entities and does not need to be touched when scripting.

Description.ext and Event Scripts have to be placed directly in the root of the scenario folder (i.e. next to mission.sqm), but all other files can be placed in subfolders of the scenario folder. A well-structured scenario folder could look like this:

Apex%20Protocol.Tanoa/
├── functions/
│   ├── fn_myFirstFunction.sqf
│   └── fn_mySecondFunction.sqf
├── scripts/
│   ├── myFirstScript.sqf
│   └── mySecondScript.sqf
├── description.ext
├── initPlayerLocal.sqf
├── initServer.sqf
└── mission.sqm

Each scenario folder is stored in either the missions or the mpmissions subfolder of the folder containing the Arma Profile that was used to create the scenario. For instance, the path to the scenario folder from the example above could be:

C:\Users\Scott Miller\Documents\Arma 3 - Other Profiles\Keystone\missions\Apex%20Protocol.Tanoa

The Editor uses percent-encoding for scenario folder names, that is why whitespaces in the scenario name are replaced with %20.

The Eden Editor provides a useful shortcut to quickly open a mission's scenario folder in the Windows File Explorer: With the mission open in the Editor, go to Scenario in the top left and then click on Open Scenario Folder.

See Also:

Editing Script Files

Because script files are essentially plain text files, they can be edited with just about any text editor. For instance, the native Windows Notepad can be used, but working with it is not very comfortable. As such, regular scripters typically use more versatile applications such as Notepad++ or Visual Studio Code, usually in combination with plugins that add additional support for SQF. One feature commonly provided by these plugins is syntax highlighting, and for good reason: Syntax highlighting makes code significantly more readable and helps recognizing and avoiding basic syntax errors. Consequently, it is highly recommended to use syntax highlighting.

See Community Tools - Code Edition for a selection of community-made applications and plugins for Arma Scripting.

Script Execution

The execVM command is used to execute script files.

For instance, myFirstScript.sqf from the File Locations example above can simply be executed like so:

execVM "scripts\myFirstScript.sqf";

This can be done anywhere: Within another script, from the Debug Console, in the On Activation or On Deactivation expression of a Trigger or in the init field of an Object in the Editor.


Intermediate Scripting


Advanced Scripting


Miscellaneous

This section contains content from an old version of this page which is due to be updated.


Before anything

Is your idea necessary?
Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!
Is it possible to do this in the editor?
The Eden Editor is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.
Poorly written scripts are a frequent cause of poor performance, both in singleplayer and multiplayer scenarios.
Can it be scripted using SQF?
This question might be hard to answer. Try to get as much information about what you want to do and what commands and functions there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.
Scripting is not the solution for everything!

Terms

The following is a collection of terms frequently encountered when talking or reading about scripting.

Game Engine
The core program of the game which executes your scripting commands at run time.
Script / Script File
Scripts are usually placed in script files. Script files contain code.
Syntax
See SQF Syntax (Arma, Arma 2, Arma 3).
See SQS Syntax (Operation Flashpoint, Arma).
Variables
A Variable is a named storage container for data.
The name of a variable is called its Identifier.
Data Types
The Data Type of a variable specifies which kind of data that variable can contain.
Operators
See Operators
Control Structures
See Control Structures
Functions
See Function

Must-Read Articles

Best Practices

See Code Best Practices

Debugging

Optimisation

Useful Links

These pages cover further aspects of scripting:

Consider the following resources for more general learning: