Debugging Unity Games

Debugging Unity Games

dnSpy can debug Unity debug builds and release builds. Release builds require a modified mono.dll / mono-2.0-bdwgc.dll file. It's also possible to turn a release build into a debug build.

Debugging release builds

Make a backup copy of your game. You need a patched mono.dll / mono-2.0-bdwgc.dll file. You can find 32-bit and 64-bit builds of Unity 4.x, 5.x, and 2017.x-2018.x on the releases page. You need to know the Unity version that was used to build the game. To get the Unity version number, check the file properties of the <game>.exe or UnityPlayer.dll. You also need to know if it's a 32-bit or a 64-bit game. If it's a 32-bit game, use the win32 directory, else if it's a 64-bit game, use the win64 directory. Different Unity versions use different mono.dll filenames. Older Unity games use .NET 2.0-3.5 assemblies and use mono.dll, and newer Unity games that use .NET 4.x assemblies use mono-2.0-bdwgc.dll. This file is stored in different locations depending on Unity version:

• <root>\<GAME>_Data\Mono\mono.dll
• <root>\<GAME>_Data\Mono\EmbedRuntime\mono.dll
• <root>\<GAME>_Data\MonoBleedingEdge\EmbedRuntime\mono-2.0-bdwgc.dll
• <root>\Mono\EmbedRuntime\mono.dll
• <root>\MonoBleedingEdge\EmbedRuntime\mono-2.0-bdwgc.dll

Copy dnSpy's patched mono.dll / mono-2.0-bdwgc.dll file to the game, overwriting its file. Now go to Debug -> Start Debugging and select Unity debug engine. If the game crashes you probably used the wrong version or you used a 32-bit file when the game is 64-bit or vice versa. You can also choose Unity (Connect) if the game has already started. dnSpy's mono.dll will look for an environment variable called DNSPY_UNITY_DBG (Unity with .NET 2.0-3.5 assemblies) or DNSPY_UNITY_DBG2 (Unity with .NET 4.x assemblies)

• DNSPY_UNITY_DBG:
  • --debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,defer=y or
  • --debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,defer=y,no-hide-debugger to enable detection of the debugger.
• DNSPY_UNITY_DBG2:
  • --debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,suspend=n or
  • --debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,suspend=n,no-hide-debugger to enable detection of the debugger.

If the environment variable is missing, it will listen on port 55555.

If you want to compile mono.dll yourself, see https://github.com/dnSpyEx/dnSpy-Unity-mono

Debugging debug builds

• Build a development build with script debugging enabled, or turn a release build into a debug build, see below
• Run the game or press play in the Unity Editor
• Start dnSpy and go to Debug -> Attach to Process (Unity) NOTE: There's a 'step over' bug in Unity versions that use mono-2.0-bdwgc.dll. Use the patched mono-2.0-bdwgc.dll instead, it has the bug fix. If you don't see the game in the dialog box, it's possible that the whole process is paused when it doesn't have keyboard focus. In that case, press Refresh in dnSpy and then quickly switch back to the game, and then back to dnSpy. If you still can't see it, wait until its intro is over and try again. If you still don't see the game, then it's probably not a Unity game or a debug build.

Turning a release build into a debug build

Have a look at the exe's properties in Explorer. You should see the Unity version number. Go to Unity download archive and download and install the correct version of Unity Editor. You'll find the windows players in <unity-install-dir>\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations. Most likely you'll want the files in win32_development_mono since it's probably a 32-bit game. Make a backup copy of your game. Copy the debug build Data directory to your games <name>_Data directory, overwriting everything in it.

• Older Unity versions: copy player_win.exe and rename it to <game-name>.exe.
• Newer Unity versions: Copy WindowsPlayer.exe + UnityPlayer.dll, and rename WindowsPlayer.exe to <game-name>.exe.
• Some Unity versions also require WinPixEventRuntime.dll to be copied such as 2018.4-mbe To enable script (.NET) debugging, you have to create a file in the <game-name>_Data directory. If it's Unity 4.x - 5.x or Unity 2017.1: <game-name>_Data\PlayerConnectionConfigFile Example:

listen 3060108046 1 1

Or if it's Unity 2017.2 or later <game-name>_Data\boot.config Example:

player-connection-mode=Listen
player-connection-guid=3060108046
player-connection-debug=1
player-connection-wait-timeout=-1
player-connection-ip=123.45.67.89

It seems like only player-connection-debug=1 is needed, the other lines can be removed.