Debugging HK Mods

doorstop_config.ini

# General options for Unity Doorstop
[General]

# Enable Doorstop?
enabled=true

# Path to the assembly to load and execute
# NOTE: The entrypoint must be of format `static void Doorstop.Entrypoint.Start()`
target_assembly=hollow_knight_Data/Managed/Assembly-CSharp.dll

# If true, Unity's output log is redirected to <current folder>\output_log.txt
redirect_output_log=false

# If enabled, DOORSTOP_DISABLE env var value is ignored
# USE THIS ONLY WHEN ASKED TO OR YOU KNOW WHAT THIS MEANS
ignore_disable_switch=false


# Options specific to running under Unity Mono runtime
[UnityMono]

# Overrides default Mono DLL search path
# Sometimes it is needed to instruct Mono to seek its assemblies from a different path
# (e.g. mscorlib is stripped in original game)
# This option causes Mono to seek mscorlib and core libraries from a different folder before Managed
# Original Managed folder is added as a secondary folder in the search path
dll_search_path_override=

# If true, Mono debugger server will be enabled
debug_enabled=true

# When debug_enabled is true, specifies the address to use for the debugger server
debug_address=127.0.0.1:55555

# If true and debug_enabled is true, Mono debugger server will suspend the game execution until a debugger is attached
debug_suspend=false

# Options sepcific to running under Il2Cpp runtime
[Il2Cpp]

# Path to coreclr.dll that contains the CoreCLR runtime
coreclr_path=

# Path to the directory containing the managed core libraries for CoreCLR (mscorlib, System, etc.)
corlib_dir=

instructions.md

Really easy way to attach a debugger to your mod. Easily togglable, no modifications to Unity Mono or HK needed (techniques stolen borrowed/adapted from BepInEx and RoR2 documentation)

1. Install Unity Doorstop. Find the release for your OS and extract it next to your game files in the Hollow Knight folder (the files should be adjacent to your executable).
2. Set up your Doorstop configuration. I've included mine here; on Windows you can just paste that in the same directory. On linux/macos you'll either need to modify the parameters in run.sh (recommended) or provide these options as command line arguments to run.sh. You can use the included ini file as reference, the options are roughly 1:1.
   • Note that you can point the target_assembly to any DLL, including a custom doorstop entry point if you choose. However, Doorstop runs very early in the runtime, before most Unity types are loaded, and will choke if you accidentally or intentionally reference one - there's not a ton useful you can do with it.
3. Run the game. On Windows, start the game normally. Doorstop will inject itself automatically; you can disable it by changing enabled=false in the config file. On linux/mac, use run.sh as specified by the documentation in that file.
4. Attach a Unity debugger of your choosing and do some debugging.
   • Visual Studio: install the unity workload following these instructions. The debugger can be attached from Debug -> Attach Unity Debugger -> Input IP and input the connection details as defined by your Doorstop config. Optionally, install the RoR2 UnityModExtension which can be configured in Tools -> Options -> Unity Mod and provides a convenience function to start the game and attach the debugger.
   • dnSpy: Go to Debug -> Start Debugging. For "Debug Engine," select "Unity (connect)." Input the connection details as defined by your Doorstop config.