Advanced Modding Guide/Hooks

Hooks are used to override or to use them as an entry point for your code, and provide an easy way to add to or modify the game's behaviour. Hooks can be done with Harmony or with MonoMod, this guide will focus on Harmony.

Harmony is a powerful hooking API, which comes with BepInEx. To use Harmony, add a reference to 0Harmony.dll from the  folder.

For full documentation on Harmony, see:
 * The Official Documentation, however many things are not explained very well.
 * For BepInEx, a modified version of Harmony is used called HarmonyX. See the '''HarmonyX Documentation here.

Basics of Harmony
First, let's take a look at the basics of Harmony. Before we get started writing a hook, there are some important things to remember:


 * Patch methods need to be static.
 * There are four main types of patches: Prefix, Postfix, Finalizer and Transpiler.

Before you actually write the hook, you'll need to set up the Harmony environment in your project. At the top of your class, add the following using directive:

In the  of your mod, you need to create an instance of the  class, and then call.

This will find all the classes you have defined in your project (ie. your DLL, any namespace) and apply them.

Basic Example
For an example, we will patch the. method with a Prefix, meaning that it will run before the original method, and then a Postfix that will run after it.

This method is when the game loads all Item and Effect prefabs from their resources bundles, so it's a good time to do lots of various things.

This was a very simple example, Harmony can do many more things such as modifying the input variables, passing variables between Prefix and Postfix, etc.

Ambiguous Methods
It is not uncommon to encounter multiple methods with the same name on a class, so how do we allow Harmony to distinguish between them? If we try to simply use the name of the method by itself like above, it results in an.

Well, one of the overloads for [HarmonyPatch(...)] is to include a Type[] array that corresponds to the types of arguments on the method. For the example below we will borrow the same example from the Reflection guide.

Let's look at the method .. There are actually two methods with this name: one which expects a string _eventUID, int _stackAmount and a bool _sendEvent, and another method which expects a _event and an int _stackAmount. So what would the argument type array look like for these?

By including the Type[] array, Harmony can correctly identify the proper method that we want and avoid any exceptions.

Method Arguments
A lot of the power of Harmony comes from the arguments you can include in your Patch methods. By including ref before the argument, this will allow you to modify the value by reference instead of just getting the value.

Original Arguments
Firstly, you can include any original argument of the method by simply using the same argument Type and Name. For an example of this we will use the QuestEventManager.AddEvent method from above.

Two Underscores
There are some special keyword arguments which require two underscores  before them, and they are __instance, __result and __state.

The __instance argument will give you the object instance that is calling this method. This is only valid for non-static methods, because static methods are not called by instances, and therefore this keyword would be invalid for them. In other words, "__instance" is the equivalent of the C# keyword "this".

The __result keyword is the return value of the method, which would only be valid if the method does not return void. By including ref before __result, you can modify the return value. You can do this on Prefix, however if your Prefix allows the original to be executed then the result could be overridden by the original method, so normally Postfix or Finalizer is the best time to modify the result.

For example, let's imagine a method that returns a string:

The __state keyword is for passing data between the Prefix and Postfix. The __state can be ANY object, for example you can make it an object[] __state to pass limitless information between prefix and postfix, or it can just be one value, whatever you need.

Here's a quick example:

Three Underscores
Finally, there is one more aspect to the arguments of a Harmony patch, and that is when you include three underscores before an argument. In this case, Harmony will use Reflection on that field name for the declaring class Type.

An important caveat with this is that the field must actually be on the class of your Method, and not inherited from a base class. For inherited members you will need to use your own manual reflection.

For an example, let's look at the class, and the method.

Prefix Return False
In the case that you want to completely override the original method and never have it run at all, you can use a Prefix which returns false.

Ideally, you would want to avoid using this wherever possible, but sometimes it is necessary to achieve your desired effect. Note that two patches can't both do a prefix return false on the same method.

Finalizer
A finalizer patch will wrap the entire method inside a try/catch block, and allow you to override or catch any exceptions as well.

This is mainly used for two reasons:
 * To fix a bug with the game
 * To ensure that your code always runs, no matter what other Patches do to this method.

A finalizer patch can make use of an additional two-underscore keyword, __exception, which will be the Exception returned by the method (if any).