Difference between revisions of "execVM"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "[[Category:Scripting_Commands_Take_On_Helicopters" to "[[Category:Scripting Commands Take On Helicopters")
m (Text replacement - "Script (Handle)" to "Script Handle")
 
(41 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Command|Comments=
+
{{RV|type=command
____________________________________________________________________________________________
 
  
| arma |Game name=
+
|game1= arma1
 +
|version1= 1.00
  
|1.00|Game version=
+
|game2= arma2
____________________________________________________________________________________________
+
|version2= 1.00
  
| Compiles and adds [[SQF_syntax|SQF]] [[Script]] to the [[Scheduler|scheduler]] queue and returns script handle. The script is first searched for in the mission folder, then in the campaign scripts folder and finally in the global scripts folder. The script does not execute immediately upon running [[execVM]] command, but with some delay. How much delay is unknown as it largely depends on how many other scripts there are in the queue and how busy is VM. The optional argument is passed to the script in [[private]] variable <tt>_this</tt>. In Arma 3 the script handle is also passed to the script in <tt>_thisScript</tt> variable.
+
|game3= arma2oa
<br><br>In order to understand [[execVM]] consider the following comparison:
+
|version3= 1.50
<code>[[private]] _handle {{=}} _args [[execVM]] "someFile.sqf";
 
{{cc|is practically identical to}}
 
[[private]] _handle {{=}} _args [[spawn]] [[compile]] [[preprocessFileLineNumbers]] "someFile.sqf";</code>
 
So if you need multiple execution of the same file, you might want to store it in a function ([[Functions_Library_(Arma_3)|Functions Library]]), otherwise, for a single execution, [[execVM]] is a good choice.<br><br>
 
  
To see what VM scripts are currently in the scheduler, use [[diag_activeSQFScripts]] command.<br><br>
+
|game4= tkoh
{{Warning | If the file you are executing is not prepared using UTF-8 encoding and contains some characters [[toArray | with codes]] > 127, they might convert incorrectly}}
+
|version4= 1.00
|DESCRIPTION=
 
____________________________________________________________________________________________
 
  
| arguments [[execVM]] filename |SYNTAX=
+
|game5= arma3
 +
|version5= 0.50
  
|p1= arguments: [[Anything]] - arguments accessible as <tt>[[_this]]</tt> in the script |PARAMETER1=
+
|gr1= Program Flow
  
|p2= filename: [[String]] - file with sqf code (doesn't have to have .sqf extension, but not using standard extensions may cause problems later during binarisation) |PARAMETER2=
+
|descr= Compiles and adds an [[SQF Syntax|SQF]] [[Script Handle|script]] to the [[Scheduler|scheduler]] queue and returns script handle (see also {{HashLink|#Example 4}}).
 +
The script does not execute immediately upon running [[execVM]] command but with some delay depending on the VM's scripts queue and engine load.
  
| [[Script]] - script handle, can be used to determine (via [[scriptDone]] (also via [[isNull]] in Arma 3)) when the execVMed script has finished. In Arma 3, the handle is also available inside the execVMed script in <tt>_thisScript</tt> variable.|RETURNVALUE=
+
{{Feature|informative|
 
+
* If the same script is to be executed more than one time, declaring it as a [[Arma 3: Functions Library|Function]] is recommended.
|s2= [[execVM]] filename |SYNTAX2=
+
* The script is searched for in the following directories in that order:
 
+
** mission directory
|p21= filename: [[String]] - file with sqf code (doesn't have to have .sqf extension, but not using standard extensions may cause problems later, during binarisation) |PARAMETER21=
+
** campaign scripts directory
 
+
** global scripts directory.
|r2= [[Script]] - script handle, can be used to determine (via [[scriptDone]] (also via [[isNull]] in Arma 3)) when the execVMed script has finished. In Arma 3, the handle is also available inside the execVMed script in <tt>_thisScript</tt> variable.|RETURNVALUE2=
+
* To see what VM scripts are currently in the scheduler, use [[diag_activeSQFScripts]] command.
____________________________________________________________________________________________
+
}}
 
 
|x1= <code>_handle = [[execVM]] "test.sqf";</code> |EXAMPLE1=
 
 
 
|x2= <code>_handle = [[player]] [[execVM]] "test.sqf";
 
[[waitUntil]] { [[scriptDone]] _handle };</code> |EXAMPLE2=
 
  
|x3= In Arma 3 this is also possible:
+
{{Feature|important|
<code>_handle = [[execVM]] "123.sqf";
+
* The <tt>.sqf</tt> file extension is not mandatory but is strongly recommended as using non-standard extensions may cause problems during binarisation
[[waitUntil]] { [[isNull]] _handle };</code> |EXAMPLE3=
+
* If the script file is not prepared using UTF-8 encoding and contains some characters [[toArray|with codes]] > 127, they might convert incorrectly.
 
 
|x4= <code>[4] [[execVM]] "showDamage.sqf";
 
{{cc|showDamage.sqf}}
 
[[private]] _damage = _this [[select]] 0;
 
[[hint]] [[format]] ["%1", _damage];</code> |EXAMPLE4=
 
____________________________________________________________________________________________
 
 
 
| [[call]], [[spawn]], [[exec]], [[execFSM]], [[scriptDone]], [[scriptNull]], [[terminate]], [[sleep]], [[uiSleep]], [[waitUntil]], [[canSuspend]], [[diag_activeScripts]], [[diag_activeSQFScripts]], [[SQF syntax]], [[Control Structures]] |SEEALSO=
 
 
}}
 
}}
  
<h3 style="display:none">Notes</h3>
+
|s1= arguments [[execVM]] filename
<dl class="command_description">
 
</dl>
 
  
<h3 style="display:none">Notes</h3>
+
|p1= arguments: [[Anything]] - arguments accessible as <tt>[[Magic Variables#this|_this]]</tt> in the script
<dl class="command_description">
 
<!-- Note Section BEGIN -->
 
  
<dd class="notedate">Posted on November 23, 2010 - 15:56
+
|p2= filename: [[String]] - path to the [[SQF Syntax|SQF]] script file
<dt class="note">[[User:Kabilen|Kabilen]]
 
<dd class="note">Passing variables to the script file''
 
  
To pass multiple variables to the script file, use an array e.g:
+
|r1= [[Script Handle]]
  
'''null = [myunit,1234] execVM "test.sqf";'''
+
|s2= [[execVM]] filename
  
Now within test.sqf to access the elements, use the following:
+
|p21= filename: [[String]] - path to the [[SQF Syntax|SQF]] script file
  
'''_myunit = _this select 0;'''<br>
+
|r2= [[Script Handle]]
'''_myvar = _this select 1;'''
 
  
 +
|x1= <code>_handle = [[execVM]] "test.sqf";</code>
  
 +
|x2= <code>_handle = [[player]] [[execVM]] "test.sqf";
 +
[[waitUntil]] { [[scriptDone]] _handle };</code>
 +
The following is also possible in {{arma3}}:
 +
<code>[[private]] _handle = [[execVM]] "123.sqf";
 +
[[waitUntil]] { [[isNull]] _handle };</code>
  
 +
|x3= <code>[<nowiki/>[[player]], 0.75] [[execVM]] "setDamage.sqf";</code>
 +
setDamage.sqf:
 +
<code>[[params]] ["_unit", "_damage"];
 +
_unit [[setDamage]] _damage;</code>
  
<!-- Note Section END -->
+
|x4= [[execVM]] equivalence:<code>[[private]] _handle = _args [[execVM]] "someFile.sqf";
</dl>
+
{{cc|is practically identical to}}
 +
[[private]] _handle = _args [[spawn]] [[compile]] [[preprocessFileLineNumbers]] "someFile.sqf";</code>
  
<h3 style="display:none">Notes</h3>
+
|seealso= [[call]], [[spawn]], [[exec]], [[execFSM]], [[scriptDone]], [[scriptNull]], [[terminate]], [[sleep]], [[uiSleep]], [[waitUntil]], [[canSuspend]], [[diag_activeScripts]], [[diag_activeSQFScripts]], [[SQF Syntax]], [[Control Structures]]
<dl class="command_description">
+
}}
<!-- Note Section BEGIN -->
 
 
 
<!-- Note Section END -->
 
</dl>
 
 
 
<h3 style="display:none">Bottom Section</h3>
 
 
 
[[Category:Scripting Commands|{{uc:{{PAGENAME}}}}]]
 
[[Category:Scripting Commands ArmA|{{uc:{{PAGENAME}}}}]]
 
[[Category:Scripting Commands Arma 2|{{uc:{{PAGENAME}}}}]]
 
[[Category:Scripting Commands Arma 3|{{uc:{{PAGENAME}}}}]]
 
[[Category:Scripting Commands Take On Helicopters|{{uc:{{PAGENAME}}}}]]
 
[[Category:Command Group: Program Flow|{{uc:{{PAGENAME}}}}]]
 

Latest revision as of 19:10, 28 August 2021

Hover & click on the images for description

Description

Description:
Compiles and adds an SQF script to the scheduler queue and returns script handle (see also Example 4). The script does not execute immediately upon running execVM command but with some delay depending on the VM's scripts queue and engine load.
  • If the same script is to be executed more than one time, declaring it as a Function is recommended.
  • The script is searched for in the following directories in that order:
    • mission directory
    • campaign scripts directory
    • global scripts directory.
  • To see what VM scripts are currently in the scheduler, use diag_activeSQFScripts command.
  • The .sqf file extension is not mandatory but is strongly recommended as using non-standard extensions may cause problems during binarisation
  • If the script file is not prepared using UTF-8 encoding and contains some characters with codes > 127, they might convert incorrectly.
Groups:
Program Flow

Syntax

Syntax:
arguments execVM filename
Parameters:
arguments: Anything - arguments accessible as _this in the script
filename: String - path to the SQF script file
Return Value:
Script Handle

Alternative Syntax

Syntax:
execVM filename
Parameters:
filename: String - path to the SQF script file
Return Value:
Script Handle

Examples

Example 1:
_handle = execVM "test.sqf";
Example 2:
_handle = player execVM "test.sqf"; waitUntil { scriptDone _handle }; The following is also possible in Arma 3: private _handle = execVM "123.sqf"; waitUntil { isNull _handle };
Example 3:
[player, 0.75] execVM "setDamage.sqf"; setDamage.sqf: params ["_unit", "_damage"]; _unit setDamage _damage;
Example 4:
execVM equivalence:private _handle = _args execVM "someFile.sqf"; // is practically identical to private _handle = _args spawn compile preprocessFileLineNumbers "someFile.sqf";

Additional Information

See also:
callspawnexecexecFSMscriptDonescriptNullterminatesleepuiSleepwaitUntilcanSuspenddiag_activeScriptsdiag_activeSQFScriptsSQF SyntaxControl Structures

Notes

Report bugs on the Feedback Tracker and/or discuss them on the Arma Discord or on the Forums.
Only post proven facts here! Add Note