ArmA 2: SQF scripting guide. v.3.2 INTRODUCTION TO THIS DOCUMENT ....................................................................................... 2 Conventions used ............................................................................................................................................. 2 SCRIPTING ........................................................................................................................................... 3 What you need ................................................................................................................................................. 3 Mission location ............................................................................................................................................... 3 Common topics for scripting ............................................................................................................................ 4 Examples .......................................................................................................................................................... 5 My first Procedure .............................................................................................................................................. 5 My first function ................................................................................................................................................. 6 My first trigger condition using a Function ......................................................................................................... 7 My first combined Function and Procedure. .................................................................................................... 10 Procedures and Functions explained .............................................................................................................. 11 Procedures ........................................................................................................................................................ 11 Functions .......................................................................................................................................................... 12 Variables ........................................................................................................................................................ 13 More on variables ............................................................................................................................................. 14 Strings ........................................................................................................................................................... 14 Arrays ........................................................................................................................................................... 15 Numbers ....................................................................................................................................................... 16 Objects.......................................................................................................................................................... 16 Magic variables ................................................................................................................................................. 17 Advanced usage of variables ............................................................................................................................ 17 Even more information about variables ........................................................................................................... 17 Control structures .......................................................................................................................................... 17 if-statement ...................................................................................................................................................... 17 if-else statement ............................................................................................................................................... 18 else-if statement ............................................................................................................................................... 18 switch-statement .............................................................................................................................................. 18 for-loop ............................................................................................................................................................. 19 forEach-loop ..................................................................................................................................................... 19 Even more on control structures ...................................................................................................................... 19 Operators ....................................................................................................................................................... 20 Logical Operators .............................................................................................................................................. 20 Comparison Operators ..................................................................................................................................... 20 Even more on Operators .................................................................................................................................. 20 When Do I Need Scripting? ............................................................................................................................. 21 1 | P age Best practices ................................................................................................................................................. 22 Naming conventions ...................................................................................................................................... 24 APPENDIX ......................................................................................................................................... 25 Related wiki articles used in this document ................................................................................................... 25 Control structures ............................................................................................................................................. 25 Data types ......................................................................................................................................................... 25 SQF Syntax ........................................................................................................................................................ 25 Operators .......................................................................................................................................................... 25 Example of Crew command wiki article .......................................................................................................... 25 ABOUT THE AUTHOR.................................................................................................................... 26 VERSIONING ..................................................................................................................................... 27 To-do:............................................................................................................................................................. 27 Introduction to this document This guide aims at people without or little scripting experience. You don’t need to have any previous coding experience with say; java-script, vb-script. However, if you have worked with SQF previously you might still find this guide interesting. The guide also makes references to articles on the BIS:Wiki, where you should look to find more information about commands, and to search for commands which may cover your needs. The scripting commands are quite easy to understand, search and you will most certainly find what you are looking for. Please read the guide thoroughly, when finished you should be able to make your first more advanced missions which includes both procedures and functions, and have more understanding about the data types and structure of the code. All examples found in this guide are working and may be used as you want. Conventions used BIS commands are in Italic e.g. format Both commands and code is in a different font and size and color where applicable. e.g. _myString = ""; 2 | P age Scripting What you need Notepad or a text editor of your choice. A bookmark to Scripting commands ArmA 2 “Hide extensions for known file types” turned off in windows. Windows explorer > Tools > Folder Options View tab Add -showScriptErrors to your ArmA 2 shortcut. e.g. “…Bohemia Interactive\ArmA 2\ArmA 2.exe” -showScriptErrors Basic knowledge about the mission editor, read more in the ArmA: Mission editor –article. To know what you want to accomplish with your script. It’s better to lay out a development plan for your script before starting instead of doing it “on the fly” Patience Mission location Windows Vista %userprofile%\Documents\ArmA 2 <profile>\<player>\missions\<mission name>.<island> Windows XP %appdata%\Documents\ArmA 2 <profile>\<player>\missions\<mission name>.<island> e.g. ..\Documents\ArmA 2 Other Profiles\Taurus \missions\ MyFirstSQFTest.utes If you are unsure, open a windows explorer and copy the line corresponding to your OS in the URL box, as such. 3 | P age Common topics for scripting There are two types of scripts in ArmA 2. Functions Procedures These two types will be explained in detail later in this guide. The functions and procedures are compiled by compile preProcessfile "filename.sqf" compile preprocessFileLineNumbers "filename.sqf" preprocessFileLineNumbers will return the failing line if a compile error, or misuse of a command is found in the script. Or in the case of when you used execVM you don’t need to explicitly compile the files. This is done by the game engine with the preprocessFileLineNumbers command. Input arguments are fetched by the “magic” _this e.g. _this select 0; Which will fetch the first element of the arguments array sent into the function or procedure. Arguments are always sent as an array, you will see this later on as you progress through this guide. If you chose to put the script files in folders, they are then accessed by relative path of the “mission.sqm”-file e.g. MyFunction = compile preProcessfile "MyFunctions\MyFunction.sqf"; Files compiled with the above mentioned compile options: preProcessfile, preprocessFileLineNumbers can include comments(like the ones from C++,Java,and Javascript) e.g. //Single line comment /*Comment covering one, two or even more lines */ Use comments to document your script, what it does and why, which arguments it requires, even author information and etc can be used. All scripts will be treated as complete of the script engine after the last line has been reached. Use of variables, please see section about Variables. 4 | P age Examples These examples might look overwhelming at a glance, but follow the steps and you’ll see that it works. Details about what the code does and why will be covered later. The scripts in the examples are narrowed down because they should be easy to read, feel free to see the comments in the source-files found in the .zip-file. My first Procedure Start ArmA 2. Open up a new mission in the editor, Utes preferably. Place one unit of a side of your choice and put in its init line: MyProcedureHandler = [this] execVM "MyProcedure.sqf" Press “OK” Place an empty Hmmwv next to him, and save the mission as “MyFirstSQFTest” (alt+tab) to return to the desktop, and browse to your mission folder described in “Mission location” Open the folder called “MyFirstSQFTest.utes” In it you will have one file called “mission.sqm” Create a new text file, name that “MyProcedure.sqf” Then right-click and open the file, chose “notepad” as the program to open this file with. 5 | P age In this file write. _myGuy = _this select 0; //This is a while loop which will run until _myGuy dies while {alive _myGuy} do { //HintSilent will show the text in the upper right corner hintSilent format ["Current speed: %1", round(speed (vehicle _myGuy))]; //And updates the value every second. sleep 1; }; Save the file (ctrl+s) and close it. Now (alt+tab) back to ArmA 2 and the editor and preview the mission, run around a bit and enter the car you placed and see the current speed(km/h) in the upper right corner. You will notice the speed to be the same as the car UI but just updated a little bit slower, you can lower the sleep 1; to sleep 0.125; to make it update the value more often. Exit the mission. My first function Now place a Radio Alpha trigger in your mission. In the “On Act” field, write: player sideChat format ["%1",[player] call MyFunction] Click “OK” and save the mission. (alt+tab) to return to the desktop, and go back to your mission folder, create a new file called “init.sqf” This is the init file of your mission, and will run after the unit init lines have been processed. 6 | P age Open “init.sqf” as you did with the other file with Notepad. In this file write. MyFunction = compile preProcessfile "MyFunction.sqf"; Save the file (ctrl+s) and close it. Create another file, call this “MyFunction.sqf” Open it as you did with the other file, and write in it. _myGuy = _this select 0; //Variable to hold the out value _myOutStr = "I'm not in a vehicle!"; //Checks whether or not the unit is in a vehicle if(_myGuy != (vehicle _myGuy)) then{ _myOutStr = "I'm in a vehicle!"; }; //Return value _myOutStr Save the file (ctrl+s) and close it. (alt+tab) back to the editor and preview the mission. Use Radio Alpha and see what you say. Then enter the car and use Radio Alpha again. You will promptly say if you are in a vehicle or not, to your current side. Exit the mission. My first trigger condition using a Function One way of making good use of functions is to let them handle the condition in triggers. The editor triggers can be set to trigger when a BLUFOR unit enters it, but what if you want to check more things like: There need to be at least 2 BLUEFOR units in the trigger area The player should use the radio to report he is done with his duties. The code statement could be written directly in the condition box, but for more complex conditions it is easier to let a function do the job. 7 | P age Update your “MyFirstSQFTest”-mission by adding another soldier of the same side as you. Click “OK”. Now add the condition trigger. Place this trigger somewhere in the middle of the hangar. In the condition field write: ([thisList,2] call MyConditionFunction) Please note that you should not place “;” in any condition fields. Click “OK”. 8 | P age Add another radio trigger. Make this one Radio Bravo, and in its OnAct write: ImHere = true; Click “Ok”. Your mission should look something like this in the editor. Save the mission. It is now time to do some more scripting. 9 | P age (alt+tab) to return to the desktop. First thing you need to do is to update the “init.sqf” file. Open this file as you did with the others, and add: MyConditionFunction = compile preProcessfile "MyConditionFunction.sqf"; ImHere = false; Save the file (ctrl+s) and close it. Then create a new sqf-file, call this “MyConditionFunction.sqf”, write in it. _triggerList = _this select 0; _condNumbOfUnits = _this select 1; _returnValue = false; _unitCount = (count _triggerList); //Checks if condition number of units equals the current count of units in this trigger if((_condNumbOfUnits == _unitCount) && ImHere) then{ _returnValue = true; }else{ if(ImHere) then{ player sideChat format ["Condition not met! Only %1 unit(s) in the trigger!",_unitCount]; //Reset ImHere value ImHere = false; }; }; //Return _returnValue Save the file (ctrl+s) and close it. (alt+tab) back to ArmA 2 and the editor, preview the mission. Order your soldier to enter the hangar and use Radio Bravo. The condition is not met and will not make the mission end. Now join him in the hangar and press Radio Bravo again. My first combined Function and Procedure. Now when you have learnt how to code two functions and a procedure, it’s time to put this knowledge together. Instead of having to use the radio to see if you are in a vehicle, you want to see what type of vehicle you are in, as well as see your current speed. (alt+tab) to return to the desktop. Open the “MyFirstSQFTest”-mission folder again if not already opened. 10 | P age
Description: