Harmony

Harmony is a high-level library for altering functionality in C# applications at runtime via monkey patching. Unlike other solutions, it does not modify the contents of DLL files on disk.

Supported Environments:

• Mono and .NET on Windows, Unix, and macOS.
• Unity: Works with most profiles, including .NET 4.x. Note that it may not work if Unity uses a heavily stripped-down NetStandard profile.

A Transpiler in Harmony is a specialized patch used to rewrite the Common Intermediate Language (CIL) of an existing method. Unlike prefix or postfix patches that run before or after a method, a Transpiler allows you to manipulate the actual instruction stream (the code inside the method) by receiving the original instructions and returning a modified sequence.

Key Concepts:

• Input/Output: It takes an IEnumerable<CodeInstruction> and must return an IEnumerable<CodeInstruction>.
• Complexity: Writing transpilers requires a deep understanding of CIL (Common Intermediate Language) and how the stack-based execution model works.
• Stack Management: You must ensure that your modifications do not leave unnecessary elements on the stack or cause stack underflows, as this will lead to compilation errors.

When working with infix patching, understand the following roles:

• Outer: The method being patched.
• Inner: The target method being called inside the outer method.
• Call site: A specific occurrence of a call to the inner method within the outer method.

Unlike simple hooking libraries that only allow replacing a method, Harmony provides several advanced capabilities:

• Preserve Original Logic: Keep the original method intact while executing your own code.
• Prefix/Postfix Execution: Execute your code specifically before (Prefix) or after (Postfix) the original method.
• IL Code Processing: Modify the original method using IL code processors.
• Coexistence: Multiple Harmony patches can coexist on the same method without conflicting.

Harmony provides four primary types of patches to inject code into original methods:

• Prefix: Runs before the original method. Used to modify arguments, set the return value, skip the original method, or set state for a postfix.
• Postfix: Runs after the original method. Used to read/change the result, access arguments, or read state set by a prefix.
• Transpiler: An advanced patch that modifies the original method's IL (Intermediate Language) instructions directly during the patching process.
• Finalizer: Runs after all other patches (including postfixes). It is the only patch type immune to exceptions thrown by the original method or other patches. It is used for guaranteed cleanup or exception handling.

Additionally, Reverse Patching allows you to patch your own methods by defining a stub that mimics the original and applying the original's logic onto it.

A Transpiler is a post-compiler stage that modifies the IL (Intermediate Language) code of an original method. Unlike Prefix or Postfix patches, which execute at runtime, a Transpiler runs once during the patching process to alter the method's source code.

Key characteristics:

• It modifies IL code, not C# source code.
• It is executed only once when the method is patched (and again if subsequent transpilers are added).
• It cannot access runtime state because it runs during the patching phase.
• Multiple transpilers can be chained together to produce the final IL output.
• Use this for advanced cases where you need to modify the internal logic of a method, such as inserting static method calls, removing parts of the original code, or changing values/method calls.

A reverse patch is a stub method in your own code that copies the implementation of an original method (or part of it) into your own class. This allows you to call private methods with native performance, without reflection or delegates.

To create one, apply the [HarmonyReversePatch] attribute to your stub method. The method signature must match the original method's signature (including static/non-static status). If patching an instance method, you can include the instance as the first argument (position 0) to access the original object.

Warning: If you define an instance method as a stub, the copied IL expects this to point to the original class type. This will fail if your stub is in a different class type.

For a typical Unity target, configure your project settings as follows:

• Set your project to .Net 3.5 or Mono 2.x.
• Include the Harmony.dll in your project.

If you do not want to use annotations, you can perform manual patching. You are responsible for retrieving the MethodInfo for your patch methods and wrapping them in HarmonyMethod objects to pass them to the Patch() method.

Patch methods must be static. While they cannot be dynamic methods directly, you can use static factory methods that return MethodInfo or DynamicMethod objects.

[HarmonyPatch(...)]
class Patch
{
	// the return type of factory methods can be either MethodInfo or DynamicMethod
	[HarmonyPrefix]
	static MethodInfo PrefixFactory(MethodBase originalMethod)
	{
		// return an instance of MethodInfo or an instance of DynamicMethod
	}

	[HarmonyPostfix]
	static MethodInfo PostfixFactory(MethodBase originalMethod)
	{
		// return an instance of MethodInfo or an instance of DynamicMethod
	}
}