Difference between revisions of "Debugging Techniques"

From Bohemia Interactive Community
Jump to navigation Jump to search
m (Text replacement - "Category:Arma 2: Editing" to "{{GameCategory|arma2|Editing}}")
m (Text replacement - "\[\[SQS[ _]syntax" to "[[SQS Syntax")
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{SideTOC}}
+
{{TOC|side}}
  
 
[[Debugging Techniques]] are ways for a developers to debug (narrow down/determine the root source), or to learn and understand where and why errors or unexpected outcomes are occurring within their code.
 
[[Debugging Techniques]] are ways for a developers to debug (narrow down/determine the root source), or to learn and understand where and why errors or unexpected outcomes are occurring within their code.
  
{{quote|Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system.|Wikipedia|https://en.wikipedia.org/w/index.php?title{{=}}Debugging}}
+
{{Feature|quote|Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system.|Wikipedia|https://en.wikipedia.org/w/index.php?title{{=}}Debugging}}
  
  
Line 9: Line 9:
  
 
Various links about code and how to write it:
 
Various links about code and how to write it:
* [[SQF syntax]]
+
* [[SQF Syntax]]
* [[SQS syntax]]
+
* [[SQS Syntax]]
 
* [[Code Optimisation]]
 
* [[Code Optimisation]]
  
Line 32: Line 32:
 
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).
 
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).
  
{{Important|Make sure you enable ''Show Script Errors'' in the Launcher (for {{arma3}}) or set the corresponding [[Arma_3_Startup_Parameters|-showScriptErrors]] startup parameter.}}
+
{{Feature|important|Make sure you enable ''Show Script Errors'' in the Launcher (for {{arma3}}) or set the corresponding [[Arma_3_Startup_Parameters|-showScriptErrors]] startup parameter.}}
  
 
A script error will greet you with this box:
 
A script error will greet you with this box:
 
[[File:A3_ScriptErrorMsg.jpg|thumb|Script error message|center|500px]]
 
[[File:A3_ScriptErrorMsg.jpg|thumb|Script error message|center|500px]]
  
It tells you what went wrong, shows a snippet of the code that failed and what file and line it occurred in (unless you used a command combination like eg. {{Inline code|[[compile]] [[loadFile]]}}).
+
It tells you what went wrong, shows a snippet of the code that failed and what file and line it occurred in (unless you used a command combination like eg. {{ic|[[compile]] [[loadFile]]}}).
 
Knowing this, you now can proceed to find the actual reason why that specific piece of code errored.
 
Knowing this, you now can proceed to find the actual reason why that specific piece of code errored.
  
{{informative|This information can also be found in the [[arma.RPT|RPT log]].}}
+
{{Feature|Informative|This information can also be found in the [[arma.RPT|RPT log]].}}
  
 
To solve an issue, you must first to became aware that of it. Aside from your script not having the desired result/effect (if any), an error message can tell you about the problem.
 
To solve an issue, you must first to became aware that of it. Aside from your script not having the desired result/effect (if any), an error message can tell you about the problem.
Line 53: Line 53:
 
One can also write information to it by using commands like [[diag_log]].
 
One can also write information to it by using commands like [[diag_log]].
  
{{Important|The RPT file might be disabled using the Arma 3 launcher or by setting the corresponding [[Arma_3_Startup_Parameters|-noLogs]] startup parameter ({{arma3}} or {{arma2oa}} option)}}
+
{{Feature|important|The RPT file might be disabled using the Arma 3 launcher or by setting the corresponding [[Arma_3_Startup_Parameters|-noLogs]] startup parameter ({{arma3}} or {{arma2oa}} option)}}
  
{|class="bikitable"
+
{|class="wikitable"
 
|+ RPT File location per game (See [[Crash Files]] for more information)
 
|+ RPT File location per game (See [[Crash Files]] for more information)
 
!Game
 
!Game
Line 66: Line 66:
 
|-
 
|-
 
| {{GVI|arma2|1.00}} {{arma2}}
 
| {{GVI|arma2|1.00}} {{arma2}}
| <code>'''%localappdata%'''\ArmA 2</code>
+
| <code>'''%localappdata%'''\Arma 2</code>
 
| <code>arma2.rpt</code>
 
| <code>arma2.rpt</code>
 
|-
 
|-
| {{GVI|arma|1.00}} {{arma}}
+
| {{GVI|arma1|1.00}} {{arma1}}
 
| <code>'''%localappdata%'''\ArmA</code>
 
| <code>'''%localappdata%'''\ArmA</code>
 
| <code>arma.rpt</code>
 
| <code>arma.rpt</code>
Line 88: Line 88:
 
The same can be done for non-critical errors like when a method is "just" computing the wrong values.
 
The same can be done for non-critical errors like when a method is "just" computing the wrong values.
  
{{Informative|
+
{{Feature|Informative|
 
If you're having great difficulty solving a problem, the good way is to narrow down the issue to the simplest code block possible;
 
If you're having great difficulty solving a problem, the good way is to narrow down the issue to the simplest code block possible;
 
or take the mission part that doesn't work, paste it into a new test mission and go from here.
 
or take the mission part that doesn't work, paste it into a new test mission and go from here.
Line 94: Line 94:
  
 
==== Common errors ====
 
==== Common errors ====
{| class="bikitable"
+
{| class="wikitable"
 
!Error message
 
!Error message
 
!Cause
 
!Cause
Line 104: Line 104:
 
|
 
|
 
* in the case of a [[spawn]]ed code, previous local variables are '''not''' accessible and must be passed as arguments in order to access them.
 
* in the case of a [[spawn]]ed code, previous local variables are '''not''' accessible and must be passed as arguments in order to access them.
* a variable may have been ''undefined'' ({{Inline code|_varName {{=}} [[nil]]}}). Unset it ''after'' you are done using it.
+
* a variable may have been ''undefined'' ({{ic|_varName {{=}} [[nil]]}}). Unset it ''after'' you are done using it.
 
|-
 
|-
 
|<tt>Error x elements provided, y is expected</tt>
 
|<tt>Error x elements provided, y is expected</tt>
 
|A wrong number of arguments in array was provided
 
|A wrong number of arguments in array was provided
<code>_unit [[setPos]] [0]; {{codecomment|// [[setPos]] only takes an array of 2 to 3 elements}}</code>
+
<code>_unit [[setPos]] [0]; {{cc|[[setPos]] only takes an array of 2 to 3 elements}}</code>
 
|rowspan="2" align="center"|'''Read the wiki about said command'''.<br><br>Use [[typeName]] to output a variable type and compare it to the command's wiki page.
 
|rowspan="2" align="center"|'''Read the wiki about said command'''.<br><br>Use [[typeName]] to output a variable type and compare it to the command's wiki page.
 
|-
 
|-
 
|<tt>Error type x, expected y</tt>
 
|<tt>Error type x, expected y</tt>
 
|An ill-typed argument was provided.
 
|An ill-typed argument was provided.
<code>[[hint]] 5; {{codecomment|// must be [[String]] or [[Structured Text]], [[Number]] provided}}</code>
+
<code>[[hint]] 5; {{cc|must be [[String]] or [[Structured Text]], [[Number]] provided}}</code>
 
|-
 
|-
 
|rowspan="2"|<tt>Error Zero divisor</tt>
 
|rowspan="2"|<tt>Error Zero divisor</tt>
Line 124: Line 124:
 
|-
 
|-
 
|Also happens when using an invalid [[select]] index.
 
|Also happens when using an invalid [[select]] index.
<code>["a","b","c"] [[select]] 20; {{codecomment|// index can only be 0, 1 or 2}}</code>
+
<code>["a","b","c"] [[select]] 20; {{cc|index can only be 0, 1 or 2}}</code>
 
|
 
|
 
* Ensure your [[select]] happens within the array boundaries.
 
* Ensure your [[select]] happens within the array boundaries.
Line 131: Line 131:
 
|<tt>Local variable in global space</tt>
 
|<tt>Local variable in global space</tt>
 
|An attempt to [[private]] a public variable happened
 
|An attempt to [[private]] a public variable happened
<code>[[private]] "myVar"; {{codecomment|// should be "_myVar"}}</code>
+
<code>[[private]] "myVar"; {{cc|should be "_myVar"}}</code>
 
|
 
|
 
* Replace public variable usage with private variables.
 
* Replace public variable usage with private variables.
Line 141: Line 141:
 
* Do '''not''' use such suspending commands in unscheduled environment.
 
* Do '''not''' use such suspending commands in unscheduled environment.
 
* For an '''FSM''' condition, a common workaround would be:
 
* For an '''FSM''' condition, a common workaround would be:
<code>[[private]] _t = [[time]] + 5; {{codecomment|// Code - having to wait for 5 seconds}}</code>
+
<code>[[private]] _t = [[time]] + 5; {{cc|Code - having to wait for 5 seconds}}</code>
<code>[[time]] > _t {{codecomment|// Condition}}</code>
+
<code>[[time]] > _t {{cc|Condition}}</code>
 
* [[spawn]] code:
 
* [[spawn]] code:
 
<code>[[player]] [[addEventHandler]] ["Fired", { [] [[spawn]] { [[sleep]] 1; [[hint]] "bang"; }; }];</code>
 
<code>[[player]] [[addEventHandler]] ["Fired", { [] [[spawn]] { [[sleep]] 1; [[hint]] "bang"; }; }];</code>
Line 179: Line 179:
 
See [[:Category:Community Tools#SQF and debug Tools|Community Tools - SQF and debug Tools]].
 
See [[:Category:Community Tools#SQF and debug Tools|Community Tools - SQF and debug Tools]].
  
 
[[Category:Operation Flashpoint: Editing]]
 
[[Category:ArmA: Editing]]
 
{{GameCategory|arma2|Editing}}
 
{{GameCategory|arma3|Editing}}
 
[[Category:Take_On Helicopters: Editing]]
 
 
[[Category:Scripting Topics]]
 
[[Category:Scripting Topics]]

Revision as of 00:00, 25 March 2021

Debugging Techniques are ways for a developers to debug (narrow down/determine the root source), or to learn and understand where and why errors or unexpected outcomes are occurring within their code.

«
« Debugging is the process of finding and resolving defects or problems within a computer program that prevent correct operation of computer software or a system. » – Wikipedia (source)


Code basics

Various links about code and how to write it:

IDE and Syntax Highlight

Syntax errors are a frequent occurrence when developing scripts. Syntax highlight will help you find typos in commands and in your scripts.

An Integrated Development Environment (short IDE) is a development environment software that provides among other things code analysis, code completion and syntax highlight to help you write better, more error free 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 behavior. Error are not to happen as it may reduce performance as well as break a mission/feature. So if you notice an issue, address it as 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).

Make sure you enable Show Script Errors in the Launcher (for Arma 3) or set the corresponding -showScriptErrors startup parameter.

A script error will greet you with this box:

Script error message

It tells you what went wrong, shows a snippet of the code that failed and what file and line it occurred in (unless you used a command combination like eg. compile loadFile). Knowing this, you now can proceed to find the actual reason why that specific piece of code errored.

This information can also be found in the RPT log.

To solve an issue, you must first to became aware that of it. Aside from your script not having the desired result/effect (if any), an error message can tell you about the problem.

RPT files

The RPT is also used by the game's engine log other type of problems (low level engine issues, or content problems for example). Hence it will dump all kinds of debug information, warnings, errors as well as encountered script errors. One can also write information to it by using commands like diag_log.

The RPT file might be disabled using the Arma 3 launcher or by setting the corresponding -noLogs startup parameter (Arma 3 or Arma 2: Operation Arrowhead option)
RPT File location per game (See Crash Files for more information)
Game Location Files
Arma 3 logo black.png1.00 Arma 3 %localappdata%\Arma 3 Arma3_x64_yyyy-mm-dd_hh-mm-ss.rpt
Logo A2.png1.00 Arma 2 %localappdata%\Arma 2 arma2.rpt
Logo A1 black.png1.00 Armed Assault %localappdata%\ArmA arma.rpt
Logo A0.png1.00 Operation Flashpoint OFP root directory flashpoint.rpt
context.bin

Solving Errors

Once the script error is located: Make sure to check first the BiKi page corresponding to the command/function you are using to learn about potential misuse or other important information mentioned on the page!

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.

If you're having great difficulty solving a problem, the good way is to narrow down the issue to the simplest code block possible;

or take the mission part that doesn't work, paste it into a new test mission and go from here.

Doing so will save you dealing with other scripts' potential side effects!

Common errors

Error message Cause Solution
Error Undefined variable in expression: _varName variable _varName has not been initialised properly in this context.

hint _nonExistentVar;

  • in the case of a spawned code, previous local variables are not accessible and must be passed as arguments in order to access them.
  • a variable may have been undefined (_varName = nil). Unset it after you are done using it.
Error x elements provided, y is expected A wrong number of arguments in array was provided

_unit setPos [0]; // setPos only takes an array of 2 to 3 elements

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.

hint 5; // must be String or Structured Text, Number provided

Error Zero divisor Pretty self-explanatory, somewhere in the code is a division by zero.

private _number = 0; private _result = 100/_number;

  • Make sure to check that your divisor is different from zero before dividing.

private _result = [100, 100/_number] select (_number != 0);

Also happens when using an invalid select index.

["a","b","c"] select 20; // index can only be 0, 1 or 2

  • Ensure your select happens within the array boundaries.
  • use selectRandom to pick a random item in an array.
Local variable in global space An attempt to private a public variable happened

private "myVar"; // should be "_myVar"

  • Replace public variable usage with private variables.
Error Generic error in expression A sleep/uiSleep/waitUntil command has been used in an unscheduled environment.

player addEventHandler ["Fired", { sleep 1; hint "bang"; }];

  • Do not use such suspending commands in unscheduled environment.
  • For an FSM condition, a common workaround would be:

private _t = time + 5; // Code - having to wait for 5 seconds time > _t // Condition

player addEventHandler ["Fired", { [] spawn { sleep 1; hint "bang"; }; }];

Further code reading is required.
  • cut your code in smaller pieces and locate the concerned line(s).

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

Code Edition

See Community Tools - Code Edition.

Debug Console/System

See Community Tools - Debug Console/System.

SQF and debug Tools

See Community Tools - SQF and debug Tools.