Confirmedusers
6
edits
Modding:Monkey patching: Difference between revisions
From Vintage Story Wiki
Made heading level more consistent with other pages
m (Updated game version and removed needless parameters) |
(Made heading level more consistent with other pages) |
||
| Line 1: | Line 1: | ||
{{GameVersion|1.18}} | {{GameVersion|1.18}} | ||
Monkey patching (changing code at runtime) in Vintage Story is available through [https://harmony.pardeike.net/articles/basics.html Harmony]. | Monkey patching (changing code at runtime) in Vintage Story is available through [https://harmony.pardeike.net/articles/basics.html Harmony]. | ||
With Harmony you can change methods, constructors and properties. | With Harmony you can change methods, constructors and properties. | ||
| Line 10: | Line 7: | ||
It is recommended that you use [https://github.com/dnSpyEx/dnSpy dnSpy] on any dlls or mods you wish to patch, rather than viewing the source code on GitHub. This is because there is often more in the dlls than can be found on GitHub. On Linux, this executable can be run through wine. | It is recommended that you use [https://github.com/dnSpyEx/dnSpy dnSpy] on any dlls or mods you wish to patch, rather than viewing the source code on GitHub. This is because there is often more in the dlls than can be found on GitHub. On Linux, this executable can be run through wine. | ||
== Getting Started == | |||
To use Harmony in you Vintage Story mod you first have to reference the "0Harmony.dll" file in the Vintage Story "Lib" directory (VintageStory\Lib\0Harmony.dll) in your project. | To use Harmony in you Vintage Story mod you first have to reference the "0Harmony.dll" file in the Vintage Story "Lib" directory (VintageStory\Lib\0Harmony.dll) in your project. | ||
| Line 19: | Line 16: | ||
Now you are all set to patch everything inside the game like described in the documentation. | Now you are all set to patch everything inside the game like described in the documentation. | ||
== Basic Patching == | |||
The simplest and easiest way to patch code is to run <code>harmony.PatchAll()</code> after initializing harmony with the constructor, and to put your patches into various "multi-patch classes". To mark a class as one of these multi-patch classes, put the <code>[HarmonyPatch]</code> annotation at the top. | The simplest and easiest way to patch code is to run <code>harmony.PatchAll()</code> after initializing harmony with the constructor, and to put your patches into various "multi-patch classes". To mark a class as one of these multi-patch classes, put the <code>[HarmonyPatch]</code> annotation at the top. | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
| Line 69: | Line 66: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Transpilers == | |||
Transpilers are a special kind of patch that allow you to change a small part of the code of a function, without canceling the whole thing with a prefix and rewriting it. | Transpilers are a special kind of patch that allow you to change a small part of the code of a function, without canceling the whole thing with a prefix and rewriting it. | ||
| Line 93: | Line 90: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Cleaning Up == | |||
For good practice, if you patch the game with your mod, make sure you unpatch it when your mod unloads. The easiest way to do this is to run <code>harmony.UnpatchAll("MyModId")</code> in the <code>Dispose</code> method of a ModSystem. Make sure you include the id in the call to <code>UnpatchAll()</code>, as otherwise you may accidentally unpatch other mods before they expect | For good practice, if you patch the game with your mod, make sure you unpatch it when your mod unloads. The easiest way to do this is to run <code>harmony.UnpatchAll("MyModId")</code> in the <code>Dispose</code> method of a ModSystem. Make sure you include the id in the call to <code>UnpatchAll()</code>, as otherwise you may accidentally unpatch other mods before they expect. | ||
<syntaxhighlight lang="c#"> | <syntaxhighlight lang="c#"> | ||
public void Dispose() { | public void Dispose() { | ||
| Line 102: | Line 99: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== Remarks == | |||
* Just because you can use monkey patching, does not mean you should. Patches are often fragile and break easily (especially if you access internal private methods). So if you can use normal means of modding you probably should. | * Just because you can use monkey patching, does not mean you should. Patches are often fragile and break easily (especially if you access internal private methods). So if you can use normal means of modding you probably should. | ||
* You can't use harmony to patch fields (because they are not called), so in order to change field access you have to patch all calls to this field with patches. You can patch getters and setters, if they are available. | * You can't use harmony to patch fields (because they are not called), so in order to change field access you have to patch all calls to this field with patches. You can patch getters and setters, if they are available. | ||
{{Navbox/modding|Vintage Story}} | {{Navbox/modding|Vintage Story}} | ||
