Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(changed wording to (try and) reflect the meaning a bit better in English~~~~)
m (Spacing)
(35 intermediate revisions by 13 users not shown)
Line 1: Line 1:
{{Stub}}
{{SideTOC}}
{{wip}}


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 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.
== 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.
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 [[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 some of these 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]]


; Script
'''Syntax''':
: When speaking about a [[Script (File)|script]], it is generally considered a '''.sqs''' file, the same can be said for [[Function|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.
* See [[SQF syntax]]
* See [[SQS syntax]] (obsolete)


; Game Engine
'''Script''':
: The core program of the game which reads and executes your scripting commands at run time.
When speaking about a [[Script (File)|script]], we usually mean a .sqs or .sqf file.


== When Do I Need Scripting? ==
'''Game Engine''':
The core program of the game which reads and executes your scripting commands at run time.


'''Be careful:''' Scripting isn't a solution to everything.
'''Function''':
See [[Function]]


'''Variables''':
See [[Variables]]


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.
'''Operators''':
See [[Operators]]
<!--
= The things to ask yourself beforehand =


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.  
{{note|Be careful: Scripting isn't a solution to everything. }}


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


If you aren't sure even after working out the preliminaries - just ask in the [http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi official forums] or at [http://www.ofpec.com 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!).
*Should any question above be answered with ‘’’Yes’’’, then you should rethink your approach.
-->




== Recommended programs ==


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


In summary:
* [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 ==


# Can I do it with the([[ArmA: Mission Editor|mission editor]], [[ArmA: Addon Configuration|addon ]] config files etc.).
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.      
# 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 ==
===Let's start===
 
Every script consist of commands (see category [[:Category:Scripting Commands|Scripting Commands]]) and [[Control Structures|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"]


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.
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 [[:Category:Types|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.


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 (f.i. through [[Triggers|triggers]]) during the running mission.
[[titleText]]["Good morning, captain", "PLAIN DOWN", 5]


=== Syntax ===
Scripts which are called [[function]]s) are stored in .SQF files the mission folder, or in .SQSs files and then called only scripts.


Every code has to follow a '''syntax'''. The syntax makes sure that the ''game engine'' can read and understand the code.
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.)


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.
== Scripting Code ==


All scripting pages about Armed Assault will focus on [[SQF syntax]].
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.


=== Layout ===
=== Layout ===
Line 61: Line 104:
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.
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|statement]] per line''' in [[Script (File)|scripts]]. This doesn't concern script lines in the mission editor, since there all the code has to be written within a single line.
* There should be '''only one [[Statement|statement]] per line''' in [[Script (File)|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 [[Block|blocks]]. This way you can easily tell to which block some code belongs.
* Use '''spaces or tabs''' to indent code in [[Block|blocks]]. This way you can easily tell to which block some code belongs.


Line 99: Line 142:
== Code Execution ==
== Code Execution ==


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


=== Mission Editor ===
=== Mission Editor ===
Line 131: Line 174:


Writing the code
Writing the code
-->


=== Test ===


Testing the code
== Best Practices ==


== Further Reading ==
* [[Code Best Practices]]


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


* [[Variables]]
== Debugging ==
* [[Data Types]]
 
* [[Operators]]
* [[Debugging Techniques]]
* [[Control Structures]]
 
* [[Exception Handling]]
 
== Optimisation ==
 
* [[Code Optimisation]]
* [[Mission Optimisation]]
 


== See also ==
== Useful Links ==


These links offer a great deal of information about [[Scripting]]:
* [[:Category:Example Code|Example Code]]
* [[Control Structures]]
* [[Multiplayer Scripting]]
* [[Exception handling]]
* [[Script (File)]]
* [[Script (File)]]
* [[Function]]
* [[Function]]
* [[SQF syntax]]
* [[SQS to SQF conversion]]
 
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|Introduction to Scripting]]
[[Category:Scripting Topics]]
[[Category:Operation Flashpoint: Editing]]
[[Category:ArmA: Editing]]
[[Category:ArmA 2: Editing]]
[[Category:Arma 3: Editing]]

Revision as of 20:59, 12 September 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.


Best Practices


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=137133"