# MelonLoader: one mod loader for both halves of the Unity world

> MelonLoader is an Apache-2.0 universal mod loader for Unity games, billing itself as the world's first to support both the Il2Cpp and Mono runtimes. It drops into a game's installation folder behind a version.dll proxy, creates Plugins, Mods and Logs directories, exposes its behavior through Loader.cfg and a large set of launch options, and includes a Mono debug server for mod development, with Linux support through WINE, Steam Proton and native builds.

**LavaGang/MelonLoader** — The World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono

- Repository: https://github.com/LavaGang/MelonLoader
- Website: https://discord.gg/2Wn3N2P
- Stars: 4,225 · Forks: 655
- Language: C#
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/lavagang-melonloader

## One loader, both Unity runtimes

MelonLoader calls itself the world's first universal mod loader for Unity games, compatible with both Il2Cpp and Mono, and the claim rests on a real divide in the Unity ecosystem. Il2Cpp games compile C# to C++ ahead of time, producing native binaries where normal .NET modding techniques cannot attach, while Mono games keep the managed runtime that hooking libraries like Harmony were built for. A loader covering both needs an Assembly Generator for the Il2Cpp side, visible in the launch options where an agfoffline flag forces it to run without contacting a remote server, plus the standard Mono path. Supporting every Unity game with one tool is the universality promise, and there is even a development branch named for it among the nightly builds. Every option in the config file is mirrored by a launch option of the same meaning, so a troubleshooting session can toggle behavior per launch without editing files, the duality that makes both casual users and support helpers productive.

## version.dll is the trigger

Manual installation is a file copy with a clear mechanism. With the game closed and the requirements installed, you download the MelonLoader archive from the releases page, extract the MelonLoader folder into the game's installation folder, and extract version.dll and dobby.dll alongside it. The trick is that Windows games load version.dll from their directory at startup, so the proxy file boots the loader before the game does, with dobby providing the native hooking underneath. Uninstallation mirrors it exactly, remove version.dll and the MelonLoader folder and the game is stock again, with an optional full uninstall also removing the Plugins, Mods and UserData folders that accumulate. Update and reinstall are defined as uninstall then install, no in place upgrade path to get wrong.

## An installer on three desktops

For anyone not extracting archives by hand, a separate MelonLoader.Installer repository publishes installers as a Windows executable, a Linux binary and a macOS dmg, all linked from the README's latest release. The installer handles four flows, install, update, reinstall and uninstall, each documented in the installer repository's own guide, and it is the recommended path precisely because the manual steps differ subtly per game layout. The directory conventions the loader creates after first run are the same either way, logs under MelonLoader/Logs, plugins under Plugins and mods under Mods, all inside the game's installation folder, a layout mod authors can rely on when telling users where files go. Il2Cpp games additionally need the .NET 6.0 Desktop Runtime, installed automatically on Windows by the tooling.

## Loader.cfg, with debug on by default

Configuration lives at UserData/Loader.cfg in TOML form, generated after the first run, and its opening reads:

```toml
[loader]
# Disables MelonLoader. Equivalent to the '--no-mods' launch option
disable = false
# Equivalent to the '--melonloader.debug' launch option
debug_mode = true
# Capture all Unity player logs into MelonLoader's logs even if the game disabled them. NOTE: Depending on the game or Unity version, these logs can be overly verbose. Equivalent to the '--melonloader.captureplayerlogs' launch option
capture_player_logs = true
```

The visible defaults hold a surprise worth knowing, debug_mode defaults to true, because Debug Mode exists for development purposes, to help develop and debug MelonLoader, plugins and mods, and the default assumes the user is a modder. The disable option turns the whole loader off, equivalent to the --no-mods launch option, and capture_player_logs defaults to true, pulling all Unity player logs into MelonLoader's logs even when the game disabled them, with the caveat that depending on the game or Unity version these can be overly verbose. The Harmony log verbosity setting ranges from None through Error, Warn, Info and Debug up to IL, controlling how much of the hooking library's output lands in the log.

## A launch option for every console behavior

The launch option table reads like a troubleshooting kit. --no-mods launches the game without any plugins or mods, the safe mode for separating game bugs from mod bugs. --quitfix addresses the hanging process issue some games have. The console, MelonLoader's visible face, gets six options of its own, consolemode for theme, consoleontop to keep it above other applications, consoledst to preserve the original console title, hideconsole and hidewarnings for silence, plus the debug flag enabling debug mode. maxlogs caps log files at 10 by default with 0 removing the cap, loadmodeplugins and loadmodemods control plugin and mod load modes, basedir changes the proxy's load directory, and disablestartscreen skips the splash. Unity specific options include forcing the engine version and the Assembly Generator offline mode.

## A Mono debug server inside the loader

The most developer oriented launch options expose a Mono debug server, debugsuspend makes it wait until a debugger is attached when in Debug Mode, debugipaddress sets the listening address and debugport the port, all noted as applying only to Mono games. That turns a modded game launch into a standard remote debugging session, attach the IDE of a C# developer and step through mod code as the game runs, the workflow that separates writing mods from writing log statements and praying. Combined with the example projects the organization maintains, TestPlugin and TestMod, the path from installation to a debugging a first mod is fully paved, and the wiki's debugging page extends it further.

## Bootstrap, NativeHost and three nightly branches

The repository structure names its layers, MelonLoader.Bootstrap for the version.dll entry, MelonLoader.NativeHost for the native side, BaseLibs and Dependencies for the vendored foundations, UnityUtilities for engine helpers, and PortablePdbToMdb for symbol format conversion, a small tell of real debugging support since Windows debuggers want mdb symbols. Linux support spans WINE, Steam Proton and native executions with wiki instructions, and Android with Oculus Quest is marked work in progress. Nightly builds publish from three branches, master, alpha-development and universality, so bleeding edge users can pick their stability level. Releases are current, v0.7.1 Open-Beta in June 2025, v0.7.2 in March 2026 and v0.7.3 on 2026-05-14, with the last push on 2026-09-25 under Apache-2.0. A compile.sh beside the solution file covers non Windows builds, and the NOTICE.txt alongside the Apache license does the attribution bookkeeping that a project vendoring this many native libraries accumulates.

## Conclusion

Use MelonLoader when modding a Unity game that ships as Il2Cpp or Mono and you want the standard loader its ecosystem targets, since the Plugins and Mods convention and the debugging tools make it the shared infrastructure of that scene. It is only as trustworthy as the mods loaded into it, vet mods individually rather than the loader. Before installing, close the game, install the .NET 6.0 Desktop Runtime for Il2Cpp titles, prefer the installer over manual extraction on the three desktop platforms, and keep the uninstall sequence in mind, removing version.dll and the MelonLoader folder restores the game, with Plugins, Mods and UserData as the optional full cleanup. For Android and Oculus Quest, check the wiki first, that support is explicitly work in progress.

## FAQ

### What is a MelonLoader used for?

MelonLoader is a universal mod loader for Unity games, compatible with both Il2Cpp and Mono runtimes. It loads plugins from a Plugins folder and mods from a Mods folder in the game's installation directory, logs to MelonLoader/Logs, and provides debug tooling including a Mono debug server for developing mods.

### how to install melonloader?

Either run the MelonLoader Installer for Windows, Linux or macOS and follow its guide, or install manually by closing the game, downloading the release archive, and extracting the MelonLoader folder plus version.dll and dobby.dll into the game's installation folder. Il2Cpp games require the .NET 6.0 Desktop Runtime.

### How do I get rid of melon loader?

Close the game, remove version.dll and the MelonLoader folder from the game's installation folder. For a full uninstall, also remove the Plugins, Mods and UserData folders, which contain your mods and their settings.

### how to use melonloader on linux?

MelonLoader supports Linux through WINE, Steam Proton and native execution, with instructions on the official wiki's Linux page. The installer ships a Linux binary, and the same Plugins and Mods folder conventions apply once installed.

## Sources

- [LavaGang/MelonLoader on GitHub](https://github.com/LavaGang/MelonLoader)
- [License: Apache-2.0](https://github.com/LavaGang/MelonLoader/blob/master/LICENSE)
- [Project website](https://discord.gg/2Wn3N2P)
- [README](https://github.com/LavaGang/MelonLoader/blob/master/README.md)
- [Releases](https://github.com/LavaGang/MelonLoader/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/lavagang-melonloader