Script File: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
m (link fix)
(19 intermediate revisions by 4 users not shown)
Line 7: Line 7:
== Usage ==
== 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.
Scripts are mainly used for any game processes where '''timing''' is important. They are unlike [[Function|functions]] where the ''result'' or ''calculation'' is important.


Thus scripts can be used for cutscenes, dialogs, radio scripting and much more.
Thus scripts can be used for cutscenes, dialogs, radio scripting and much more.
Line 18: Line 18:


== Execution ==
== Execution ==
[[Image: Script_Execution.png|frame|right||Script Execution Diagram<br/><br/>'''Executing Instance:''' script, [[Function|function]] or game engine]]


Scripts can be executed from several points in the game:
Scripts can be executed from several points in the game:
Line 23: Line 25:
* Other scripts
* Other scripts
* Other [[Function|functions]]
* Other [[Function|functions]]
* Scripting lines in the [[Mission Editor]]
* Scripting lines in the [[ArmA: Mission Editor|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 (Armed Assault only)
: [[execVM]] starts thread for scripts in [[SQF syntax]].
: [[execVM]] [[compile|compiles]] a script in [[SQF syntax]] and starts a thread for it.


; spawn (Armed Assault only)
; spawn (Armed Assault only)
: [[spawn]] starts a thread for a [[compile|compiled]] script or code and returns a [[Script (Handle)|script handle]].
: [[spawn]] starts a thread for [[compile|compiled]] [[Code]] and returns a [[Script (Handle)|script handle]].
 


; call (Armed Assault only)
'''Note:''' The following statements do not apply for [[Function|functions]].
: [[call]] executes a [[compile|compiled]] script or code within the scope of the current script. Such code is considered a [[Function|function]].


Scripts are running ''besides'' the executing instance. 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]].
Scripts run ''alongside'' (parallels) the executing instance in their own threads. That means that the executing instance (i.e. script or [[Function|function]]) doesn't wait for the script to end. This means scripts should not be used for code that should return a value used in the calling script. This is done 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.
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 ==
== Special Variables ==
Line 75: Line 60:
: You can set the script to sleep for a number of seconds using the command [[sleep]].
: You can set the script to sleep for a number of seconds using the command [[sleep]].


  COMMAND 1;
  STATEMENT 1;
   
   
  // wait 10 seconds
  // wait 10 seconds
  sleep 10;
  sleep 10;
   
   
  COMMAND 2;
  STATEMENT 2;


; Waiting for a condition
; Waiting for a condition
Line 90: Line 75:
  waitUntil BOOL;
  waitUntil BOOL;
   
   
  COMMAND;
  STATEMENT;


=== SQS syntax ===
=== SQS syntax ===
Line 97: Line 82:
: 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.
: 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.


  COMMAND 1
  STATEMENT 1
   
   
  ; wait 10 seconds
  ; wait 10 seconds
  ~10
  ~10
   
   
  COMMAND 2
  STATEMENT 2


; Waiting for a condition
; Waiting for a condition
Line 112: Line 97:
  @BOOL
  @BOOL
   
   
  COMMAND
  STATEMENT


; Waiting for a time
; Waiting for a time
Line 128: Line 113:
* [[SQF syntax]]
* [[SQF syntax]]
* [[SQS syntax]]
* [[SQS syntax]]
* [[Statement]]


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

Revision as of 12:09, 27 September 2011

Template:Stub

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.

Usage

Scripts are mainly used for any game processes where timing is important. They are unlike functions where the result or calculation is important.

Thus scripts can be used for cutscenes, dialogs, radio scripting and much more.

Syntax

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.

Execution

Script Execution Diagram

Executing Instance: script, function or game engine

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 (Armed Assault only)
execVM compiles a script in SQF syntax and starts a thread for it.
spawn (Armed Assault only)
spawn starts a thread for compiled Code and returns a script handle.


Note: The following statements do not apply for functions.

Scripts run alongside (parallels) the executing instance in their own threads. That means that the executing instance (i.e. script or function) doesn't wait for the script to end. This means scripts should not be used for code that should return a value used in the calling script. This is done by functions.

Since Armed Assault, scripts return a script handle which you can use to verify whether a script is still running.

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

Delay
You can set the script to sleep for a number of seconds using the command sleep.
STATEMENT 1;

// wait 10 seconds
sleep 10;

STATEMENT 2;
Waiting for a condition
You can set the script to sleep until a specific condition is met using the command waitUntil.
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 ~, 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 @, 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 &, followed by the time.
&100

; is equivalent to 

@_time >= 100

See also

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