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/ILHooklet 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 throwsArgumentException("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
NotImplementedExceptionorPlatformNotSupportedException. See Installation. - If you only need one replacement detour and nothing else,
MonoMod.Corecan 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 markedIsPackable=false, so this repository's build does not produce NuGet packages for them. See Installation.
Where to Go Next
- Installation: packages, target frameworks, and supported platforms.
- Quick Start: your first
HookandILHook. - Hook: every constructor and the rules for hook method signatures.
- ILHook and ILCursor: runtime IL editing.
- Detour Order: making several mods cooperate.
- Switches and Logging: environment variables that change MonoMod's behavior.
- Patcher: ahead-of-time patching.
- Troubleshooting: common errors and surprising behavior.