-
Notifications
You must be signed in to change notification settings - Fork 7
Debugging Plugins via IDE
This article is based upon turning a release build into debug build, and Debugging Unity Games.
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:
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 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.
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.
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.