-
Notifications
You must be signed in to change notification settings - Fork 7
Debugging Plugins via IDE
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.
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
andResources
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 asvalheim.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:
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.
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 ofpdb2mdb.exe
whileYourPlugin.pbd
is in the same folder asYourPlugin.dll
. This will create a file calledYourPlugin.mdb
.
- If you didn't automate this step, drop
- 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.
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.
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.
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.
This may be caused by attaching the process too early. Try to attach it after Main Menu finish loading.