114
edits
Changes
Jump to navigation
Jump to search
mLine 4:
Line 4: − + − '''This page is for modders. Players: see [[Modding:Mod compatibility]] instead.''' − Line 53:
Line 51: − + Line 61:
Line 59: − + Line 69:
Line 67: − + Line 76:
Line 74: − + Line 82:
Line 80: − + − +
Modding:Migrate to Harmony 2.0 (view source)
Revision as of 17:45, 19 February 2021
, 17:45, 19 February 2021Replace deprecated <source> tags with <syntaxhighlight> tags; add new template Template:Modder compatibility header
'''The following describes a future version of SMAPI, and may change before release.'''
'''The following describes a future version of SMAPI, and may change before release.'''
</div>
</div>
{{Modder compatibility header}}
This page explains how to update your mod code for Harmony 2.0. This only applies to mods which use Harmony directly; [[Modding:Modder Guide/APIs/Harmony|that's discouraged]] in most cases, isn't officially part of SMAPI's public API, and isn't subject to SMAPI's normal versioning policy.
This page explains how to update your mod code for Harmony 2.0. This only applies to mods which use Harmony directly; [[Modding:Modder Guide/APIs/Harmony|that's discouraged]] in most cases, isn't officially part of SMAPI's public API, and isn't subject to SMAPI's normal versioning policy.
The <tt>AccessTools</tt> methods for constructors (<tt>Constructor</tt>, <tt>DeclaredConstructor</tt>, and <tt>GetDeclaredConstructors</tt>) no longer match static constructors by default. Use the new <tt>searchForStatic</tt> argument if you need to match them:
The <tt>AccessTools</tt> methods for constructors (<tt>Constructor</tt>, <tt>DeclaredConstructor</tt>, and <tt>GetDeclaredConstructors</tt>) no longer match static constructors by default. Use the new <tt>searchForStatic</tt> argument if you need to match them:
<source lang="c#">
<syntaxhighlight lang="c#">
// match static constructors only
// match static constructors only
var method = AccessTools.Constructor(typeof(ExampleType), searchForStatic: true);
var method = AccessTools.Constructor(typeof(ExampleType), searchForStatic: true);
AccessTools.Constructor(typeof(ExampleType), searchForStatic: true)
AccessTools.Constructor(typeof(ExampleType), searchForStatic: true)
?? AccessTools.Constructor(typeof(ExampleType));
?? AccessTools.Constructor(typeof(ExampleType));
</source>
</syntaxhighlight>
Note that Harmony no longer matches static constructors for a good reason — they're only called once for the type, so often static constructor patches won't work correctly.
Note that Harmony no longer matches static constructors for a good reason — they're only called once for the type, so often static constructor patches won't work correctly.
For example, consider this code:
For example, consider this code:
<source lang="c#">
<syntaxhighlight lang="c#">
public class GameLocation
public class GameLocation
{
{
public class Farm : GameLocation {}
public class Farm : GameLocation {}
</source>
</syntaxhighlight>
<tt>Farm.cleanupBeforePlayerExit</tt> doesn't exist, so it's inherited 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 it's inherited 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>HarmonyMethod</tt> no longer allows null===
===<tt>HarmonyMethod</tt> no longer allows null===
Harmony 1.''x'' allowed <code>new HarmonyMethod(null)</code>, so you could safely use it with methods that might not exist. Harmony 2.0 now throws an exception in that case, so you should check if the method might not exist:
Harmony 1.''x'' allowed <code>new HarmonyMethod(null)</code>, so you could safely use it with methods that might not exist. Harmony 2.0 now throws an exception in that case, so you should check if the method might not exist:
<source lang="c#">
<syntaxhighlight lang="c#">
MethodInfo prefix = AccessTools.Method(this.GetType(), "Prefix");
MethodInfo prefix = AccessTools.Method(this.GetType(), "Prefix");
if (prefix != null)
if (prefix != null)
harmony.Patch(original, new HarmonyMethod(prefix));
harmony.Patch(original, new HarmonyMethod(prefix));
</source>
</syntaxhighlight>
[[Category:Modding]]
[[Category:Modding]]