Line 10: |
Line 10: |
| [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 [https://harmony.pardeike.net/api/HarmonyLib.Transpilers.html <tt>Manipulator</tt>] utility, <tt>CodeInstruction</tt> extensions, and other improvements for transpilers. | + | * Added [https://harmony.pardeike.net/articles/patching-postfix.html pass-through postfixes]. |
− | * Added more <tt>AccessTools.Is*</tt> methods. | + | * Added [https://harmony.pardeike.net/api/HarmonyLib.Transpilers.html <samp>Manipulator</samp>] utility, <samp>CodeInstruction</samp> extensions, and other improvements for transpilers. |
| + | * Added more <samp>AccessTools.Is*</samp> methods. |
| * Added support for .NET 5. | | * Added support for .NET 5. |
− | * Transpilers can now default to the original input by returning <tt>null</tt>. | + | * Transpilers can now default to the original input by returning <samp>null</samp>. |
| * Improved compatibility with Android modding. | | * Improved compatibility with Android modding. |
| * Improved exception messages. | | * Improved exception messages. |
Line 26: |
Line 27: |
| Nope. Although this is a major change, significant efforts were undertaken to minimise the impact: | | Nope. Although this is a major change, significant efforts were undertaken to minimise the impact: |
| * mods which don't use Harmony directly aren't affected; | | * mods which don't use Harmony directly aren't affected; |
− | * most mods will be rewritten automatically for compatibility, so many mods will work without an update; | + | * most mods are rewritten automatically for compatibility, so they'll work without an update; |
− | * pull requests will be submitted to update affected open-source mods; | + | * pull requests were submitted to update affected open-source mods; |
− | * unofficial updates will be created if needed for mods which haven't updated officially; | + | * unofficial updates were created as needed for mods which hadn't updated officially; |
− | * the changes will be actively communicated and documented to modders. | + | * the changes were actively communicated and documented to modders. |
| | | |
− | In addition, the current target is ''at least'' 90% compatibility for open-source mods before SMAPI migrates. All of this means that the release should have minimal impact on mod compatibility, despite the scope of the changes. | + | In addition, the target was ''at least'' 90% compatibility for open-source mods before SMAPI migrates. All of this means that the release should have minimal impact on mod compatibility, despite the scope of the changes. |
| | | |
| ===How to update your mod=== | | ===How to update your mod=== |
Line 45: |
Line 46: |
| | | |
| ===Stricter validation=== | | ===Stricter validation=== |
− | 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. | + | Harmony 2.x has stricter validation in general, so invalid patches that would previously somewhat work (''e.g.,'' setting <samp>__result</samp> to the wrong type) will now cause errors. See the exception messages for help fixing these. |
| | | |
| ===Patching static constructors=== | | ===Patching static constructors=== |
− | 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 <samp>AccessTools</samp> methods for constructors (<samp>Constructor</samp>, <samp>DeclaredConstructor</samp>, and <samp>GetDeclaredConstructors</samp>) no longer match static constructors by default. Use the new <samp>searchForStatic</samp> argument if you need to match them: |
| | | |
| <syntaxhighlight lang="c#"> | | <syntaxhighlight lang="c#"> |
Line 75: |
Line 76: |
| </syntaxhighlight> | | </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). | + | <samp>Farm.cleanupBeforePlayerExit</samp> doesn't exist, so it's inherited from <samp>GameLocation</samp>. Harmony 1.x would let you patch <samp>Farm.cleanupBeforePlayerExit</samp>, but in Harmony 2.x you must target the actual method (<samp>GameLocation.cleanupBeforePlayerExit</samp> in this example). |
| | | |
− | ===<tt>HarmonyMethod</tt> no longer allows null=== | + | ===<samp>HarmonyMethod</samp> 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.x now throws an exception in that case, so you should check if you're not sure it exists: | | 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#"> |