Home

Documentation

A library for patching .NET assemblies during runtime.

If you develop in C# and your code is loaded as a module/plugin into a host application, you can use Harmony to alter the functionality of all the available assemblies of that application. Where other patch libraries simply allow you to replace the original method, Harmony goes one step further and gives you:

• A way to keep the original method intact
• Execute your code before and/or after the original method
• No conflicts with other Harmony patches

Prerequisites

Harmony is designed to work with .NET 2.0 and is compatible with Mono which makes it a great way to develop extensions for Unity games. It has no other dependencies than .NET 2.0 and will most likely work in other environments too. Harmony was tested on PC, Mac and Linux and support 32- and 64-bit.

Quick example

Here is a very short example on how to patch the method WindowStack.Add(Window) in a mod for the game RimWorld so that it logs the window object to the games debug window:

using System;
using Verse;
using Harmony;

namespace CameraPlus
{
	[StaticConstructorOnStartup]
	class Main
	{
		static Main()
		{
			var harmony = HarmonyInstance.Create("com.github.harmony.rimworld.mod.example");
			harmony.PatchAll(typeof(Main).Module);
		}
	}

	[HarmonyPatch(typeof(WindowStack))]
	[HarmonyPatch("Add")]
	[HarmonyPatch(new Type[] { typeof(Window) })]
	class Patch
	{
		static bool Prefix(WindowStack instance, ref Window window)
		{
			Log.Warning("Opening window " + window);
			return true;
		}
	}
}

The important parts that are not RimWorld specific are the two lines inside the Main() method and the Patch class. The Prefix is always execute before Window.Add() everywhere that method is called and logs the window instance to the RimWorld debug window.

For more details, please refer to the following sections:

Contents

• Bootstrapping
• Patching
• Target method annotations
• Execution flow
• Priorities annotations
• Utilities