Difference between revisions of "Introduction to Arma Scripting"

From Bohemia Interactive Community
Jump to navigation Jump to search
(page updated (still WIP))
m (added WIP note)
Line 1: Line 1:
 
{{SideTOC}}
 
{{SideTOC}}
 +
{{Informative|This page is WIP. Feel free to contribute!}}
 +
 
==Introduction==
 
==Introduction==
 
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.
 
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.

Revision as of 20:55, 19 May 2018

This page is WIP. Feel free to contribute!

Introduction

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


Algorithm: In mathematics and computer science, an algorithm is an explicit specification of how to solve a class of problems. Algorithms can perform calculation, data processing and automated reasoning tasks.

Interpreter: Reads your code from a script file and translates it into instructions for you to achieve your desired outcome/effect in the game.

Control Structures: See Control Structures

Syntax: See SQF syntax See SQS syntax

Script: When speaking about a script, we usually mean a .sqs or .sqf file.

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

Function: See Function

Variables: See Variables

Operators: See Operators


The things to ask yourself beforehand

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

Is it not possible to do this in the editor?

  • Eden Editor is an incredible powerful tool and with it alone one can achive a lot of things, even without writing a single line of SQF.
  • Poorly written scripts are often the reason for poor performance both in singleplayer and multiplayer scenarios.

Is it necessary?

  • Will players even notice or use what you want to script? Just because you can doesn’t mean you should. Sometimes less is more!

Can it be scripted by using SQF?

  • This might be hard to answer, especially for beginners. Try to get as much information about what you want to do and what commands there are before spending time on writing a script, just to find out it’s #not possible in the end.
  • Should any question above be answered with ‘’’Yes’’’, then you should rethink your approach.

Recommended programms

The following programms are recommended when working with sqf, sqs, cpp or many other file types. Most of them offer syntax highlighting and other useful features. Check them out and select the one you like the most.

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.


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.)


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.

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

This page is WIP!

Optimisation

See also

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

Additionally, the following are more resources for more general learning: