Modding:Migrate to Harmony 2.0 - Revision history

imported>Margotbean: zh link

2026-04-14T08:01:44Z

zh link

← Older revision		Revision as of 08:01, 14 April 2026
Line 90:		Line 90:

	[[Category:Modding]]		[[Category:Modding]]

			[[zh:模组:迁移至Harmony 2.0]]

imported>Pathoschild: /* Is this the modapocalypse? */ past tense now

2023-08-01T19:18:25Z

Is this the modapocalypse?: past tense now

← Older revision		Revision as of 19:18, 1 August 2023
Line 27:		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===

imported>Margotbean: Text replacement - "''e.g.''," to "''e.g.,''"

2021-11-08T00:40:43Z

Text replacement - "''e.g.''," to "''e.g.,''"

← Older revision		Revision as of 00:40, 8 November 2021
Line 46:		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 <samp>__result</samp> 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===

imported>Margotbean: Text replacement - "(e.g. " to "(''e.g.'', "

2021-11-07T23:41:27Z

Text replacement - "(e.g. " to "(''e.g.'', "

← Older revision		Revision as of 23:41, 7 November 2021
Line 46:		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 <samp>__result</samp> 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===

imported>Margotbean: Text replacement - "tt>" to "samp>"

2021-11-04T18:48:50Z

Text replacement - "tt>" to "samp>"

← Older revision		Revision as of 18:48, 4 November 2021
Line 11:		Line 11:
	* 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/articles/patching-postfix.html pass-through postfixes].		* Added [https://harmony.pardeike.net/articles/patching-postfix.html pass-through postfixes].
	* 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/api/HarmonyLib.Transpilers.html <samp>Manipulator</samp>] utility, <samp>CodeInstruction</samp> extensions, and other improvements for transpilers.
	* Added more <tt>AccessTools.Is*</tt> methods.		* 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 46:		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 76:		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#">

imported>Pathoschild: /* What's changing? */ + pass-through postfixes

2021-09-07T19:31:49Z

What's changing?: + pass-through postfixes

← Older revision		Revision as of 19:31, 7 September 2021
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/articles/patching-postfix.html pass-through postfixes].
	* 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/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.

imported>Pathoschild: /* What's changing? */ fix inconsistent grammar

2021-08-02T06:28:18Z

What's changing?: fix inconsistent grammar

← Older revision		Revision as of 06:28, 2 August 2021
Line 14:		Line 14:
	* 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 <tt>null</tt>.
	* ~~Better~~ compatibility with Android modding.		* Improved compatibility with Android modding.
	* ~~Better~~ exception messages.		* Improved exception messages.
	* ~~Better~~ validation for invalid patches.		* Improved validation for invalid patches.
	* Fixed cases where methods were inlined and unpatchable on Linux/Mac.		* Fixed cases where methods were inlined and unpatchable on Linux/Mac.
	* Fixed methods with struct return types being unpatchable.		* Fixed methods with struct return types being unpatchable.

imported>Pathoschild: /* Breaking changes */ + transpiler changes

2021-08-02T01:33:44Z

Breaking changes: + transpiler changes

← Older revision		Revision as of 01:33, 2 August 2021
Line 84:		Line 84:
	harmony.Patch(original, new HarmonyMethod(prefix));		harmony.Patch(original, new HarmonyMethod(prefix));
	</syntaxhighlight>		</syntaxhighlight>

			===Transpiler changes===
			Harmony 2.x uses a new engine ({{github\|MonoMod/MonoMod\|MonoMod}}) under the hood, so there may be unexpected changes in the way transpiler patches work. For example, short-form branches may become long-form. If your mod uses transpilers, you should test each one to make sure it's working as you expect.

	[[Category:Modding]]		[[Category:Modding]]

imported>Pathoschild: update for SMAPI 3.12 release

2021-08-01T21:26:29Z

update for SMAPI 3.12 release

← Older revision		Revision as of 21:26, 1 August 2021
Line 1:		Line 1:
	←[[Modding:Index\|Index]]		←[[Modding:Index\|Index]]

	~~{{SMAPI upcoming\|3.12}}~~
	{{Modder compatibility header}}		{{Modder compatibility header}}

imported>Pathoschild: update and clarify a bit

2021-07-13T12:48:27Z

update and clarify a bit

← Older revision		Revision as of 12:48, 13 July 2021
Line 1:		Line 1:
	←[[Modding:Index\|Index]]		←[[Modding:Index\|Index]]

	~~<div style="border: 1px solid gray; border-left: 1em solid gray; padding: 0.5em 1em; border-radius: 5px;">~~		{{SMAPI upcoming\|3.12}}
	~~'''The following describes a future version of~~ SMAPI~~, and may change before release~~.~~'''~~
	~~</div>~~
	{{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__
Line 12:		Line 11:
	[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.
Line 23:		Line 22:
	* 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?===
Line 30:		Line 29:
	* 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.

Line 47:		Line 46:

	===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===
Line 65:		Line 64:

	===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:
Line 80:		Line 79:

	===<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");