Introduction to Arma Scripting

This page should give beginners an overview of how to begin with scripting and where to find most of the information they need in the beginning. Some information might not be complete and can be found on other wiki pages.

During mission editing and addon editing you may come across situations where actions or features you would like to have in your mission or addon cannot be accomplished using the basic (or even the more advanced) capabilities of the 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.

The solution for this is to take advantage of the game-engine's ability to employ an even more versatile feature known as scripting. Arma's scripting language SQF (and its predecessor SQS from Operation Flashpoint) can give you more direct control over core game features through script commands and scripted functions.

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 often the 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.

Depending on your answer for these questions, you may want to rethink your approach.

ⓘ

Scripting is not the solution for everything!

Basics

File Creation

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.

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 10 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

File Locations

In the context of scenario creation, script files generally need to be placed in the corresponding scenario folder (often also called the mission root folder). Every scenario 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 previous example could be:

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

The Editor uses percent-encoding to encode scenario names, that is why whitespaces in scenario names are replaced with %20.

ⓘ

The Mission Editors provide 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:

• 2D Editor: External
• Eden Editor: Scenario Folder

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

Recommended programs

Code Edition programs can be found on the Community Tools - Code Edition page section.

Must-read articles

Best Practices

See Code Best Practices

Debugging

• Debugging Techniques
• Community Tools - Debug Console/System

Optimisation

• Code Optimisation
• Mission Optimisation

Useful Links

These pages cover further aspects of scripting:

• Example Code
• Control Structures
• Multiplayer Scripting
• Exception handling
• Script (File)
• Function
• SQS to SQF conversion

Consider the following resources for more general learning:

• 6thSense.eu Editing Guide
• Fockers Arma 3 Scripting Guide
• Mr-Murray's Armed Assault Editing Guide - Deluxe Edition
• Excellent German SQF tutorial (YouTube)