Function: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(Changed to reflect/divide info in new SQS and SQF syntax pages)
Line 1: Line 1:
==Introduction==
==Introduction==


Functions were first introduced into a OFP: Resistance patch.  
Functions were first introduced into an OFP: Resistance patch.  


A function is much like a regular scripting command except that you can use functions to create something like a custom command. A '''function''' is simply a chunk of code that does something, the function can then return a value to the point which 'called' that function or it can simply return [[Nothing]].
Function files use the [sqf syntax|SQF syntax]]


Functions halt all other game engine processes until the function has completed its instructions.  This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes.  When creating a functions you want the function to be short and sweet to achieve the best results.
==Usage==


Function files are denoted with the file extension '''.SQF''' (as opposed to '''.SQS''' used for scripts)
A function is much like a regular scripting command except that you can use functions to create something like a custom command. A '''function''' is simply a chunk of code that does something, the function can then return a value to the point which 'called' that function or it can simply return [[Nothing]].
 
'''Example:'''
myfunctionname.'''sqf'''
 
 
While Sqs [[Script syntax|script syntax]] is line based, functions (see [[call]], [[execVM]], [[compile]], [[then]], [[do]]) are based on structured expressions. End-of-line has no special meaning - it is considered to be equivalent to space or tab, and is therefore not required, even when ending a statement.
 
==Functions in ArmA==
 
Starting with Armed Assault there exist [[Script|scripts]] which use the same structured expression syntax as functions, but can wait suspended, using [[sleep]] or [[waitUntil]]. While '''SQS scripts''' still work, they '''are considered deprecated''' and wherever possible, structured syntax scripts should be used instead. OFP-like Functions are still important in Armed Assault, as the calling script waits until they are executed, while the new type scripts are running parallel.


==Functions in OFP==
Functions differ from scripts in that they halt all other game engine processes until the function has completed its instructions.  This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes.  When creating a functions you want the function to be short and sweet to achieve the best results.


Functions have a limitation of 10,000 loops before they are forced to exit by the game engine in order to maintain some level of stability.


===Operation Flashpoint===


In Operation Flashpoint .sqs scripts could do some things that are not possible in '''functions'''. Scripts can wait suspended until some condition is met, they can also use goto to change execution point at any time.''
Functions are first compiled via [[preprocessfile]] command or loaded dynamically via the [[loadfile]] command. They are then executed via the [[call]] command. Functions in OFP cannot be paused and must finish execution before the game will continue.


==Language Constructs==
===Armed Assault===


Main language contructs used in functions are:
Starting with Armed Assault, functions can wait suspended (like SQS or SQF-style scripts), using [[sleep]] or [[waitUntil]].  
*[[if]]..[[then]]..[[else]]
*[[while]]..[[do]]
* since [[ArmA]]: [[for]] ... [[from]] ... [[to]] ... [[step]]
* since [[ArmA]]: [[switch]] ... [[do]]
*Curled braces '''{ }'''
*Multiple commands (including assigment commands) are delimited with a semicolon.


Result of the last expression evaluated is returned as a function result.
[[Image:Function_Execution_Diagram.jpg]]


This can be [[Nothing]] when a function returns no value.


==Examples==
==Examples==
Line 63: Line 48:


<b>Example 3</b> (inline function)
<b>Example 3</b> (inline function)
An inline-function can be created in any script (e.g init.sqs):
An inline-function can be created in any script:


  FNC_sayhello = {hint format["hello %1",_this];}
  FNC_sayhello = {hint format["hello %1",_this];}
Line 73: Line 58:
Notice that there are '''no''' brackets around the functions arguments which precede the call command.<br>In case the function doesn't require any arguments you can use empty brackets instead (<code>[] call FNC_helloall</code>).
Notice that there are '''no''' brackets around the functions arguments which precede the call command.<br>In case the function doesn't require any arguments you can use empty brackets instead (<code>[] call FNC_helloall</code>).


==Notes==
Due to line-based nature of Sqs scripts it is not possible to create multiline string constants in them.<br>
To overcome this limitation you can store multiline in separate files, and load them using [[loadFile]] or [[preprocessFile]] functions (the second uses C-like preprocessor with // or /* */ comments and #define macros).<br>


==See also==
==See also==
[[call (ArmA)|call]]
[[call]]


[[Category: Scripting_Topics]]
[[Category: Scripting_Topics]]

Revision as of 19:53, 20 December 2006

Introduction

Functions were first introduced into an OFP: Resistance patch.

Function files use the [sqf syntax|SQF syntax]]

Usage

A function is much like a regular scripting command except that you can use functions to create something like a custom command. A function is simply a chunk of code that does something, the function can then return a value to the point which 'called' that function or it can simply return Nothing.

Functions differ from scripts in that they halt all other game engine processes until the function has completed its instructions. This means functions run faster than scripts, and the result of functions is immediate and unambiguous. It can also mean that if a function takes too long to run it will have an adverse effect on game play - large functions or CPU intensive functions can cause the game to seize up until it completes. When creating a functions you want the function to be short and sweet to achieve the best results.

Functions have a limitation of 10,000 loops before they are forced to exit by the game engine in order to maintain some level of stability.

Operation Flashpoint

Functions are first compiled via preprocessfile command or loaded dynamically via the loadfile command. They are then executed via the call command. Functions in OFP cannot be paused and must finish execution before the game will continue.

Armed Assault

Starting with Armed Assault, functions can wait suspended (like SQS or SQF-style scripts), using sleep or waitUntil.

Function Execution Diagram.jpg


Examples

Example 1 (max.sqf) In this example the function returns maximum of first and second argument. 

comment "Return maximum of first and second argument"
private {"_a","_b"};
_a = _this select 0;
_b = _this select 1;
if (_a>_b) then {_a} else {_b}


Example 2 (infantrySafe.sqf) In this example the function returns no value and switches all units to safe mode. 

comment "Switch all infantry units to safe mode";
{
 if (vehicle _x == _x) then
 {
  _x setBehaviour "safe"
 }
} forEach _this


Example 3 (inline function) An inline-function can be created in any script: 

FNC_sayhello = {hint format["hello %1",_this];}

This function can then be called (in other scripts, functions, unit's init lines, trigger activation fields, etc.) via: 

name player call FNC_sayhello

Notice that there are no brackets around the functions arguments which precede the call command.
In case the function doesn't require any arguments you can use empty brackets instead ([] call FNC_helloall).


See also

call

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