Editing Debug Dumps

==Overview==
There are various functions in [[:Category:Functions (NVSE)|NVSE]] that allow you to dump debugging information from any game to a text file. This is highly useful when attempting to solve third party bug reports, as all the information you need may be provided by the user simply uploading you a text file, created by running a script which could be triggered by clicking an [[Mod Configuration Menu|MCM]] button, or by console adding some object or spell, etc. 

This article describes a template of useful features you may want to include in a debug dump script.
===Start===
<pre>
scn CreateDebugDump

int LastEcho
int iTotalMods
int iIndex
array_var UT
array_var aQuests
array_Var aObjects
array_var entry
string_var file_name
string_var svkey
string_var FO_dir
ref rQuest
ref rObject

Begin Function { }
</pre>
A [[User Defined Function]] is a convenient way to run the script, although it could just as easily be on object <b>OnAdd</b> or spell <b>ScriptEffectStart</b>. Above is the variable declaration for the proceeding examples.

===File naming===
<pre>
    let file_name := "MyModName-Debug-Dump-"
    let UT := GetUserTime
    foreach entry <- (Ar_List "Year", "Month", "Day", "Hour", "Minute", "Second")
        let svkey := entry["value"]
        if eval svkey == "Hour"
            let file_name += "-"
        endif
        let file_name += "-" + $UT[svkey]
    loop
    let file_name += ".txt"

    con_SCOF $file_name

    Print "Starting debug dump to file: " + file_name
</pre>
A [[String Variable]] and the [[GetUserTime]] function can be used to create a unique and recognizable file name for your dump, based on your mod name and the real life time it is created. The [[Con_SCOF]] command writes all console output to the specified file, which will be found in the main game directory of the user. The [[Print]] command outputs text to the console, and supports many convenient features. 

The debug dump file name will look like: "MyModName-Debug-Dump-YEAR-MONTH-DAY--HOUR-MINUTE-SECOND.txt"

===Versions===
<pre>
; * Versions
    Print "My Mod Version: " + $MyModMainQuest.version
    Print "My Mod's Master Version: " + $MyMasterMainQuest.version
    Print "NVSE Version: " + $(GetNVSEVersion) + "." + $(GetNVSERevision) + "." + $(GetNVSEBeta)
    Print "NX (An NVSE plugin) Version: " + $(NX_GetVersion)
</pre>
It is helpful to reliably know what version of your mod, and any requirements it might have that the user has installed. The [[ToString|ToString($)]] command converts anything to a string for printing. Notice <b>Print</b> allows direct printing of quest variables and function returns (eg: [[GetNVSEVersion|$(GetNVSEVersion)]], the added brackets allow clear distinction of functions). 

===Load Order===
<pre>
; * Load Order
    Print "Load Order:"
    let iTotalMods := GetNumLoadedMods
    let iIndex := 0
    while iIndex < iTotalMods
        Print (NumToHex iIndex, 2) + " (" + $iIndex + "): " + (GetNthModName iIndex)
        let iIndex += 1
    loop
    Print " * End Load Order *"
</pre>
By using [[GetNthModName]] you can find out for certain what a user's load order is. This prints all loaded mods with their index in both hexadecimal and decimal. (See also: [[GetNumLoadedMods]], [[While]], [[NumToHex]])

===Quest Statuses===
<pre>
; * Quest statuses
    let aQuests := Ar_List MyQuest1, MyQuest2, MyQuest3 ... MyQuest20

    let LastEcho := SetConsoleEcho 1
    foreach entry <- aQuests
        let rQuest := entry["value"]
        Print "Quest: " + $rQuest
        con_SQV rQuest
        Print " * * * * * "
    loop
    SetConsoleEcho LastEcho
</pre>
The [[Con_SQV]] command human readably prints the name and value of all variables attached to a quest (except array_var and string_var, which you get the ID number, not contents), and it's current running status, stage and priority. You need to use [[SetConsoleEcho]] before calling it, however. 

Above, we create an array with [[Ar_List]] and put all the quests we want to dump in it. You can specify up to 20 entries in one <b>Ar_List</b> call, see the [[Tutorial: Array Variables 1|arrays tutorial]] if you want more than 20 entries. Then we print the name of the quest '$rQuest' and do <b>Con_SQV</b> [[Foreach|for each]] one.

===Object Script Variables===
<pre>
; * Object Variable Statuses
    let aObjects := Ar_List SunnyREF, MyActorREF, MyDoorREF, PlayerREF...
    let LastEcho := SetConsoleEcho 1
    foreach entry <- aObjects
        let rObject := *entry ; '*' is shorthand for entry["value"]
        Print "Variables for " + $rObject
        Con_ShowVars rObject
        Print " * * * * * "
    loop
    SetConsoleEcho LastEcho
</pre>
The function, [[Con_ShowVars]] is similar to <b>Con_SQV</b> for quests; it prints the name and value of all variables in object scripts attached to the reference (including those on their inventory items). It also requires console echo to be toggled on.

===Actor Inventory===
<pre>
; * Player inventory
    Print "Player Inventory: "
    let LastEcho := SetConsoleEcho 1
    PlayerREF.Con_Inv
    SetConsoleEcho LastEcho
    Print " * End Inventory *"
</pre>
The [[Con_Inv]] command is equivalent to typing [[ShowInventory|Inv]] into the game console to print the contents of an inventory. This command also requires console echo to be toggled on. (You can just toggle it on once at start, if you need it multiple times)

===Array dumping===
<pre>
    Ar_Dump SomeQuest.SomeArray
</pre>
If you have some arrays you want to read, you can use [[Ar_Dump]], or call some UDF that does a more bespoke version. 

===Player Actor Values===
<pre>
; * Player Actor Values
    Print "Player Actor Values: "
    let iChoice := 0
    while iChoice < 73
        Print $iChoice + " (" + (ActorValueToStringC iChoice) + "): " +  $(PlayerREF.GetAV iChoice)
        let iChoice += 1
    loop
    Print " * End Actor Values *"
</pre>
To use this convenient code, you need to use the [[Script Compiler Override]] to allow you to reference [[GetActorValue|Actor Values]] by their [[Actor Value Codes|int codes]]. It prints the code number, [[ActorValueToStringC|the language localized name]], and value for all the player's actor values.

===Player NX variables===
<pre>
; Player NX variables
    Print "Player NX variables: "
    foreach entry <- (Ar_List (PlayerREF.NX_GetEVFlAr ""), (PlayerREF.NX_GetEVFoAr ""), (PlayerREF.NX_GetEVStAr ""))
        Ar_Dump entry["value"]
    loop
    Print " * End Player NX variables *"
</pre>
If you are using the [[NX]] NVSE plugin, you can dump the name and value of every NX variable stored on the player like this. Replacing the "" empty strings with your mod prefix allows you to only dump relevant ones.

===Misc===
<pre>
; * Misc
    Print "GameDaysPassed: " + $GameDaysPassed
    Print "Hardcore mode: " + $(PlayerREF.IsHardcore)
    Print "Player Level: " + $(PlayerREF.GetLevel)
</pre>
You can print anything else that might be useful.

===End===
<pre>
; * End
    Print "*** All done! ***"
    let FO_dir := GetFalloutDirectory
    MessageBoxEx "My Mod completed a debug dump, please upload the file '%z' to me, which is in your FNV main directory ('%z')" file_name, FO_dir

    Sv_Destruct file_name, svkey, FO_dir

End
</pre>
Finally, you can use [[MessageBoxEx]] (which sadly requires [[String Formatting]] unlike <b>Print</b>) to notify the user with your instructions, and tell them what the dump file is called and where they can find it, by using [[GetFalloutDirectory]] to return thier FNV main directory. You then need to [[Sv_Destruct]] the local string variables or they can cause save game bloat.

[[Category:Debugging]]
[[Category:Advanced Modding Techniques]]