Press / to search

Advanced Modding using Harmony

Great care has been taken to design, refactor, and implement an API that gives you the flexibility to implement any number of mods that affect game code.

However there’s always limits to what you can do with what Jump King exposes, and in these cases Harmony is an option you can leverage to push the limits of your creativity!

Harmony

Harmony is an Open Source library for patching, replacing, and decorating .NET functions during the runtime.

You can use Harmony to have custom code run before, after, or instead of any methods in Jump King, and is how a lot of the early mods for the game were written.

Learn more about Harmony here: https://github.com/pardeike/Harmony

Learn more about how to use Harmony here: https://harmony.pardeike.net/articles/intro.html

Patching Etiquette

You should always assume that a player may have more than just your mod installed, so try to prevent implementing any patching logic that could stop other modder’s code from running.

For example, you could add a patch method to run before the JumpState.DoJump function. At the end of your function you can return true to allow the original DoJump (or any other patches) to continue, or false to prevent it.

Now your mod may have an appropriate reason to stop the player from jumping (maybe they are meant to be in some form of cutscene or stuck state for your mod) but keep in mind this could prevent other mods from having their code executed.

Adding Harmony to a mod

To add Harmony in your mod project, you can follow one of the following two ways.

Adding Harmony as a NuGet

Open your mod project in Visual Studio.
From the right-side of your Visual Studio interface, you should see the Solution Explorer with a tree view.
Right-click on the project you want to add Harmony to and click on ‘Manage NuGet Packages…’.
If you don’t see this option, make sure you are not currently debugging your mod.
If nothing happens, it might be because the solution file is missing, which can be easily generated by:
- clicking the multiple floppy disks displayed as Save All or,
- clicking Ctrl Shift S on your keyboard or,
- by clicking File then Save All.
After doing so, a prompt will ask you to save the SLN file, clicking Save will solve this issue.
Once clicked, a new page will display. You should be on the Browse tab. If not, change it to Browse.
Click on the search bar (or hold Ctrl+L to focus on it) and type Harmony.
From the results, click on Lib.Harmony by Andreas Pardeike.
Click Install, then Apply (to apply changes). From the Output you can see its install progress.

Once finished, you can easily access Harmony from your file using the HarmonyLib namespace like so:

 [BeforeLevelLoad]
 public static void BeforeLevelLoad()
 {
     // initializes harmony
     Harmony harmony = new Harmony("phoenixx19.Localmod.Harmony");

 // configuration dependent snippet
 // if it's DEBUG, then the containing code it will be found in the Debug build
 #if DEBUG

     // this will enable you to use breakpoints & debug inside Visual Studio
     Debugger.Launch();

     // this enables harmony to log everything related to patching
     Harmony.DEBUG = true;
 #endif

     // your awesome code here...
 }

Examples of mods that use Harmony

(Most of) JumpKingPlus mods by the JumpKingPlus team
Switch block mod by Zebra
Disabled Screen Events mod from .Gotch(ごっち)
Less Auto Equipping mod by Zebra