Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(Some scaffolding and groundwork for future changes)
(46 intermediate revisions by 14 users not shown)
Line 1: Line 1:
{{Stub}}
{{TOC|side}} {{Navbox/Scripting}}


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.
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:ArmA: Scripting Commands|scripting commands]] you can then create custom processes that meet the specific needs of your mission or addon.
The solution for this is to take advantage of the game-engine's ability to employ an even more versatile feature known as scripting. Arma's scripting language [[SQF Syntax|SQF]] (and its predecessor [[SQS Syntax|SQS]] from {{ofp}}) can give you more direct control over core game features through [[:Category: Scripting Commands|script commands]] and [[:Category: Functions|scripted functions]].


== Terms ==
== Before anything ==
<!-- This section is not cool and should be reworked or removed -->
; Is your idea necessary?
: Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!


Before getting started, you should understand the meaning of some of these terms.  
; Is it possible to do this in the editor?
: The [[Eden Editor]] is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.
: Poorly written scripts are often the cause of poor performance both in singleplayer and multiplayer scenarios.


; Script
; Can it be scripted using SQF?
: 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.
: This question might be hard to answer. Try to get as much information about what you want to do and what [[:Category: Scripting Commands|commands]] and [[:Category: Functions|functions]] there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.


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


== When Do I Need Scripting? ==
Depending on your answer for these questions, you may want to rethink your approach.


'''Be careful:''' Scripting isn't a solution to everything.
{{Feature|Informative|Scripting is <u>not</u> the solution for 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.
== Terms ==
The following is a collection of terms frequently encountered when talking or reading about scripting.


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.
; Game Engine
 
: The core program of the game which executes your scripting commands at run time.
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 [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!).
 
 
 
=== Checklist ===
 
In summary:
 
# Can I do it with the([[ArmA: Mission Editor|mission editor]], [[ArmA: Addon Configuration|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 [[:Category:ArmA: 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 (f.i. through [[Triggers|triggers]]) during the running mission.


=== Syntax ===
; Script <!-- meh -->
: When speaking about a script, one is usually referring to a <tt>.sqs</tt> or <tt>.sqf</tt> [[Script (File)|script file]].


Every code has to follow a '''syntax'''. The syntax makes sure that the ''game engine'' can read and understand the code.
; Syntax <!-- TODO: Explanation -->
: See [[SQF Syntax]] ({{arma}}, {{arma2}}, {{arma3}}, {{tkoh}}).
: See [[SQS Syntax]] ({{ofp}}, {{arma}}).


The primary syntax used in [[Armed Assault]] is [[SQF syntax]]. Read the corresponding article to inform yourself about it.
; Variables
: A [[Variables|Variable]] is a named storage container for data.
: The name of a variable is called its [[Identifier]].


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.
; Data Types
: The [[:Category: Data Types|Data Type]] of a variable specifies which kind of data that variable can contain.


All scripting pages about Armed Assault will focus on [[SQF syntax]].
; Operators <!-- TODO: Explanation -->
: See [[Operators]]


=== Layout ===
; Control Structures <!-- TODO: Explanation -->
: See [[Control Structures]]


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.
; Functions <!-- TODO: Explanation -->
: See [[Function]]


* 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.
* Use '''spaces or tabs''' to indent code in [[Block|blocks]]. This way you can easily tell to which block some code belongs.


Example:
== Recommended programs ==
Code Edition programs can be found on the [[:Category:Community Tools#Code Edition|Community Tools - Code Edition]] page section.


Statement 1;
Block
{
    Statement 2;
    Nested block
    {
        Statement 3;
        Statement 4;
    };
};


=== Comments ===
== Must-read articles ==
<!-- Bad section title, should be changed -->
=== Best Practices ===
See [[Code Best Practices]]


You can and should write comments into your [[Script (File)|scripts]] that describe the purpose of your code. These comments are written in free text and completely ignored by the game engine.
=== Debugging ===
* [[Debugging Techniques]]
* [[:Category:Community_Tools#Debug_Console.2FSystem|Community Tools - Debug Console/System]]


Check out [[SQF syntax]] for information about the notation of comments.
=== Optimisation ===
* [[Code Optimisation]]
* [[Mission Optimisation]]


'''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:
== Useful Links ==
 
These pages cover further aspects of scripting:
// the variable i gets the value 1
* [[:Category:Example Code|Example Code]]
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:
 
* [[Variables]]
* [[Data Types]]
* [[Operators]]
* [[Control Structures]]
* [[Control Structures]]
* [[Exception Handling]]
* [[Multiplayer Scripting]]
* [[Exception handling]]
* [[Script (File)]]
* [[Function]]
* [[SQS to SQF conversion]]


== See also ==
Consider the following resources for more general learning:
* [[6thSense.eu/EG|6thSense.eu Editing Guide]]
* [https://www.armaholic.com/page.php?id=20465 Fockers Arma 3 Scripting Guide]
* [https://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 (YouTube)]


* [[Script (File)]]
* [[Function]]
* [[SQF syntax]]


[[Category: Scripting Topics|Introduction to Scripting]]
[[Category:Arma Scripting Tutorials]]

Revision as of 20:39, 25 February 2021

Template:Navbox/Scripting

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 for this is to take advantage of the game-engine's ability to employ an even more versatile feature known as scripting. Arma's scripting language SQF (and its predecessor SQS from Operation Flashpoint) can give you more direct control over core game features through script commands and scripted functions.

Before anything

Is your idea necessary?
Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!
Is it possible to do this in the editor?
The Eden Editor is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.
Poorly written scripts are often the cause of poor performance both in singleplayer and multiplayer scenarios.
Can it be scripted using SQF?
This question might be hard to answer. Try to get as much information about what you want to do and what commands and functions there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.


Depending on your answer for these questions, you may want to rethink your approach.

ⓘ
Scripting is not the solution for everything!


Terms

The following is a collection of terms frequently encountered when talking or reading about scripting.

Game Engine
The core program of the game which executes your scripting commands at run time.
Script
When speaking about a script, one is usually referring to a .sqs or .sqf script file.
Syntax
See SQF Syntax (Arma, Arma 2, Arma 3, Take On Helicopters).
See SQS Syntax (Operation Flashpoint, Arma).
Variables
A Variable is a named storage container for data.
The name of a variable is called its Identifier.
Data Types
The Data Type of a variable specifies which kind of data that variable can contain.
Operators
See Operators
Control Structures
See Control Structures
Functions
See Function


Recommended programs

Code Edition programs can be found on the Community Tools - Code Edition page section.


Must-read articles

Best Practices

See Code Best Practices

Debugging

Optimisation


Useful Links

These pages cover further aspects of scripting:

Consider the following resources for more general learning:

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