Lou Montana/Sandbox – User

From Bohemia Interactive Community
< Lou Montana
Category: Sandbox
m (Debugging Techniques stub update (merging with X39's edits)
m (Update w/ links)
 
(94 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{SideTOC}}
[[Category: Sandbox]]
[[Debugging Techniques]] are ways in which developers can debug, or find out where errors or unexpected outcomes are occurring within their scripts.
{{Feature|informative|To go on [[Initialisation Order]].}}
{{note|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 – ''[https://en.wikipedia.org/w/index.php?title{{=}}Debugging Wikipedia - Debugging]'' }}


== Code ==
{| class="wikitable sortable align-center align-left-col-1"
|+ Order of Initialisation (use column sorting for respective machine order)
! rowspan="2" class="unsortable" style="text-align: center" | Task
! rowspan="2" | Exec Environment
! rowspan="1" colspan="5" class="unsortable" | Machine
|-
! Single Player
! Dedicated Server
! Hosted Server
! Multiplayer Client
! [[Multiplayer Scripting#Join In Progress|JIP]] MP Client


Various links about code and how to write it:
|-
* [[SQF syntax]]
| [[Arma 3: Functions Library|Functions]] with <syntaxhighlight lang="cpp" inline>recompile</syntaxhighlight> {{Link|Arma 3: Functions Library#Attributes 3|attribute}} are recompiled
* [[SQS syntax]]
| {{n/a}}
* [[Code Optimisation]]
| 1 <!-- Single Player -->
| 1 <!-- Dedicated Server -->
| 1 <!-- Hosted Server -->
| 1 <!-- Multiplayer Client -->
| 1 <!-- JIP MP Client -->


=== IDE and Syntax Highlight ===
|-
| [[Arma 3: Functions Library|Functions]] with <syntaxhighlight lang="cpp" inline>preInit</syntaxhighlight> {{Link|Arma 3: Functions Library#Attributes 3|attribute}} are called
| [[Scheduler#Unscheduled Environment|Unscheduled]]
| 2 <!-- Single Player -->
| 2 <!-- Dedicated Server -->
| 2 <!-- Hosted Server -->
| 2 <!-- Multiplayer Client -->
| 2 <!-- JIP MP Client -->


Syntax errors can be a frequent occurrence when developing scripts. '''Syntax highlight''' will help you find typos in commands and in your scripts.<br />
|-
An '''I'''ntegrated '''D'''evelopment '''E'''nvironment, shortened to '''IDE''' is as its name says a development environment program, providing '''syntax highlight''' helping you writing code.<br />
| Object Init Event Handlers are called
<br />
| [[Scheduler#Unscheduled Environment|Unscheduled]]
See further [[#Downloadable Tools|Downloadable Tools]] page section for download links.
| 3 <!-- Single Player -->
| 3 <!-- Dedicated Server -->
| 3 <!-- Hosted Server -->
| 3 <!-- Multiplayer Client -->
| {{Icon|unchecked}} <!-- JIP MP Client -->


=== Finding Errors ===
|-
| Expressions of [[Eden Editor: Configuring Attributes|Eden Editor entity attributes]] are called<ref name="isPlayer"><sqf inline>isPlayer _entity</sqf> does not return [[true]] immediately. Once the entity has become a [[player]], it is transferred to the client.</ref>
| [[Scheduler#Unscheduled Environment|Unscheduled]]
| 4 <!-- Single Player -->
| 4 <!-- Dedicated Server -->
| 4 <!-- Hosted Server -->
| {{Icon|unchecked}} <!-- Multiplayer Client -->
| {{Icon|unchecked}} <!-- JIP MP Client -->


Debugging is, most of the time, literally as complicated as writing the actual code itself.
|-
You usually get hinted by the game, where some error happened, and what it was.<br />
| Object initialisation fields are called
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).
| [[Scheduler#Unscheduled Environment|Unscheduled]]
| 5 <!-- Single Player -->
| 5 <!-- Dedicated Server -->
| 5 <!-- Hosted Server -->
| 4 <!-- Multiplayer Client -->
| 3 <!-- JIP MP Client -->


{{Important|For Arma 3, you need to enable ''Show Script Errors'' in the Launcher or set the corresponding [[Arma_3_Startup_Parameters|-showScriptErrors]] flag}}
|- style="background-color: #95F0AD"
 
| [[Event Scripts#init.sqs|init.sqs]] is executed
A script error will greet you with this box:
|
[[File:A3_ScriptErrorMsg.jpg|thumb|Script error message|center|500px]]
| 6 <!-- Single Player -->
 
| <!-- Dedicated Server -->
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.
| <!-- Hosted Server -->
Knowing this, you now can proceed to find the actual reason why you errored on that specific piece of code.
| <!-- Multiplayer Client -->
 
| <!-- JIP MP Client -->
{{informative|This information can also be found in the RPT log.}}
 
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 [[Arma 3 Startup Parameters#Developer Options|<tt>-showScriptErrors</tt>&nbsp;startup&nbsp;parameter]] to display the error on-screen
* To ensure error location in your script, prefer [[preprocessFileLineNumbers]] to [[preprocessFile]]
* Read [[Crash Files|RPT files]] for more information (make sure [[Arma 3 Startup Parameters#Performance|<tt>-noLogs</tt> 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 locations depending upon the type of server being run.
** Scripts running on a client use the '''ArmaX.RPT''' file.
** RPT files location is usually <tt>%localappdata%\ArmaX</tt>


|- style="background-color: #95F0AD"
| [[Event Scripts#init.sqf|init.sqf]] is executed
| [[Scheduler#Scheduled Environment|Scheduled]]<ref name="enginewaits">Note '''in single player''' that while the environment is [[Scheduler#Scheduled Environment|Scheduled]] ([[canSuspend]] returns true), the engine seems to wait until the script is done executing, essentially behaving similarly to an [[Scheduler#Unscheduled Environment|Unscheduled environment]] - infinite loops will freeze the game, [[uiSleep]] may pause the game for up to ~20s (postInit), [[waitUntil]] can cause catastrophic issues, etc.</ref>
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


==== RPT files ====
An [[arma.RPT|RPT]] (or [[Crash Files|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]].
{{Feature arma3|The RPT file might be disabled using the Arma 3 launcher or by setting the corresponding [[Arma_3_Startup_Parameters|-noLogs]] flag.}}
{|class="bikitable"
|+ RPT File location per game
!Game
!Location
|-
| {{GVI|arma3|1.00}} {{arma3}}
| <code>'''%userprofile%'''\AppData\Local\Arma 3</code>
|-
| {{GVI|arma2|1.00}} {{arma2}}
| <code>'''%userprofile%'''\AppData\Local\ArmA 2</code>
|-
| {{GVI|arma|1.00}} {{arma}}
| <code>'''%userprofile%'''\AppData\Local\ArmA</code>
|-
|-
| {{GVI|ofp|1.00}} {{ofp}}
| Expressions of [[Eden Editor: Configuring Attributes|Eden Editor scenario attributes]] are called<ref name="playerCommandNotAvailable">[[player]] is not available immediately.</ref>
| <code>'''''OFP root directory'''''\flashpoint.rpt</code>
| [[Scheduler#Unscheduled Environment|Unscheduled]]
<code>'''''OFP root directory'''''\context.bin</code>
| <!-- Single Player -->
|}
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


|- style="background-color: #95DEF0"
| Persistent functions are called
|
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


=== Removing 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|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 [[Variables|variable]] A is not set, go to where [[Variables|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.
{{Informative|If you're having great difficulty solving a problem, the good way is to bring the issue to the simplest code;
take the mission part that doesn't work, paste it into a new test mission and work from here.
Doing so will save you dealing with other scripts' potential side effects!}}
==== Common errors ====
{| class="bikitable"
!Error message
!Cause
!Solution
|-
|-
|<tt>Error Undefined variable in expression: _varName</tt>
| [[Modules]] are initialised
|variable ''_varName'' has not been initialised properly in this context.
|
|
* 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.
| <!-- Single Player -->
* a variable may have been ''undefined'' ({{Inline code|_varName {{=}} [[nil]]}}). Unset it ''after'' you are done using it.
| <!-- Dedicated Server -->
|-
| <!-- Hosted Server -->
|<tt>Error Zero divisor</tt>
| <!-- Multiplayer Client -->
|Pretty self-explanatory, somewhere in your code is a division by zero.
| {{Icon|unchecked}} <!-- JIP MP Client -->
|* Make sure to check if your divisor is different from zero before dividing.
|-
|<tt>Generic error</tt>
|Further code reading is required.
|* If it happens on a [[sleep]]/[[uiSleep]]/[[waitUntil]], you may be in [[Scheduler#Unscheduled Environment|unscheduled environment]].
|}


=== Working with Addons ===
|- style="background-color: #DEF0AD"
If you are working on an addon, repacking a PBO can be time-intensive.
| [[Event Scripts#initServer.sqf|initServer.sqf]] is executed
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.
| [[Scheduler#Scheduled Environment|Scheduled]]
The easiest way of accomplishing this is by the use of [[Event Scripts]] to run your code such as [[init.sqf]].
| <!-- Single Player -->
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.
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| {{n/a}} <!-- Multiplayer Client -->
| {{n/a}} <!-- JIP MP Client -->


=== Debugging specific sections of code ===
|- style="background-color: #DEF0AD"
Although primitive, the combined use of [[diag_log]], [[systemChat]]/[[hint]] and [[format]] can help to debug the content of function arguments.
| [[Event Scripts#initPlayerLocal.sqf|initPlayerLocal.sqf]] is executed
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.
| [[Scheduler#Scheduled Environment|Scheduled]]
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.
| <!-- Single Player -->
| {{n/a}} <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


|- style="background-color: #DEF0AD"
| [[Event Scripts#initPlayerServer.sqf|initPlayerServer.sqf]] is executed on the server
| [[Scheduler#Scheduled Environment|Scheduled]]
| <!-- Single Player -->
| {{n/a}} <!-- Dedicated Server -->
| ?? <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


== Downloadable Tools ==
|-
| [[Arma 3: Functions Library|Functions]] with <syntaxhighlight lang="cpp" inline>postInit</syntaxhighlight> {{Link|Arma 3: Functions Library#Attributes 3|attribute}} are called
| [[Scheduler#Scheduled Environment|Scheduled]]<ref name="enginewaits"/>
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


=== IDE ===
|- style="background-color: #95DEF0"
* [[User:Sbsmac|Sbsmac]]'s '''Squint''': [https://forums.bohemia.net/forums/topic/101921-squint-the-sqf-editor-and-error-checker/ Forum post] - [https://sites.google.com/site/macsarmatools/squint website]<br />Provides a fully-featured code editor which allows for syntax highlighting, displaying of errors and code correction.
| [[Event Scripts#init.sqs|init.sqs]] is executed
* [https://forums.bohemia.net/profile/1044335-krzmbrzl/ krzmbrzl]'s '''SQDev''': [https://forums.bohemia.net/forums/topic/202181-sqdev-sqf-developing-in-eclipse/ Forum post] - [https://github.com/Krzmbrzl/SQDev GitHub repository]<br />Provides code validation (linting) while you are typing it.
| [[Scheduler#Scheduled Environment|Scheduled]]
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


=== Syntax Highlight ===
|- style="background-color: #95DEF0"
* [https://forums.bohemia.net/profile/797692-sanjo/ Sanjo]'s '''Notepad++ SQF''' (npp-sqf, plugin for [https://notepad-plus-plus.org/download/ Notepad++]): [http://www.armaholic.com/page.php?id=8680 Forum post] - [https://github.com/Sanjo/npp-sqf GitHub repository]
| [[Event Scripts#init.sqf|init.sqf]] is executed
| [[Scheduler#Scheduled Environment|Scheduled]]
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


=== Debug Console ===
|-
A '''Debug Console''' is a powerful tool; it is very helpful at debugging your scripting in real time.
| [[remoteExec]]'s [[Multiplayer Scripting#Join In Progress|JIP]] queue
* {{arma3}}
| {{n/a}}
** The game already features [[Mission Editor: Debug Console (Arma 3)|Arma 3 Debug Console]].
| {{n/a}} <!-- Single Player -->
** [https://forums.bohemia.net/profile/761667-charon-productions/ Charon Productions]' [http://www.armaholic.com/page.php?id=19898 TroopMon3] for Arma 3 (alpha)
| {{n/a}} <!-- Dedicated Server -->
* {{tkoh}}
| {{n/a}} <!-- Hosted Server -->
** The game already features [[Mission Editor: Debug Console (Take On Helicopters)|TKOH Debug Console]].
| {{n/a}} <!-- Multiplayer Client -->
* {{arma2}}
| 42 <!-- JIP MP Client -->
** [[User:Str|Str]]'s [http://temp.moricky.com/arma2/stra_debug2.rar Debug console]
** [https://forums.bohemia.net/profile/761667-charon-productions/ Charon Productions]' [http://www.armaholic.com/page.php?id=7948 TroopMon3] for Arma 2 ([http://www.armaholic.com/page.php?id=7948 TroopMon2] being obsolete and rewritten into this TroopMon3)
** [http://forums.bistudio.com/showthread.php?t=126249 DevCon] by [[User:Kju|Kju]]
* {{arma}}
** [https://forums.bohemia.net/profile/761667-charon-productions/ Charon Productions]' [http://www.armaholic.com/page.php?id=727 TroopMon v0.8b] - Complex debugging system providing lot of information for mission-makers, especially about AI.
** [[User:Str|Str]]'s [http://www.armaholic.com/page.php?id=549 Debug Console] - available in all singleplayer missions, intros and outros. Easy and simple to use (Escape-Enter execute)
* {{ofp}}
** [[User:Vektorboson|Vektorboson]]'s [http://home.arcor.de/vektorboson/res/console_3.7z Debug Console]


=== Emulators and Debuggers ===
|- style="background-color: #EEE"
* [[User:X39|X39]]'s [https://forums.bohemia.net/forums/topic/210118-sqf-vm-an-sqf-emulator/ SQF VM] - an SQF emulator
| ''Scenario going''
* [[User:Dedmen|Dedmen]]'s [https://github.com/dedmen/ArmaScriptProfiler/ Arma Script Profiler]
| {{n/a}}
* [[User:Dedmen|Dedmen]]'s [https://github.com/dedmen/ArmaDebugEngine Arma Debug Engine]
| <!-- Single Player -->
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->


=== Others (table) ===
{| class="bikitable"
! Game
! User
! Addon/Toolname
! Description
! Link
|-
|-
|{{GVI|arma|1.00}}
| [[Event Scripts#exit.sqf|exit.sqf]]
|[[User:Vektorboson|Vektorboson]]
|
|
|Debugging console
| <!-- Single Player -->
|<s>[http://home.arcor.de/vektorboson/res/console_3.7z '''''LINK DEAD''''']</s>
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->
 
|-
|-
|{{GVI|arma|1.00}}
| [[Event Scripts#exit.sqs|exit.sqs]]
|[[User:Str|Str]]
|
|
|Debugging console (addon, available in intros, missions and outros)
| <!-- Single Player -->
|<s>[http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi?s=1593a8bb7375674288e681ba36b48dc3;act=ST;f=70;t=56294 '''''LINK DEAD''''']</s>
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->
 
|-
|-
|{{GVI|arma|1.0}}
| {{Link|Arma 3: Mission Event Handlers#Ended|"Ended" Mission Event Handler}}
|Charon Productions
|TroopMon
|Debugging system containing informations relevant to mission-makers (especially about AI)
|<s>[http://www.flashpoint1985.com/cgi-bin/ikonboard311/ikonboard.cgi?s=c10d84cce14a63a54ac915506d008e80;act=ST;f=69;t=57493 '''''LINK DEAD''''']</s>
|-
|{{GVI|arma2|1.00}}
|[[User:Str|Str]]
|
|
|Debug console
| <!-- Single Player -->
|[http://temp.moricky.com/arma2/stra_debug2.rar download]
| <!-- Dedicated Server -->
| <!-- Hosted Server -->
| <!-- Multiplayer Client -->
| <!-- JIP MP Client -->
 
|-
|-
|{{GVI|arma2|1.00}}
| {{Link|Arma 3: Mission Event Handlers#MPEnded|"MPEnded" Mission Event Handler}}
|Charon Productions
|TroopMon3
|Debugging system containing informations relevant to mission-makers (especially about AI)
|[http://www.armaholic.com/page.php?id=7948 download]
|-
|{{GVI|arma2|1.00}}
|[[User:Kju|Kju]]
|DevCon
|
|
|[http://forums.bistudio.com/showthread.php?t=126249 download]
| <!-- Single Player -->
|-
| <!-- Dedicated Server -->
|{{GVI|arma2|1.00}}
| <!-- Hosted Server -->
|Chain of Command
| <!-- Multiplayer Client -->
|Binary gamefile viewer
| <!-- JIP MP Client -->
|Allows to check variables and script states in save files
 
|<s>[http://ofp.gamepark.cz/index.php?showthis=6989&newlang=eng '''''LINK DEAD''''']</s>
|-
|{{GVI|tkoh|1.00}}
|[[Bohemia_Interactive|Bohemia Interactive]]
| ''N/A''
|Debug Console capable of executing code and more.
|[[Mission_Editor:_Debug_Console_(Take_On_Helicopters)|Shipped With Game]]
|-
|{{GVI|arma3|1.00}}
|[[Bohemia_Interactive|Bohemia Interactive]]
| ''N/A''
|Debug Console capable of executing code and more.
|[[Mission_Editor:_Debug_Console_(Arma 3)|Shipped With Game]]
|}
|}




[[Category:Operation Flashpoint: Editing]]
== See Also ==
[[Category:ArmA: Editing]]
[[Category:ArmA 2: Editing]]
[[Category:Take_On Helicopters: Editing]]
[[Category:Arma 3: Editing]]
[[Category:Scripting Topics]]
 


[[Category:Sandbox]]
* [[Arma 3: Functions Library]]<!--
* [[Arma 2: Functions Library]] -->
* [[Arma 3: Remote Execution]], [[BIS_fnc_MP]] <!-- keep? -->
* [[Eden Editor: Configuring Attributes|Eden Editor: Configuring Attributes]]
* [[Event Scripts]]
* [[Scheduler]]

Latest revision as of 01:29, 18 March 2024

ⓘ
Order of Initialisation (use column sorting for respective machine order)
Task Exec Environment Machine
Single Player Dedicated Server Hosted Server Multiplayer Client JIP MP Client
Functions with recompile attribute are recompiled N/A 1 1 1 1 1
Functions with preInit attribute are called Unscheduled 2 2 2 2 2
Object Init Event Handlers are called Unscheduled 3 3 3 3 Unchecked
Expressions of Eden Editor entity attributes are called[1] Unscheduled 4 4 4 Unchecked Unchecked
Object initialisation fields are called Unscheduled 5 5 5 4 3
init.sqs is executed 6
init.sqf is executed Scheduled[2]
Expressions of Eden Editor scenario attributes are called[3] Unscheduled
Persistent functions are called
Modules are initialised Unchecked
initServer.sqf is executed Scheduled N/A N/A
initPlayerLocal.sqf is executed Scheduled N/A
initPlayerServer.sqf is executed on the server Scheduled N/A ??
Functions with postInit attribute are called Scheduled[2]
init.sqs is executed Scheduled
init.sqf is executed Scheduled
remoteExec's JIP queue N/A N/A N/A N/A N/A 42
Scenario going N/A
exit.sqf
exit.sqs
"Ended" Mission Event Handler
"MPEnded" Mission Event Handler


See Also

  1. ↑ isPlayer _entity does not return true immediately. Once the entity has become a player, it is transferred to the client.
  2. ↑ 2.0 2.1 Note in single player that while the environment is Scheduled (canSuspend returns true), the engine seems to wait until the script is done executing, essentially behaving similarly to an Unscheduled environment - infinite loops will freeze the game, uiSleep may pause the game for up to ~20s (postInit), waitUntil can cause catastrophic issues, etc.
  3. ↑ player is not available immediately.
Retrieved from "https://community.bistudio.com/wiki?title=User:Lou_Montana/Sandbox&oldid=353415"