Script File: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "{{Feature | Informative | " to "{{Feature|informative|")
 
(33 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{Stub}}
{{TOC|side}}
A [[{{PAGENAME}}|script file]] is multiple commands and arguments defining wanted behaviour from the game, all grouped together in a textfile. This code does a specific task handled by the game engine. The common extensions for Arma scripts are '''.sqf''' and '''.sqs''', depending on the used syntax: [[SQF Syntax|SQF]] or (deprecated) [[SQS Syntax]].
{{Feature|informative|See [[:Category:Community Tools#Code Edition|Community Tools - Code Edition]] for recommended text editors.}}


A '''script''' is a chunk of code grouped together in a seperate textfile. This code does a specific task handled by the game engine. The common extensions for scripts are '''.sqs''' and '''.sqf''', depending on the used syntax (see below). You can use any text editor like Notepad to edit scripts.


A special kind of a script is a [[Function|function]].
== Syntax ==
 
== Usage ==
 
Scripts are mainly used for any game processes where '''timing''' is important. They are different to [[Function|functions]] where the ''result'' or ''calculation'' is important.


Thus scripts can be used for cutscenes, dialogs, radio scripting and much more.
In [[:Category:Operation Flashpoint|{{ofp}}]], scripts are limited to [[SQS Syntax]].
* See [[exec]]


== Syntax ==
The already existing (since {{ofp}} v1.85) [[SQF Syntax]] was introduced for scripts in [[:Category:ArmA: Armed Assault|{{arma1}}]]. [[SQS Syntax]] is still usable but is considered deprecated since.
* See [[execVM]], [[spawn]]


In [[Operation Flashpoint]], scripts are limited to [[SQS syntax]].


In [[Armed Assault]], the already existing [[SQF syntax]] was introduced for scripts. [[SQS syntax]] is still usable, but is considered deprecated in Armed Assault.
[[File: Script_Execution.png|frame|right||Script Execution Diagram<br>'''Executing Instance:''' script, [[Function|function]] or game engine]]


== Execution ==
== Execution ==
Line 23: Line 21:
* Other scripts
* Other scripts
* Other [[Function|functions]]
* Other [[Function|functions]]
* Scripting lines in the [[Mission Editor]]
* Init fields and (de)activation triggers in the [[Mission Editor]]
* [[Event Handlers]] in addon config files
* [[:Category:Event Handlers|Event Handlers]] in addon config files
 


The commands to execute scripts are:
The commands to execute scripts are:


; exec
; exec
: [[exec]] starts thread for scripts in [[SQS syntax]].
: [[exec]] starts a thread for a script in [[SQS Syntax]].
 
; execVM (Armed Assault only)
: [[execVM]] starts thread for scripts in [[SQF syntax]].
 
; spawn (Armed Assault only)
: [[spawn]] starts a thread for a [[compile|compiled]] script or code and returns a [[Script (Handle)|script handle]].
 
; call (Armed Assault only)
: [[call]] executes a [[compile|compiled]] script or code within the scope of the current script. Such code is considered a [[Function|function]]. The following statements do not apply for functions.
 
Scripts are running ''besides'' the executing instance in own threads. That means that the executing instance (f.i. script or [[Function|function]]) doesn't wait for the script to end. Thus scripts should not be used for code that should return a value, which is used in the calling script. This part is taken over by [[Function|functions]].
 
Since [[Armed Assault]], scripts return a [[Script (Handle)|script handle]] which you can use to verify whether a script is still running.
 
''nserted from sqf syntax''
 
With the release of Armed Assault, the SQS syntax for scripting was deprecated. SQF syntax is expected to be used for both scripts and [[Function|functions]].
[[sqs syntax|SQS syntax]] is compiled line-by-line as it is executed. SQF files must be compiled ahead of time and are thus more efficient at time of execution. SQF scripts are compiled and executed with either the [[execVM]] command or manually via [[compile]] and [[spawn]]. Since scripts run parallel with each other, you must use [[scriptDone]] if you wish to have a ''calling'' script wait for a ''called'' script to finish.
<br>
 
 
'''Diagram of Scripts Running in Parallel'''
 
[[Image:ParallelSQFScript.jpg]]
 
<br>
'''Diagram of Scripts Running in Parallel using [[waitUntil]] and [[scriptDone]] to pause execution'''
 
[[Image:ParallelSQFScript_WaitUntil.jpg]]
 
<br>
 
== Special Variables ==
 
_time in both syntax ?
 
== Special Commands ==
 
Due to the fact, that calling instances aren't waiting for the scripts to end, scripts can be halted for a custom period of time. There are different methods to do this in [[SQF syntax]] (Armed Assault '''only''') and [[SQS syntax]] ('''deprecated''' since Armed Assault).


=== SQF syntax ===
; execVM
: [[execVM]] [[preprocessFileLineNumbers|preprocesses]] and [[compile|compiles]] a [[SQF Syntax]] script file and starts a thread for it.


; Delay
; call
: You can set the script to sleep for a number of seconds using the command [[sleep]].
: [[call]] adds provided [[Code]] to the stack and wait for it to execute, then returns the code's last returned value.


STATEMENT 1;
; spawn
: [[spawn]] starts a thread for provided [[Code]].
// wait 10 seconds
sleep 10;
STATEMENT 2;


; Waiting for a condition
{{Feature | Informative |
: You can set the script to sleep until a specific condition is met using the command [[waitUntil]].
* [[execVM]] is almost like using <sqf inline>[] spawn compile preprocessFile</sqf>.
* [[spawn]] and [[execVM]] both add the thread to the [[Scheduler]] and provide a [[Script Handle|script handle]] which allows you to check if the spawned script is done (using [[scriptDone]]).}}


BOOL = false;
// wait until BOOL gets true
waitUntil BOOL;
STATEMENT;
=== SQS syntax ===
; Delay
: You can set the script to sleep for a number of seconds by introducing a line with <tt>~</tt>, followed by the number of seconds.
STATEMENT 1
; wait 10 seconds
~10
STATEMENT 2
; Waiting for a condition
: You can set the script to sleep until a condition is met by introducing a line with <tt>@</tt>, followed by the condition.
BOOL = false
; wait until BOOL gets true
@BOOL
STATEMENT
; Waiting for a time
: You can set the script to sleep until a time (number of seconds since the beginning of the script) is met by introducing a line with <tt>&</tt>, followed by the time.
&100
; is equivalent to
@_time >= 100


== See also ==
== See also ==


* [[Function|Functions]]
* [[Function|Functions]]
* [[SQF syntax]]
* [[:Category:Syntax|Syntax]]
* [[SQS syntax]]
** [[SQF Syntax]]
** [[SQS Syntax]]
* [[Statement]]
 


[[Category:Scripting Topics]]
[[Category:Scripting Topics]]
[[Category:ArmA: Scripting]]

Latest revision as of 21:42, 16 May 2024

A script file is multiple commands and arguments defining wanted behaviour from the game, all grouped together in a textfile. This code does a specific task handled by the game engine. The common extensions for Arma scripts are .sqf and .sqs, depending on the used syntax: SQF or (deprecated) SQS Syntax.

ⓘ
See Community Tools - Code Edition for recommended text editors.


Syntax

In Operation Flashpoint, scripts are limited to SQS Syntax.

The already existing (since Operation Flashpoint v1.85) SQF Syntax was introduced for scripts in Armed Assault. SQS Syntax is still usable but is considered deprecated since.


Script Execution Diagram
Executing Instance: script, function or game engine

Execution

Scripts can be executed from several points in the game:


The commands to execute scripts are:

exec
exec starts a thread for a script in SQS Syntax.
execVM
execVM preprocesses and compiles a SQF Syntax script file and starts a thread for it.
call
call adds provided Code to the stack and wait for it to execute, then returns the code's last returned value.
spawn
spawn starts a thread for provided Code.
ⓘ


See also

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