Lou Montana/Sandbox – User
Template:SideTOC Debugging Techniques are ways in which developers can debug, or find out where errors or unexpected outcomes are occurring within their scripts. Template:note
Code
Various links about code and how to write it:
IDE and Syntax Highlight
Syntax errors can be a frequent occurrence when developing scripts. Syntax highlight will help you find typos in commands and in your scripts.
An Integrated Development Environment, shortened to IDE is as its name says a development environment program, providing among other things syntax highlight and autocompletion, helping you writing code.
See further Debugging Tools page section for download links.
Errors
An error in SQF will purely and simply halt the current script, leading to unpredictable behaviour. An error is not something that should happen, as it can hinder performance as well as break a mission. So if you encounter one, do not overlook it by saying "it's a minor one"; your script will stop.
Finding Errors
Debugging is usually as complicated as writing the actual code itself. You usually get hinted by the game, where some error happened, and what it was.
There are instances where actual error reason might be something completely different than announced (eg. you get the error on a variable being nil somewhere, but the actual error is that you mistyped it where you set it initially).
A script error will greet you with this box:
It tells you what went wrong, shows a snippet of the code that failed and, unless you used a command combination like eg. compile loadFile, what file and line it occured on.
Knowing this, you now can proceed to find the actual reason why that specific piece of code errored.
To solve an issue, you must first find out there is one. Besides your script not having the wanted effect (if any), an error message helps you locate the code issue.
- Be sure to use -showScriptErrors startup parameter to display the error on-screen
- To ensure error location in your script, prefer preprocessFileLineNumbers to preprocessFile
- Read RPT files for more information (make sure -noLogs startup parameter is not enabled or the logs will never be filled)
- Scripts running on a server use the ArmaXServer.RPT file which has varying location depending upon the type of server being run.
- Scripts running on a client use the ArmaX.RPT file.
RPT files
An RPT (or crash file) is the game's log file; it will dump debug information as well as encountered errors. One can also dump information in it by using commands like diag_log.
| Game | Location | Files |
|---|---|---|
 1.00 Arma 3
|
%localappdata%\Arma 3
|
Arma3_x64_yyyy-mm-dd_hh-mm-ss.rpt
|
 1.00 Arma 2
|
%localappdata%\ArmA 2
|
arma2.rpt
|
| -wrong parameter ("Arma") defined!-1.00 Arma | %localappdata%\ArmA
|
arma.rpt
|
 1.00 Operation Flashpoint
|
OFP root directory
|
flashpoint.rpt
|
Solving Errors
Once the script error is located: be sure to check the BiKi page corresponding to the command/function you are using!!
The most simple thing you can do is to output expected values. This can be done using for example diag_log or systemChat. Output yourself a few variables that relate to your problem (for example: When the error occurs because you land in some if block, output the corresponding variables inside of the if). You continue doing this until you hit the actual problem: When variable A is not set, go to where variable A gets set and check around there, repeat and continue.
The same can be done for non-critical errors like when a method is "just" computing the wrong values.
Common errors
| Error message | Cause | Solution |
|---|---|---|
| Error Undefined variable in expression: _varName | variable _varName has not been initialised properly in this context. | |
| Error x elements provided, y is expected | A wrong number of arguments in array was provided | Read the wiki about said command. Use typeName to output a variable type and compare it to the command's wiki page. |
| Error type x, expected y | An ill-typed argument was provided (e.g hint 5; // should be String, not Number)
| |
| Error Zero divisor | Pretty self-explanatory, somewhere in your code is a division by zero. |
|
Also happens when using an invalid select index (e.g [0,1,2] select 20;)
|
| |
| Local variable in global space | An attempt to private a public variable (e.g private "myVar"; // should be "_myVar")
|
Replace public variable usage with private variables. |
| Error Generic error in expression (Suspending not allowed in this context) | A sleep/uiSleep/waitUntil command has been used in an unscheduled environment | Do not use such suspending commands; a workaround could be:
|
| Generic error | Further code reading is required. |
|
Working with Addons
If you are working on an addon, repacking a PBO can be time-intensive. This operation can be replaced simply by creating a basic mission in the "Missions" or "MPmissions" (if your feature is multiplayer-specific) folder of your game installation, and running the mission locally. The easiest way of accomplishing this is by the use of Event Scripts to run your code such as init.sqf. Once you have tested your code this way, you can then sequentially pack your PBO when major changes have been made, rather than for each debug session of a script or piece of code.
Debugging specific sections of code
Although primitive, the combined use of diag_log, systemChat/hint and format can help to debug the content of function arguments. In the case that specific pieces of code do not run, or if specific if conditions don't appear to fire, debugging the variable content with diag_log can be useful. As with all debugging, as long as the developer is methodical and logical in checking each section of code that runs, finding bugs and resolving them can be straightforward.
Debugging Tools
| Game | User | Addon/Toolname | Category | Description | Link |
|---|---|---|---|---|---|
| N/A | Sanjo | Notepad++ SQF | Text editor plugin - Notepad++ | Notepad++ SQF Syntax highlighter plugin. Forum post | Download |
| N/A | K-Town | Arma IntelliJ plugin | IDE plugin - IntelliJ | Forum post | Download |
| N/A | Armitxes | SQF Language | IDE plugin - Visual Studio Code | Forum post | Download |
| N/A | ole1986 | Arma Dev | IDE plugin - Visual Studio Code | Download | |
| N/A | SkaceKachna | SQFLint | IDE plugin - Visual Studio Code | Forum post | Download |
| N/A | krzmbrzl | SQDev | IDE plugin - Eclipse | Provides code validation (linting) while you are typing it. Forum post | Download |
| N/A | Sbsmac | Squint | IDE | Provides a fully-featured code editor which allows for syntax highlighting, displaying of errors and code correction. Forum post | Download |
| N/A | X39 | SQF VM | Emulator | Forum post | Download |
| N/A | Dedmen | Arma Script Profiler | Tool | Forum post | Download |
| N/A | Dedmen | Arma Debug Engine | Tool | Workshop link | Download |
| 1.00
|
Bohemia Interactive | N/A | Debug console | Debug Console capable of executing code and more. | Wiki page |
| 1.00
|
Kju | DevCon | Debug console | Download | |
 1.00
|
Bohemia Interactive | N/A | Debug console | Debug Console capable of executing code and more. | Wiki page |
| 1.00
|
Kju | DevCon | Debug console | Download | |
| 1.00
|
Charon Productions | TroopMon v3 | Debug system | Debugging system containing informations relevant to mission-makers (especially about AI) | Download |
| 1.00
|
Str | Debug console | Download | ||
| -wrong parameter ("Arma") defined!-1.00 | Charon Productions | TroopMon v0.8b | Debug system | Complex debugging system providing lots of information for mission-makers, especially about AI. | Download |
| -wrong parameter ("Arma") defined!-1.00 | Str | Debug console | available in all singleplayer missions, intros and outros. Easy and simple to use (Escape-Enter execute) | Download |