Modding:Migrate to Harmony 2.0

←Index

The following describes the upcoming SMAPI 3.x, and may change before release.

This page is for modders. Players: see Modding:Mod compatibility instead.

This page explains how to update your mods for compatibility with Harmony 2.0. This only applies to mods which use Harmony directly; this is discouraged in most cases, isn't officially part of SMAPI's public API, and isn't subject to SMAPI's normal versioning policy.

What's new?

See the Harmony 2.0 release notes and Harmony 2.0 documentation for more info.

Migration steps

1. Make sure you follow best practices outlined in the Harmony guide. In particular, use the EnableHarmony option (don't reference the Harmony DLL directly) and use the code API.
2. Change using Harmony; to using HarmonyLib;.
3. Change HarmonyInstance harmony = HarmonyInstance.Create("your mod id"); to Harmony harmony = new Harmony("your mod id");.
4. Recompile the mod.

That's it! Otherwise usage should be identical.

Troubleshooting

"You can only patch implemented methods/constructors"

Consider this example:

public class GameLocation
{
   public virtual void cleanupBeforePlayerExit() {}
}

public class Farm : GameLocation {}

Farm.cleanupBeforePlayerExit doesn't exist, so Farm inherits it from GameLocation. Harmony 1.x would let you patch Farm.cleanupBeforePlayerExit, but in Harmony 2.x you must target the actual method (GameLocation.cleanupBeforePlayerExit in this example).