Changes

←[[Modding:Index|Index]]

←[[Modding:Index|Index]]

{{SMAPI upcoming|3.12}}

'''The following describes a future version of SMAPI, and may change before release.'''

{{Modder compatibility header}}

{{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.

 

SMAPI 3.12 updates from Harmony 1.2.0.1 to Harmony 2.1. That only affects mods which use Harmony directly; that's [[Modding:Modder Guide/APIs/Harmony|discouraged in most cases]], isn't officially part of SMAPI's public API, and isn't subject to SMAPI's normal versioning policy. If you use Harmony in your mods, this page explains how the update affects them.

__TOC__

__TOC__

[https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0] and [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 2.1] have many changes that benefit SMAPI and mods. Some notable changes:

[https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0] and [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 2.1] have many changes that benefit SMAPI and mods. Some notable changes:

* Added [https://harmony.pardeike.net/articles/patching-finalizer.html finalizers] and [https://harmony.pardeike.net/articles/reverse-patching.html reverse patches].

* Added [https://harmony.pardeike.net/articles/patching-finalizer.html finalizers] and [https://harmony.pardeike.net/articles/reverse-patching.html reverse patches].

* Added <tt>CodeInstruction</tt> extensions, <tt>Manipulator</tt> utility, and other improvements for transpilers.

* Added [https://harmony.pardeike.net/api/HarmonyLib.Transpilers.html <tt>Manipulator</tt>] utility, <tt>CodeInstruction</tt> extensions, and other improvements for transpilers.

* Added more <tt>AccessTools.Is*</tt> methods.

* Added more <tt>AccessTools.Is*</tt> methods.

* Added support for .NET 5.

* Added support for .NET 5.

* Various other improvements and fixes; see the [https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0 release notes], [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 Harmony 2.1 release notes], and [https://harmony.pardeike.net new Harmony documentation] for more info.

* Various other improvements and fixes; see the [https://github.com/pardeike/Harmony/releases/tag/v2.0.0 Harmony 2.0 release notes], [https://github.com/pardeike/Harmony/releases/tag/v2.1.0.0 Harmony 2.1 release notes], and [https://harmony.pardeike.net new Harmony documentation] for more info.

After waiting at least half a year to make sure the release is stable, SMAPI will transition to Harmony 2.''x''.

After waiting over a year to make sure the release is stable, SMAPI is transitioning to Harmony 2.1.

===Is this the modapocalypse?===

===Is this the modapocalypse?===

* most mods will be rewritten automatically for compatibility, so many mods will work without an update;

* most mods will be rewritten automatically for compatibility, so many mods will work without an update;

* pull requests will be submitted to update affected open-source mods;

* pull requests will be submitted to update affected open-source mods;

* unofficial updates will be created for mods which haven't updated officially by the time SMAPI migrates;

* unofficial updates will be created if needed for mods which haven't updated officially;

* the changes will be actively communicated and documented to modders.

* the changes will be actively communicated and documented to modders.

===Stricter validation===

===Stricter validation===

Harmony 2.0 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. See the exception messages for help fixing these.

Harmony 2.x has stricter validation in general, so invalid patches that would previously somewhat work (e.g. setting <tt>__result</tt> to the wrong type) will now cause errors. See the exception messages for help fixing these.

===Patching static constructors===

===Patching static constructors===

===Patching virtual methods===

===Patching virtual methods===

You can no longer patch a non-implemented virtual method; doing so results in the error "''You can only patch implemented methods/constructors''".

When patching a virtual method, you must now patch the specific type which implements it. Patching the wrong type now results in the error "''You can only patch implemented methods/constructors''".

For example, consider this code:

For example, consider this code:

===<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.x now throws an exception in that case, so you should check if you're not sure it exists:

<syntaxhighlight lang="c#">

<syntaxhighlight lang="c#">

MethodInfo prefix = AccessTools.Method(this.GetType(), "Prefix");

MethodInfo prefix = AccessTools.Method(this.GetType(), "Prefix");