Difference between revisions of "Modding:Migrate to Harmony 2.0"
Pathoschild (talk | contribs) (+ troubleshooting > "You can only patch implemented methods/constructors") |
Pathoschild (talk | contribs) (update, expand a bit) |
||
Line 1: | Line 1: | ||
←[[Modding:Index|Index]] | ←[[Modding:Index|Index]] | ||
− | {{SMAPI upcoming|3. | + | {{SMAPI upcoming|3.6}} |
'''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.''' | '''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.''' | ||
Line 9: | Line 9: | ||
__TOC__ | __TOC__ | ||
− | ==What's new?== | + | ==For modders== |
− | See the [https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0 release notes] and [https://harmony.pardeike.net Harmony 2.0 documentation] for more info. | + | ===What's new?=== |
+ | See the [https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0 release notes] and [https://harmony.pardeike.net Harmony 2.0 documentation] for more info. Harmony 2.0 also has stricter validation in general, so invalid patches that would previously work (e.g. setting <tt>__result</tt> to the wrong type) will now cause errors. | ||
− | ==Migration steps== | + | ===Migration steps=== |
# Make sure you follow best practices outlined in the [[Modding:Modder Guide/APIs/Harmony|Harmony guide]]. In particular, use the <code>EnableHarmony</code> option (don't reference the Harmony DLL directly) and use the code API. | # Make sure you follow best practices outlined in the [[Modding:Modder Guide/APIs/Harmony|Harmony guide]]. In particular, use the <code>EnableHarmony</code> option (don't reference the Harmony DLL directly) and use the code API. | ||
# Change <code>using Harmony;</code> to <code>using HarmonyLib;</code>. | # Change <code>using Harmony;</code> to <code>using HarmonyLib;</code>. | ||
Line 20: | Line 21: | ||
That's it! Otherwise usage should be identical. | That's it! Otherwise usage should be identical. | ||
− | ==Troubleshooting== | + | ===Troubleshooting=== |
− | + | ; "You can only patch implemented methods/constructors" | |
− | Consider this example: | + | : Consider this example: |
− | <source lang="C#"> | + | : <source lang="C#"> |
public class GameLocation | public class GameLocation | ||
{ | { | ||
Line 32: | Line 33: | ||
</source> | </source> | ||
− | <tt>Farm.cleanupBeforePlayerExit</tt> doesn't exist, so <tt>Farm</tt> inherits it from <tt>GameLocation</tt>. Harmony 1.x would let you patch <tt>Farm.cleanupBeforePlayerExit</tt>, but in Harmony 2.x you must target the actual method (<tt>GameLocation.cleanupBeforePlayerExit</tt> in this example). | + | : <tt>Farm.cleanupBeforePlayerExit</tt> doesn't exist, so <tt>Farm</tt> inherits it from <tt>GameLocation</tt>. Harmony 1.x would let you patch <tt>Farm.cleanupBeforePlayerExit</tt>, but in Harmony 2.x you must target the actual method (<tt>GameLocation.cleanupBeforePlayerExit</tt> in this example). |
+ | |||
+ | ==Mod compatibility== | ||
+ | SMAPI automatically rewrites most Harmony 1.''x'' mods for compatibility, though some mods may break due to Harmony 2.0 changes that can't be handled automatically (e.g. stricter validation). This rewriting will be removed in SMAPI 4.0, so mod authors should update their code when possible even if it still works for now. | ||
[[Category:Modding]] | [[Category:Modding]] |
Revision as of 19:57, 6 May 2020
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.
For modders
What's new?
See the Harmony 2.0 release notes and Harmony 2.0 documentation for more info. Harmony 2.0 also has stricter validation in general, so invalid patches that would previously work (e.g. setting __result to the wrong type) will now cause errors.
Migration steps
- 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. - Change
using Harmony;
tousing HarmonyLib;
. - Change
HarmonyInstance harmony = HarmonyInstance.Create("your mod id");
toHarmony harmony = new Harmony("your mod id");
. - 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).
Mod compatibility
SMAPI automatically rewrites most Harmony 1.x mods for compatibility, though some mods may break due to Harmony 2.0 changes that can't be handled automatically (e.g. stricter validation). This rewriting will be removed in SMAPI 4.0, so mod authors should update their code when possible even if it still works for now.