translators
8,404
edits
Changes
Jump to navigation
Jump to search
Line 72:
Line 72: + + + + + + + + + + + + + +
Modding:Modder Guide/APIs/Harmony (view source)
Revision as of 16:00, 30 March 2022
, 16:00, 30 March 2022+ prefer code API, FAQs
<li>Use postfixes when possible for best compatibility and stability.</li>
<li>Use postfixes when possible for best compatibility and stability.</li>
<li>Don't use transpile patches unless you have no choice and you know what you're doing. This has a much higher chance of causing issues, is more fragile and likely to break in game updates, and makes it much less likely that other modders can help if you need it.</li>
<li>Don't use transpile patches unless you have no choice and you know what you're doing. This has a much higher chance of causing issues, is more fragile and likely to break in game updates, and makes it much less likely that other modders can help if you need it.</li>
<li>[[#How to use it|Use the code API]] instead of annotations like <samp>[HarmonyPatch]</samp> (see ''[[#Why should I avoid Harmony annotations and PatchAll?|Why should I avoid Harmony annotations and <samp>PatchAll</samp>?]]'').</li>
</ol>
</ol>
==FAQs==
===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.
===Why should I avoid Harmony annotations and <samp>PatchAll</samp>?===
There are two ways to add patches:
* [[#How to use it|Use the code API]] (recommended).
* Use annotations like <samp>[HarmonyPatch]</samp> on static classes, then call Harmony's <samp>PatchAll</samp> to dynamically scan the assembly for those annotations. This is fragile and discouraged.
For context, SMAPI automatically rewrites mods when needed for compatibility. That's used to keep mods working when there are breaking changes in the game/SMAPI/Harmony, or to handle crossplatform differences (e.g. using PC mods on Android). For example, the Stardew Valley 1.5.5 update broke most C# mods, but nearly all of them were fixed automatically by SMAPI's rewriting.
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.