Introduction to Arma Scripting
During mission editing and 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 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 some of these terms.
- Script
- When speaking about a script, it is generally considered a .sqs file, the same can be said for 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
- The core program of the game which reads and executes your scripting commands at run time.
When Do I Need Scripting?
Be careful: Scripting isn't a solution to everything.
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.
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.
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.
If you aren't sure even after working out the preliminaries - just ask in the official forumsor at 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!).
Checklist
In summary:
- Can I do it with the (mission editor, addon, config files etc.).
- Will players notice and/or use it?
- 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. ;-)
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 (f.i. through triggers) during the running mission.
Syntax
Every code has to follow a syntax. The syntax makes sure that the game engine can read and understand the code.
The primary syntax used in Armed Assault is SQF syntax. Read the corresponding article to inform yourself about it.
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 doesn't concern 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: