{"name":"Introduction to Arma Scripting","title":"Introduction to Arma Scripting","type":"topic","url":"https://community.bistudio.com/wiki/Introduction_to_Arma_Scripting","revid":371144,"updated":"2025-02-28T17:08:27Z","aliases":["ArmA: Armed Assault: Introduction to Scripting","ArmA: Introduction to Scripting","Scripting"],"markdown":"Scripting is one of the most powerful and most versatile tools available in the Arma sandbox. Unfortunately, it is also one of the most complex and unforgiving aspects of addon (i.e. mod) and mission creation.\n\nAll Arma games from Arma: Cold War Assault to Arma 3 use a scripting language called SQF. Its predecessor SQS has been considered deprecated since Armed Assault (2006) and is no longer used.\nAs of Arma Reforger (2022), SQF has been succeeded by Enforce Script. This document only considers SQF.\n\n### Scripting Topics\n\nThere is a plethora of topics to learn about in the context of Arma scripting (see the table below).\nFortunately, there is no need to acquire detailed knowledge about all of these things in order to get started with scripting.\nTo aid with prioritisation, this page provides three selections of topics, each relevant to beginner, intermediate and advanced scripters respectively.\n\n| Real Virtuality Scripting |  |  |\n|---|---|---|\n| Terminology |  | Argument ● Identifier ● Expression ● Operand ● Operators ● Parameter ● Statement ● Variables ● Magic Variables ● Function |\n| Syntax |  | SQF Syntax ● SQS Syntax ● Order of Precedence ● Control Structures |\n| Tutorials |  | Introduction to Arma Scripting ● Code Best Practices ● Example Code ● Code Optimisation ● Mission Optimisation ● Multiplayer Scripting ● SQS → SQF |\n| Data Types | General | Array ● Boolean ● Code ● Config ● Control ● Diary Record ● Display ● Eden Entity ● Eden ID ● Editor Object ● Group ● HashMap ● Location ● Namespace ● Number ● Object ● Script Handle <br>Side ● String ● Structured Text ● Task ● Team ● Team Member ● NaN ● Anything ● Nothing ● Void ● Switch Type ● While Type ● With Type ● For Type ● If Type |\n| Data Types | Special Arrays | Array of Eden Entities ● Color ● Date ● ParticleArray ● Position ● Unit Loadout Array ● Vector3D ● Waypoint |\n| Scripting Commands |  | Scripting Commands ● Scripting Commands by Functionality |\n| Scripting Functions |  | Scripting Functions ● Functions by Functionality |\n| Debugging |  | Common Scripting Errors ● Debugging Techniques ● Exception handling |\n| Advanced |  | Event Scripts ● Event Handlers ● PreProcessor Commands ● Initialisation Order ● Performance Profiling |\n\n### Beginner Scripting\n\n#### Variables\n\nVariables are a fundamental building block of scripting (and programming in general). Like in mathematics, they serve as placeholders for values. A few examples:\n\n- `A = 1;` The variable `A` now has the value 1.\n- `B = 2;` The variable `B` now has the value 2.\n- `C = \"Hello World!\";` The variable `C` now has the value \"Hello World!\".\n\nA variable always has a Data Type. In the example above, the variables `A` and `B` both have the data type Number, while `C` has the data type String. The data type of a variable is not fixed and changes automatically based on the current value of the variable.\n\n#### Commands and Operators\n\nTwo other basic tools of scripting are commands and Operators. In fact, they are so basic that the examples in the Variables section above already had to make use of an operator: The equals sign (`=`) serves as the assignment operator, assigning values to variables. Similarly, symbols such as `+`, `-`, `*` and `/` are also operators. Using operators is quite simple:\n\n```sqf\nA = 1.5;\nB = -2 * A;\nC = A + B + 3.5; // Result: C is 2\n```\n\nCommands are often more versatile and complex than operators and can sometimes be used to interact with the game in some way. For instance, the setPosATL command can be used to change the position of an object in the game world, the damage command returns the amount of damage an object has suffered and the systemChat command can be used to display a message in the system chat.\n\nWhile operators are usually fairly intuitive to use, commands are often more complicated. As such, every single command (and every single operator) has a dedicated Community Wiki page documenting it. This makes the Community Wiki an essential resource for scripting as it can be consulted whenever an unfamiliar command is encountered or needs to be used. The documentation commonly includes information about the behaviour and effect of the command, its return value and the purpose and data types of its parameters.\n\n> [!NOTE]\n> Commands List can be found here: Scripting Commands.\n\n#### Control Structures, Conditions and Booleans\n\nControl Structures allow scripts to accomplish complex tasks. See the following:\n\n```sqf\nif (damage player > 0.5) then\n{\n    player setDamage 0;\n    systemChat \"The player has been healed.\";\n}\nelse\n{\n    systemChat \"The player is fine.\";\n};\n```\n\nThis code behaves differently depending on the damage status of the player. The systemChat output and whether or not the player is healed changes dynamically based on how much health the player has when the code is executed.\n\n##### Conditions\n\nIn the example above, the condition is `damage player > 0.5`. Like all conditions, it results in a Boolean value when evaluated:\n\n1. First, `damage player` is evaluated and returns a number.\n1. Then, the `>` operator compares that number to 0.5:\n   - If the number is greater than 0.5, the `>` operator returns true.\n   - If the number is less than or equal to 0.5, the `>` operator returns false.\n\n##### Booleans\n\nThe data type Boolean only has two possible values: true and false.\n\n###### Boolean Operations\n\nThere are three basic operations that can be performed on Boolean values:\n\n| Operation | Description | SQF Operator | SQF Command |\n|---|---|---|---|\n| NOT (Negation) | Inverts the input value. | `!` | not |\n| AND (Conjunction) | Combines two Booleans into one. Only returns true if both input values are true. | `&&` | and |\n| OR (Disjunction) | Combines two Booleans into one. Returns true if at least one of the input values is true. | `\\|\\|` | or |\n\nBoth the input and the output of these operations are Boolean values. Their behaviour is defined as follows:\n\n|  |  |  |\n|---|---|---|\n| \\| NOT \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `!true` \\| false \\|<br>\\| `!false` \\| true \\| | \\| AND \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `true && true` \\| true \\|<br>\\| `true && false` \\| false \\|<br>\\| `false && true` \\| false \\|<br>\\| `false && false` \\| false \\| | \\| OR \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `true \\\\|\\\\| true` \\| true \\|<br>\\| `true \\\\|\\\\| false` \\| true \\|<br>\\| `false \\\\|\\\\| true` \\| true \\|<br>\\| `false \\\\|\\\\| false` \\| false \\| |\n\n##### Complex Conditions\n\nBoolean operations can be used to create complex conditions by combining multiple conditions into one.\n\n```sqf\nif ((alive VIP_1 && triggerActivated VIP_1_Task_Complete) || (alive VIP_2 && triggerActivated VIP_2_Task_Complete)) then\n{\n    systemChat \"At least one VIP has been rescued.\";\n};\n```\n\n> [!NOTE]\n> Beginners sometimes write conditions such as `if (Condition == true)` or `if (Condition == false)`.\n>\n> While doing so is not a real error, it is unnecessary because Control Structures (and Triggers) always implicitly compare the condition to true.\n>\n> The correct (as in faster, more common and more readable) way to write such conditions is `if (Condition)` and `if (!Condition)` respectively.\n\n#### Arrays\n\nAn Array is a Data Type that can be seen as a list of items. This list can hold none to multiple elements of different types:\n\n```sqf\n[]                        // an empty array\n[true]                    // an array of 1 element (Boolean)\n[0, 10, 20, 30, 40, 50]    // an array of 6 elements of Number type\n[\"John Doe\", 32, true]    // an array of 3 elements of different types (String, Number, Boolean)\n```\n\nAn array is a useful way to keep data together and is used for example to store positions.\n\n##### Positions\n\nPositions are represented as 2D or 3D Arrays of Numbers (usually in the format `[X, Y]` or `[X, Y, Z]`) where X represents West-East, Y represents South-North and Z represents altitude.\nHowever, there are some important caveats and distinctions one should be aware of - for instance, the positions `[0, 0, 0]` ASL (**A**bove **S**ea **L**evel) and `[0, 0, 0]` AGL (**A**bove **G**round **L**evel) are not necessarily equivalent.\nIt is therefore highly recommended to read the Positions page before working with positions.\n\n#### Script Files\n\nScripts are usually placed in Script Files. It is of course possible and sometimes even necessary to use short pieces of code in the Editor (e.g. in the *On Activation* expression of a Trigger), but scripts can become long and complex, and then working with them is far easier when they are properly placed in script files. Additionally, some features are only accessible through the use of script files (Event Scripts for example).\n\nScript files are basically just text files with a certain filename extension. For script files, that file extension is `.sqf` (or `.sqs`), but in the broader context of Arma scripting, modification, configuration and mission design, more file extensions can be encountered: `.ext`, `.hpp`, `.cpp` and `.cfg` to mention the most common ones.\n\n##### File Creation\n\nUnfortunately, Windows does not make the creation of blank files with a desired file extension easily accessible.\n\nFor instance, a common pitfall when trying to use Description.ext (a file that is used to configure certain mission features such as the respawn settings) for the first time is (unknowingly) creating `Description.ext.txt` instead of `Description.ext` because the Windows File Explorer hides file extensions by default.\nObviously, `Description.ext.txt` will not work and will not have any of the desired effects on the mission because the game does not recognize it as `Description.ext`, but identifying a wrong file extension as the root cause of an issue when troubleshooting is notoriously difficult as one is usually looking for errors in the code and not in the filename.\n\nWhile there are many different ways to create a blank text file with a specific file extension, the easiest method using native Windows tools is probably this:\n\n- Preparation (only needs to be done once):\n\n1. Open the File Explorer\n1. Open the *View* tab at the top\n1. Tick the *File name extensions* checkbox\n\n- File Creation:\n\n1. Navigate to the location where you want to create a new script file\n1. Right-click\n1. Go to *New*\n1. Click on *Text Document*\n1. Rename `New Text Document.txt` to what you need\n\n> [!NOTE]\n> It is also possible to bypass Notepad's automatic addition of the `.txt` extension by wrapping the file name in quote, e.g `\"description.ext\"`.\n\n##### File Locations\n\nIn the context of mission creation, script files generally need to be placed in the corresponding *scenario folder* (often also called the *mission root folder*). Every mission has its own scenario folder, it is created by the Editor when saving the scenario for the first time.\nBy default it only contains a single file called `mission.sqm`; this file mostly stores data regarding Editor-placed entities and does not need to be touched when scripting.\n\nDescription.ext and Event Scripts have to be placed directly in the root of the scenario folder (i.e. next to `mission.sqm`), but all other files can be placed in subfolders of the scenario folder.\nA well-structured scenario folder could look like this:\n\n```\nApex%20Protocol.Tanoa/\n├── functions/\n│   ├── fn_myFirstFunction.sqf\n│   └── fn_mySecondFunction.sqf\n├── scripts/\n│   ├── myFirstScript.sqf\n│   └── mySecondScript.sqf\n├── description.ext\n├── initPlayerLocal.sqf\n├── initServer.sqf\n└── mission.sqm\n```\n\nEach scenario folder is stored in either the `missions` or the `mpmissions` subfolder of the folder containing the Arma Profile that was used to create the scenario.\nFor instance, the path to the scenario folder from the example above could be:\n\n```\nC:\\Users\\Scott Miller\\Documents\\Arma 3 - Other Profiles\\Keystone\\missions\\Apex%20Protocol.Tanoa\n```\n\nThe Editor uses [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding) for scenario folder names, that is why whitespaces in the scenario name are replaced with `%20`.\n\n> [!NOTE]\n> The Eden Editor provides a useful shortcut to quickly open a mission's scenario folder in the Windows File Explorer:\n> With the mission open in the Editor, go to *Scenario* in the top left and then click on *Open Scenario Folder*.\n\n**See Also:**\n\n- 2D Editor: External\n- Eden Editor: Scenario Folder\n- Profile (the possible profile folder paths are listed there)\n\n##### Editing Script Files\n\nBecause script files are essentially plain text files, they can be edited with just about any text editor. For instance, the native Windows Notepad can be used, but working with it is not very comfortable. As such, regular scripters typically use more versatile applications such as [Notepad++](https://notepad-plus-plus.org) or [Visual Studio Code](https://code.visualstudio.com), usually in combination with plugins that add additional support for SQF. One feature commonly provided by these plugins is *syntax highlighting*, and for good reason: Syntax highlighting makes code significantly more readable and helps recognizing and avoiding basic syntax errors. Consequently, it is highly recommended to use syntax highlighting.\n\nSee Community Tools - Code Edition for a selection of community-made applications and plugins for Arma Scripting.\n\n##### Script Execution\n\nThe execVM command is used to execute script files.\n\nFor instance, `myFirstScript.sqf` from the File Locations example above can simply be executed like so:\n\n```sqf\nexecVM \"scripts\\myFirstScript.sqf\";\n```\n\nThis can be done anywhere: Within another script, from the Debug Console, in the *On Activation* or *On Deactivation* expression of a Trigger or in the init field of an Object in the Editor.\n\n### Intermediate Scripting\n\n### Advanced Scripting\n\n### Miscellaneous\n\n> [!NOTE]\n> This section contains content from an old version of this page which is due to be updated.\n\n### Before anything\n\n**Is your idea necessary?** Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!\n\n**Is it possible to do this in the editor?** The Eden Editor is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.\n\nPoorly written scripts are a frequent cause of poor performance, both in singleplayer and multiplayer scenarios.\n\n**Can it be scripted using SQF?** This question might be hard to answer. Try to get as much information about what you want to do and what commands and functions there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.\n\n> [!NOTE]\n> Scripting is not the solution for everything!\n\n#### Terms\n\nThe following is a collection of terms frequently encountered when talking or reading about scripting.\n\n**Game Engine:** The core program of the game which executes your scripting commands at run time.\n\n**Script / Script File:** Scripts are usually placed in script files. Script files contain code.\n\n**Syntax:** See SQF Syntax (Arma, Arma 2, Arma 3).\n\nSee SQS Syntax (Operation Flashpoint, Arma).\n\n**Variables:** A Variable is a named storage container for data.\n\nThe name of a variable is called its Identifier.\n\n**Data Types:** The Data Type of a variable specifies which kind of data that variable can contain.\n\n**Operators:** See Operators\n\n**Control Structures:** See Control Structures\n\n**Functions:** See Function\n\n#### Must-Read Articles\n\n##### Best Practices\n\nSee Code Best Practices\n\n##### Debugging\n\n- Debugging Techniques\n- Community Tools - Debug Console/System\n\n##### Optimisation\n\n- Code Optimisation\n- Mission Optimisation\n\n#### Useful Links\n\nThese pages cover further aspects of scripting:\n\n- Example Code\n- Control Structures\n- Multiplayer Scripting\n- Exception handling\n- Script File\n- Function\n- SQS to SQF conversion\n\nConsider the following resources for more general learning:\n\n- 6thSense.eu Editing Guide\n- *Fockers Arma 3 Scripting Guide* (dead link)\n- *Mr-Murray's Armed Assault Editing Guide - Deluxe Edition* (dead link)\n- [Excellent German SQF tutorial (YouTube)](https://youtu.be/WmEBN-RbK44)","sections":[{"heading":null,"level":1,"markdown":"Scripting is one of the most powerful and most versatile tools available in the Arma sandbox. Unfortunately, it is also one of the most complex and unforgiving aspects of addon (i.e. mod) and mission creation.\n\nAll Arma games from Arma: Cold War Assault to Arma 3 use a scripting language called SQF. Its predecessor SQS has been considered deprecated since Armed Assault (2006) and is no longer used.\nAs of Arma Reforger (2022), SQF has been succeeded by Enforce Script. This document only considers SQF."},{"heading":"Scripting Topics","level":3,"markdown":"There is a plethora of topics to learn about in the context of Arma scripting (see the table below).\nFortunately, there is no need to acquire detailed knowledge about all of these things in order to get started with scripting.\nTo aid with prioritisation, this page provides three selections of topics, each relevant to beginner, intermediate and advanced scripters respectively.\n\n| Real Virtuality Scripting |  |  |\n|---|---|---|\n| Terminology |  | Argument ● Identifier ● Expression ● Operand ● Operators ● Parameter ● Statement ● Variables ● Magic Variables ● Function |\n| Syntax |  | SQF Syntax ● SQS Syntax ● Order of Precedence ● Control Structures |\n| Tutorials |  | Introduction to Arma Scripting ● Code Best Practices ● Example Code ● Code Optimisation ● Mission Optimisation ● Multiplayer Scripting ● SQS → SQF |\n| Data Types | General | Array ● Boolean ● Code ● Config ● Control ● Diary Record ● Display ● Eden Entity ● Eden ID ● Editor Object ● Group ● HashMap ● Location ● Namespace ● Number ● Object ● Script Handle <br>Side ● String ● Structured Text ● Task ● Team ● Team Member ● NaN ● Anything ● Nothing ● Void ● Switch Type ● While Type ● With Type ● For Type ● If Type |\n| Data Types | Special Arrays | Array of Eden Entities ● Color ● Date ● ParticleArray ● Position ● Unit Loadout Array ● Vector3D ● Waypoint |\n| Scripting Commands |  | Scripting Commands ● Scripting Commands by Functionality |\n| Scripting Functions |  | Scripting Functions ● Functions by Functionality |\n| Debugging |  | Common Scripting Errors ● Debugging Techniques ● Exception handling |\n| Advanced |  | Event Scripts ● Event Handlers ● PreProcessor Commands ● Initialisation Order ● Performance Profiling |"},{"heading":"Beginner Scripting","level":3,"markdown":""},{"heading":"Variables","level":4,"markdown":"Variables are a fundamental building block of scripting (and programming in general). Like in mathematics, they serve as placeholders for values. A few examples:\n\n- `A = 1;` The variable `A` now has the value 1.\n- `B = 2;` The variable `B` now has the value 2.\n- `C = \"Hello World!\";` The variable `C` now has the value \"Hello World!\".\n\nA variable always has a Data Type. In the example above, the variables `A` and `B` both have the data type Number, while `C` has the data type String. The data type of a variable is not fixed and changes automatically based on the current value of the variable."},{"heading":"Commands and Operators","level":4,"markdown":"Two other basic tools of scripting are commands and Operators. In fact, they are so basic that the examples in the Variables section above already had to make use of an operator: The equals sign (`=`) serves as the assignment operator, assigning values to variables. Similarly, symbols such as `+`, `-`, `*` and `/` are also operators. Using operators is quite simple:\n\n```sqf\nA = 1.5;\nB = -2 * A;\nC = A + B + 3.5; // Result: C is 2\n```\n\nCommands are often more versatile and complex than operators and can sometimes be used to interact with the game in some way. For instance, the setPosATL command can be used to change the position of an object in the game world, the damage command returns the amount of damage an object has suffered and the systemChat command can be used to display a message in the system chat.\n\nWhile operators are usually fairly intuitive to use, commands are often more complicated. As such, every single command (and every single operator) has a dedicated Community Wiki page documenting it. This makes the Community Wiki an essential resource for scripting as it can be consulted whenever an unfamiliar command is encountered or needs to be used. The documentation commonly includes information about the behaviour and effect of the command, its return value and the purpose and data types of its parameters.\n\n> [!NOTE]\n> Commands List can be found here: Scripting Commands."},{"heading":"Control Structures, Conditions and Booleans","level":4,"markdown":"Control Structures allow scripts to accomplish complex tasks. See the following:\n\n```sqf\nif (damage player > 0.5) then\n{\n    player setDamage 0;\n    systemChat \"The player has been healed.\";\n}\nelse\n{\n    systemChat \"The player is fine.\";\n};\n```\n\nThis code behaves differently depending on the damage status of the player. The systemChat output and whether or not the player is healed changes dynamically based on how much health the player has when the code is executed."},{"heading":"Conditions","level":5,"markdown":"In the example above, the condition is `damage player > 0.5`. Like all conditions, it results in a Boolean value when evaluated:\n\n1. First, `damage player` is evaluated and returns a number.\n1. Then, the `>` operator compares that number to 0.5:\n   - If the number is greater than 0.5, the `>` operator returns true.\n   - If the number is less than or equal to 0.5, the `>` operator returns false."},{"heading":"Booleans","level":5,"markdown":"The data type Boolean only has two possible values: true and false."},{"heading":"Boolean Operations","level":6,"markdown":"There are three basic operations that can be performed on Boolean values:\n\n| Operation | Description | SQF Operator | SQF Command |\n|---|---|---|---|\n| NOT (Negation) | Inverts the input value. | `!` | not |\n| AND (Conjunction) | Combines two Booleans into one. Only returns true if both input values are true. | `&&` | and |\n| OR (Disjunction) | Combines two Booleans into one. Returns true if at least one of the input values is true. | `\\|\\|` | or |\n\nBoth the input and the output of these operations are Boolean values. Their behaviour is defined as follows:\n\n|  |  |  |\n|---|---|---|\n| \\| NOT \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `!true` \\| false \\|<br>\\| `!false` \\| true \\| | \\| AND \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `true && true` \\| true \\|<br>\\| `true && false` \\| false \\|<br>\\| `false && true` \\| false \\|<br>\\| `false && false` \\| false \\| | \\| OR \\|  \\|<br>\\|---\\|---\\|<br>\\| Expression \\| Result \\|<br>\\| `true \\\\|\\\\| true` \\| true \\|<br>\\| `true \\\\|\\\\| false` \\| true \\|<br>\\| `false \\\\|\\\\| true` \\| true \\|<br>\\| `false \\\\|\\\\| false` \\| false \\| |"},{"heading":"Complex Conditions","level":5,"markdown":"Boolean operations can be used to create complex conditions by combining multiple conditions into one.\n\n```sqf\nif ((alive VIP_1 && triggerActivated VIP_1_Task_Complete) || (alive VIP_2 && triggerActivated VIP_2_Task_Complete)) then\n{\n    systemChat \"At least one VIP has been rescued.\";\n};\n```\n\n> [!NOTE]\n> Beginners sometimes write conditions such as `if (Condition == true)` or `if (Condition == false)`.\n>\n> While doing so is not a real error, it is unnecessary because Control Structures (and Triggers) always implicitly compare the condition to true.\n>\n> The correct (as in faster, more common and more readable) way to write such conditions is `if (Condition)` and `if (!Condition)` respectively."},{"heading":"Arrays","level":4,"markdown":"An Array is a Data Type that can be seen as a list of items. This list can hold none to multiple elements of different types:\n\n```sqf\n[]                        // an empty array\n[true]                    // an array of 1 element (Boolean)\n[0, 10, 20, 30, 40, 50]    // an array of 6 elements of Number type\n[\"John Doe\", 32, true]    // an array of 3 elements of different types (String, Number, Boolean)\n```\n\nAn array is a useful way to keep data together and is used for example to store positions."},{"heading":"Positions","level":5,"markdown":"Positions are represented as 2D or 3D Arrays of Numbers (usually in the format `[X, Y]` or `[X, Y, Z]`) where X represents West-East, Y represents South-North and Z represents altitude.\nHowever, there are some important caveats and distinctions one should be aware of - for instance, the positions `[0, 0, 0]` ASL (**A**bove **S**ea **L**evel) and `[0, 0, 0]` AGL (**A**bove **G**round **L**evel) are not necessarily equivalent.\nIt is therefore highly recommended to read the Positions page before working with positions."},{"heading":"Script Files","level":4,"markdown":"Scripts are usually placed in Script Files. It is of course possible and sometimes even necessary to use short pieces of code in the Editor (e.g. in the *On Activation* expression of a Trigger), but scripts can become long and complex, and then working with them is far easier when they are properly placed in script files. Additionally, some features are only accessible through the use of script files (Event Scripts for example).\n\nScript files are basically just text files with a certain filename extension. For script files, that file extension is `.sqf` (or `.sqs`), but in the broader context of Arma scripting, modification, configuration and mission design, more file extensions can be encountered: `.ext`, `.hpp`, `.cpp` and `.cfg` to mention the most common ones."},{"heading":"File Creation","level":5,"markdown":"Unfortunately, Windows does not make the creation of blank files with a desired file extension easily accessible.\n\nFor instance, a common pitfall when trying to use Description.ext (a file that is used to configure certain mission features such as the respawn settings) for the first time is (unknowingly) creating `Description.ext.txt` instead of `Description.ext` because the Windows File Explorer hides file extensions by default.\nObviously, `Description.ext.txt` will not work and will not have any of the desired effects on the mission because the game does not recognize it as `Description.ext`, but identifying a wrong file extension as the root cause of an issue when troubleshooting is notoriously difficult as one is usually looking for errors in the code and not in the filename.\n\nWhile there are many different ways to create a blank text file with a specific file extension, the easiest method using native Windows tools is probably this:\n\n- Preparation (only needs to be done once):\n\n1. Open the File Explorer\n1. Open the *View* tab at the top\n1. Tick the *File name extensions* checkbox\n\n- File Creation:\n\n1. Navigate to the location where you want to create a new script file\n1. Right-click\n1. Go to *New*\n1. Click on *Text Document*\n1. Rename `New Text Document.txt` to what you need\n\n> [!NOTE]\n> It is also possible to bypass Notepad's automatic addition of the `.txt` extension by wrapping the file name in quote, e.g `\"description.ext\"`."},{"heading":"File Locations","level":5,"markdown":"In the context of mission creation, script files generally need to be placed in the corresponding *scenario folder* (often also called the *mission root folder*). Every mission has its own scenario folder, it is created by the Editor when saving the scenario for the first time.\nBy default it only contains a single file called `mission.sqm`; this file mostly stores data regarding Editor-placed entities and does not need to be touched when scripting.\n\nDescription.ext and Event Scripts have to be placed directly in the root of the scenario folder (i.e. next to `mission.sqm`), but all other files can be placed in subfolders of the scenario folder.\nA well-structured scenario folder could look like this:\n\n```\nApex%20Protocol.Tanoa/\n├── functions/\n│   ├── fn_myFirstFunction.sqf\n│   └── fn_mySecondFunction.sqf\n├── scripts/\n│   ├── myFirstScript.sqf\n│   └── mySecondScript.sqf\n├── description.ext\n├── initPlayerLocal.sqf\n├── initServer.sqf\n└── mission.sqm\n```\n\nEach scenario folder is stored in either the `missions` or the `mpmissions` subfolder of the folder containing the Arma Profile that was used to create the scenario.\nFor instance, the path to the scenario folder from the example above could be:\n\n```\nC:\\Users\\Scott Miller\\Documents\\Arma 3 - Other Profiles\\Keystone\\missions\\Apex%20Protocol.Tanoa\n```\n\nThe Editor uses [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding) for scenario folder names, that is why whitespaces in the scenario name are replaced with `%20`.\n\n> [!NOTE]\n> The Eden Editor provides a useful shortcut to quickly open a mission's scenario folder in the Windows File Explorer:\n> With the mission open in the Editor, go to *Scenario* in the top left and then click on *Open Scenario Folder*.\n\n**See Also:**\n\n- 2D Editor: External\n- Eden Editor: Scenario Folder\n- Profile (the possible profile folder paths are listed there)"},{"heading":"Editing Script Files","level":5,"markdown":"Because script files are essentially plain text files, they can be edited with just about any text editor. For instance, the native Windows Notepad can be used, but working with it is not very comfortable. As such, regular scripters typically use more versatile applications such as [Notepad++](https://notepad-plus-plus.org) or [Visual Studio Code](https://code.visualstudio.com), usually in combination with plugins that add additional support for SQF. One feature commonly provided by these plugins is *syntax highlighting*, and for good reason: Syntax highlighting makes code significantly more readable and helps recognizing and avoiding basic syntax errors. Consequently, it is highly recommended to use syntax highlighting.\n\nSee Community Tools - Code Edition for a selection of community-made applications and plugins for Arma Scripting."},{"heading":"Script Execution","level":5,"markdown":"The execVM command is used to execute script files.\n\nFor instance, `myFirstScript.sqf` from the File Locations example above can simply be executed like so:\n\n```sqf\nexecVM \"scripts\\myFirstScript.sqf\";\n```\n\nThis can be done anywhere: Within another script, from the Debug Console, in the *On Activation* or *On Deactivation* expression of a Trigger or in the init field of an Object in the Editor."},{"heading":"Intermediate Scripting","level":3,"markdown":""},{"heading":"Advanced Scripting","level":3,"markdown":""},{"heading":"Miscellaneous","level":3,"markdown":"> [!NOTE]\n> This section contains content from an old version of this page which is due to be updated."},{"heading":"Before anything","level":3,"markdown":"**Is your idea necessary?** Will players even notice or use what you want to script? Just because you can does not mean you should. Sometimes less is more!\n\n**Is it possible to do this in the editor?** The Eden Editor is a powerful tool and with it alone one can achieve a lot of things without writing a single line of code.\n\nPoorly written scripts are a frequent cause of poor performance, both in singleplayer and multiplayer scenarios.\n\n**Can it be scripted using SQF?** This question might be hard to answer. Try to get as much information about what you want to do and what commands and functions there are before spending time on writing a script, just to find out that what you hoped to achieve is not possible after all.\n\n> [!NOTE]\n> Scripting is not the solution for everything!"},{"heading":"Terms","level":4,"markdown":"The following is a collection of terms frequently encountered when talking or reading about scripting.\n\n**Game Engine:** The core program of the game which executes your scripting commands at run time.\n\n**Script / Script File:** Scripts are usually placed in script files. Script files contain code.\n\n**Syntax:** See SQF Syntax (Arma, Arma 2, Arma 3).\n\nSee SQS Syntax (Operation Flashpoint, Arma).\n\n**Variables:** A Variable is a named storage container for data.\n\nThe name of a variable is called its Identifier.\n\n**Data Types:** The Data Type of a variable specifies which kind of data that variable can contain.\n\n**Operators:** See Operators\n\n**Control Structures:** See Control Structures\n\n**Functions:** See Function"},{"heading":"Must-Read Articles","level":4,"markdown":""},{"heading":"Best Practices","level":5,"markdown":"See Code Best Practices"},{"heading":"Debugging","level":5,"markdown":"- Debugging Techniques\n- Community Tools - Debug Console/System"},{"heading":"Optimisation","level":5,"markdown":"- Code Optimisation\n- Mission Optimisation"},{"heading":"Useful Links","level":4,"markdown":"These pages cover further aspects of scripting:\n\n- Example Code\n- Control Structures\n- Multiplayer Scripting\n- Exception handling\n- Script File\n- Function\n- SQS to SQF conversion\n\nConsider the following resources for more general learning:\n\n- 6thSense.eu Editing Guide\n- *Fockers Arma 3 Scripting Guide* (dead link)\n- *Mr-Murray's Armed Assault Editing Guide - Deluxe Edition* (dead link)\n- [Excellent German SQF tutorial (YouTube)](https://youtu.be/WmEBN-RbK44)"}],"categories":["Arma Scripting Tutorials","To-do"],"groups":["Scripting"]}