Debugging

Explanation

The release of Gungeon available for purchase is a Unity release build. This means that not only is there no debugging information included for the game itself or Unity, there isn't even a way to load debugging information in the game. It doesn't even make use of information that it technically could. Here is an example of an error stack trace:

NullReferenceException: Object reference not set to an instance of an object
  at Pathfinding.Pathfinder.GetPath (IntVector2 start, IntVector2 goal, CellTypes passableCellTypes, Boolean canPassOccupied, Pathfinding.Path& path, IntVector2 clearance, Pathfinding.CellValidator cellValidator, Pathfinding.ExtraWeightingFunction extraWeightingFunction) [0x00000] in <filename unknown>:0 
  at Pathfinding.Pathfinder.GetPath (IntVector2 start, IntVector2 end, Pathfinding.Path& path, Nullable`1 clearance, CellTypes passableCellTypes, Pathfinding.CellValidator cellValidator, Pathfinding.ExtraWeightingFunction extraWeightingFunction, Boolean canPassOccupied) [0x00000] in <filename unknown>:0 
  at AIActor.PathfindToPosition (Vector2 targetPosition, Nullable`1 overridePathEnd, Boolean smooth, Pathfinding.CellValidator cellValidator, Pathfinding.ExtraWeightingFunction extraWeightingFunction, Nullable`1 overridePathableTiles, Boolean canPassOccupied) [0x00000] in <filename unknown>:0 
  at SeekTargetBehavior.Update () [0x00000] in <filename unknown>:0 
  at BehaviorSpeculator.UpdateBehaviorClass (IList behaviors, Boolean isTick, Boolean onGlobalCooldown) [0x00000] in <filename unknown>:0 
  at BehaviorSpeculator.UpdateBehaviors (Boolean isTick, Boolean onGlobalCooldown) [0x00000] in <filename unknown>:0 
  at BehaviorSpeculator.Update () [0x00000] in <filename unknown>:0 

Most C# decompilers have the ability to display the code in a much "simpler" language called IL - IL is a representation of the actual bytecode in the file, and while very verbose and sometimes difficult to understand, it absolutely can be used to locate where in code (decompiled or not) the error happened. The numbers in brackets - [0x00000] - normally tell you where in the IL the exception was thrown, but everything except for names is completely blanked out here, due to how Unity release builds are setup.

Since version [TODO], the Semi Installer is able to convert the release build of the game into a build with debugging enabled (on all three supported platforms), bringing long awaited proper stacktraces and even the ability to attach an external Mono debugger!

Here is how a stacktrace looks with full debugging capabilities:

at Semi.DebugConsole.Console.ResolveCommand (System.String path) [0x00037] in /home/zatherz/.local/share/Steam/steamapps/common/Enter the Gungeon/EtG_Data/Managed/IL_Assembly-CSharp/Semi/DebugConsole/Console/ResolveCommand.il:2
at Semi.DebugConsole.Console.<.ctor>b__9_0 (System.String name, System.Collections.Generic.List`1 args, Nullable`1 history_index) [0x00003] in /home/zatherz/.local/share/Steam/steamapps/common/Enter the Gungeon/EtG_Data/Managed/IL_Assembly-CSharp/Semi/DebugConsole/Console/<.ctor>b__9_0.il:2
at Semi.DebugConsole.Parser.Executor.ExecuteCommand (Command cmd, Nullable`1 history_index) [0x00052] in /home/zatherz/.local/share/Steam/steamapps/common/Enter the Gungeon/EtG_Data/Managed/IL_Assembly-CSharp/Semi/DebugConsole/Parser/Executor/ExecuteCommand.il:2
at Semi.DebugConsole.Console.ExecuteCommand (System.String cmd) [0x0001d] in /home/zatherz/.local/share/Steam/steamapps/common/Enter the Gungeon/EtG_Data/Managed/IL_Assembly-CSharp/Semi/DebugConsole/Console/ExecuteCommand.il:2
at Semi.DebugConsole.Console.ExecuteCommandAndPrintResult (System.String cmd) [0x0003c] in /home/zatherz/.local/share/Steam/steamapps/common/Enter the Gungeon/EtG_Data/Managed/IL_Assembly-CSharp/Semi/DebugConsole/Console/ExecuteCommandAndPrintResult.il:2

You get IL offsets within the method (e.g. [0x00037]) and paths to files containing decompiled IL instructions for methods that come from the game or Semi. For Unity methods that don't come from the core library, the stack traces will point to actual source code that you can see under the 2017.4 branch in the official UnityCsReference repository.

Semi Debugging

To enable debugging capabilities, click the "gear" icon in the Semi installer.

This will lead you to the Advanced Settings page.

Simply scroll down, and you should see a "Debugging" section with some options:

Debugging Options

Unity debug build

This tells the installer to convert the release build of the Unity player into a debug build. If enabled, the conversion will happen automatically after Semi is successfully installed.

The installer will download an appropriate Unity installer for the platform (the actual installer for Windows or export templates for Linux/Mac) or use one that it already downloaded. It will then unpack the files from that installer, locate the debug Unity Player executable appropriate for the OS and swap certain files within Gungeon, including EtG.exe (or equivalent).

If this option is enabled and Semi is installed, your game will look a bit different than in the release build:

Please note that while the Unity debug build does include debugging symbols for all UnityEngine DLLs, debugging symbols for UnityEngine.CoreModule.dll will not be installed, as that file is modified by Semi.

Please note that this option alone also does not provide any debugging symbols for Assembly-CSharp.dll or the aforementioned UnityEngine.CoreModule.dll. Also note that you have to set the 7zip path for this option to work (see below), otherwise installing will fail.

IL debugging

This option enables the use of MonoMod DebugIL for generating debug symbols for assemblies that lack it based on IL. You can read up more on IL here. If you enable this option, an extra step will be ran after the Unity debug build step which will generate this information for Assembly-CSharp.dll and UnityEngine.CoreModule.dll. The IL of both of these will be put in folder hierarches under IL_Assembly-CSharp and IL_UnityEngine.CoreModule in the EtG_Data/Managed folder, if at any point you wish to inspect them.

This also enables displaying the IL offset in stack traces, which you can use to locate the exact point at which a call was made/exception was thrown.

This option will not work unless "Unity debug build" is also enabled.

7z Exe Path

Part of the process of converting a Unity release build to a debug build is automatically downloading an appropriate installer from the Unity web server and unpacking certain files from it. Unity uses an installer framework called NSIS, and 7zip is by far the most common and best tool that can extract files from installers made with this framework.

On Windows, this should point to 7za.exe, not 7z.exe. On Linux, 7z, usually located in /usr/bin/7z.

On Mac, you can get 7zip through Homebrew. Run this command in the Terminal to install Homebrew (if you don't have it):

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Then run this command to install p7zip:

brew install p7zip

Now you will have the 7zip executable at /usr/local/bin/7z.