Home

Awesome

MonoMod

<a href="https://discord.gg/jm7GCZB"><img align="right" alt="MonoMod Discord" src="https://discordapp.com/api/guilds/295566538981769216/embed.png?style=banner2" /></a> General purpose .NET assembly modding "basework", powered by cecil.
<sup>MIT-licensed.</sup>

Build status Deployment status

GitHub: AllNuGet: PatcherNuGet: UtilsNuGet: RuntimeDetourNuGet: HookGen
GitHub releasesCoreUtilsRuntimeDetourHookGen
VersionVersionVersionVersionVersion

<sup>... or download fresh build artifacts for the last commit.</sup>

Sections

Special thanks to my patrons on Patreon:

Introduction

MonoMod is a modding "basework" (base tools + framework).
Mods / mod loaders for the following games are already using it in one way or another:

It consists of the following modular components:

Why?

Using MonoMod

Drop MonoMod.exe, all dependencies (Utils, cecil) and your patches into the game directory. Then, in your favorite shell (cmd, bash):

MonoMod.exe Assembly.exe

MonoMod scans the directory for files named [Assembly].*.mm.dll and generates MONOMODDED_[Assembly].exe, which is the patched version of the assembly.

Example Patch

You've got Celeste.exe and want to patch the method public override void Celeste.Player.Added(Scene scene).

If you haven't created a mod project yet, create a shared C# library project called Celeste.ModNameHere.mm, targeting the same framework as Celeste.exe.
Add Celeste.exe, MonoMod.exe and all dependencies (.Utils, cecil) as assembly references.
Note: Make sure to set "Copy Local" to False on the game's assemblies. Otherwise your patch will ship with a copy of the game!

#pragma warning disable CS0626 // orig_ method is marked external and has no attributes on it.
namespace Celeste {
    // The patch_ class is in the same namespace as the original class.
    // This can be bypassed by placing it anywhere else and using [MonoModPatch("global::Celeste.Player")]

    // Visibility defaults to "internal", which hides your patch from runtime mods.
    // If you want to "expose" new members to runtime mods, create extension methods in a public static class PlayerExt
    class patch_Player : Player { // : Player lets us reuse any of its visible members without redefining them.
        // MonoMod creates a copy of the original method, called orig_Added.
        public extern void orig_Added(Scene scene);
        public override void Added(Scene scene) {
            // Do anything before.

            // Feel free to modify the parameters.
            // You can even replace the method's code entirely by ignoring the orig_ method.
            orig_Added(scene);
            
            // Do anything afterwards.
        }
    }
}

Build Celeste.ModNameHere.mm.dll, copy it into the game's directory and run MonoMod.exe Celeste.exe, which generates MONOMODDED_Celeste.exe.
Note: This can be automated by a post-build step in your IDE and integrated in an installer, f.e. Everest.Installer (GUI), MiniInstaller (CLI) or PartialityLauncher (GUI).

To make patching easy, yet flexible, the MonoMod patcher offers a few extra features:

FAQ

How does the patcher work?

How can I check if my assembly has been modded?

MonoMod creates a type called "WasHere" in the namespace "MonoMod" in your assembly:

if (Assembly.GetExecutingAssembly().GetType("MonoMod.WasHere") != null) {
    Console.WriteLine("MonoMod was here!");
} else {
    Console.WriteLine("Everything fine, move on.");
}

Note: This can be easily bypassed. More importantly, it doesn't detect changes made using other tools like dnSpy.
If you're a gamedev worried about cheating: Please don't fight against the modding community. Cheaters will find another way to cheat, and modders love to work together with gamedevs.

Am I allowed to redistribute the patched assembly?

This depends on the licensing situation of the input assemblies. If you're not sure, ask the authors of the patch and of the game / program / library.

Is it possible to use multiple patches?

Yes, as long as the patches don't affect the same regions of code.

While possible, its behaviour is not strictly defined and depends on the patching order.
Instead, please use runtime detours / hooks instead, as those were built with "multiple mod support" in mind.