Code Optimisation: Difference between revisions

From Bohemia Interactive Community
Jump to navigation Jump to search
(joinString vs + vs format)
m (Added if else and switch comparison)
 
(52 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{SideTOC|0.9}}
{{TOC|side|0.9}}
{{ Informative | This page is about [[Code Optimisation]]. For ''conception'' optimisation, see [[Mission Optimisation]]. }}
{{Feature|informative|This page is about [[Code Optimisation]]. For ''conception'' optimisation, see [[Mission Optimisation]].}}
== Introduction ==
 
This article will try to be a general guide about improving your code '''and''' its performance.
This article will try to be a general guide about improving your code '''and''' its performance.
* The first part ([[#Rules|Rules]]) will focus on having a clean, readable and maintainable code.
* The first part ([[#Rules|Rules]]) will focus on having a clean, readable and maintainable code.
Line 15: Line 15:
With that being said, here are the three basic rules to get yourself in the clear:
With that being said, here are the three basic rules to get yourself in the clear:


# [[#Make it work|Make it work]]
# {{Link|#Make It Work|Make it work}}
# [[#Make it readable|Make it readable]]
# {{Link|#Make It Readable|Make it readable}}
# [[#Optimise then|Optimise then]]
# {{Link|#Optimise Then|Optimise then}}


=== Make it work ===
=== Make It Work ===


{{quote|Premature optimization is the root of all evil.|[https://en.wikipedia.org/wiki/Donald_Knuth Donald Knuth]}}
{{Feature|quote|Premature optimization is the root of all evil.|{{Link|https://en.wikipedia.org/wiki/Donald_Knuth|Donald Knuth}}}}
Your first goal when coding is to make your code do what you want it does. A good way to reach this objective is to read and getting inspired by other people's code. If you understand it by reading it once, it is probably a good source of inspiration.
Your first goal when coding is to make your code do what you want it does. A good way to reach this objective is to read and getting inspired by other people's code. If you understand it by reading it once, it is probably a good source of inspiration.


Line 28: Line 28:
* Read your [[Crash_Files|Arma RPT]] (report) to read more details about the error that happened in your code.
* Read your [[Crash_Files|Arma RPT]] (report) to read more details about the error that happened in your code.


=== Make it readable ===
=== Make It Readable ===


Whether you are cleaning your code or a different person's, you must understand the code without twisting your brain:
Whether you are cleaning your code or a different person's, you must understand the code without twisting your brain:


* While [[SQF syntax|SQF]] ''is'' (non-noticeably) impacted by variable name length, this should not take precedence on the fact that code must be readable by a human being. Variables like '''_u''' instead of '''_uniform''' should not be present.
* While [[SQF Syntax|SQF]] ''is'' (non-noticeably) impacted by variable name length, this should not take precedence on the fact that code must be readable by a human being. Variables like '''_u''' instead of '''_uniform''' should not be present.
* ''One-lining'' (putting everything in one statement) memory improvement is most of the time not worth the headache it gives when trying to read it. Don't overuse it.
* ''One-lining'' (putting everything in one statement) memory improvement is most of the time not worth the headache it gives when trying to read it. Don't overuse it.
* Indentation is important for the human mind, and space is too. Space is free, use it.
* Indentation is important for the human mind, and space is too. Space is free, use it.
Line 41: Line 41:
* Finally, camel-casing (namingLikeThis) your variables will naturally make the code more readable, especially for long names.
* Finally, camel-casing (namingLikeThis) your variables will naturally make the code more readable, especially for long names.


{{Informative | See '''[[Code Best Practices]]''' for more information.}}
{{Feature|informative|See '''[[Code Best Practices]]''' for more information.}}


See the following code:
See the following code:
  _w=[]; {_w pushbackunique primaryweapon _x} foreach((allunits+alldeadmen) select{_x call bis_fnc_objectside==east});
  _w=[]; {_w pushbackunique primaryweapon _x} foreach((allunits+alldeadmen) select{_x call BIS_fnc_objectside==east});


The same example is far more readable with proper spacing, good variable names and intermediate results:
The same example is far more readable with proper spacing, good variable names and intermediate results:
Line 59: Line 59:
==== Constants ====
==== Constants ====
Using a hard-coded constant more than once? Use preprocessor directives rather than storing it in memory or cluttering your code with numbers. Such as:
Using a hard-coded constant more than once? Use preprocessor directives rather than storing it in memory or cluttering your code with numbers. Such as:
a = _x + 1.053;
<sqf>
b = _y + 1.053;
a = _x + 1.053;
b = _y + 1.053;
</sqf>
And
And
_buffer = 1.053;
<sqf>
a = _x + _buffer;
_buffer = 1.053;
b = _y + _buffer;
a = _x + _buffer;
b = _y + _buffer;
</sqf>
Becomes
Becomes
<span style="color: purple; font-weight: bold;">#define BUFFER 1.053</span> {{codecomment|// note: no semicolon}}
<sqf>
_a = _x + BUFFER;
#define BUFFER 1.053 // note: no semicolon
_b = _y + BUFFER;
_a = _x + BUFFER;
{{Informative | Using the '''#define''' macro only works within the current [[SQF]] ''file''. Such definition will not propagate anywhere else.}}
_b = _y + BUFFER;
</sqf>
{{Feature|informative|Using the <sqf inline>#define</sqf> macro only works within the current [[SQF Syntax|SQF]] ''file''. Such definition will not propagate anywhere else.}}
'''Global''' "constants" can be defined ''via'' a [[Description.ext]] declaration, though, and accessed using [[getMissionConfigValue]] command:
'''Global''' "constants" can be defined ''via'' a [[Description.ext]] declaration, though, and accessed using [[getMissionConfigValue]] command:


Line 76: Line 82:
var1 = 123;
var1 = 123;
var2 = "123";
var2 = "123";
var3[] = {1,2,3};
var3[] = { 1, 2, 3 };
rand = __EVAL(random 999);
rand = __EVAL(random 999);
</syntaxhighlight>
</syntaxhighlight>


Usage in code:
Usage in code:
[[hint]] [[str]] [[getMissionConfigValue]] "var1"; // 123 {{codecomment|// 0.0007 ms}}
<sqf>
[[hint]] [[str]] [[getMissionConfigValue]] "var2"; // "123" {{codecomment|// 0.0008 ms}}
hint str getMissionConfigValue "var1"; // 123 // 0.0007 ms
[[hint]] [[str]] [[getMissionConfigValue]] "var3"; // [1,2,3] {{codecomment|// 0.0017 ms}}
hint str getMissionConfigValue "var2"; // "123" // 0.0008 ms
[[hint]] [[str]] [[getMissionConfigValue]] "rand"; // constant random, for example 935.038 {{codecomment|// 0.0007 ms}}
hint str getMissionConfigValue "var3"; // [1,2,3] // 0.0017 ms
hint str getMissionConfigValue "rand"; // constant random, for example 935.038 // 0.0007 ms
</sqf>


The [[getMissionConfigValue]] command searching [[Description.ext]] from top to bottom,
The [[getMissionConfigValue]] command searching [[Description.ext]] from top to bottom,
it is better for a matter of performance to put all your definitions at the top of the file.
it is better for a matter of performance to put all your definitions at the top of the file.


=== Optimise then ===
=== Optimise Then ===


Once you know what is what, you can understand your code better.
Once you know what is what, you can understand your code better.
* Use private variables instead of global variables (preceded with an underscore) as much as possible
* Use [[Variables#Scopes|private variables]] instead of global variables (preceded by an underscore) as much as possible.
* You were iterating multiple times on the same array?
* You were iterating multiple times on the same array?
** You should be able to spot your issue now.
** You should be able to spot your issue now.
* Are you using [[execVM]] on the same file, many times?
* Are you using [[execVM]] on the same file, many times?
** Store your function in memory to avoid file reading every call with {{Inline code|_myFunction {{=}} [[compile]] [[preprocessFileLineNumbers]] "myFile.sqf";}}
** Store your function in memory to avoid file reading every call ( e.g <sqf inline>_myFunction = compile preprocessFileLineNumbers "myFile.sqf";</sqf>).
* Is your variable name far too long?
* Is your variable name far too long?
** Find a smaller name, according to the variable scope:
** Find a smaller name, according to the variable scope;<!--
e.g
-->e.g:<sqf>{ _opforUnitUniform = uniform _x; systemChat _opforUnitUniform; } forEach _allOpforUnits;</sqf><!--
{ _opforUnitUniform {{=}} [[uniform]] [[_x]]; [[systemChat]] _opforUnitUniform; } [[forEach]] _allOpforUnits;
-->becomes<sqf>{ _uniform = uniform _x; systemChat _uniform; } forEach _allOpforUnits;</sqf>
becomes
{ _uniform {{=}} [[uniform]] [[_x]]; [[systemChat]] _uniform; } [[forEach]] _allOpforUnits;




== Code optimisation ==
== Code Optimisation ==


{{Important|
{{Feature|important|
'''Please note:''' Tests and benchmarks were done with the latest {{arma3}} version at the time {{GVI|arma3|1.82}} with '''Tank DLC'''. Game engine performance may have changed since.<br />Benchmark result in milliseconds (ms) is an average for '''10000''' iterations.}}
'''Please note:''' Tests and benchmarks were done with the latest {{arma3}} version at the time {{GVI|arma3|1.82}} with '''Tank DLC'''. Game engine performance may have changed since.<br>Benchmark result in milliseconds (ms) is an average for '''10000''' iterations.
}}


{{Informative|
{{Feature|informative|
{{colorball|red|1.125}}   means you '''must''' change your ways today, ''or with us you will ride…''<br />
{{Colorball|red|1.125}} means you '''must''' change your ways today, ''or with us you will ride…''<br>
{{colorball|orange|1.125}} means you may want to look at it if you are targeting pure performance<br />
{{Colorball|orange|1.125}} means you may want to look at it if you are targeting pure performance<br>
{{colorball|green|1.125}} means the gain is little to insignificant. Going through your code for this replacement is not worth it. You ''may'' only consider it for future code.
{{Colorball|green|1.125}} means the gain is little to insignificant. Going through your code for this replacement is not worth it. You ''may'' only consider it for future code.
}}
}}


=== Scheduled and unscheduled environment ===
=== Scheduled and Unscheduled Environment ===


There are two code environment types, [[Scheduler#Scheduled_Environment|scheduled]] and [[Scheduler#Unscheduled_Environment|unscheduled]].
There are two code environment types, [[Scheduler#Scheduled_Environment|scheduled]] and [[Scheduler#Unscheduled_Environment|unscheduled]].
* A '''scheduled''' script has an execution time limit of '''3 ms''' before being suspended to the benefit of another script until its turn comes back. It is a bit slower than '''unscheduled''' but [[canSuspend|suspending]] ([[sleep]], [[waitUntil]]) is allowed.
* A '''scheduled''' script has an execution time limit of '''3 ms''' before being suspended to the benefit of another script until its turn comes back. It is a bit slower than unscheduled, but [[canSuspend|suspending]] ([[sleep]], [[waitUntil]]) is allowed.
* An '''unscheduled''' script is not watched and will run without limitations. It is recommended for time-critical scripts, but [[canSuspend|suspending]] ([[sleep]], [[waitUntil]]) is '''not''' allowed!
* An '''unscheduled''' script is not watched and will run without limitations. It is recommended for time-critical scripts, but [[canSuspend|suspending]] ([[sleep]], [[waitUntil]]) is '''not''' allowed!
{{Informative | See [[Scheduler]] full article for more information.}}
{{Feature|informative|See [[Scheduler]] for more information.}}
 
=== {{Colorball|orange|0.9}} Variable Assignment ===
 
<sqf>
private _myVar = [33, 66] select false; // 0.0013 ms
private _myVar = if (false) then { 33; } else { 66; }; // 0.0020 ms
private "_myVar"; if (false) then { _myVar = 33; } else { _myVar = 66; }; // 0.0025 ms
</sqf>


=== {{colorball|orange|0.9}} Lazy evaluation ===
=== {{Colorball|orange|0.9}} Lazy Evaluation ===


[[private]] _myVar = [33, 66] [[select]] ([[false]]); {{codecomment|// 0.0013 ms}}
In [[SQF Syntax|SQF]] the following code will evaluate every single condition, even if one fails:
[[private]] _myVar = [[if]] ([[false]]) [[then]] { 33; } [[else]] { 66; }; {{codecomment|// 0.0020 ms}}
<sqf>if (a && b && c) then {};</sqf>
[[private]] "_myVar"; [[if]] ([[false]]) [[then]] { _myVar = 33; } [[else]] { _myVar = 66; }; {{codecomment|// 0.0025 ms}}
Even if <var>a</var> returns [[false]] (and thus the entire [[Boolean]] expression can no longer become [[true]]), <var>b</var> and <var>c</var> will still be executed and evaluated regardless.


=== {{colorball|orange|0.9}} Successive condition check ===
To avoid this behaviour, one can either imbricate [[if]] statements or use '''lazy evaluation'''. The latter is done like so:
<sqf>if (a && { b && { c } }) then {};</sqf>
In the example above, condition evaluation stops once any condition evaluates to [[false]].


In [[SQF syntax|SQF]] the following code will check '''all and every''' conditions, even if one fails:
==== Influence on Semantics ====
[[if]] (condition1 && condition2 && condition3) [[then]] { {{codecomment|/* thenCode */}} };
Depending on the arrangement of the curly brackets, lazy evaluation can change the precedence (and therefore the semantics) of a condition. Consider this example:
This code will check ''condition1'', and if it is not [[true]] ''condition2'' and ''condition3'' will execute anyway.
To avoid this behaviour, you can either imbricate [[if|ifs]] or use '''lazy evaluation''' such as the following:
[[if]] (condition1 && { condition2 } && { condition3 }) [[then]] { {{codecomment|/* thenCode */}} };
This method will stop condition evaluation on the first [[false]] statement.


Using lazy evaluation is not always the best way as it could speed up the code as well as slow it down, depending on the current condition being evaluated:
{| class="wikitable align-center" style="margin: auto"
["[[true]] &nbsp;|| {&nbsp;[[false]]&nbsp; || {[[false]]}}", [[nil]], 100000] [[call]] [[BIS_fnc_codePerformance]]; {{codecomment|// 0.00080 ms}}
|-
["[[true]] &nbsp;|| &nbsp;{[[false]]} || {[[false]]}&nbsp;", [[nil]], 100000] [[call]] [[BIS_fnc_codePerformance]]; {{codecomment|// 0.00105 ms}}
! rowspan="2" | Expression !! colspan="3" | Condition Value !! rowspan="2" | Evaluated Conditions !! rowspan="2" | Result
["[[false]] || &nbsp;&nbsp;[[false]] &nbsp;|| &nbsp;[[false]]&nbsp;&nbsp;", [[nil]], 100000] [[call]] [[BIS_fnc_codePerformance]]; {{codecomment|// 0.00123 ms}}
|-
["[[true]] &nbsp;|| &nbsp;&nbsp;[[false]] &nbsp;|| &nbsp;[[false]]&nbsp;&nbsp;", [[nil]], 100000] [[call]] [[BIS_fnc_codePerformance]]; {{codecomment|// 0.00128 ms}}
! <var>a</var> !! <var>b</var> !! <var>c</var>
["[[false]] || &nbsp;{[[false]]} || {[[false]]}&nbsp;", [[nil]], 100000] [[call]] [[BIS_fnc_codePerformance]]; {{codecomment|// 0.00200 ms}}
|-
| style="text-align: left" | <sqf>a && b  ||  c</sqf> || rowspan="3" | [[false]] || rowspan="3" | any [[Boolean]] || rowspan="3" | [[true]] || <var>a</var>, <var>b</var>, <var>c</var> || [[true]]
|-
| style="text-align: left" | <sqf>a && {b} || {c}</sqf> || <var>a</var>, <var>c</var> || [[true]]
|-
| style="text-align: left" | <sqf>a && {b  || {c}}</sqf> || <var>a</var> || [[false]]
|}


=== {{colorball|red|0.9}} Concatenating multiple small strings together ===
==== Performance ====
Using lazy evaluation is not always the best way as it can both speed up and slow down the code, depending on the current condition being evaluated:
<sqf>
["true  || { false  || {false}}", nil, 100000] call BIS_fnc_codePerformance; // 0.00080 ms
["true  ||  {false} || {false} ", nil, 100000] call BIS_fnc_codePerformance; // 0.00105 ms
["false ||  false  || false  ", nil, 100000] call BIS_fnc_codePerformance; // 0.00123 ms
["true  ||  false  ||  false  ", nil, 100000] call BIS_fnc_codePerformance; // 0.00128 ms
["false ||  {false} || {false} ", nil, 100000] call BIS_fnc_codePerformance; // 0.00200 ms
</sqf>


{{Inline code|myString {{=}} myString + otherString}} works fine for small strings, however the bigger the string gets the slower the operation becomes:
=== {{Colorball|red|0.9}} Concatenating Strings ===
myString = ""; [[for]] "_i" [[from]] 1 [[to]] 10000 [[do]] { myString = myString + "123" }; {{codecomment|// 290 ms}}
 
<sqf inline>myString = myString + otherString</sqf> works fine for small strings, however the bigger the string gets the slower the operation becomes:
<sqf>myString = ""; for "_i" from 1 to 10000 do { myString = myString + "123" }; // 290 ms</sqf>


The solution is to use a string array that you will concatenate later:
The solution is to use a string array that you will concatenate later:
strings = [];
<sqf>
[[for]] "_i" [[from]] 1 [[to]] 10000 [[do]] {strings [[pushBack]] "123"};
strings = [];
strings = strings [[joinString]] ""; {{codecomment|// 30 ms}}
for "_i" from 1 to 10000 do { strings pushBack "123" };
strings = strings joinString ""; // 30 ms
</sqf>


=== {{colorball|red|0.9}} Manipulating arrays ===
=== {{Colorball|red|0.9}} Array Manipulation ===


==== Adding elements ====
==== Add Elements ====
New commands [[append]] and [[pushBack]] hold the best score.
New commands [[append]] and [[pushBack]] hold the best score.
_array = [0,1,2,3]; _array [[append]] [4,5,6]; {{codecomment|// 0.0020 ms}}
<sqf>
_array = [0,1,2,3]; _array = _array + [4,5,6]; {{codecomment|// 0.0023 ms}}
_array = [0,1,2,3]; _array append [4,5,6]; // 0.0020 ms
_array = [0,1,2,3]; { _array [[set]] <nowiki>[</nowiki>[[count]] _array, [[_x]]]; } [[forEach]] [4,5,6]; {{codecomment|// 0.0080 ms}}
_array = [0,1,2,3]; _array = _array + [4,5,6]; // 0.0023 ms
_array = [0,1,2,3]; { _array set [count _array, _x]; } forEach [4,5,6]; // 0.0080 ms
</sqf>
 
<sqf>
_array = [0,1,2,3]; _array pushBack 4; // 0.0016 ms
_array = [0,1,2,3]; _array = _array + [4]; // 0.0021 ms
_array = [0,1,2,3]; _array set [count _array, _x]; // 0.0022 ms
</sqf>
 
==== Iterate Elements ====
[[for]] is twice as fast as [[forEach]] and is recommended '''if [[Magic_Variables#x|_x]] is not required'''.
 
<sqf>
private _array = allUnits; // 64 units 256 units
 
// if the amount of loops is known
for "_i" from 0 to 63 do {}; // 0.0120 ms 0.0460 ms
for "_i" from 0 to count _array -1 do {}; // 0.0170 ms 0.0480 ms
for "_i" from 0 to count _array -1 do { private _x = _array select _i }; // 0.0500 ms 0.1896 ms <
for "_i" from 0 to count _array -1 do { private _x = array select _i; _x setDamage 0 }; // 0.107 ms 0.39 ms
 
{} forEach _array; // 0.0250 ms 0.098 ms
{ _x setDamage 0 } forEach _array; // 0.0770 ms 0.312 ms
 
_array apply {}; // 0.0250 ms 0.098 ms
_array apply { _x setDamage 0 }; // 0.0770 ms 0.312 ms
 
private _i = 0;
while { _i < 64 } do { _i = _i + 1; }; // 0.048 ms 0.200 ms


_array = [0,1,2,3]; _array [[pushBack]] 4; {{codecomment|// 0.0016 ms}}
// counts array every loop
_array = [0,1,2,3]; _array = _array + [4]; {{codecomment|// 0.0021 ms}}
private _i = 0;
_array = [0,1,2,3]; _array [[set]] <nowiki>[</nowiki>[[count]] _array, [[_x]]]; {{codecomment|// 0.0022 ms}}
while { _i < count _array } do { _i = _i + 1; }; // 0.062 ms 0.247 ms


==== Removing elements ====
private _i = 0;
_array = [0,1,2,3]; _array [[deleteAt]] 0; {{codecomment|// 0.0015 ms}}
while { _i < 64 } do { private _x = _array select _i; _i = _i + 1; }; // 0.086 ms 0.42 ms
_array = [0,1,2,3]; _array [[set]] [0, [[objNull]]]; _array = _array - <nowiki>[</nowiki>[[objNull]]]; {{codecomment|// 0.0038 ms}}
</sqf>


_array = [0,1,2,3]; _array [[deleteRange]] [1, 2]; {{codecomment|// 0.0018 ms}}
==== Remove Elements ====
_array = [0,1,2,3]; { _array [[set]] <nowiki>[</nowiki>[[_x]], [[objNull]]] } [[forEach]] [1,2]; _array = _array - <nowiki>[</nowiki>[[objNull]]]; {{codecomment|// 0.0078 ms}}
<sqf>
_array = [0,1,2,3]; _array deleteAt 0; // 0.0015 ms
_array = [0,1,2,3]; _array set [0, objNull]; _array = _array - [objNull]; // 0.0038 ms
</sqf>


=== {{colorball|red|0.9}} Multiplayer recommendations ===
<sqf>
_array = [0,1,2,3]; _array deleteRange [1, 2]; // 0.0018 ms
_array = [0,1,2,3]; { _array set [_x, objNull] } forEach [1,2]; _array = _array - [objNull]; // 0.0078 ms
</sqf>
 
=== {{Colorball|red|0.9}} Multiplayer Recommendations ===


* Do not saturate the network with information: [[publicVariable]] or public [[setVariable]] shouldn't be used at high frequency, else '''everyone's performance experience''' is at risk!
* Do not saturate the network with information: [[publicVariable]] or public [[setVariable]] shouldn't be used at high frequency, else '''everyone's performance experience''' is at risk!
* The server is supposed to have a good CPU and a lot of memory, use it: store functions, run them from it, send only the result to the clients
* The server is supposed to have a good CPU and a lot of memory, use it: store functions, run them from it, send only the result to the clients
* [[publicVariable]] and [[setVariable]] variable name length impacts network, be sure to send well-named, understandable variables<br /><span style="font-size: 0.9em;">(''and not '''<span style="word-break: break-word">playerNameBecauseThePlayerIsImportantAndWeNeedToKnowWhoTheyAreAllTheTimeEspeciallyInsideThisImpressiveFunction</span>''''')</span>
* [[publicVariable]] and [[setVariable]] variable name length impacts network, be sure to send well-named, understandable variables<br><span style="font-size: 0.9em;">(''and not '''<span style="word-break: break-word">playerNameBecauseThePlayerIsImportantAndWeNeedToKnowWhoTheyAreAllTheTimeEspeciallyInsideThisImpressiveFunction</span>''''')</span>
* Use, use and use [[remoteExec]] &amp; [[remoteExecCall]]. Ditch [[BIS_fnc_MP]] for good!
* Use, use and use [[remoteExec]] &amp; [[remoteExecCall]]. Ditch [[BIS_fnc_MP]] for good!
{{Informative | See [[Multiplayer Scripting]] for more information.}}
{{Feature|informative|See [[Multiplayer Scripting]] for more information.}}
<!--
 
=== {{colorball|red|0.9}} createSimpleObject vs createVehicle ===
''TODO''
* [[createSimpleObject]] is over '''43x''' faster than createVehicle!
createVehicle ["Land_VR_Shape_01_cube_1m_F",[0,0,0],[],0,"none"];// ~3.5 ms
createSimpleObject ["a3\structures_f_mark\vr\shapes\vr_shape_01_cube_1m_f.p3d",[0,0,0]];// ~0.08 ms
private _cube = createVehicle ["Land_VR_Shape_01_cube_1m_F",[0,0,0],[],0,"none"]; deleteVehicle _cube; // 244 cycles, 4.11066 ms
private _cube = createSimpleObject ["a3\structures_f_mark\vr\shapes\vr_shape_01_cube_1m_f.p3d",[0,0,0]]; deleteVehicle _cube; // freezes the game for seconds, but 9748 cycles / 0.102585 ms?? Cannot confirm.
* Creating an object at [0,0,0] ''then'' [[setPos]] it will be faster than creating it at the wanted pos (''if spawning obstacles are present? What about "CAN_COLLIDE"?'')
-->


== Equivalent commands performance ==
== Equivalent Commands Performance ==


=== {{colorball|orange|0.9}} call ===
=== {{Colorball|orange|0.9}} call ===


[[call]] without arguments is faster than call with arguments:
[[call]] without arguments is faster than call with arguments:
<sqf>
[[call]] {}; {{codecomment|// 0.0007 ms}}
call {}; // 0.0007 ms
123 [[call]] {}; {{codecomment|// 0.0013 ms}}
123 call {}; // 0.0013 ms
</sqf>


Since the variables defined in the parent scope will be available in the [[call]]ed child scope, it could be possible to speed up the code by avoiding passing arguments all together, for example writing:
Since the variables defined in the parent scope will be available in the [[call]]ed child scope, it could be possible to speed up the code by avoiding passing arguments all together, for example writing:
[[player]] [[addEventHandler]] ["HandleDamage", { [[call]] my_fnc_damage }];
<sqf>player addEventHandler ["HandleDamage", { call my_fnc_damage }];</sqf>
instead of:
instead of:
[[player]] [[addEventHandler]] ["HandleDamage", { _this [[call]] my_fnc_damage }];
<sqf>player addEventHandler ["HandleDamage", { _this call my_fnc_damage }];</sqf>


<!-- TODO: compare execVM and spawn, and/or waitUntil scriptDone / call
=== {{Colorball|red|0.9}} execVM and call ===
=== {{colorball|red|0.9}} execVM and call ===


{{Feature|important|
Using [[execVM]] multiple times make the game read the file and recompile it every time.<br>
Using [[execVM]] multiple times make the game read the file and recompile it every time.<br>
If you will use the script more than once, store its code in a variable:
If you use the script more than once, store its code in a variable or better, make it a [[Arma 3: Functions Library|Function]]!
}}
<sqf>
// myFile.sqf is an EMPTY file
private _myFunction = compile preprocessFileLineNumbers "myFile.sqf"; // compile time is done only once
call _myFunction; // 0.0009 ms
execVM "myFile.sqf"; // 0.275 ms


{{cc|myFile.sqf is an '''empty''' file}}
// myFile.sqf is BIS_fnc_showRespawnMenu
_myFunction {{=}} [[compile]] [[preprocessFileLineNumbers]] "myFile.sqf"; {{cc|compile time is done only once}}
private _myFunction = compile preprocessFileLineNumbers "myFile.sqf"; // compile time is done only once
[[call]] _myFunction; {{cc|0.0009 ms}}
["close"] call _myFunction; // 0.0056 ms
["close"] execVM "myFile.sqf"; // 0.506 ms
[[execVM]] "myFile.sqf"; {{cc|0.275 ms}}
</sqf>


{{cc|myFile.sqf is [[BIS_fnc_showRespawnMenu]]}}
=== {{Colorball|orange|0.9}} loadFile, preprocessFile and preprocessFileLineNumbers ===
_myFunction {{=}} [[compile]] [[preprocessFileLineNumbers]] "myFile.sqf";
["close"] [[call]] _myFunction; {{cc|0.0056 ms}}
["close"] [[execVM]] "myFile.sqf"; {{cc|0.506 ms}}


{{cc|myFile.sqf is a '''missing''' file}}
<sqf>
_myFunction {{=}} [[compile]] [[preprocessFileLineNumbers]] "myFile.sqf";
// myFile.sqf is an empty file
[[call]] _myFunction; {{cc|0.0009 ms}}
loadFile "myFile.sqf"; // 0.219 ms
preprocessFile "myFile.sqf"; // 0.353 ms
[[execVM]] "myFile.sqf"; {{cc|0.275 ms}}
preprocessFileLineNumbers "myFile.sqf"; // 0.355 ms
-->
</sqf>
 
<sqf>
// myFile.sqf is BIS_fnc_showRespawnMenu
loadFile "myFile.sqf"; // 0.3516 ms
preprocessFile "myFile.sqf"; // 2.75 ms
preprocessFileLineNumbers "myFile.sqf"; // 2.73 ms
</sqf>
 
<sqf>
// myFile.sqf is a missing file
loadFile "myFile.sqf"; // 0.692 ms
preprocessFile "myFile.sqf"; // 0.6225 ms
preprocessFileLineNumbers "myFile.sqf"; // 0.6225 ms
</sqf>
 
{{Feature|important|The comparison of [[loadFile]] with preprocessFile* is not exactly fair as [[loadFile]] doesn't preprocess the file's content.<br><!--
-->On the other hand, the loaded file cannot contain any {{cc|}} or {{codecomment|/* */}} comments nor any [[PreProcessor Commands|preprocessor instructions]] (including debug information like line numbers or file information).}}


=== {{colorball|orange|0.9}} loadFile, preprocessFile and preprocessFileLineNumbers ===
=== {{Colorball|green|0.9}} if ===


{{cc|myFile.sqf is an '''empty''' file}}
<sqf>
[[loadFile]] "myFile.sqf"; {{cc|0.219 ms}}
if (condition) then { /* thenCode */ }; // 0.0011 ms
[[preprocessFile]] "myFile.sqf"; {{cc|0.353 ms}}
if (condition) exitWith { /* exitCode */ }; // 0.0014 ms
[[preprocessFileLineNumbers]] "myFile.sqf"; {{cc|0.355 ms}}
if (condition) then { /* thenCode */ } else { /* elseCode */ }; // 0.0015 ms
if (condition) then [{ /* thenCode */ }, { /* elseCode */ }]; // 0.0016 ms
</sqf>


{{cc|myFile.sqf is [[BIS_fnc_showRespawnMenu]]}}
=== {{Colorball|green|0.9}} if and select ===
[[loadFile]] "myFile.sqf"; {{cc|0.3516 ms}}
[[preprocessFile]] "myFile.sqf"; {{cc|2.75 ms}}
[[preprocessFileLineNumbers]] "myFile.sqf"; {{cc|2.73 ms}}


{{cc|myFile.sqf is a '''missing''' file}}
Use <sqf inline>[array] select boolean</sqf> instead of the lazy-evaluated [[if]].
[[loadFile]] "myFile.sqf"; {{cc|0.692 ms}}
<sqf>
[[preprocessFile]] "myFile.sqf"; {{cc|0.6225 ms}}
_result = ["false result", "true result"] select true; // 0.0011 ms
[[preprocessFileLineNumbers]] "myFile.sqf"; {{cc|0.6225 ms}}
_result = if (true) then { "true result"; } else { "false result"; }; // 0.0017 ms
</sqf>


{{Important | The comparison of [[loadFile]] with preprocessFile* is not exactly fair as [[loadFile]] doesn't preprocess the file's content.<br><!--
=== {{Colorball|orange|0.9}} if and switch ===
-->On the other hand, the loaded file cannot contain any {{cc|}} or {{codecomment|/* */}} comments nor any [[PreProcessor Commands|preprocessor instructions]] (including debug informations like line numbers or file informations).}}


=== {{colorball|green|0.9}} if ===
<sqf>
_result = call {
if (false) exitWith {};
if (false) exitWith {};
if (true)  exitWith {};
if (false) exitWith {};
if (false) exitWith {};
}; // 0.0032 ms
</sqf>


[[if]]..[[then]] { {{codecomment|/* thenCode */}} }; {{codecomment|// 0.0011 ms}}
<sqf>
[[if]]..[[exitWith]] { {{codecomment|/* exitCode */}} }; {{codecomment|// 0.0014 ms}}
_result = switch (true) do {
[[if]]..[[then]] { {{codecomment|/* thenCode */}} } [[else]] { {{codecomment|/* elseCode */}} }; {{codecomment|// 0.0015 ms}}
case (false): {};
[[if]]..[[then]] [{ {{codecomment|/* thenCode */}} }, { {{codecomment|/* elseCode */}} }] {{codecomment|// 0.0016 ms}}
case (false): {};
case (true) : {};
case (false): {};
case (false): {};
}; // 0.0047 ms
</sqf>


=== {{colorball|green|0.9}} if and select ===
=== {{Colorball|green|0.9}} if else and switch ===


Use {{Inline code|[array] [[select]] [[Boolean]]}} instead of the lazy-evaluated [[if]].
<sqf>
_result = ["false result", "true result"] [[select]] [[true]]; {{codecomment|// 0.0011 ms}}
_mode = "killed";
_result = [[if]] ([[true]]) [[then]] { "true result"; } [[else]] { "false result"; }; {{codecomment|// 0.0017 ms}}


=== {{colorball|orange|0.9}} if and switch ===
switch _mode do {
    case "init": {};
    case "killed": {};
    case "respawned": {};
}; // 0.0019 ms
</sqf>


_result = [[call]] {
<sqf>
[[if]] ([[false]]) [[exitWith]] {};
_mode = "killed";
[[if]] ([[false]]) [[exitWith]] {};
[[if]] ([[true]])  [[exitWith]] {};
[[if]] ([[false]]) [[exitWith]] {};
[[if]] ([[false]]) [[exitWith]] {};
}; {{codecomment|// 0.0032 ms}}


_result = [[switch]] ([[true]]) [[do]] {
if (_mode == "init") then {} else {
[[case]] ([[false]]): {};
    if (_mode == "killed") then {} else {
[[case]] ([[false]]): {};
        if (_mode == "respawned") then {};
[[case]] ([[true]]) : {};
    };
[[case]] ([[false]]): {};
}; // 0.0019 ms
[[case]] ([[false]]): {};
</sqf>
}; {{codecomment|// 0.0047 ms}}


=== {{colorball|orange|0.9}} in vs find ===
=== {{Colorball|orange|0.9}} in vs find ===


Since Arma 3 v1.95.146032 one can use [[in]] instead of [[find]] to check existence of a string within a string:
<sqf>
// String search
"bar" in "foobar" // 0.0008 ms
"foobar" find "bar" > -1 // 0.0012 ms
</sqf>


''Old method''
<sqf>
"foobar" [[find]] "bar" > -1 {{codecomment| // 0.0012 ms}}
// array search - case-sensitive
''New method''
"bar" in ["foo", "Bar", "bar", "BAR"]; // 0.0012 ms
"bar" [[in]] "foobar" {{codecomment| // 0.0008 ms}}
["foo", "Bar", "bar", "BAR"] find "bar" > -1; // 0.0016 ms
</sqf>


=== {{colorball|orange|0.9}} for ===
=== {{Colorball|orange|0.9}} for ===


The {{Inline code|[[for]]..[[from]]..[[to]]..[[do]]}} is twice as fast as its alternative syntax, {{Inline code|[[for]]..[[do]]}}.
The {{hl|[[for]]..[[from]]..[[to]]..[[do]]}} is twice as fast as its alternative syntax, {{hl|[[for]]..[[do]]}}.
[[for]] "_i" [[from]] 0 [[to]] 10 [[do]] { {{codecomment|/* forCode */}} }; {{codecomment|// 0.015 ms}}
<sqf>
[[for]] [{_i = 0}, {_i < 100}, {_i = _i + 1}] [[do]] { {{codecomment|/* forCode */}} }; {{codecomment|// 0.030 ms}}
for "_i" from 0 to 10 do { /* forCode */ }; // 0.015 ms
for [{ _i = 0 }, { _i < 100 }, { _i = _i + 1 }] do { /* forCode */ }; // 0.030 ms
</sqf>


=== {{colorball|green|0.9}} forEach vs count vs findIf ===
=== {{Colorball|green|0.9}} forEach vs count vs findIf ===


Both [[forEach]] and [[count]] commands will step through ''all'' the array elements and both commands will contain reference to current element with the [[_x]] variable.
Both [[forEach]] and [[count]] commands will step through ''all'' the array elements and both commands will contain reference to current element with the [[Magic Variables#x|_x]] variable.
However, [[count]] loop is a little faster than [[forEach]] loop, but it does not benefit from the [[_forEachIndex]] variable.<br />
However, [[count]] loop is a little faster than [[forEach]] loop, but it does not benefit from the [[Magic Variables#forEachIndex|_forEachIndex]] variable.<br>
Also, there is a limitation as the code inside [[count]] expects [[Boolean]] or [[Nothing]] while the command itself returns [[Number]].
Also, there is a limitation as the code inside [[count]] expects [[Boolean]] or [[Nothing]] while the command itself returns [[Number]].
This limitation is very important if you try to replace your [[forEach]] by [[count]]. If you have to add a extra true/false/nil at the end to make count work, it will be slower than the forEach equivalent.
This limitation is very important if you try to replace your [[forEach]] by [[count]]. If you have to add an extra [[true]]/[[false]]/[[nil]] at the end to make [[count]] work, it will be slower than the [[forEach]] equivalent.


{ [[diag_log]] [[_x]] } [[count]]   [1,2,3,4,5]; {{codecomment|// 0.082 ms}}
<sqf>
{ [[diag_log]] [[_x]] } [[forEach]] [1,2,3,4,5]; {{codecomment|// 0.083 ms}}
{ diag_log _x } count  [1,2,3,4,5]; // 0.082 ms
{ diag_log _x } forEach [1,2,3,4,5]; // 0.083 ms
</sqf>


{{codecomment|// with an empty array}}
<sqf>
_someoneIsNear = ([[allUnits]] [[findIf]] { [[_x]] [[distance]] [0,0,0] < 1000 }) != -1; {{codecomment|// 0.0046 ms}}
// with an empty array
_someoneIsNear = { [[_x]] [[distance]] [0,0,0] < 1000 } [[count]] [[allUnits]] > 0; {{codecomment|// '''0.0047 ms'''}}
_someoneIsNear = (allUnits findIf { _x  distance [0,0,0] < 1000 }) != -1; // 0.0046 ms
_someoneIsNear = {
_someoneIsNear = { _x distance [0,0,0] < 1000 } count allUnits > 0; // 0.0047 ms <
[[if]] ([[_x]] [[distance]] [0,0,0] < 1000) [[exitWith]] { [[true]] };
_someoneIsNear = {
[[false]]
if (_x distance [0,0,0] < 1000) exitWith { true };
} [[forEach]] [[allUnits]]; {{codecomment|// 0.0060 ms}}
false
} forEach allUnits; // 0.0060 ms
</sqf>


{{codecomment|// with a 30 items array}}
<sqf>
_someoneIsNear = ([[allUnits]] [[findIf]] { [[_x]] [[distance]] [0,0,0] < 1000 }) != -1; {{codecomment|// 0.0275 ms}}
// with a 30 items array
_someoneIsNear = { [[_x]] [[distance]] [0,0,0] < 1000 } [[count]] [[allUnits]] > 0; {{codecomment|// '''0.0645 ms'''}}
_someoneIsNear = (allUnits findIf { _x  distance [0,0,0] < 1000 }) != -1; // 0.0275 ms
_someoneIsNear = {
_someoneIsNear = { _x distance [0,0,0] < 1000 } count allUnits > 0; // 0.0645 ms <
[[if]] ([[_x]] [[distance]] [0,0,0] < 1000) [[exitWith]] { [[true]] };
_someoneIsNear = {
[[false]]
if (_x distance [0,0,0] < 1000) exitWith { true };
} [[forEach]] [[allUnits]]; {{codecomment|// 0.0390 ms}}
false
} forEach allUnits; // 0.0390 ms
</sqf>


=== {{colorball|red|0.9}} findIf ===
=== {{Colorball|red|0.9}} findIf ===


[[findIf]] stops array iteration as soon as the condition is met.
[[findIf]] stops array iteration as soon as the condition is met.
[0,1,2,3,4,5,6,7,8,9] [[findIf]] { [[_x]] == 2 }; {{codecomment|// 0.0050 ms}}
<sqf>
{ [[if]] ([[_x]] == 2) [[exitWith]] { [[_forEachIndex]]; }; } [[forEach]] [0,1,2,3,4,5,6,7,8,9]; {{codecomment|// 0.0078 ms}}
[0,1,2,3,4,5,6,7,8,9] findIf { _x == 2 }; // 0.0050 ms
_quantity = { [[_x]] == 2 } [[count]] [0,1,2,3,4,5,6,7,8,9]; {{codecomment|// 0.0114 ms}}
{ if (_x == 2) exitWith { _forEachIndex; }; } forEach [0,1,2,3,4,5,6,7,8,9]; // 0.0078 ms
_quantity = { _x == 2 } count [0,1,2,3,4,5,6,7,8,9]; // 0.0114 ms
</sqf>


=== {{colorball|green|0.9}} format vs str ===
=== {{Colorball|green|0.9}} format vs str ===


[[str]] 33 {{codecomment|// 0.0016 ms}}
<sqf>
[[format]] ["%1", 33] {{codecomment|// 0.0022 ms}}
str 33; // 0.0016 ms
format ["%1", 33]; // 0.0022 ms
</sqf>


=== {{colorball|green|0.9}} + vs format vs joinString ===
=== {{Colorball|green|0.9}} + vs format vs joinString ===


[[str]] 33 + [[str]] 45 + [[str]] 78 {{codecomment|// 0.0059 ms - no length limit}}
non-[[String]] data:
[[format]] ["%1%2%3", 33, 45, 78] {{codecomment|// 0.0054 ms - limited to ~8Kb}}
<sqf>
[33, 45, 78] [[joinString]] "" {{codecomment|// 0.0052 ms - no length limit}}
[33, 45, 78] joinString ""; // 0.0052 ms - no length limit
format ["%1%2%3", 33, 45, 78]; // 0.0054 ms - limited to ~8Kb
str 33 + str 45 + str 78; // 0.0059 ms - no length limit
</sqf>


=== {{colorball|orange|0.9}} private ===
[[String]] data:
<sqf>
["str1", "str2", "str3"] joinString ""; // 0.0015 ms - no length limit
format ["%1%2%3", "str1", "str2", "str3"]; // 0.0015 ms - limited to ~8Kb
"str1" + "str2" + "str3"; // 0.0012 ms - no length limit
</sqf>


Direct declaration ({{Inline code|[[private]] _var {{=}} value}}) is faster than declaring ''then'' assigning the variable.
=== {{Colorball|orange|0.9}} private ===
[[private]] _a = 1;
[[private]] _b = 2;
[[private]] _c = 3;
[[private]] _d = 4;
{{codecomment|// 0.0023 ms}}


[[private]] ["_a", "_b", "_c", "_d"];
Direct declaration (<sqf inline>private _var = value</sqf>) is faster than declaring ''then'' assigning the variable.
_a = 1;
<sqf>
_b = 2;
private _a = 1;
_c = 3;
private _b = 2;
_d = 4;
private _c = 3;
{{codecomment|// 0.0040 ms}}
private _d = 4;
// 0.0023 ms
</sqf>


However, if you have to reuse the same variable in a loop, external declaration is faster.<br />
<sqf>
The reason behind this is that a declaration in the loop will create, assign and delete the variable in each loop.<br />
private ["_a", "_b", "_c", "_d"];
_a = 1;
_b = 2;
_c = 3;
_d = 4;
// 0.0040 ms
</sqf>
 
However, if you have to reuse the same variable in a loop, external declaration is faster.<br>
The reason behind this is that a declaration in the loop will create, assign and delete the variable in each loop.<br>
An external declaration creates the variable only once and the loop only assigns the value.
An external declaration creates the variable only once and the loop only assigns the value.
[[private]] ["_a", "_b", "_c", "_d"];
<sqf>
[[for]] "_i" [[from]] 1 [[to]] 10 [[do]]
private ["_a", "_b", "_c", "_d"];
{
for "_i" from 1 to 10 do
_a = 1; _b = 2; _c = 3; _d = 4;
{
};
_a = 1; _b = 2; _c = 3; _d = 4;
{{codecomment|// 0.0195 ms}}
};
// 0.0195 ms
</sqf>


[[for]] "_i" [[from]] 1 [[to]] 10 [[do]]
<sqf>
{
for "_i" from 1 to 10 do
[[private]] _a = 1; [[private]] _b = 2; [[private]] _c = 3; [[private]] _d = 4;
{
};
private _a = 1; private _b = 2; private _c = 3; private _d = 4;
{{codecomment|// 0.0235 ms}}
};
// 0.0235 ms
</sqf>


=== {{colorball|orange|0.9}} isNil ===
=== {{Colorball|orange|0.9}} isNil ===


[[isNil]] "varName"; {{codecomment|// 0.0007 ms}}
<sqf>
[[isNil]] {varName}; {{codecomment|// 0.0012 ms}}
isNil "varName"; // 0.0007 ms
isNil { varName }; // 0.0012 ms
</sqf>


=== {{colorball|red|0.9}} isEqualType and typeName ===
=== {{Colorball|red|0.9}} isEqualType and typeName ===


[[isEqualType]] is much faster than [[typeName]]
[[isEqualType]] is much faster than [[typeName]]
"string" [[isEqualType]] 33; {{codecomment|// 0.0006 ms}}
<sqf>
[[typeName]] "string" == [[typeName]] 33; {{codecomment|// 0.0018 ms}}
"string" isEqualType 33; // 0.0006 ms
typeName "string" == typeName 33; // 0.0018 ms
</sqf>


=== {{colorball|green|0.9}} isEqualTo and count ===
=== {{Colorball|green|0.9}} isEqualTo and count ===


{{codecomment|// with a items array}}
<sqf>
[[allUnits]] [[isEqualTo]] []; {{codecomment|// 0.0040 ms}}
// with a items array
[[count]] [[allUnits]] == 0; {{codecomment|// 0.0043 ms}}
allUnits isEqualTo []; // 0.0040 ms
count allUnits == 0; // 0.0043 ms
</sqf>


=== {{colorball|green|0.9}} select and param ===
=== {{Colorball|green|0.9}} select and param ===


  [1,2,3] [[select]] 0; {{codecomment|// 0.0008 ms}}
<sqf>
  [1,2,3] [[param]] [0]; {{codecomment|// 0.0011 ms}}
[1,2,3] select 0; // 0.0008 ms
[1,2,3] param [0]; // 0.0011 ms
</sqf>


=== {{colorball|orange|0.9}} objectParent and vehicle ===
=== {{Colorball|red|0.9}} createSimpleObject vs createVehicle ===


[[isNull]] [[objectParent]] [[player]]; {{codecomment|// 0.0013 ms}}
<sqf>
[[vehicle]] [[player]] == [[player]]; {{codecomment|// 0.0022 ms}}
// createSimpleObject is over 43× faster than createVehicle!
deleteVehicle createSimpleObject ["a3\structures_f_mark\vr\shapes\vr_shape_01_cube_1m_f.p3d", [0,0,0]]; // ~0.08 ms
deleteVehicle createSimpleObject ["Land_VR_Shape_01_cube_1m_F", [0,0,0]]; // ~3.2 ms
deleteVehicle createVehicle ["Land_VR_Shape_01_cube_1m_F", [0,0,0], [], 0, "CAN_COLLIDE"]; // ~2.7 ms
deleteVehicle createVehicle ["Land_VR_Shape_01_cube_1m_F", [0,0,0], [], 0, "NONE"]; // ~78 ms
</sqf>


=== {{colorball|red|0.9}} nearEntities and nearestObjects ===
=== {{Colorball|orange|0.9}} objectParent and vehicle ===
 
<sqf>
isNull objectParent player; // 0.0013 ms
vehicle player == player; // 0.0022 ms
</sqf>
 
[[File:nearEntities vs nearestObjects.png|thumb|150px|right|nearEntities vs nearestObjects]]
=== {{Colorball|red|0.9}} nearEntities and nearestObjects ===


[[nearEntities]] is much faster than [[nearestObjects]] given on range and amount of objects within the given range.
[[nearEntities]] is much faster than [[nearestObjects]] given on range and amount of objects within the given range.
If range is over 100 meters it is highly recommended to use [[nearEntities]] over [[nearestObjects]].
If range is over 100 meters it is highly recommended to use [[nearEntities]] over [[nearestObjects]].
{{codecomment|// tested with a NATO rifle squad amongst solar power plant panels on [[Altis]] at coordinates [20762,15837]}}
<sqf>
[[getPosATL]] [[player]] [[nearEntities]] [["Man"], 50]; {{codecomment|// 0.0075 ms}}
// tested with a NATO rifle squad amongst solar power plant panels on Altis at coordinates [20762,15837]
[[nearestObjects]] <nowiki>[</nowiki>[[getPosATL]] [[player]], ["Man"], 50]; {{codecomment|// 0.0145 ms}}
getPosATL player nearEntities [["Man"], 50]; // 0.0075 ms
nearestObjects [getPosATL player, ["Man"], 50]; // 0.0145 ms
</sqf>


{{Important|[[nearEntities]] only searches for [[alive]] objects and on-foot soldiers.<br />
{{Feature|important|[[nearEntities]] only searches for [[alive]] objects and on-foot soldiers.<br>
In-vehicle units, killed units, destroyed vehicles, static objects and buildings will be ignored.}}
In-vehicle units, killed units, destroyed vehicles, static objects and buildings will be ignored.}}


=== {{colorball|orange|0.9}} Global variables vs local variables ===
{{Clear}}
=== {{Colorball|orange|0.9}} Global Variables vs Local Variables ===


If you need to use global variable repeatedly in a loop, copy its value to local variable and use local variable instead:
If you need to use global variable repeatedly in a loop, copy its value to local variable and use local variable instead:


<code>SomeGlobalVariable = [123];
<sqf>
[[for]] "_i" [[from]] 1 [[to]] 100 [[do]]
SomeGlobalVariable = [123];
for "_i" from 1 to 100 do
{
{
SomeGlobalVariable [[select]] 0;
SomeGlobalVariable select 0;
};
};
{{codecomment|// 0.13 ms}}</code>
// 0.13 ms
</sqf>


is noticeably slower than
is noticeably slower than


<code>SomeGlobalVariable = [123];
<sqf>
[[private]] _var = SomeGlobalVariable;
SomeGlobalVariable = [123];
[[for]] "_i" [[from]] 1 [[to]] 100 [[do]]
private _var = SomeGlobalVariable;
for "_i" from 1 to 100 do
{
{
_var [[select]] 0;
_var select 0;
};
};
{{codecomment|// 0.08 ms}}</code>
// 0.08 ms
</sqf>


=== {{colorball|green|0.9}} Config path delimiter ===
=== {{Colorball|green|0.9}} Config path delimiter ===


{{Inline code|[[config_greater_greater_name|>>]]}} is slightly faster than {{Inline code|[[config_/_name|/]]}} when used in config path with [[configFile]] or [[missionConfigFile]].
{{hl|[[config greater greater name|>>]]}} is slightly faster than {{hl|[[a / b|/]]}} when used in config path with [[configFile]] or [[missionConfigFile]].
[[configFile]] >> "CfgVehicles"; {{codecomment|// 0.0019 ms}}
<sqf>
[[configFile]] / "CfgVehicles"; {{codecomment|// 0.0023 ms}}
configFile >> "CfgVehicles"; // 0.0019 ms
{{Informative | A config path can be stored in a variable for later use, saving CPU time: ''{{Inline code|_cfgVehicles {{=}} [[configFile]] >> "CfgVehicles"}}'' }}
configFile  / "CfgVehicles"; // 0.0023 ms
</sqf>
{{Feature|informative|A config path can be stored in a variable for later use, saving CPU time: <sqf inline>_cfgVehicles = configFile >> "CfgVehicles"</sqf>.}}


=== {{colorball|orange|0.9}} getPos* and setPos* ===
=== {{Colorball|orange|0.9}} getPos* and setPos* ===


[[getPosWorld]] {{codecomment|// 0.0015 ms}}
<sqf>
[[getPosASL]] {{codecomment|// 0.0016 ms}}
getPosWorld // 0.0015 ms
[[getPosATL]] {{codecomment|// 0.0016 ms}}
getPosASL // 0.0016 ms
[[getPos]] {{codecomment|// 0.0020 ms}}
getPosATL // 0.0016 ms
[[position]] {{codecomment|// 0.0020 ms}}
getPosASLW // 0.0023 ms
[[getPosVisual]] {{codecomment|// 0.0021 ms}}
getPos // 0.0030-0.0300 ms; performance depends on where this command is used - see its documentation
[[visiblePosition]] {{codecomment|// 0.0021 ms}}
position // same as getPos
[[getPosASLW]] {{codecomment|// 0.0023 ms}}
getPosVisual // same as getPos
visiblePosition // same as getPos
</sqf>


[[setPosWorld]] {{codecomment|// 0.0060 ms}}
<sqf>
[[setPosASL]] {{codecomment|// 0.0060 ms}}
setPosWorld // 0.0060 ms
[[setPosATL]] {{codecomment|// 0.0060 ms}}
setPosASL // 0.0060 ms
[[setPos]] {{codecomment|// 0.0063 ms}}
setPosATL // 0.0060 ms
[[setPosASLW]] {{codecomment|// 0.0068 ms}}
setPos // 0.0063 ms
[[setVehiclePosition]] {{codecomment|// 0.0077 ms with "CAN_COLLIDE"}}
setPosASLW // 0.0068 ms
{{codecomment|// 0.0390 ms with "NONE"}}
setVehiclePosition // 0.0077 ms with "CAN_COLLIDE"
// 0.0390 ms with "NONE"
</sqf>


=== {{colorball|orange|0.9}} toLower and toLowerANSI ===
=== {{Colorball|orange|0.9}} toLower/toUpper vs toLowerANSI/toUpperANSI ===


{{codecomment|// _myString is a 100 chars "aAaAaA(…)" string}}
<sqf>
[[toLower]] _myString; {{codecomment|// 0.0016 ms}}
// _myString is a 100 chars "aAaAaA(…)" string
[[toLowerANSI]] _myString; {{codecomment|// 0.0006 ms}}
toLowerANSI _myString; // 0.0006 ms
toLower _myString; // 0.0016 ms


{{Informative|Similar performance difference between [[toUpper]] and [[toUpperANSI]].}}
toUpperANSI _myString; // 0.0006 ms
toUpper _myString; // 0.0016 ms
</sqf>


== Conversion from earlier versions ==


Each iteration of Bohemia games ({{ofp}}, {{arma}}, {{arma2}}, {{tkoh}}, {{arma3}}) brought their own new commands, especially {{arma2}} and {{arma3}}.<br />
== Equivalent Data Structures Performance ==
 
=== Key-Value Data Structures ===
 
<sqf>
private _hashMap = createHashMapFromArray [["id", 123], ["name", "player name"], ["unit", player]]; // since Arma 3 v2.02
private _goodFormat = [["id", "name", "unit"], [123, "player name", player]];
private _slowFormat = [["id", 123], ["name", "player name"], ["unit", player]];
</sqf>
 
<sqf>
private _name = _hashMap get "name"; // 0.0018ms
 
// this takes 0.0038ms:
private _index = _goodFormat select 0 find "name"; // loop in engine
private _name = _goodFormat select 1 select _index;
 
// this takes 0.0116ms:
private _index = _slowFormat findIf { _x select 0 == "name" }; // loop in script
private _name = _slowFormat select _index select 1;
</sqf>
 
{{Feature|informative|[[:Category:Function Group: Database|Database Functions]] use a slow format.}}
 
 
== Conversion From Earlier Versions ==
 
Each iteration of Bohemia games ({{ofp}}, {{arma1}}, {{arma2}}, {{tkoh}}, {{arma3}}) brought their own new commands, especially {{arma2}} and {{arma3}}.<br>
For that, if you are converting scripts from older versions of the engine, the following aspects should be reviewed.
For that, if you are converting scripts from older versions of the engine, the following aspects should be reviewed.


Line 479: Line 666:
** [[select]]
** [[select]]


=== Array operations ===
=== Array Operations ===


* '''Adding an item:''' {{Inline code|myArray [[valuea_plus_valueb|+]] [element]}} and {{Inline code|myArray [[set]] <nowiki>[</nowiki>[[count]] myArray, element]}} have been replaced by [[pushBack]]
* '''Adding an item:''' <sqf inline>myArray + [element]</sqf> and <sqf inline>myArray set [count myArray, element]</sqf> have been replaced by [[pushBack]]
* '''Selecting a random item:''' [[BIS_fnc_selectRandom]] has been replaced by [[selectRandom]]
* '''Selecting a random item:''' [[BIS_fnc_selectRandom]] has been replaced by [[selectRandom]]
* '''Removing items:''' {{Inline code|myArray [[set]] [1, objNull]; myArray [[a_-_b|-]] [objNull]}} has been replaced by [[deleteAt]] and [[deleteRange]]
* '''Removing items:''' <sqf inline>myArray set [1, objNull]; myArray - [objNull]</sqf> has been replaced by [[deleteAt]] and [[deleteRange]]
* '''Concatenating:''' {{Inline code|myArray {{=}} myArray [[valuea_plus_valueb|+]] [element]}} has been ''reinforced'' with [[append]]: if you don't need the original array to be modified, use [[+]]
* '''Concatenating:''' <sqf inline>myArray = myArray + [element]</sqf> has been ''reinforced'' with [[append]]: if you don't need the original array to be modified, use [[+]]
* '''Comparing:''' use [[isEqualTo]] instead of [[BIS_fnc_areEqual]]
* '''Comparing:''' use [[isEqualTo]] instead of [[BIS_fnc_areEqual]]
* '''Finding common items:''' [[in]] [[forEach]] loop has been replaced by [[arrayIntersect]]
* '''Finding common items:''' [[in]] [[forEach]] loop has been replaced by [[arrayIntersect]]
* '''Condition filtering:''' [[forEach]] can be replaced by [[select]] (alternative syntax)
* '''Condition filtering:''' [[forEach]] can be replaced by [[select]] (alternative syntax)
result = (arrayOfNumbers [[select]] { [[_x]] % 2 == 0 }); {{codecomment|// 1.55 ms}}
<sqf>result = (arrayOfNumbers select { _x % 2 == 0 }); // 1.55 ms</sqf>
<sqf>
result = [];
{
if (_x % 2 == 0) then { result pushBack _x; };
} forEach arrayOfNumbers; // 2.57 ms
</sqf>
 
=== Vector Operations ===


result = [];
* [[BIS_fnc_vectorMultiply]] has been replaced by [[vectorMultiply]] (at least 6x faster)
{
* [[BIS_fnc_vectorDivide]] too, to an extent (see [[BIS_fnc_vectorDivide|its page]] for more information)
[[if]] ([[_x]] % 2 == 0) [[then]] { result [[pushBack]] [[_x]]; };
} [[forEach]] arrayOfNumbers; {{codecomment|// 2.57 ms}}


=== String operations ===
<sqf>
private _vector = [102, 687, 1543];
private _factor = 53;
 
_vector vectorMultiply _factor; // 0.0028 ms
[_vector, _factor] call BIS_fnc_vectorMultiply; // 0.0145 ms
 
_vector vectorMultiply (1 / _factor); // 0.003 ms - but beware of 0 divisor
[_vector, _factor] call BIS_fnc_vectorDivide; // 0.017 ms
</sqf>
 
=== String Operations ===


[[String]] manipulation has been simplified with the following commands:
[[String]] manipulation has been simplified with the following commands:
* alternative syntax for [[select]]: {{Inline code|string [[select]] index}}
* alternative syntax for [[select]]: <sqf inline>string select index</sqf>
* [[toArray]] and [[toString]] have been ''reinforced'' with [[splitString]] and [[joinString]]
* [[toArray]] and [[toString]] have been ''reinforced'' with [[splitString]] and [[joinString]]


=== Number operations ===
=== Number Operations ===


* [[BIS_fnc_linearConversion]] has been replaced by [[linearConversion]]. The command is '''9 times faster'''.
* [[BIS_fnc_linearConversion]] has been replaced by [[linearConversion]]. The command is '''9 times faster'''.
* [[BIS_fnc_selectRandomWeighted]] has been replaced by [[selectRandomWeighted]]. The command is '''7 times faster'''.
* [[BIS_fnc_selectRandomWeighted]] has been replaced by [[selectRandomWeighted]]. The command is '''7 times faster'''.


=== Type comparison ===
=== Type Comparison ===


* [[typeName]] has been more than ''reinforced'' with [[isEqualType]].
* [[typeName]] has been more than ''reinforced'' with [[isEqualType]].
Line 513: Line 717:


* [[BIS_fnc_MP]] has been replaced by [[remoteExec]] and [[remoteExecCall]] and internally uses them. Use the engine commands from now on!
* [[BIS_fnc_MP]] has been replaced by [[remoteExec]] and [[remoteExecCall]] and internally uses them. Use the engine commands from now on!
{{Feature|informative|See also [[Multiplayer Scripting]].}}


=== Parameters ===
=== Parameters ===
Line 519: Line 725:




[[Category: Scripting Topics]]
[[Category:Arma Scripting Tutorials]]

Latest revision as of 05:56, 19 May 2024

This page is about Code Optimisation. For conception optimisation, see Mission Optimisation.

This article will try to be a general guide about improving your code and its performance.

  • The first part (Rules) will focus on having a clean, readable and maintainable code.
  • The second part (Code optimisation) is about improving performance, sometimes trading it against code readability.
  • The third part (Equivalent commands performance) mentions commands that in appearance have identical effects but may differ in terms of performance according to the use you may have of them.
  • The fourth part (Conversion from earlier versions) is a hopefully helpful, short guide about useful new commands or syntaxes to replace the old ways.


Rules

In the domain of development, any rule is a rule of thumb. If a rule states for example that it is better that a line of code doesn't go over 80 characters, it doesn't mean that any line must not go over 80 characters; sometimes, the situation needs it. If you have a good structure, do not change your code to enforce a single arbitrary rule. If you break many of them, you may have to change something. Again, this is according to your judgement.

With that being said, here are the three basic rules to get yourself in the clear:

  1. Make it work
  2. Make it readable
  3. Optimise then

Make It Work

«
« Premature optimization is the root of all evil. » – Donald Knuth

Your first goal when coding is to make your code do what you want it does. A good way to reach this objective is to read and getting inspired by other people's code. If you understand it by reading it once, it is probably a good source of inspiration.

  • When starting from scratch if you know what you want but miss the specific steps to get to your point, it is a good practice to write down in your native language what you want to do. E.g Get all the units near the city, and for each west soldier in them, add 30% damage.
  • Use -showScriptErrors startup parameter and make sure your code doesn't throw errors. Not only will your code run slower but it may also not work at all. Be sure to read the error, isolate the issue and sort it out thanks to this Wiki.
  • Read your Arma RPT (report) to read more details about the error that happened in your code.

Make It Readable

Whether you are cleaning your code or a different person's, you must understand the code without twisting your brain:

  • While SQF is (non-noticeably) impacted by variable name length, this should not take precedence on the fact that code must be readable by a human being. Variables like _u instead of _uniform should not be present.
  • One-lining (putting everything in one statement) memory improvement is most of the time not worth the headache it gives when trying to read it. Don't overuse it.
  • Indentation is important for the human mind, and space is too. Space is free, use it.
  • Same goes for line return; it helps to see a code block wrapping multiple common instructions instead of having to guess where it starts and stops.
  • Do you see the same code multiple times, only with different parameters? Now is the time to write a function!
  • If you have a lot of if..else, you may want to look at a switch condition, or again break your code in smaller functions.
  • Is your function code far too long? Break it in understandable-sized bites for your own sanity.
  • Finally, camel-casing (namingLikeThis) your variables will naturally make the code more readable, especially for long names.
See Code Best Practices for more information.

See the following code:

_w=[]; {_w pushbackunique primaryweapon _x} foreach((allunits+alldeadmen) select{_x call BIS_fnc_objectside==east});

The same example is far more readable with proper spacing, good variable names and intermediate results:

_weaponNames = [];
_allUnitsAliveAndDead = allUnits + allDeadMen;
_allEastAliveAndDead = _allUnitsAliveAndDead select { _x call BIS_fnc_objectSide == east };
{ _weaponNames pushBackUnique primaryWeapon _x } forEach _allEastAliveAndDead;

Constants

Using a hard-coded constant more than once? Use preprocessor directives rather than storing it in memory or cluttering your code with numbers. Such as:

a = _x + 1.053; b = _y + 1.053;

And

_buffer = 1.053; a = _x + _buffer; b = _y + _buffer;

Becomes

#define BUFFER 1.053 // note: no semicolon _a = _x + BUFFER; _b = _y + BUFFER;

Using the #define macro only works within the current SQF file. Such definition will not propagate anywhere else.

Global "constants" can be defined via a Description.ext declaration, though, and accessed using getMissionConfigValue command:

Declaration in Description.ext:

var1 = 123;
var2 = "123";
var3[] = { 1, 2, 3 };
rand = __EVAL(random 999);

Usage in code:

hint str getMissionConfigValue "var1"; // 123 // 0.0007 ms hint str getMissionConfigValue "var2"; // "123" // 0.0008 ms hint str getMissionConfigValue "var3"; // [1,2,3] // 0.0017 ms hint str getMissionConfigValue "rand"; // constant random, for example 935.038 // 0.0007 ms

The getMissionConfigValue command searching Description.ext from top to bottom, it is better for a matter of performance to put all your definitions at the top of the file.

Optimise Then

Once you know what is what, you can understand your code better.

  • Use private variables instead of global variables (preceded by an underscore) as much as possible.
  • You were iterating multiple times on the same array?
    • You should be able to spot your issue now.
  • Are you using execVM on the same file, many times?
  • Is your variable name far too long?


Code Optimisation

Please note: Tests and benchmarks were done with the latest Arma 3 version at the time Arma 3 logo black.png1.82 with Tank DLC. Game engine performance may have changed since.
Benchmark result in milliseconds (ms) is an average for 10000 iterations.
means you must change your ways today, or with us you will ride…
means you may want to look at it if you are targeting pure performance
means the gain is little to insignificant. Going through your code for this replacement is not worth it. You may only consider it for future code.

Scheduled and Unscheduled Environment

There are two code environment types, scheduled and unscheduled.

  • A scheduled script has an execution time limit of 3 ms before being suspended to the benefit of another script until its turn comes back. It is a bit slower than unscheduled, but suspending (sleep, waitUntil) is allowed.
  • An unscheduled script is not watched and will run without limitations. It is recommended for time-critical scripts, but suspending (sleep, waitUntil) is not allowed!
See Scheduler for more information.

Variable Assignment

private _myVar = [33, 66] select false; // 0.0013 ms private _myVar = if (false) then { 33; } else { 66; }; // 0.0020 ms private "_myVar"; if (false) then { _myVar = 33; } else { _myVar = 66; }; // 0.0025 ms

Lazy Evaluation

In SQF the following code will evaluate every single condition, even if one fails:

if (a && b && c) then {};

Even if a returns false (and thus the entire Boolean expression can no longer become true), b and c will still be executed and evaluated regardless.

To avoid this behaviour, one can either imbricate if statements or use lazy evaluation. The latter is done like so:

if (a && { b && { c } }) then {};

In the example above, condition evaluation stops once any condition evaluates to false.

Influence on Semantics

Depending on the arrangement of the curly brackets, lazy evaluation can change the precedence (and therefore the semantics) of a condition. Consider this example:

Expression Condition Value Evaluated Conditions Result
a b c
a && b || c
false any Boolean true a, b, c true
a && {b} || {c}
a, c true
a && {b || {c}}
a false

Performance

Using lazy evaluation is not always the best way as it can both speed up and slow down the code, depending on the current condition being evaluated:

["true || { false || {false}}", nil, 100000] call BIS_fnc_codePerformance; // 0.00080 ms ["true || {false} || {false} ", nil, 100000] call BIS_fnc_codePerformance; // 0.00105 ms ["false || false || false ", nil, 100000] call BIS_fnc_codePerformance; // 0.00123 ms ["true || false || false ", nil, 100000] call BIS_fnc_codePerformance; // 0.00128 ms ["false || {false} || {false} ", nil, 100000] call BIS_fnc_codePerformance; // 0.00200 ms

Concatenating Strings

myString = myString + otherString works fine for small strings, however the bigger the string gets the slower the operation becomes:

myString = ""; for "_i" from 1 to 10000 do { myString = myString + "123" }; // 290 ms

The solution is to use a string array that you will concatenate later:

strings = []; for "_i" from 1 to 10000 do { strings pushBack "123" }; strings = strings joinString ""; // 30 ms

Array Manipulation

Add Elements

New commands append and pushBack hold the best score.

_array = [0,1,2,3]; _array append [4,5,6]; // 0.0020 ms _array = [0,1,2,3]; _array = _array + [4,5,6]; // 0.0023 ms _array = [0,1,2,3]; { _array set [count _array, _x]; } forEach [4,5,6]; // 0.0080 ms

_array = [0,1,2,3]; _array pushBack 4; // 0.0016 ms _array = [0,1,2,3]; _array = _array + [4]; // 0.0021 ms _array = [0,1,2,3]; _array set [count _array, _x]; // 0.0022 ms

Iterate Elements

for is twice as fast as forEach and is recommended if _x is not required.

private _array = allUnits; // 64 units 256 units // if the amount of loops is known for "_i" from 0 to 63 do {}; // 0.0120 ms 0.0460 ms for "_i" from 0 to count _array -1 do {}; // 0.0170 ms 0.0480 ms for "_i" from 0 to count _array -1 do { private _x = _array select _i }; // 0.0500 ms 0.1896 ms < for "_i" from 0 to count _array -1 do { private _x = array select _i; _x setDamage 0 }; // 0.107 ms 0.39 ms {} forEach _array; // 0.0250 ms 0.098 ms { _x setDamage 0 } forEach _array; // 0.0770 ms 0.312 ms _array apply {}; // 0.0250 ms 0.098 ms _array apply { _x setDamage 0 }; // 0.0770 ms 0.312 ms private _i = 0; while { _i < 64 } do { _i = _i + 1; }; // 0.048 ms 0.200 ms // counts array every loop private _i = 0; while { _i < count _array } do { _i = _i + 1; }; // 0.062 ms 0.247 ms private _i = 0; while { _i < 64 } do { private _x = _array select _i; _i = _i + 1; }; // 0.086 ms 0.42 ms

Remove Elements

_array = [0,1,2,3]; _array deleteAt 0; // 0.0015 ms _array = [0,1,2,3]; _array set [0, objNull]; _array = _array - [objNull]; // 0.0038 ms

_array = [0,1,2,3]; _array deleteRange [1, 2]; // 0.0018 ms _array = [0,1,2,3]; { _array set [_x, objNull] } forEach [1,2]; _array = _array - [objNull]; // 0.0078 ms

Multiplayer Recommendations

  • Do not saturate the network with information: publicVariable or public setVariable shouldn't be used at high frequency, else everyone's performance experience is at risk!
  • The server is supposed to have a good CPU and a lot of memory, use it: store functions, run them from it, send only the result to the clients
  • publicVariable and setVariable variable name length impacts network, be sure to send well-named, understandable variables
    (and not playerNameBecauseThePlayerIsImportantAndWeNeedToKnowWhoTheyAreAllTheTimeEspeciallyInsideThisImpressiveFunction)
  • Use, use and use remoteExec & remoteExecCall. Ditch BIS_fnc_MP for good!
See Multiplayer Scripting for more information.


Equivalent Commands Performance

call

call without arguments is faster than call with arguments:

call {}; // 0.0007 ms 123 call {}; // 0.0013 ms

Since the variables defined in the parent scope will be available in the called child scope, it could be possible to speed up the code by avoiding passing arguments all together, for example writing:

player addEventHandler ["HandleDamage", { call my_fnc_damage }];

instead of:

player addEventHandler ["HandleDamage", { _this call my_fnc_damage }];

execVM and call

Using execVM multiple times make the game read the file and recompile it every time.
If you use the script more than once, store its code in a variable or better, make it a Function!

// myFile.sqf is an EMPTY file private _myFunction = compile preprocessFileLineNumbers "myFile.sqf"; // compile time is done only once call _myFunction; // 0.0009 ms execVM "myFile.sqf"; // 0.275 ms // myFile.sqf is BIS_fnc_showRespawnMenu private _myFunction = compile preprocessFileLineNumbers "myFile.sqf"; // compile time is done only once ["close"] call _myFunction; // 0.0056 ms ["close"] execVM "myFile.sqf"; // 0.506 ms

loadFile, preprocessFile and preprocessFileLineNumbers

// myFile.sqf is an empty file loadFile "myFile.sqf"; // 0.219 ms preprocessFile "myFile.sqf"; // 0.353 ms preprocessFileLineNumbers "myFile.sqf"; // 0.355 ms

// myFile.sqf is BIS_fnc_showRespawnMenu loadFile "myFile.sqf"; // 0.3516 ms preprocessFile "myFile.sqf"; // 2.75 ms preprocessFileLineNumbers "myFile.sqf"; // 2.73 ms

// myFile.sqf is a missing file loadFile "myFile.sqf"; // 0.692 ms preprocessFile "myFile.sqf"; // 0.6225 ms preprocessFileLineNumbers "myFile.sqf"; // 0.6225 ms

The comparison of loadFile with preprocessFile* is not exactly fair as loadFile doesn't preprocess the file's content.
On the other hand, the loaded file cannot contain any //  or /* */ comments nor any preprocessor instructions (including debug information like line numbers or file information).

if

if (condition) then { /* thenCode */ }; // 0.0011 ms if (condition) exitWith { /* exitCode */ }; // 0.0014 ms if (condition) then { /* thenCode */ } else { /* elseCode */ }; // 0.0015 ms if (condition) then [{ /* thenCode */ }, { /* elseCode */ }]; // 0.0016 ms

if and select

Use [array] select boolean instead of the lazy-evaluated if.

_result = ["false result", "true result"] select true; // 0.0011 ms _result = if (true) then { "true result"; } else { "false result"; }; // 0.0017 ms

if and switch

_result = call { if (false) exitWith {}; if (false) exitWith {}; if (true) exitWith {}; if (false) exitWith {}; if (false) exitWith {}; }; // 0.0032 ms

_result = switch (true) do { case (false): {}; case (false): {}; case (true) : {}; case (false): {}; case (false): {}; }; // 0.0047 ms

if else and switch

_mode = "killed"; switch _mode do { case "init": {}; case "killed": {}; case "respawned": {}; }; // 0.0019 ms

_mode = "killed"; if (_mode == "init") then {} else { if (_mode == "killed") then {} else { if (_mode == "respawned") then {}; }; }; // 0.0019 ms

in vs find

// String search "bar" in "foobar" // 0.0008 ms "foobar" find "bar" > -1 // 0.0012 ms

// array search - case-sensitive "bar" in ["foo", "Bar", "bar", "BAR"]; // 0.0012 ms ["foo", "Bar", "bar", "BAR"] find "bar" > -1; // 0.0016 ms

for

The for..from..to..do is twice as fast as its alternative syntax, for..do.

for "_i" from 0 to 10 do { /* forCode */ }; // 0.015 ms for [{ _i = 0 }, { _i < 100 }, { _i = _i + 1 }] do { /* forCode */ }; // 0.030 ms

forEach vs count vs findIf

Both forEach and count commands will step through all the array elements and both commands will contain reference to current element with the _x variable. However, count loop is a little faster than forEach loop, but it does not benefit from the _forEachIndex variable.
Also, there is a limitation as the code inside count expects Boolean or Nothing while the command itself returns Number. This limitation is very important if you try to replace your forEach by count. If you have to add an extra true/false/nil at the end to make count work, it will be slower than the forEach equivalent.

{ diag_log _x } count [1,2,3,4,5]; // 0.082 ms { diag_log _x } forEach [1,2,3,4,5]; // 0.083 ms

// with an empty array _someoneIsNear = (allUnits findIf { _x distance [0,0,0] < 1000 }) != -1; // 0.0046 ms _someoneIsNear = { _x distance [0,0,0] < 1000 } count allUnits > 0; // 0.0047 ms < _someoneIsNear = { if (_x distance [0,0,0] < 1000) exitWith { true }; false } forEach allUnits; // 0.0060 ms

// with a 30 items array _someoneIsNear = (allUnits findIf { _x distance [0,0,0] < 1000 }) != -1; // 0.0275 ms _someoneIsNear = { _x distance [0,0,0] < 1000 } count allUnits > 0; // 0.0645 ms < _someoneIsNear = { if (_x distance [0,0,0] < 1000) exitWith { true }; false } forEach allUnits; // 0.0390 ms

findIf

findIf stops array iteration as soon as the condition is met.

[0,1,2,3,4,5,6,7,8,9] findIf { _x == 2 }; // 0.0050 ms { if (_x == 2) exitWith { _forEachIndex; }; } forEach [0,1,2,3,4,5,6,7,8,9]; // 0.0078 ms _quantity = { _x == 2 } count [0,1,2,3,4,5,6,7,8,9]; // 0.0114 ms

format vs str

str 33; // 0.0016 ms format ["%1", 33]; // 0.0022 ms

+ vs format vs joinString

non-String data:

[33, 45, 78] joinString ""; // 0.0052 ms - no length limit format ["%1%2%3", 33, 45, 78]; // 0.0054 ms - limited to ~8Kb str 33 + str 45 + str 78; // 0.0059 ms - no length limit

String data:

["str1", "str2", "str3"] joinString ""; // 0.0015 ms - no length limit format ["%1%2%3", "str1", "str2", "str3"]; // 0.0015 ms - limited to ~8Kb "str1" + "str2" + "str3"; // 0.0012 ms - no length limit

private

Direct declaration (private _var = value) is faster than declaring then assigning the variable.

private _a = 1; private _b = 2; private _c = 3; private _d = 4; // 0.0023 ms

private ["_a", "_b", "_c", "_d"]; _a = 1; _b = 2; _c = 3; _d = 4; // 0.0040 ms

However, if you have to reuse the same variable in a loop, external declaration is faster.
The reason behind this is that a declaration in the loop will create, assign and delete the variable in each loop.
An external declaration creates the variable only once and the loop only assigns the value.

private ["_a", "_b", "_c", "_d"]; for "_i" from 1 to 10 do { _a = 1; _b = 2; _c = 3; _d = 4; }; // 0.0195 ms

for "_i" from 1 to 10 do { private _a = 1; private _b = 2; private _c = 3; private _d = 4; }; // 0.0235 ms

isNil

isNil "varName"; // 0.0007 ms isNil { varName }; // 0.0012 ms

isEqualType and typeName

isEqualType is much faster than typeName

"string" isEqualType 33; // 0.0006 ms typeName "string" == typeName 33; // 0.0018 ms

isEqualTo and count

// with a items array allUnits isEqualTo []; // 0.0040 ms count allUnits == 0; // 0.0043 ms

select and param

[1,2,3] select 0; // 0.0008 ms [1,2,3] param [0]; // 0.0011 ms

createSimpleObject vs createVehicle

// createSimpleObject is over 43× faster than createVehicle! deleteVehicle createSimpleObject ["a3\structures_f_mark\vr\shapes\vr_shape_01_cube_1m_f.p3d", [0,0,0]]; // ~0.08 ms deleteVehicle createSimpleObject ["Land_VR_Shape_01_cube_1m_F", [0,0,0]]; // ~3.2 ms deleteVehicle createVehicle ["Land_VR_Shape_01_cube_1m_F", [0,0,0], [], 0, "CAN_COLLIDE"]; // ~2.7 ms deleteVehicle createVehicle ["Land_VR_Shape_01_cube_1m_F", [0,0,0], [], 0, "NONE"]; // ~78 ms

objectParent and vehicle

isNull objectParent player; // 0.0013 ms vehicle player == player; // 0.0022 ms

nearEntities vs nearestObjects

nearEntities and nearestObjects

nearEntities is much faster than nearestObjects given on range and amount of objects within the given range. If range is over 100 meters it is highly recommended to use nearEntities over nearestObjects.

// tested with a NATO rifle squad amongst solar power plant panels on Altis at coordinates [20762,15837] getPosATL player nearEntities [["Man"], 50]; // 0.0075 ms nearestObjects [getPosATL player, ["Man"], 50]; // 0.0145 ms

nearEntities only searches for alive objects and on-foot soldiers.
In-vehicle units, killed units, destroyed vehicles, static objects and buildings will be ignored.

Global Variables vs Local Variables

If you need to use global variable repeatedly in a loop, copy its value to local variable and use local variable instead:

SomeGlobalVariable = [123]; for "_i" from 1 to 100 do { SomeGlobalVariable select 0; }; // 0.13 ms

is noticeably slower than

SomeGlobalVariable = [123]; private _var = SomeGlobalVariable; for "_i" from 1 to 100 do { _var select 0; }; // 0.08 ms

Config path delimiter

>> is slightly faster than / when used in config path with configFile or missionConfigFile.

configFile >> "CfgVehicles"; // 0.0019 ms configFile / "CfgVehicles"; // 0.0023 ms

A config path can be stored in a variable for later use, saving CPU time: _cfgVehicles = configFile >> "CfgVehicles".

getPos* and setPos*

getPosWorld // 0.0015 ms getPosASL // 0.0016 ms getPosATL // 0.0016 ms getPosASLW // 0.0023 ms getPos // 0.0030-0.0300 ms; performance depends on where this command is used - see its documentation position // same as getPos getPosVisual // same as getPos visiblePosition // same as getPos

setPosWorld // 0.0060 ms setPosASL // 0.0060 ms setPosATL // 0.0060 ms setPos // 0.0063 ms setPosASLW // 0.0068 ms setVehiclePosition // 0.0077 ms with "CAN_COLLIDE" // 0.0390 ms with "NONE"

toLower/toUpper vs toLowerANSI/toUpperANSI

// _myString is a 100 chars "aAaAaA(…)" string toLowerANSI _myString; // 0.0006 ms toLower _myString; // 0.0016 ms toUpperANSI _myString; // 0.0006 ms toUpper _myString; // 0.0016 ms


Equivalent Data Structures Performance

Key-Value Data Structures

private _hashMap = createHashMapFromArray [["id", 123], ["name", "player name"], ["unit", player]]; // since Arma 3 v2.02 private _goodFormat = [["id", "name", "unit"], [123, "player name", player]]; private _slowFormat = [["id", 123], ["name", "player name"], ["unit", player]];

private _name = _hashMap get "name"; // 0.0018ms // this takes 0.0038ms: private _index = _goodFormat select 0 find "name"; // loop in engine private _name = _goodFormat select 1 select _index; // this takes 0.0116ms: private _index = _slowFormat findIf { _x select 0 == "name" }; // loop in script private _name = _slowFormat select _index select 1;

Database Functions use a slow format.


Conversion From Earlier Versions

Each iteration of Bohemia games (Operation Flashpoint, Armed Assault, Arma 2, Take On Helicopters, Arma 3) brought their own new commands, especially Arma 2 and Arma 3.
For that, if you are converting scripts from older versions of the engine, the following aspects should be reviewed.

Loops

Array Operations

result = (arrayOfNumbers select { _x % 2 == 0 }); // 1.55 ms
result = []; { if (_x % 2 == 0) then { result pushBack _x; }; } forEach arrayOfNumbers; // 2.57 ms

Vector Operations

private _vector = [102, 687, 1543]; private _factor = 53; _vector vectorMultiply _factor; // 0.0028 ms [_vector, _factor] call BIS_fnc_vectorMultiply; // 0.0145 ms _vector vectorMultiply (1 / _factor); // 0.003 ms - but beware of 0 divisor [_vector, _factor] call BIS_fnc_vectorDivide; // 0.017 ms

String Operations

String manipulation has been simplified with the following commands:

Number Operations

Type Comparison

Multiplayer

Parameters