Introduction to Arma Scripting: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
No edit summary
(65 intermediate revisions by 17 users not shown)
Line 1: Line 1:
{{Stub}}
{{SideTOC}}
== Introduction ==


During [[ArmA: Mission Editing|mission editing]] and [[ArmA: Addon Editing|addon editing]] you will often come into the situation, where your imaginations can't be implemented using the native methods of the editors (f.i. cutscenes in missions, special animations in addons). The '''solution''' is either to learn more about the editor (f.i. advanced features and methods) or [[ArmA: Scripting|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.


[[Armed Assault|Armed Assault's]] '''scripting language''' gives you the possibility of influencing the game engine. With any combination of so-called [[ArmA: Scripting Commands|scripting commands]] you can create custom processes, that handle any specific needs and problems in a mission.
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.


== When Do I Need Scripting? ==
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.


[[ArmA: Scripting|Scripting]] is primarily needed in [[ArmA: Mission Editing|user missions]] by the mission editor. The goal is to create processes that can't be done with the native features of the [[ArmA: Mission Editor|mission editor]]. So this is the first important check before you start scripting. Often the mission editor wants tiny features in a mission that '''arent't worth a script'''. Ask yourself, whether the user will notice and/or use the outcome of your script.


'''Be careful:''' Scripting isn't a solution to everything. The third step is to make sure, whether your needs can be implemented in the scripting language. This can be hard for a beginner, but if you made sure the two above steps, it will be possible in most of the cases. If you aren't sure - just ask in the [http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi official forums] or at [http://www.ofpec.com OFPEC].
== Before anything ==


=== Checklist ===
=== Is your idea necessary? ===


Here is a short summed up checklist of the above mentioned points:
* 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 I do it with the native features? ([[ArmA: Mission Editor|mission editor]], [[ArmA: Addon Configuration|addon config files]], ...)
=== Is it possible to do this in the editor? ===
# Will the player 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. ;-)
* [[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.


== Scripting Code ==
=== Can it be scripted using SQF? ===


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


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


Code should be written in a specific layout. This layout has two reasons: First it assures that the code is readable by the game engine, second, that the code is readable by humans.
{{Informative | '''Scripting''' is <u>not</u> a solution to everything.}}


Binding rules:


* Curled braces group code to '''blocks'''
== Terms ==
* Commands and blocks are followed by '''semicolons'''


The latter rule tells the game engine where one command ends and the next starts.
Before getting started, you should understand the meaning of these terms.


Example:
'''Data Types''':
See [[Data Types]]


Command 1;
'''Algorithm''':
Command 2;
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.
Block
{
    Command 3;
    Command 4;
};


There are additional conventions used to make the code more readable:
'''Interpreter''':
Reads your code from a script file and translates it into instructions for you to achieve your desired outcome/effect in the game.


* There should be '''only one command per line''' in [[ArmA: Script Files|script files]]. This doesn't concern script lines in the mission editor, since there all the code has to be written within a single line.
'''Control Structures''':
* Use '''spaces or tabs''' to indent code in blocks. This way you can easily tell to which block some code belongs.
See [[Control Structures]]


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


Command 1;
'''Script''':
When speaking about a [[Script (File)|script]], we usually mean a .sqs or .sqf file.
Block
{
    Command 2;
    Nested block
    {
        Command 3;
        Command 4;
    };
};


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


You can and should write comments into your [[ArmA: Script Files|script files]] that describe the purpose of your code. These comments are written in free text and completely ignored by the game engine.
'''Function''':
See [[Function]]


There are three forms of comments:
'''Variables''':
See [[Variables]]


; Comments with the command "comment"
'''Operators''':
: You can write comments using the command [[comment]]. This command is followed by a string that includes your text.
See [[Operators]]


; Line comments (require [[preprocessFile|preprocessing]])
: Line comments are started with <tt>//</tt> and make the '''whole line after''' a comment.


; Block comments (require [[preprocessFile|preprocessing]])
== Recommended programs ==
: Block comments are started with <tt>/*</tt> and ended with <tt>*/</tt>. All text between these marks is considered a comment.


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


comment "This is a comment using the command";
// This is also a comment.
/*
This comment
can be
very long
*/


'''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:
== Must-read articles ==


Bad comment:
=== Best Practices ===


// the variable i gets the value 1
* [[Code Best Practices]]
i = 1;


Good comment:
=== Debugging ===


// reset the counter to start with 1 again
* [[Debugging Techniques]]
i = 1;
* [[:Category:Community_Tools#Debug_Console.2FSystem|Community Tools - Debug Console/System]]


== Code Execution ==
=== Optimisation ===


how can I execute code? (external files vs. mission editor)
* [[Code Optimisation]]
* [[Mission Optimisation]]


=== Mission Editor ===


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


=== External Files ===
These links offer a great deal of information about [[Scripting]]:
* [[:Category:Example Code|Example Code]]
* [[Control Structures]]
* [[Multiplayer Scripting]]
* [[Exception handling]]
* [[Script (File)]]
* [[Function]]
* [[SQS to SQF conversion]]


how to execute code in external files, scripts & functions
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)]


== Developing a Script ==


script in this case: code in external files (scripts/functions). how to develop a script?
[[Category:Scripting Topics]]
 
[[Category:Operation Flashpoint: Editing]]
* Requirements
[[Category:ArmA: Editing]]
* Concept
{{GameCategory|arma2|Editing}}
* Implementation
{{GameCategory|arma3|Editing}}
* Test
[[Category:Take On Helicopters: Editing]]
 
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
 
== What's next? ==
 
learning about scripts
 
[[ArmA: Script|Scripts >>]]
 
[[Category:ArmA: Scripting|Introduction to Scripting]]

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"