KC Grimes/Sandbox – User

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 to this is to take advantage of the game-engines ability to call on an even more advanced feature known as scripting. Armed Assault's scripting language gives you more direct control of core game commands. With any combination of these scripting commands you can then create custom processes that meet the specific needs of your mission or addon.

Terms

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

Script

When speaking about a script, we usually mean a .sqs or .sqf file. Both file types can be edited as a plain text file using a program like Notepad or Geany.

Game Engine

The core program of the game which reads and executes your scripting commands at run time.

Function

Piece of code which performs a specific task. A function may return a value. The mission author often writes complicated functions in .sqf files and then executes them in-game. Functions can be considered a kind of script. Usually, however, a "script" means a .sqs or .sqf file that runs over a period of time and directs gameplay, while a "function" is usually meant to run instantaneously and return a value. See function.

When Do I Need Scripting?

Be careful: Scripting isn't a solution to everything.

The first thing to ask yourself is, "Am I absolutely sure this cannot be done using just the editor?" The goal with scripting is to create processes that can't be done otherwise. Because scripting does use system resources, poorly written scripts can affect game play 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.

The second thing to ask before you start scripting away is, "Will players even notice 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.

The third step (which may be the hardest, especially for people new to scripting) is to determine if what you want to do can be implemented with the scripting language.

If you aren't sure even after working out the preliminaries, just ask in the official forums or at OFPEC. These would also be good places to ask other players for their feedback on question number two. If they become interested, they may serve as beta testers!

Checklist

In summary:

1. Can I do it with the (mission editor, addon, config files etc.)?
2. Will players notice and/or use it?
3. Is it possible?

If the first point is answered "No", but the second and third are answered "Yes", go on and script it! But be warned: It won't always be easy. ;-)

The Concept

Scripts are an essential part of making missions. They allow you to create amazing cutscenes, create effects and customize almost every aspect of your mission. Some diverse examples of what could be scripted are: a simulation of artillery fire, a poisonous gas cloud, or a money system for purchasing equipment.

Algorithm

Your first task in writing scripts is to decide what sequence of steps is needed to solve a particular problem. This sequence is what would be called an algorithm.

For example, if you wanted to transport weapons from Petrovice to Lipany, you would (as commander) give these orders:

• Commander: Private Honka, private Kouba, come here!
• Commander: Private Kouba, get in Ural as driver!
• Commander: Private Honka, get in Ural!
• Commander: Private Kouba, drive to Petrovice and load Ural!

• Private Kouba: I don't know where Petrovice is, sir.

Now we have a problem. Kouba only knows how to get to Lipany and Honka only knows how to get to Petrovice. Our soldiers are new recruits and are really quite stupid. They can only take simple orders, one order at a time. They can get in and out of vehicles, drive, and load and unload weapons and ammo. The commander must plan this sequence of orders and make provisions for obstacles that may arise.

1. Destination is Petrovice
2. Get in vehicle
3. If driver does not know the way to Destination, swap driver and passenger
4. Drive to Destination
5. Get out of vehicle
6. Load vehicle
7. Destination is Lipany
8. Get in vehicle
9. If driver does not know the way to Destination, swap driver and passenger
10. Drive to Destination
11. Get out of vehicle
12. Unload vehicle

Interpreter

If you have an algorithm, you need something that can execute it. We have a computer game, Armed Assault, which is able to do this; commanders have soldiers.

Programming language

It's the way how to write our algorithm for Armed Assault. ArmA scripts are a sequence of 'orders' describing how to do it.

Source code

Source code is algorithm written in any programming language.

Syntax

Syntax is made up of commands and parameters, sometimes just the command is required as in exit, other times the syntax is made up of one or more parameters. Each command has it's own reference in the Scripting section of the wiki. In each case the command + its parameters are listed with examples on how that particular command works.

if(PrivateHonka == TheMostCleverSoldierInTheWorld) then {
    IAmChineseGodOfHumour = true;
};

You should however be aware that there are two similar scripting grammars in Armed Assault, namely SQF and SQS. While the functions are almost the same, there are still minor differences in statement notations, program flow and control structures.

Interpreting works

The Armed Assault engine reads your code from script files and translates those instructions for you to achieve your desired outcome/effect in the game.

Let's start

Every script consist of commands (see category Scripting Commands) and program flow statements (they are implemented as commands in Armed Assault, but it isn't relevant for now). The most useful command in your first script is titleText. It can write any text you want to the player's screen.

titleText["Good morning, captain", "PLAIN DOWN"]

It's a typical way to run commands. Behind the name of the command the parameters follow (but it depends on the command (see Category:Scripting Commands). Every command can only have one parameter before it's name and/or one after (more arguments can be given with arrays which count as one parameter). Parameters can be of various Data types. In this case it's an Array - a list of other data types. It can contain 0 - 4096? values. The first value is a String representing the text to be displayed and the second, in this case, says in what position on the screen the text will be displayed. There can be a third value: a Number which says how long the text needs to fade in. If this value is not entered, its default value (1) is used.

titleText["Good morning, captain", "PLAIN DOWN", 5]

Scripts which are called functions) are stored in .SQF files the mission folder, or in .SQSs files and then called only scripts.

If you want to try our 'script', create a mission in the mission editor, save it as testingmission, open your favorite text edtior (eg. Notepad), write titleText["Good morning, captain", "PLAIN DOWN"];and save it as hello.sqf to gamefolder/user/yourname/missions/testingmission. Then add a soldier in the mission editor and type nul = [] execVM "hello.sqf" to his initialization line. When you run this mission, you should see output of your first script. Well done, soldier! (If you are confused from this quantum of informations, don't panic, more continuously explanation follows.)

Variables

See Variables

Operators

See Operators

Scripting Code

The core of scripting is scripting code. The code consists of scripting commands that tell the game engine what to do. These commands are executed one after another.

The code is written into special fields of the mission editor (see below) or into separate files that are executed at some defined point (i.e. through triggers) during the running mission.

Syntax

Every code has to follow a syntax. The syntax is the "grammar" of the scripting language. It makes sure that the game engine can read and understand the code.

The primary syntax used in Armed Assault and ArmA 2 is SQF syntax. Read the corresponding article to inform yourself about the exact details. There are some crucial points which you must know about:

• Every statement of SQF code except for the last one should end with a semicolon. Otherwise, the engine doesn't know when one statement ends and the next begins. In SQF (unlike SQS), line breaks made with the ENTER key are only visible to the script writer. Spaces between lines are completely ignored by the engine.

There is an exception to this rule. When using commands such as |if () then {}, the final statement of code inside the parentheses and {} brackets can go without a semicolon. If this confuses you, just put a semicolon after all statements except for the last one.

• The final statement of SQF code should not have a semicolon after it. (As of the current version of ArmA2:OA, this is not a problem, but it was in previous games).

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.

All scripting pages about Armed Assault will focus on SQF syntax.

Layout

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.

• There should be only one statement per line in scripts. This rule doesn't apply to script lines in the mission editor, since there all the code has to be written within a single line.
• Use spaces or tabs to indent code in blocks. This way you can easily tell to which block some code belongs.

Example:

Statement 1;

Block
{
    Statement 2;

    Nested block
    {
        Statement 3;
        Statement 4;
    };
};

Comments

You can and should write comments into your scripts that describe the purpose of your code. These comments are written in free text and completely ignored by the game engine.

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:

Bad comment:

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

Good comment:

// reset the counter to start with 1 again
i = 1;

Code Execution

how can I execute code? (external files vs. mission editor)

Mission Editor

how to execute code in the editor, listing of mission editor fields to start scripts

External Files

how to execute code in external files, scripts & functions

Developing a Script

script in this case: code in external files (scripts/functions). how to develop a script?

• Requirements
• Concept
• Implementation
• Test

usually in your head, for complex scripts on paper and drafts

Requirements

what shall the script do?

Concept

How shall the script do it?

Implementation

Writing the code

Test

Testing the code

Further Reading

If you want to learn more about Scripting, read the following articles:

• Variables
• Data Types
• Operators
• Control Structures
• Exception handling

See also

• Script (File)
• Function
• SQF syntax
• SQS to SQF conversion