Debugging Plugins via IDE

Introduction

This article is based upon Debugging-Unity-Games, and Debugging Unity Games. As described in the dnSpy article, you have two options for debugging a mono/unity game.

Option A: Converting Valheim into a Development Build

To be able to debug Valheim, the first step is to turn it into a Development Build. This enables IDEs to attach to it and follow code execution.

• Follow the instructions required to apply BepInEx to Valheim.
• Download Unity 2019.4.20 from the unity archive and install it.
• Make a backup of your game. (or trust steam "Verify Integrity" option)
• Navigate to <unity-install-dir>\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_development_mono\Data
  • When navigating to <unity-install-dir>\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_development_mono\Data ensure that your <unity-install-dir> contains the correct version number (e.g. C:\Program Files\Unity\Hub\Editor\2019.4.20f1\).
• Copy both Managed and Resources directories, placing them into <valheim-install-dir>\valheim_Data and overwriting 32 files.
• Copy WindowsPlayer.exe and paste it into <valheim-install-dir>, renaming it as valheim.exe and overwriting the original.
• Copy UnityPlayer.dll and paste it into <valheim-install-dir>, overwriting the original.
• Copy WinPixEventRuntime.dll and paste it into <valheim-install-dir>
• Open <valheim-install-dir>\valheim_Data\boot.config and append the line: player-connection-debug=1 and save.
• Launch the game

If you have followed all steps correctly, you should be able to observe a text at the bottom right hand corner of the screen that reads Development Build:

Option B: Debugging the release build

Thanks to mono and unity-mono being open source, you can patch and compile our own mono runtime and enable actual live debugging of the game and the mod itself with dnSpy, Visual Studio or Rider. All you have to do is to download and copy the patched mono-2.0-bdwgc.dll to <valheim-install-dir>\MonoBleedingEdge\EmbedRuntime overwriting the existing file.

Compiling symbols

The second step is to compile Symbols for your plugins. This allows IDEs to recognize your code when the Development Build executes it.

• Download pdb2mdb and place it in the root of your solution.
  • If you are using this Rider template, then the PostBuild should already be setup, and you can skip the following step.
  • If not, the code bellow is meant to automate the debug and release process. If you structure your binary/build directories such that the various metadata required for upload are present and in the correct location for archiving, the build events bellow should be able to be tailored to your needs.
• Add a property group which contains the following PostBuild:

  <PropertyGroup>
    <PostBuildEvent>
      if $(ConfigurationName) == Release (
      powershell Compress-Archive -Path '$(ProjectDir)Package\*' -DestinationPath '$(SolutionDir)PublishOutput\$(ProjectName).zip' -Force)
      if $(ConfigurationName) == Debug del "$(TargetPath).mdb"
      if $(ConfigurationName) == Debug $(SolutionDir)pdb2mdb.exe "$(TargetPath)"
      xcopy "$(TargetDir)" "$(GameDir)\Bepinex\plugins\$(ProjectName)\" /q /s /y /i
      xcopy "$(ProjectDir)README.md" "$(ProjectDir)Package\" /q /y /i
    </PostBuildEvent>
  </PropertyGroup>

• Go to your project debug configuration (click advanced for VS users) and ensure that Debug symbols are enabled and set to produce .pdb.
• Build the project, and observe the .mdb file sitting alongside your plugin in the plugins directory.
  • If you didn't automate this step, drop YourPlugin.dll on top of pdb2mdb.exe while YourPlugin.pbd is in the same folder as YourPlugin.dll. This will create a file called YourPlugin.mdb.

Extra Step Required for Debugging with Rider

Rider isn't able to resolve types declared in UnityEngine.CoreModule.dll (which includes MonoBehaviour, so this is a big problem) without some help.
This is due to the way that BepInEx is modifying this dll and then loading the modified version instead.
The fix is to have BepInEx dump the modified version to disk as another dll, so that Rider can find it when debugging:

1. In BepInEx\config\BepInEx.cfg you need to set DumpAssemblies = true and LoadDumpedAssemblies = true.
2. Run the game like normal, then quit again once you reach the main menu.
3. Only do this if it doesn't already work after step 2: replace your reference to UnityEngine.CoreModule.dll with the one now found in BepInEx\DumpedAssemblies.

MonoBehaviour derived types should now resolve correctly in the debugger.

Testing with Option A

• Create a breakpoint during some event after the main menu has loaded.
• Launch the game
• Attach the process after Main Menu finish loading, since doing it before may de-attach the process.
  • (VS2019) Click Debug > Attach Unity Debugger and select the only process available.
  • (Rider) Click the Unity symbol at the top: , and attach to Valheim:
• When your breakpoint is hit, the game will freeze and you will be able to proceed with debugging your plugin.

Testing with Option B

If you opted for release build debugging, you will not see any process listed there. The patched mono dll does not open it's port publicly as Developer Builds do. You have to:

• Create a breakpoint during some event after the main menu has loaded.
• Launch the game
• Click on Input IP (it should fill in your local IP automatically)
• Change the port to 55555 and accept.
• Select the process that just appeared and accept. It should be named something like "Custom Player".
• When your breakpoint is hit, the game will freeze and you will be able to proceed with debugging your plugin.

Known Issues

• VS2019 "Attach Unity Debugger" button not appearing

Some users have experienced extreme difficulty attempting to get visual studio to debug BepInEx plugins, and in some cases VS2019 simply refuses to attach to a unity process. Supposedly you just have to download "Visual Studio Tools for Unity", as shown here:

But "Attach Unity Debugger" button won't appear in Debug menu:

The current solution is to switch to a different IDE, called Rider, which include it's own tools for debugging with Unity. An user has also found that performing a complete reinstall of VS2019 could also solve the problem. If someone finds another way to resolve this issue, please update the wiki with your findings.

• Failed to load Mono

  • Solution 1. If you were trying to convert Valheim into a Development Build try to copy <unity-install-dir>\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_development_mono\MonoBleedingEdge and paste it into <valheim-install-dir>, overwriting everything.

  • Solution 2. Uninstall Unity Hub and/or Unity 2019.4.20. Install a fresh copy of Valheim or revert back to your backup. Reinstall Unity Hub. Follow the steps of Option A. Remember to install Unity 2019.4.20 through Unity Hub.

• Breakpoints are not being hit

This may be caused by attaching the process too early. Try to attach it after Main Menu finish loading.