Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Removed "Further reading" and merged it with see also)
m (Fix the fix ><)
(11 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{Stub}}
{{SideTOC}}
{{wip}}
 
== 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 [[ArmA: Mission Editing|mission editing]] and [[ArmA: Addon Editing|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 [[ArmA: Mission Editor|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.
During [[ArmA: Mission Editing|mission editing]] and [[ArmA: Addon Editing|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 [[ArmA: Mission Editor|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|scripting]]. [[Armed Assault|Armed Assault's]] '''scripting language''' gives you more direct control of core game commands. With any combination of these '''[[:Category: Scripting Commands|commands]]''' and '''[[:Category: Functions|functions]]''' you can then create custom processes that meet the specific needs of your mission or 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|scripting]]. [[Armed Assault|Armed Assault's]] '''scripting language''' gives you more direct control of core game commands. With any combination of these [[:Category:ArmA: Scripting Commands|scripting commands]] you can then create custom processes that meet the specific needs of your mission or addon.


== Terms ==
== Terms ==


Before getting started, you should understand the meaning of these terms.  
Before getting started, you should understand the meaning of these terms.
 
'''Data Types''':
See [[Data Types]]


;Script
'''Algorithm''':
: When speaking about a [[Script (File)|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, [https://notepad-plus-plus.org/ Notepad++] or [http://www.geany.org/ Geany].
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.


;Game Engine
'''Interpreter''':
: The core program of the game which reads and executes your scripting commands at run time.
Reads your code from a script file and translates it into instructions for you to achieve your desired outcome/effect in the game.


;Function
'''Control Structures''':
: Piece of code which performs a specific task when executed. 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]].
See [[Control Structures]]


'''Syntax''':
* See [[SQF syntax]]
* See [[SQS syntax]] (obsolete)


'''Script''':
When speaking about a [[Script (File)|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 =
= The things to ask yourself beforehand =


Line 32: Line 57:
=== Can it be scripted by using SQF? ===
=== 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.
* 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 programs ==


*Should any question above be answered with ‘’’Yes’’’, then you should rethink your approach.
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.


* [https://code.visualstudio.com/download Visual Studio Code] (with SQF plugin)
* [https://notepad-plus-plus.org/ Notepad++]
* [http://www.geany.org/ Geany]
* [https://atom.io/ Atom]
* [[Poseidon Tools]]
* [https://www.eclipse.org/ Eclipse] with [https://forums.bohemia.net/forums/topic/202181-sqdev-sqf-developing-in-eclipse/ SQDev]
<!--
== The Concept ==
== 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.         
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===
===Let's start===
Line 109: Line 93:
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 <code>[[titleText]]["Good morning, captain", "PLAIN DOWN"];</code>and save it as ''hello.sqf'' to gamefolder/user/yourname/missions/testingmission. Then add a soldier in the mission editor and type <code>nul = [] [[execVM]] "hello.sqf"</code> 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.)
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 <code>[[titleText]]["Good morning, captain", "PLAIN DOWN"];</code>and save it as ''hello.sqf'' to gamefolder/user/yourname/missions/testingmission. Then add a soldier in the mission editor and type <code>nul = [] [[execVM]] "hello.sqf"</code> 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 ==
== Scripting Code ==


The core of scripting is '''scripting code'''. The code consists of [[:Category:ArmA: Scripting Commands|scripting commands]] that tell the game engine what to do. These commands are executed one after another.
The core of scripting is '''scripting code'''. The code consists of [[:Category:Scripting Commands|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 [[ArmA: Mission Editor|mission editor]] (see below) or into separate files that are executed at some defined point (i.e. through [[Triggers|triggers]]) during the running mission.
The code is written into special fields of the [[ArmA: Mission Editor|mission editor]] (see below) or into separate files that are executed at some defined point (i.e. through [[Triggers|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||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 ===
=== Layout ===
Line 213: Line 174:


Writing the code
Writing the code
-->
== Debugging ==
* [[Debugging Techniques]]


=== Test ===
== Optimisation ==


Testing the code
* [[Code Optimisation]]
* [[Mission Optimisation]]


== See also ==
If you want to learn more about [[Scripting]], read the following articles:


* [[Variables]]
== Useful Links ==
* [[Data Types]]
 
* [[Operators]]
These links offer a great deal of information about [[Scripting]]:
* [[:Category:Example Code|Example Code]]
* [[Control Structures]]
* [[Control Structures]]
* [[Multiplayer Scripting]]
* [[Exception handling]]
* [[Exception handling]]
* [[Script (File)]]
* [[Script (File)]]
* [[Function]]
* [[Function]]
* [[SQF syntax]]
* [[SQS to SQF conversion]]
* [[SQS to SQF conversion]]


[[Category:Arma Scripting Tutorials|Introduction to Scripting]]
Additionally, the following are more resources for more general learning:
* [[6thSense.eu:EG]]
* [http://www.armaholic.com/page.php?id=20465 Fockers Arma 3 Scripting Guide]
* [http://www.armaholic.com/page.php?id=4847 Mr-Murray's Armed Assault Editing Guide - Deluxe Edition]
* [https://www.youtube.com/watch?v=WmEBN-RbK44 Excellent German SQF tutorial]
 
[[Category:Scripting Topics]]
[[Category:Operation Flashpoint: Editing]]
[[Category:ArmA: Editing]]
[[Category:ArmA 2: Editing]]
[[Category:Arma 3: Editing]]

Revision as of 20:11, 17 August 2019

Template:SideTOC Template:wip

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 commands and functions 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.

Data Types: See Data Types

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:

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


Recommended programs

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.


Debugging


Optimisation


Useful Links

These links offer a great deal of information about Scripting:

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

Retrieved from "https://community.bistudio.com/wiki?title=Introduction_to_Arma_Scripting&oldid=126452"