Modding:Modder Guide/APIs/Harmony - Revision history

imported>Sunbeam135 at 19:42, 9 January 2026

2026-01-09T19:42:44Z

← Older revision		Revision as of 19:42, 9 January 2026
Line 95:		Line 95:
	The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.		The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.

			[[ru:Модификации:Руководство мододела/API/Harmony]]
	[[zh:模组:制作指南/APIs/Harmony]]		[[zh:模组:制作指南/APIs/Harmony]]

imported>VulpesLucida: zh link

2025-01-05T14:35:00Z

zh link

← Older revision		Revision as of 14:35, 5 January 2025
Line 94:		Line 94:

	The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.		The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.

			[[zh:模组:制作指南/APIs/Harmony]]

imported>Pathoschild: /* Best practices */ tweak wording (players often ask for help on other mods' pages too)

2024-12-19T00:38:07Z

Best practices: tweak wording (players often ask for help on other mods' pages too)

← Older revision		Revision as of 00:38, 19 December 2024
Line 42:		Line 42:
	<ol>		<ol>
	<li>See [[#When to use Harmony\|when to use Harmony]].</li>		<li>See [[#When to use Harmony\|when to use Harmony]].</li>
	<li>Unhandled errors in a patch can be hard to troubleshoot, which often leads to players asking for help on the SMAPI ~~page instead of your~~ mod. '''Please''' handle errors, log them, and default to the original code. For example:		<li>Unhandled errors in a patch can be hard to troubleshoot, which often leads to players asking for help on the page for SMAPI or someone else's mod. '''Please''' handle errors, log them, and default to the original code. For example:
	<syntaxhighlight lang="C#">		<syntaxhighlight lang="C#">
	internal class ObjectPatches		internal class ObjectPatches

imported>BarleyZP: /* How to use it */ Add link to modding wiki examples

2024-06-16T03:57:06Z

How to use it: Add link to modding wiki examples

← Older revision		Revision as of 03:57, 16 June 2024
Line 36:		Line 36:
	);		);
	</syntaxhighlight></li>		</syntaxhighlight></li>
	<li>See the [https://harmony.pardeike.net/ Harmony tutorials and documentation].</li>		<li>See the [https://harmony.pardeike.net/ Harmony tutorials and documentation]. Additionally, you can check out some Stardew-specific examples on the [https://stardewmodding.wiki.gg/wiki/Tutorial:_Harmony_Patching Modding wiki].</li>
	</ol>		</ol>

imported>Pathoschild: /* Which version of Harmony should I use? */ update Harmony version

2024-05-17T18:22:09Z

Which version of Harmony should I use?: update Harmony version

← Older revision		Revision as of 18:22, 17 May 2024
Line 78:		Line 78:
	==FAQs==		==FAQs==
	===Which version of Harmony should I use?===		===Which version of Harmony should I use?===
	The Harmony version is managed by SMAPI (currently 2.1.''x''). If you [[#How to use it\|use the <samp>EnableHarmony</samp> option]], you'll use the version bundled with SMAPI automatically.		The Harmony version is managed by SMAPI (currently 2.2.''x''). If you [[#How to use it\|use the <samp>EnableHarmony</samp> option]], you'll use the version bundled with SMAPI automatically.

	===Why should I avoid Harmony annotations and <samp>PatchAll</samp>?===		===Why should I avoid Harmony annotations and <samp>PatchAll</samp>?===

imported>Pathoschild: /* When to use Harmony */ clarify version compatibility note

2023-09-30T22:39:56Z

When to use Harmony: clarify version compatibility note

← Older revision		Revision as of 22:39, 30 September 2023
Line 10:		Line 10:
	* It's very easy to cause crashes, errors, or subtle bugs, including difficult-to-diagnose memory corruption errors.		* It's very easy to cause crashes, errors, or subtle bugs, including difficult-to-diagnose memory corruption errors.
	* SMAPI often can't detect incompatible Harmony code.		* SMAPI often can't detect incompatible Harmony code.
	* SMAPI often can't rewrite Harmony patches for compatibility, so the mod may break on other platforms (e.g. Android) or game ~~versions~~.		* SMAPI often can't rewrite Harmony patches for compatibility, so the mod may break on other platforms (e.g. Android) or in future game updates.
	* Patches may conflict with other Harmony mods, sometimes in ways that are difficult to troubleshoot.		* Patches may conflict with other Harmony mods, sometimes in ways that are difficult to troubleshoot.
	* Patches may have unpredictable effects on other mods that aren't using Harmony. That may also irritate other modders, if players often report bugs to other mods due to your patches.		* Patches may have unpredictable effects on other mods that aren't using Harmony. That may also irritate other modders, if players often report bugs to other mods due to your patches.

imported>Pathoschild: /* When to use Harmony */ expand compatibility note to explicitly mention future updates too

2023-09-01T15:37:11Z

When to use Harmony: expand compatibility note to explicitly mention future updates too

← Older revision		Revision as of 15:37, 1 September 2023
Line 10:		Line 10:
	* It's very easy to cause crashes, errors, or subtle bugs, including difficult-to-diagnose memory corruption errors.		* It's very easy to cause crashes, errors, or subtle bugs, including difficult-to-diagnose memory corruption errors.
	* SMAPI often can't detect incompatible Harmony code.		* SMAPI often can't detect incompatible Harmony code.
	* ~~Crossplatform compatibility isn~~'t ~~guaranteed~~.		* SMAPI often can't rewrite Harmony patches for compatibility, so the mod may break on other platforms (e.g. Android) or game versions.
	* Patches may conflict with other Harmony mods, sometimes in ways that are difficult to troubleshoot.		* Patches may conflict with other Harmony mods, sometimes in ways that are difficult to troubleshoot.
	* Patches may have unpredictable effects on other mods that aren't using Harmony. That may also irritate other modders, if players often report bugs to other mods due to your patches.		* Patches may have unpredictable effects on other mods that aren't using Harmony. That may also irritate other modders, if players often report bugs to other mods due to your patches.

imported>Atravita: /* Best practices */

2022-11-28T02:35:30Z

Best practices

← Older revision		Revision as of 02:35, 28 November 2022
Line 44:		Line 44:
	<li>Unhandled errors in a patch can be hard to troubleshoot, which often leads to players asking for help on the SMAPI page instead of your mod. '''Please''' handle errors, log them, and default to the original code. For example:		<li>Unhandled errors in a patch can be hard to troubleshoot, which often leads to players asking for help on the SMAPI page instead of your mod. '''Please''' handle errors, log them, and default to the original code. For example:
	<syntaxhighlight lang="C#">		<syntaxhighlight lang="C#">
	~~public~~ class ObjectPatches		internal class ObjectPatches
	{		{
	private static IMonitor Monitor;		private static IMonitor Monitor;

	// call this method from your Entry class		// call this method from your Entry class
	~~public~~ static void Initialize(IMonitor monitor)		internal static void Initialize(IMonitor monitor)
	{		{
	Monitor = monitor;		Monitor = monitor;
	}		}

	~~public~~ static bool CanBePlacedHere_Prefix(StardewValley.Object __instance, GameLocation location, Vector2 tile, ref bool __result)		// patches need to be static!
			internal static bool CanBePlacedHere_Prefix(StardewValley.Object __instance, GameLocation location, Vector2 tile, ref bool __result)
	{		{
	try		try

imported>Atravita: /* What is inlining and why does it matter? */

2022-11-11T14:45:58Z

What is inlining and why does it matter?

← Older revision		Revision as of 14:45, 11 November 2022
Line 90:		Line 90:
	===What is inlining and why does it matter?===		===What is inlining and why does it matter?===

	[https://en.wikipedia.org/wiki/Inline_expansion Inlining] is when the JIT takes a method call and sticks the body of the ~~function~~ called instead of emitting an actual call. If this happens, a harmony patch applied to the callee will not take effect.		[https://en.wikipedia.org/wiki/Inline_expansion Inlining] is when the JIT takes a method call and sticks the body of the method called instead of emitting an actual call. If this happens, a harmony patch applied to the callee will not take effect.

	The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.		The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.

imported>Atravita: /* FAQs */

2022-11-11T14:15:15Z

FAQs

← Older revision		Revision as of 14:15, 11 November 2022
Line 87:		Line 87:

	However annotations work differently in the compiled code, so SMAPI can't rewrite them. That means mods which use annotations are more fragile; they may break without warning in future game/SMAPI/Harmony updates, and may not work on some platforms.		However annotations work differently in the compiled code, so SMAPI can't rewrite them. That means mods which use annotations are more fragile; they may break without warning in future game/SMAPI/Harmony updates, and may not work on some platforms.

			===What is inlining and why does it matter?===

			[https://en.wikipedia.org/wiki/Inline_expansion Inlining] is when the JIT takes a method call and sticks the body of the function called instead of emitting an actual call. If this happens, a harmony patch applied to the callee will not take effect.

			The heuristics the JIT uses to decide whether or not to inline a method are not documented and are subject to change, but [https://stackoverflow.com/a/31467000/19366602 small, simple methods that do not throw exceptions] are the most likely to be inlined. Additionally, the heuristic seems to change between platform and platform, with mac being more aggressive than Windows.