MonoMod

MonoMod is a general-purpose .NET assembly modding "basework": a set of base tools plus a framework for changing what .NET code does, either at runtime (detours and hooks applied to methods in a running process) or ahead of time (rewriting an assembly on disk with patches written in C#). It is built on Mono.Cecil and is MIT-licensed.

MonoMod is the foundation of many game mod loaders and modding APIs, including tModLoader (Terraria), Everest (Celeste), the BepInEx pack for Risk of Rain 2, HollowKnight.Modding and Mod the Gungeon. This documentation covers the whole repository, from the high-level Hook API down to the low-level detour core.

The Problem It Solves

When you write a mod for a .NET application you do not control its source code. You need to:

  • run your own code before, after, or instead of an existing method,
  • change the IL (the compiled instructions) of a method,
  • call private members and attach extra data to existing objects,
  • do all of that on .NET Framework, .NET (Core), and Mono, on Windows, Linux, and macOS, on x86, x64, and ARM64, often from several independent mods at once.

MonoMod handles the hard, platform-specific parts (patching machine code, following JIT recompilations, managing a chain of hooks from different mods) and exposes them through a small API.

Components

MonoMod is modular. Use only what you need.

Component Kind What it does
MonoMod.RuntimeDetour Library (NuGet) The high-level runtime hooking API: Hook, ILHook, NativeHook, ordering configs, and introspection. This is the package most users want.
MonoMod.Utils Library (NuGet) Helpers used by everything else and useful on their own: ILCursor/ILContext, DynamicMethodDefinition, DynamicData, ModInterop, PlatformDetection and DynDll, switches and logging.
MonoMod.Core Library (NuGet) The low-level detour engine that RuntimeDetour is built on. Rarely used directly. See Architecture.
MonoMod.Patcher Command-line tool The ahead-of-time patcher and relinker (MonoMod.exe). See Patcher and Patch Modifiers.
MonoMod.RuntimeDetour.HookGen Command-line tool Generates an MMHOOK_*.dll that exposes every method of an assembly as On.* and IL.* events. See HookGen.
MonoMod.DebugIL Command-line tool Dumps an assembly's IL to text files and rewrites its debug symbols so you can step through IL in a debugger. See DebugIL.
MonoMod.Backports Library (separate repository) Backports of newer BCL APIs to old frameworks; a dependency of the libraries above. It lives in its own repository.

A Short Example

Wrap a method at runtime so that your code runs around the original:

using System;
using System.Reflection;
using System.Runtime.CompilerServices;
using MonoMod.RuntimeDetour;

public class Calculator
{
    // Tiny methods are easily inlined by the JIT; inlined call sites never see a detour.
    [MethodImpl(MethodImplOptions.NoInlining)]
    public int Add(int a, int b) => a + b;
}

public static class Program
{
    public static void Main()
    {
        MethodInfo add = typeof(Calculator).GetMethod(nameof(Calculator.Add))!;

        using (new Hook(add, (Func<Calculator, int, int, int> orig, Calculator self, int a, int b) =>
        {
            Console.WriteLine($"Add({a}, {b}) called");
            return orig(self, a, b) * 10;   // call the original, then change its result
        }))
        {
            Console.WriteLine(new Calculator().Add(2, 3)); // prints "Add(2, 3) called", then 50
        }

        Console.WriteLine(new Calculator().Add(2, 3));     // hook disposed: prints 5
    }
}

The Quick Start walks through this step by step, including IL manipulation.

How It Works (in One Paragraph)

When you create a Hook, RuntimeDetour finds the detour chain for the source method (one chain per method, shared by every mod). Your hook is inserted into the chain at a position computed from its DetourConfig. The chain's entry is a generated method that calls the first hook; each hook receives an orig delegate that calls the next hook, and the last one calls a clone of the original method (with every ILHook's changes applied). MonoMod.Core then patches the machine code of the source method so that it jumps to the chain, and keeps that patch alive when the runtime recompiles the method (for example with tiered compilation). Disposing the hook removes it from the chain. The Architecture page has the full picture.

When to Use It

  • Runtime mods and mod loaders: Hook/ILHook let many mods hook the same method without stepping on each other, with explicit ordering.
  • IL-level changes at runtime with ILCursor (similar in spirit to a Harmony transpiler).
  • Native function hooks (NativeHook) for unmanaged exports.
  • Ahead-of-time patching when you want to ship a patched assembly or need features that runtime hooks cannot provide (adding fields to types, changing type hierarchies, relinking references). Use the Patcher.
  • Reflection helpers that are faster or more convenient than raw reflection (DynamicData, DynamicMethodDefinition).

When Not to Use It

  • Generic methods cannot be hooked by Hook: the constructor throws ArgumentException("Source method is generic, generic hooks are not supported") for generic methods and methods of generic types.
  • Methods that the JIT has inlined into their callers are not affected by a detour at those call sites. See Troubleshooting.
  • Unsupported platforms: Android, iOS, BSD, 32-bit ARM, and CoreCLR versions newer than the ones MonoMod knows about throw NotImplementedException or PlatformNotSupportedException. See Installation.
  • If you only need one replacement detour and nothing else, MonoMod.Core can do it, but its own README warns that it is "probably not the library you want". Use RuntimeDetour instead.

Project Status

MonoMod is actively developed. At the time of writing, the default branch is reorganize, the library versions are MonoMod.RuntimeDetour 25.4.0, MonoMod.Utils 25.1.0 and MonoMod.Core 1.4.0, and the build uses the .NET 11 SDK. The repository does not contain a changelog file; releases are produced by the repository's GitHub Actions workflows.

Note: In the current source tree, the command-line tools (MonoMod.Patcher, MonoMod.RuntimeDetour.HookGen, MonoMod.DebugIL) are marked IsPackable=false, so this repository's build does not produce NuGet packages for them. See Installation.

Where to Go Next