Debugging Plugins via IDE

Introduction

This article is based upon turning a release build into debug build, and Debugging Unity Games.

1. 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
• 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:

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.

Testing

• 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 availeable.
  • (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.

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. If someone finds a way to resolve this issue, please update this wiki and inform the community of your discovery.

Failed to load Mono

Some users will experience this error when trying to convert Valheim into a Development Build. The current solution is to copy <unity-install-dir>\Editor\Data\PlaybackEngines\windowsstandalonesupport\Variations\win64_development_mono\MonoBleedingEdge and paste it into <valheim-install-dir>, overwriting everything.

Breakpoints are not being hit

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