Introduction to Arma Scripting

From Bohemia Interactive Community
Jump to navigation Jump to search

Template:Stub

During mission editing and addon editing you will often come into the situation, where your imaginations can't be implemented using the native methods of the editors (f.i. cutscenes in missions, special animations in addons). The solution is either to learn more about the editor (f.i. advanced features and methods) or scripting.

Armed Assault's scripting language gives you the possibility of influencing the game engine. With any combination of so-called scripting commands you can create custom processes, that handle any specific needs and problems in a mission.

When Do I Need Scripting?

Scripting is primarily needed in user missions by the mission editor. The goal is to create processes that can't be done with the native features of the mission editor. So this is the first important check before you start scripting. Often the mission editor wants tiny features in a mission that arent't worth a script. Ask yourself, whether the user will notice and/or use the outcome of your script.

Be careful: Scripting isn't a solution to everything. The third step is to make sure whether your needs can be implemented with the scripting language. This can be hard for a beginner, but if you made sure the two above steps, it will be possible in most of the cases. If you aren't sure - just ask in the official forums or at OFPEC.

Checklist

Here is a short summed up checklist of the above mentioned points:

  1. Can I do it with the native features? (mission editor, addon config files, ...)
  2. Will the player notice and/or use it?
  3. 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 seperate files that are executed at some defined point (f.i. through triggers) during the running mission.

Layout

Code should be written in a specific layout. This layout has two reasons: First it assures that the code is readable by the game engine, second, that the code is readable by humans.

Binding rules:

  • Curled braces group code to blocks
  • Commands and blocks are followed by semicolons

The latter rule tells the game engine where one command ends and the next starts.

Example:

Command 1;
Command 2;

Block
{
    Command 3;
    Command 4; 
};

There are additional conventions used to make the code more readable:

  • There should be only one command per line in script files. 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:

Command 1;

Block
{
    Command 2;

    Nested block
    {
        Command 3;
        Command 4;
    };
};

Comments

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

There are three forms of comments:

Comments with the command "comment"
You can write comments using the command comment. This command is followed by a string that includes your text.
Line comments (require preprocessing)
Line comments are started with // and make the whole line after a comment.
Block comments (require preprocessing)
Block comments are started with /* and ended with */. All text between these marks is considered a comment.

Examples:

comment "This is a comment using the command";

// This is also a comment.

/*
This comment
can be
very long
*/

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

What's next?

learning about scripts

Scripts >>