[TOOL] (A15) Mod Full Debugger

[olizit]

Procedure below allow mod developers to full debugging mod C# code.
I use Windows to create this tutorial and RimWorld v0.14.1249

Installation with Xamarin Studio (all platform)

1. Install the latest version of mono runtime http://www.mono-project.com/download/
Mono runtime install directory is named <Mono_install_path> in this tutorial.

2. Install the latest version of Xamarin studio http://www.monodevelop.com/download/. GTK# for .NET is also needed.

3. Add an Environment Variable named MONODEVELOP_SDB_TEST with value 1.
MONODEVELOP_SDB_TEST enable a menu entry in Xamarin studio: Run->Run With->Custom Command Mono Soft Debugger

4. Duplicate RimWorld game directory to create a clean install for mod develop. The newly copy is named <RimWorld_mod_install_path> in this tutorial.

5. Replace <RimWorld_mod_install_path>\RimWorld1249Win_Data\Mono\mono.dll by latest mono for RimWorld (see sources and releases section)
New mono.dll is a modified version of original mono to allow debugging. DO NOT USE THIS NEW DLL IN PRODUCTION.

6. Copy your mod and all dependencies mods in Mods folder.

7. Open mod solution file with Xamarin Studio or Visual Studio

8. Edit project settings :
a. MSBuild build engine must be checked.
b. Debug info must be enabled.
c. Add an After Build Custom Commands
Command: "<Mono_install_path>\bin\pdb2mdb.bat"  <point to output dll mod>
This step convert debugging symbol pdb file to a mdb file.
After a sucessfull build your mod Assemblies must contains 3 files <name mod>.dll <name mod>.dll.mdb and <name mod>.pdb.
d. Add a Run Execute Custom Commands.
Command: <RimWorld_mod_install_path>\<Rimworld executable>.exe

9. Create a batch file in <RimWorld_mod_install_path> to setup RimWorld execution
Set an Environment Variable to set debugging parameters
set RIMWORLD_MOD_DEBUG=--debugger-agent=transport=dt_socket,address=127.0.0.1:12345,server=y
Start RimWorld with an isolated mod config folder
<Rimworld executable>.exe -savedatafolder=Mod_SaveData

10. Start RimWorld with batch file. RimWorld is started "stuck". Actually mono runtime server debugger wait a client.

11. In Xamarin Studio click on Run->Run With->Custom Command Mono Soft Debugger
Parameters must be matched with batch file address and port.
IP: 127.0.0.1
Port: 12345
Click on Connect.
Now RimWorld load all things. Configure RimWorld to mod developement (enable mods, etc...)
Xamarin Studio is now hit breakpoints in your mod methods and you can watch variables.


Installation with Visual Studio 2015 (Windows only)

1. Install the latest version of mono runtime http://www.mono-project.com/download/
Mono runtime install directory is named <Mono_install_path> in this tutorial.

2. Install Visual Studio 2015 Tools for Unity extension https://visualstudiogallery.msdn.microsoft.com/8d26236e-4a64-4d64-8486-7df95156aba9?SRC=VSIDE

3. Duplicate RimWorld game directory to create a clean install for mod develop. The newly copy is named <RimWorld_mod_install_path> in this tutorial.

4. Replace <RimWorld_mod_install_path>\RimWorld1249Win_Data\Mono\mono.dll by latest mono for RimWorld (see sources and releases section)
New mono.dll is a modified version of original mono to allow debugging. DO NOT USE THIS NEW DLL IN PRODUCTION.

5. Copy your mod and all dependencies mods in Mods folder.

6. Open mod solution file with Visual Studio

7. Edit project settings :
a. Debug info must be enabled.
b. Add an Post-build event command line
Command: "<Mono_install_path>\bin\pdb2mdb.bat" $(TargetPath)
This step convert debugging symbol pdb file to a mdb file.
After a sucessfull build your mod Assemblies must contains 3 files <name mod>.dll <name mod>.dll.mdb and <name mod>.pdb.

8. Create a batch file in <RimWorld_mod_install_path> to setup RimWorld execution
Set an Environment Variable to set debugging parameters
set RIMWORLD_MOD_DEBUG=--debugger-agent=transport=dt_socket,address=127.0.0.1:12345,server=y
Start RimWorld with an isolated mod config folder
<Rimworld executable>.exe -savedatafolder=Mod_SaveData

9. Start RimWorld with batch file. RimWorld is started "stuck". Actually mono runtime server debugger wait a client.

10. In Visual Studio click on Debug->Attach Unity Debugger->Input IP
Parameters must be matched with batch file address and port.
IP: 127.0.0.1
Port: 12345
Click on OK.
Now RimWorld load all things. Configure RimWorld to mod developement (enable mods, etc...)
Visual Studio is now hit breakpoints in your mod methods and you can watch variables.

Sources and Releases
https://github.com/olizit/RimWorld_mono/releases

Known issues

• Crash at exit

Tips and Tricks

• Breakpoint must be set in whitespace before first character of instruction even if breakpoint does not work

Limitations

• Debug command "Set next statement" is disabled (it's tricky to report code from latest mono).
• Debug command "Step Into" do a "Step Over" instead

Feedbacks
It' a BETA tutorial. Post feedbacks if there are something wrong in this tutorial.

Help
I need help to port this toturial on Linux and Mac

[Master Bucketsmith]

This looks fantastic, but as a newbie I have gotten into Visual Studio 2015 CE.
I absolutely hate having multiple programs that do the same thing just for a bunch of different tools/options/settings/etc.
Is there any chance you could set up a similar tutorial for users who use Visual Studio?

[olizit]

Tutorial up to date for Visual Studio 2015

[1000101]

This should be stickied.

[skullywag]

Agreed, done.

[Wishmaster]

I successfully connected to the game in debug mode but the breakpoints aren't working. Also the threadlist is empty.

I have all the 3 files ( .dll ; .dll.mbp  ; .pdb ) of my mod all have the same names.

I am using Xamarin.
Any ideas ?

[olizit]

Sorry for my very late reply.
I've put a sample project on github https://github.com/olizit/RimWorld_RemoteDebug
Can you add this sample mod into the RimWorld, start the game with debug mode and attach to it.
When game started, add a function breakpoint inside Xamarin "When an exception is throw" to System.Exception. When game is fully loaded open in game bottom menu "Hello World". A breakpoint should be triggered.
Now you can test a standard breakpoint. Do not forget to add breakpoint in whitespace before the code.
Tell me if it's working or not !

[Wishmaster]

It's still not working :/ .
I've tried with both your samble mod and my mod, adding a try{throw...} catch thing.
I did not forgot to make the symbols and use the command file for conversion.

edit:

I've tried using my own mods and Xamarin now detects exceptions. (I don't know why it didn't work before).
But I still can't trace the exception in my code. And step over/step into/step out... will just resume the execution.

I've tried renaming .dll.mbp to .mbp aswell.

[plenumolog]

Hello, I had some problems with game crashing at start, but found a fix (see below).

I tried this great guide with Fluffy's WorkTab mod, on RimWorld v17. https://github.com/FluffierThanThou/WorkTab
If I try open it in Xamarian, it fails saying WorkTab.csproj is an unknown solution item.
So I switched to VS2017. Built it and deployed to game Mods directory it works fine.
So far so good.

Enabled Debug info generation. Deployed to Mods directory with WorkTab.pdb and WorkTab.dll.mdb.
Now game crashes on start. Game stops crashing only when I delete WorkTab.pdb (but keep WorkTab.dll.mdb).
Now I'm able to trace, use breakpoints, etc.

[plenumolog]

Hello olizit

I tried to use the "mono.dll" (which you kindly provided) for debugging. When I used it for Fluffy's WorkTab, it worked great.
But for Hardcore-SK modpack it crashes RimWorld on program start. I've disabled all mods, except for few, and saw, that it crashes at least when those are enabled (I checked only few mods):
https://github.com/erdelf/AlienRaces
https://github.com/NoImageAvailable/CombatExtended

Can you please suggest why game might crash for those mods, and is there a way to fix that somehow?
I'm not sure if RimWorld latest published v17 uses "mono.dll" v1.0.0.1 - I'm not sure it's different from Sep 2016 version (when you released "mono.dll" for debugging).
It would be a great boost if we could use tracing for Hardcore-SK...

[LasurDragon]

Is there any updated mono dll for B18?
Current version gives "Failed to load mono: function unity_mono_reflection_method_get_method not found"


[attachment deleted by admin: too old]

[FrodoOf9Fingers]

I would like an updated mono dll also.

[mospidatru]

Mono debug for RW B18 here:
https://github.com/bananasss00/RimWorld_mono/releases/tag/mono5.6.3

In step 8 NEED use Environment Variable DNSPY_UNITY_DBG instead RIMWORLD_MOD_DEBUG
recompiled, now use RIMWORLD_MOD_DEBUG 

[Barrent]

Any chance to get mono.dll for release version of the game?

[reist]

Updated mono to version 5.6.5, debug works
https://github.com/akonogov/RimWorld_mono/releases/tag/mono5.6.5