Semi-automatically generated modding documentation for Barotrauma

IHarmonyProvider

public interface IHarmonyProvider : IPluginService

Provides a HarmonyX instance that plugins can use to patch game methods at runtime, i.e. run their own code before (prefix), after (postfix) or instead of existing methods.

Remarks

Each plugin gets its own Harmony instance. When the plugin is unloaded, every patch made through that instance is removed automatically (UnpatchSelf), so you do not need to unpatch manually.

Prefer the plugin services (hooks, registrars) when they cover what you need, and use Harmony when they don’t. Patches are applied to compiled code, so they may break when the patched method changes in a game update, and methods that get inlined by the JIT cannot be reliably patched.

The methods are instance methods. The examples assume an instance has been retrieved and stored, e.g.:

public static readonly IHarmonyProvider HarmonyProvider = PluginServiceProvider.GetService<IHarmonyProvider>();

Further reading:

  • Harmony documentation: patching concepts, prefixes, postfixes, transpilers and injected parameters.
  • HarmonyX wiki: differences and additions in HarmonyX compared to Harmony.

Example

Patch with attributes and apply all patches in the plugin assembly with PatchAll:

[HarmonyPatch(typeof(Character), nameof(Character.Kill))]
public static class CharacterKillPatch
{
    // Runs after Character.Kill. "__instance" is the character being killed.
    public static void Postfix(Character __instance, CauseOfDeathType causeOfDeath)
    {
        DebugConsole.NewMessage($"{__instance.Name} died ({causeOfDeath})");
    }
}

Plugin init:

HarmonyProvider.PatchAll();

Members

Member Description
GetHarmony() Gets the plugin’s Harmony instance, creating it on the first call. Subsequent calls return the same instance.
PatchAll() Searches the plugin assembly for classes annotated with HarmonyPatch attributes and applies them using the plugin’s Harmony instance (see GetHarmony).

Methods

GetHarmony

Harmony GetHarmony()

Gets the plugin’s Harmony instance, creating it on the first call. Subsequent calls return the same instance.

Remarks

The instance is created with a unique id (the plugin assembly’s full name), and all patches made through it are removed automatically when the plugin is unloaded.

Example

Patch a method manually, without attributes:

Harmony harmony = HarmonyProvider.GetHarmony();
harmony.Patch(
    original: AccessTools.Method(typeof(Character), nameof(Character.Kill)),
    postfix: new HarmonyMethod(typeof(MyPatches), nameof(MyPatches.KillPostfix)));
public static class MyPatches
{
    public static void KillPostfix(Character __instance)
    {
        /* Do something */
    }
}

PatchAll

void PatchAll()

Searches the plugin assembly for classes annotated with HarmonyPatch attributes and applies them using the plugin’s Harmony instance (see GetHarmony).

Remarks

Equivalent to GetHarmony().PatchAll(pluginAssembly)