MonoMod: a .NET assembly modding toolkit built on Cecil

What the toolkit is and what it is built on

MonoMod describes itself as a general purpose .NET assembly modding basework, that is, the base tools and the framework that a mod or a mod loader is built on, and the engine underneath it is Cecil, the library for reading and writing .NET assemblies. That choice explains the whole shape of the project. Because Cecil works on the intermediate language rather than on a running process, MonoMod can look at a compiled assembly, change it, and write it back, which is what makes both the ahead-of-time and the run-time approaches possible from one foundation. The licence is MIT, the packages are on NuGet, and the project also points at downloadable build artefacts for the last commit, which matters because the published packages are not the whole story. There is a Discord community, and the documentation for the run-time component has its own page in the repository.

The seven pieces, and how they divide the work

The repository is a set of components rather than one library, and the split matters because a mod author should only take what they need. MonoMod.Core is the foundation that the rest is built on. MonoMod.RuntimeDetour is the run-time component, a flexible and extensible detouring library that supports x86 and x86_64 on .NET Framework, .NET Core and Mono. MonoMod.RuntimeDetour.HookGen generates a hook helper library for any IL assembly, which is what turns interception into an ordinary event subscription. MonoMod.Patcher is the ahead-of-time counterpart, a patcher and relinker for people who want the modification compiled into the assembly. MonoMod.Utils holds the general helpers, from platform detection to fast reflection and dynamic method helpers, and is described as useful to mods in general even when they do not use the rest. MonoMod.DebugIL enables IL level debugging of third-party assemblies inside Visual Studio or MonoDevelop. And MonoMod.Backports lives in its own repository, collecting base class library backports so that newer language and library features work as far back as .NET Framework 3.5.

HookGen, and what an event-shaped hook looks like

The runtime detouring library replaces a method at run time, which is a powerful but clumsy thing to write by hand, because every call site has to be rewritten. HookGen sits on top of it and generates the helper library that does that rewriting, and the result is the API that the README shows off:

On.Namespace.Type.Method += (orig, a, b, c) => { /* ... */ }

Reading that line tells you the design. The hooked method is referred to as a member that you subscribe to, the original implementation arrives as the first argument so you can call it, and the remaining arguments are the ones the original method took. A mod author can therefore write a hook the way they would write an event handler, and the machinery underneath is generated for them rather than hand written per project. The IL variant goes further, and the README says it can manipulate IL at run time and even inline C# delegate calls between instructions, which is the level you need when a method has to be rewritten in the middle rather than only at its entry.

The four reasons the project gives for existing

The README lists the motivations, and each one is a real engineering constraint rather than a slogan. Cross-version compatibility, including with obfuscated assemblies, which is what lets one mod keep working when the game updates its own code. Cross-platform compatibility, even when the game uses a different engine on different systems, with Celeste given as the example since it runs on one engine on Windows and another on macOS and Linux. Language features that the target runtime would not otherwise support, with C# 7 in a Unity 4.3 game as the example, which is what the backports package exists for. And patching on the player's machine with an ordinary mod installer, so nothing has to be pre-patched, no game data is redistributed, and the copyright position stays clean. That last point is the one that distinguishes this approach from shipping a modified copy of a game, and it is a legal as well as a technical argument.

Who is actually using it

The introduction lists the mod loaders and mods built on MonoMod, and the list is a good map of the ecosystem. Terraria has tModLoader and TerrariaHooks. Hollow Knight has HollowKnight.Modding. Celeste has Everest. Risk of Rain 2 has a Thunderstore package that bundles BepInEx, MonoMod and R2API together. Enter the Gungeon has Mod the Gungeon, Rain World has RainDB through BepInEx, and Totally Accurate Battle Simulator has a multiplayer mod. Salt and Sanctuary has Salt.Modding, Nimbatus and Dungeon of the Endless go through Partiality, and one entry is marked as defunct, which is a useful reminder that modding projects end. The pattern is worth noting, because many of these are games that ship on more than one platform or on more than one runtime, which is exactly the case the toolkit was built for.

The repository and where the project stands

The tree shows a serious build setup rather than a hobby repository. There is a solution file in the newer solution format, shared build properties and targets and a response file, a pinned global settings file, a NuGet configuration, a strong naming key, a documentation folder with its own toolchain, an artifacts directory, a tools directory, and an external directory tracked as submodules, which is where the Cecil dependency and the other vendored pieces live. There is also a file listing revisions to ignore in the blame output, which is what a project does after a large formatting or restructure pass. The state of the project is the part to note. The published releases are from 2022, with 22.07.31.01 the newest, while the last push to the branch is dated 2026-10-19 and the default branch is called reorganize, which suggests the code is being restructured rather than released. The README therefore points at the build artefacts from the last commit, and a new consumer should take that rather than the NuGet versions.

Editorial conclusion

MonoMod fits a mod author who is targeting games that ship on several platforms and several runtime generations at once, because cross-version and cross-platform compatibility is the design goal rather than an accident, and it fits a team that would rather patch on the player's machine than distribute a modified copy of the game. It does not fit a project that needs the newest .NET only, because the published packages stopped at the 2022 releases and the branch has been reorganised since, so a new consumer should build from source or use the CI artefacts. Before adopting it, decide whether you want run-time hooking or ahead-of-time patching, because the two live in different components with different deployment stories.

Frequently asked questions

Official sources

1. License: MIT
2. MonoMod/MonoMod on GitHub
3. Project website
4. README
5. Releases