Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
No edit summary
(27 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Stub}}
{{SideTOC}}
== 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-engine's ability to call on an even more advanced feature known as [[Scripting|scripting]]. '''Arma''''s '''scripting language''' gives you a more direct control of core game features. With any combination of these '''[[:Category: Scripting Commands|commands]]''' and '''[[:Category: Functions|functions]]''' you can 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 ==


Before getting started, you should understand the meaning of these terms.
== Before anything ==


;Script
=== Is your idea necessary? ===
: 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 or [http://www.geany.org/ Geany].


;Game Engine
* Will players even notice or use what you want to script? Just because you can doesn’t mean you should. Sometimes less is more!
: The core program of the game which reads and executes your scripting commands at run time.


;Function
=== Is it possible to do this in the editor? ===
: Piece of code which performs a specific task. 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]].


== When Do I Need Scripting? ==
* [[Eden Editor]] is an incredibly powerful tool and with it alone one can achive a lot of things, even without writing a single line of [[SQF syntax|SQF]].
* ''Poorly written'' scripts are often the reason for poor performance both in singleplayer and multiplayer scenarios.


'''Be careful:''' Scripting isn't a solution to everything.
=== Can it be scripted using SQF? ===


The first thing to ask yourself is, "Am I absolutely sure this cannot be done using just the editor?" The goal with scripting is to create processes that can't be done otherwise. Because scripting does use system resources, poorly written scripts can affect game play 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.
* This might be hard to answer, especially for beginners. 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 it is ''not'' possible in the end.


The second thing to ask before you start scripting away is, "Will players even notice 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.


The third step (which may be the hardest, especially for people new to scripting) is to determine if what you want to do can be implemented with the scripting language.
Depending on your answer for these questions, you may want to rethink your approach.


If you aren't sure even after working out the preliminaries, just ask in the [http://forums.bistudio.com/ 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. If they become interested, they may serve as beta testers!
{{Informative | '''Scripting''' is <u>not</u> a solution to everything.}}


=== Checklist ===


In summary:
== Terms ==
 
# 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 the first point is answered "No", but the second and third are answered "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 (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 ===
 
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 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.
 
Example:
 
Statement 1;
Block
{
    Statement 2;
    Nested block
    {
        Statement 3;
        Statement 4;
    };
};


=== Comments ===
Before getting started, you should understand the meaning of these terms.


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.
'''Data Types''':
See [[Data Types]]


Check out [[SQF syntax]] for information about the notation of comments.
'''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.


'''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:
'''Interpreter''':
Reads your code from a script file and translates it into instructions for you to achieve your desired outcome/effect in the game.


Bad comment:
'''Control Structures''':
See [[Control Structures]]


// the variable i gets the value 1
'''Syntax''':
i = 1;
* See [[SQF syntax]]
* See [[SQS syntax]] (obsolete)


Good comment:
'''Script''':
When speaking about a [[Script (File)|script]], we usually mean a .sqs or .sqf file.


// reset the counter to start with 1 again
'''Game Engine''':
i = 1;
The core program of the game which reads and executes your scripting commands at run time.


== Code Execution ==
'''Function''':
See [[Function]]


how can I execute code? (external files vs. mission editor)
'''Variables''':
See [[Variables]]


=== Mission Editor ===
'''Operators''':
See [[Operators]]


how to execute code in the editor, listing of mission editor fields to start scripts


=== External Files ===
== Recommended programs ==


how to execute code in external files, scripts & functions
'''Code Edition''' programs can be found on the [[:Category:Community Tools#Code Edition|Community Tools - Code Edition]] page section.


== Developing a Script ==


script in this case: code in external files (scripts/functions). how to develop a script?
== Must-read articles ==


* Requirements
=== Best Practices ===
* Concept
* Implementation
* Test


usually in your head, for complex scripts on paper and drafts
* [[Code Best Practices]]


=== Requirements ===
=== Debugging ===


what shall the script do?
* [[Debugging Techniques]]
* [[:Category:Community_Tools#Debug_Console.2FSystem|Community Tools - Debug Console/System]]


=== Concept ===
=== Optimisation ===


How shall the script do it?
* [[Code Optimisation]]
* [[Mission Optimisation]]


=== Implementation ===


Writing the code
== Useful Links ==


=== Test ===
These links offer a great deal of information about [[Scripting]]:
 
* [[:Category:Example Code|Example Code]]
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]]
== See also ==
 
* [[Script (File)]]
* [[Script (File)]]
* [[Function]]
* [[Function]]
* [[SQF syntax]]
* [[SQS to SQF conversion]]
* [[SQS to SQF conversion]]


[[Category: Scripting Topics|Introduction to Scripting]]
Additionally, the following are more resources for more general learning:
* [[6thSense.eu/EG|6thSense.eu Editing Guide]]
* [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 (YouTube)]
 
 
[[Category:Scripting Topics]]
[[Category:Operation Flashpoint: Editing]]
[[Category:ArmA: Editing]]
{{GameCategory|arma2|Editing}}
{{GameCategory|arma3|Editing}}
[[Category:Take On Helicopters: Editing]]

Revision as of 22:17, 2 August 2020

Template:SideTOC

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-engine's ability to call on an even more advanced feature known as scripting. Arma's scripting language gives you a more direct control of core game features. With any combination of these commands and functions you can create custom processes that meet the specific needs of your mission or addon.


Before anything

Is your idea 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!

Is it possible to do this in the editor?

  • Eden Editor is an incredibly 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.

Can it be scripted 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 and functions there are before spending time on writing a script, just to find out it is not possible in the end.


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

ⓘ
Scripting is not a solution to everything.


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

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


Must-read articles

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