SQF scripts are used in the ARMA
games and their "serious" cousin - VBS
training simulator. Here we will focus on the Arma, but in both cases their
purpose and method of use is similar. They are used during the gamepaly to
make happen things, that the game does not do by itself. They can change AI
behavior, generate, move or delete objects, change their properties, control
the weather, display messages, modify the interface and many, many
more.
1. When do we need scripts?
If the official content of the game fully satisfies us, and any creative
impulses are completely satisfied by the built-in mission editor - no
scripts are needed.
If everything we lack in the game can be easily added via mods - no scripts
are needed.
If, however, we wish to create our own scenarios (or mods, but that's
another topic) and do in these scenarios something, that the game does not
do by default, neither available mods, or if we prefer to keep our scenarios
free from mods dependency - SQF scripts can be useful.
2. Before we write the script
Maybe you don't have to write anything yourself. Maybe others have
already written. In the Internet's areas occupied by the Arma community,
you can find many ready-made scripts.
They are published in a ready-to-run demo scenario, as separate SQF
files, and even in the form of "raw code" pasted with open text on the
forum, uploaded to the blog, etc.
So before we talk about writing our own scripts, in this chapter let's
explain how exactly to use ready-made scripts in the scenarios. The script
author's description may contain sufficient instructions, but sometimes
this is not the case - the matters raised below could be not mentioned as
obvious. Knowledge about them is assumed, which for a layman can be an
insurmountable barrier.
3. How to use ready SQF scripts in the game
There are several ways. We will focus on one, in my opinion the most
universal and recommended, and at the same time possible to explain
without too much additional knowledge.
Not always the case, but there may be differences between the correct use of a given script in the single player scenario and the multiplayer scenario. I will focus only on solo scenarios - we discuss the basics, and multiplayer complicates certain matters for us, also I rarely deal with multiplayer myself. For similar reasons, I leave out some irrelevant nuances and alternatives. I assume knowledge of the basic functions of the EDEN mission editor present in Arma 3. For the purposes of practicing the following points, I recommend running the game without any mods. If the instructions in the script description provided by the author deviate from the following, please follow the author's guidelines. Some explanations assume the Windows 10 OS.
a) Scripts are run in scenarios (also called missions), so we must
first prepare the scenario, we want in the editor. The simplest, often
sufficient for testing, is one soldier/unit/guy as a player's avatar placed
on any map - we save it (do not export!). Saved scenarios in Windows 10 can
be found here:
Each scenario saved in the editor in this way is a separate subfolder in
the "missions" folder.
As a side note, if our script has already been included by the creator in the demonstration scenario - happens often - here also a folder of the demonstration scenario will land, after which you can open it and run it from the EDEN editor..
b) Open the folder of our scenario. It should contain one file at
this stage: mission.sqm. We ignore this file.
c) If we have the script in the form of a ready .sqf file or
files, we skip this section and go to d).
If we have the code as open text to copy and paste, we must put it in a
.sqf file, from where it will run in the scenario.
The basic .sqf file from which the scenario runs its scripts is
init.sqf.
There are also a few other files with similar functions, mainly used in multiplayer scenarios, which we do not deal with here, in any case init.sqf works also there..
How to make a .sqf file? It's easy. In the folder of our scenario,
right-click and select: new > text document from the menu.
A new .txt file should appear. We change its name and extension to
init.sqf and that's it. Similarly, we can create other .sqf
files.
.Sqf files can be edited in the same programs as .txt files, including
simple Notebook/Notepad, but by default they are not associated with
any.
For code editing, I recommend choosing a more advanced program than Notepad. Which one - is a matter of taste, I use Notepad++ myself, but there are probably no worse alternatives, including those dedicated to the SQF language..
The contents of the init.sqf file are executed (made happen) at
the very beginning of the scenario gameplay. It can contain directly the
script to be executed itself, commands to run scripts from other .sqf
files present in the scenario folder (and its subfolders), or a
combination of both options.
The simplest thing we can do now is plainly paste our script into the
init.sqf file.
Exemplary result in the scenario folder:
A technical note: the script's code plainly pasted from some online forums etc. may contain hidden characters that could spoil it. To be sure, you can first paste it into a program that allows you to see hidden symbols, e.g. MS Word, to manually remove such characters. .
d) If the script is in the form of a .sqf file or files, be it in
the demo folder or "loose", we paste these files into our scenario folder.
If, according to the description provided by the author, the script
requires some specific elements in the scenario to work, we return to the
editor and carefully place the required elements in our scenario (these
can be units, vehicles, static objects, markers ...). For example, it may
be expected that the script that makes AI use artillery to fire at targets
will require the presence of the artillery unit and a target on the map,
right? If the required elements should be specifically named - we make
sure that the names match up to the letter.
It should be remembered that the computer is a complete idiot that will immediately get lost if he encounters the slightest error, either in the script itself or in the names to which the script refers. No guesswork or invention should be expected from him, and if we want to write our own scripts, we should remember this fundamental truth well (not, that the scripter got an opportunity to forget)..
Instructions for running the scripts provided in ready-made files often
include the appropriate line or lines of code to be placed in the init.sqf
file (see c)). An example of such instructions from
armaholic.com:
Then the content of the init.sqf file combining a portion of the simple
initial code (lines 1-4) and the command to execute the basic SQF script
from another file (line 5) may look like this:
and the scenario folder ready to run:
In this case, the main script files are placed in the RYD_FFE subfolder - a good practice for extensive scripts covering many files. .