Convert Figma logo to code with AI

LavaGang logoMelonLoader

The World's First Universal Mod Loader for Unity Games compatible with both Il2Cpp and Mono

2,909
504
2,909
45
View on GitHub

Top Related Projects

BepInEx's avatar

BepInEx

5,510

Unity / XNA game patcher and plugin framework

pardeike's avatar

Harmony

5,445

A library for patching, replacing and decorating .NET and Mono methods during runtime

sinai-dev's avatar

UnityExplorer

2,542

An in-game UI for exploring, debugging and modifying IL2CPP and Mono Unity games.

Quick Overview

MelonLoader is an open-source mod loader for Unity games. It allows users to load and manage mods for Unity-based games, providing a framework for modders to create and distribute custom content and modifications.

Pros

  • Cross-platform support (Windows, Linux, Android)
  • Automatic updates and mod management
  • Extensive documentation and active community support
  • Compatible with a wide range of Unity games

Cons

  • May not work with all Unity games, especially those with strong anti-cheat systems
  • Potential for conflicts between mods
  • Requires some technical knowledge to set up and use effectively
  • May impact game performance, especially with multiple mods installed

Code Examples

// Example 1: Creating a simple mod
using MelonLoader;

public class MyMod : MelonMod
{
    public override void OnApplicationStart()
    {
        LoggerInstance.Msg("My mod has been loaded!");
    }
}

// Example 2: Hooking into a game method
using HarmonyLib;

[HarmonyPatch(typeof(PlayerController), "TakeDamage")]
public class DamageModifier
{
    [HarmonyPostfix]
    public static void Postfix(ref float __result)
    {
        __result *= 0.5f; // Reduce damage taken by 50%
    }
}

// Example 3: Adding a custom GUI element
using UnityEngine;

public class CustomGUI : MelonMod
{
    public override void OnGUI()
    {
        GUI.Label(new Rect(10, 10, 100, 20), "Hello, MelonLoader!");
    }
}

Getting Started

  1. Download the latest MelonLoader installer from the official GitHub repository.
  2. Run the installer and select the Unity game executable you want to mod.
  3. Create a new C# project in your preferred IDE.
  4. Add references to MelonLoader.dll and 0Harmony.dll from the game's installation folder.
  5. Create a new class that inherits from MelonMod:
using MelonLoader;

public class MyFirstMod : MelonMod
{
    public override void OnApplicationStart()
    {
        LoggerInstance.Msg("Hello, MelonLoader!");
    }
}
  1. Build your project and place the resulting DLL in the game's Mods folder.
  2. Launch the game to see your mod in action.

Competitor Comparisons

BepInEx logo

BepInEx

5,510

Unity / XNA game patcher and plugin framework

Pros of BepInEx

  • More flexible and supports a wider range of Unity games
  • Better documentation and community support
  • Offers a plugin system for easier mod management

Cons of BepInEx

  • Slightly more complex setup process
  • May have compatibility issues with some older games
  • Performance impact can be higher in certain scenarios

Code Comparison

MelonLoader:

[MelonInfo(typeof(MyMod), "MyMod", "1.0.0", "Author")]
public class MyMod : MelonMod
{
    public override void OnApplicationStart()
    {
        // Mod initialization code
    }
}

BepInEx:

[BepInPlugin("com.example.myplugin", "MyPlugin", "1.0.0")]
public class MyPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        // Plugin initialization code
    }
}

Both MelonLoader and BepInEx are popular modding frameworks for Unity games. MelonLoader is known for its ease of use and straightforward setup, while BepInEx offers more flexibility and broader game support. The code comparison shows that both frameworks use similar attribute-based mod/plugin registration, but with slightly different class inheritance and initialization methods. Ultimately, the choice between the two depends on the specific game being modded and the developer's preferences.

pardeike logo

Harmony

5,445

A library for patching, replacing and decorating .NET and Mono methods during runtime

Pros of Harmony

  • More lightweight and focused on patching .NET methods
  • Easier to integrate into existing projects without full mod loader overhead
  • Better documentation and community support

Cons of Harmony

  • Limited to method patching, lacks broader mod management features
  • Requires more manual setup and configuration for each patch
  • Less suitable for large-scale modding projects or game-specific modifications

Code Comparison

MelonLoader:

[MelonLoader.MelonInfo(typeof(MyMod), "MyMod", "1.0.0", "Author")]
public class MyMod : MelonLoader.MelonMod
{
    public override void OnInitializeMelon()
    {
        // Mod initialization code
    }
}

Harmony:

[HarmonyPatch(typeof(TargetClass), "TargetMethod")]
class Patch
{
    static void Postfix(ref int __result)
    {
        __result *= 2; // Modify the result
    }
}

MelonLoader provides a more comprehensive modding framework with built-in mod management and lifecycle hooks, while Harmony focuses on efficient method patching. MelonLoader is better suited for large-scale game modding, whereas Harmony excels in targeted modifications and library integrations.

sinai-dev logo

UnityExplorer

2,542

An in-game UI for exploring, debugging and modifying IL2CPP and Mono Unity games.

Pros of UnityExplorer

  • More focused on runtime inspection and debugging of Unity games
  • Provides a comprehensive in-game UI for exploring and manipulating game objects
  • Offers advanced features like object browser, scene explorer, and console commands

Cons of UnityExplorer

  • Limited to runtime exploration and modification
  • May not provide as extensive modding capabilities as MelonLoader
  • Potentially higher performance impact due to real-time inspection features

Code Comparison

UnityExplorer:

public static void Init()
{
    UIManager.Init();
    ObjectExplorer.Init();
    SceneExplorer.Init();
}

MelonLoader:

public override void OnApplicationStart()
{
    ModLogger.Log("Mod initialized!");
    // Custom mod initialization code
}

UnityExplorer focuses on providing runtime inspection and debugging tools, while MelonLoader is primarily designed for modding Unity games. UnityExplorer's code snippet shows initialization of various exploration tools, whereas MelonLoader's code demonstrates a typical mod entry point. MelonLoader offers a more comprehensive framework for creating and loading mods, while UnityExplorer excels at runtime analysis and manipulation of Unity games.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

GENERAL INFORMATION:

Usage Guides:
INSTALLER
MANUAL USE
Example Projects:
TestPlugin
TestMod
Nightly Builds:
master
alpha-development
universality

❤️ SPECIAL THANKS TO OUR WONDERFUL PATRONS ❤️

  • Givo
  • Florian Fahrenberger
  • Python
  • SirCoolness
  • SlidyDev

REQUIREMENTS:

Il2Cpp Games:

On Windows, the .NET 6.0 Desktop Runtime will be installed automatically

HOW TO USE THE INSTALLER:

  1. Follow the Instructions in one of the Guides linked below.
Installer Guides:
INSTALL
UPDATE
RE-INSTALL
UN-INSTALL

HOW TO MANUALLY USE MELONLOADER:

UPDATE / RE-INSTALL:

  1. Follow the Steps to UN-INSTALL
  2. Follow the Steps to INSTALL

INSTALL:

  1. Make sure the Game is Closed and Not Running before attempting to Install.
  2. Make sure you have all the Requirements Installed before attempting to Install.
  3. Download MelonLoader [x86] [x64]
  4. Extract the MelonLoader folder from the MelonLoader Zip Archive to the Game's Installation Folder.
  5. Extract version.dll & dobby.dll from the MelonLoader Zip Archive to the Game's Installation Folder.

UN-INSTALL:

  1. Make sure the Game is Closed and Not Running before attempting to UN-INSTALL.
  2. Remove the version.dll file from the Game's Installation Folder.
  3. Remove the MelonLoader folder from the Game's Installation Folder.

These additional steps below are OPTIONAL if you want to do a FULL UN-INSTALL.

  1. Remove the Plugins folder from the Game's Installation Folder.
  2. Remove the Mods folder from the Game's Installation Folder.
  3. Remove the UserData folder from the Game's Installation Folder.

CONFIG:

MelonLoader has its own config file at ./UserData/Loader.cfg (you need to run MelonLoader at least once for it to appear).

Here is a list of the current config options (and their default values):

[loader]
# Disables MelonLoader. Equivalent to the '--no-mods' launch option
disable = false
# Equivalent to the '--melonloader.debug' launch option
debug_mode = true
# Only use this if the game freezes when trying to quit. Equivalent to the '--quitfix' launch option
force_quit = false
# Disables the start screen. Equivalent to the '--melonloader.disablestartscreen' launch option
disable_start_screen = false
# Starts the dotnet debugger (only for Il2Cpp games). Equivalent to the '--melonloader.launchdebugger' launch option
launch_debugger = false
# Sets the loader theme. Currently, the only available themes are "Normal" and "Lemon". Equivalent to the '--melonloader.consolemode' launch option (0 for Normal, 4 for Lemon)
theme = "Normal"

[console]
# Hides warnings from displaying. Equivalent to the '--melonloader.hidewarnings' launch option
hide_warnings = false
# Hides the console. Equivalent to the '--melonloader.hideconsole' launch option
hide_console = false
# Forces the console to always stay on-top of all other applications. Equivalent to the '--melonloader.consoleontop' launch option
console_on_top = false
# Keeps the console title as original. Equivalent to the '--melonloader.consoledst' launch option
dont_set_title = false

[logs]
# Sets the maximum amount of log files in the Logs folder (Default: 10). Equivalent to the '--melonloader.maxlogs' launch option
max_logs = 10

[unityengine]
# Overrides the detected UnityEngine version. Equivalent to the '--melonloader.unityversion' launch option
version_override = ""
# Disables the console log cleaner (only applies to Il2Cpp games). Equivalent to the '--melonloader.disableunityclc' launch option
disable_console_log_cleaner = false
# Forces the Il2Cpp Assembly Generator to run without contacting the remote API. Equivalent to the '--melonloader.agfoffline' launch option
force_offline_generation = false
# Forces the Il2Cpp Assembly Generator to use the specified regex. Equivalent to the '--melonloader.agfregex' launch option
force_generator_regex = ""
# Forces the Il2Cpp Assembly Generator to use the specified Il2Cpp dumper version. Equivalent to the '--melonloader.agfvdumper' launch option
force_il2cpp_dumper_version = ""
# Forces the Il2Cpp Assembly Generator to always regenerate assemblies. Equivalent to the '--melonloader.agfregenerate' launch option
force_regeneration = false
# Enables the CallAnalyzer processor for Cpp2IL. Equivalent to the '--cpp2il.callanalyzer' launch option
enable_cpp2il_call_analyzer = false
# Enables the NativeMethodDetector processor for Cpp2IL. Equivalent to the '--cpp2il.nativemethoddetector' launch option
enable_cpp2il_native_method_detector = false

LAUNCH OPTIONS:

  • These are additional Launch Options that MelonLoader adds to the Game.
  • These can be used to manipulate how MelonLoader works.
ArgumentDescription
--no-modsLaunches the Game without loading any Plugins or Mods
--quitfixFixes the Hanging Process Issue with some Games
--melonloader.consolemodeChanges the Theme Display Mode of the Console [ Default = 0 ]
--melonloader.consoleontopForces the Console to always stay on-top of all other Applications
--melonloader.consoledstKeeps the Console Title as Original
--melonloader.hideconsoleHides the Console
--melonloader.hidewarningsHides Warnings from Displaying
--melonloader.debugDebug Mode
--melonloader.maxlogsMax Log Files [ Default: 10 ] [ NoCap: 0 ]
--melonloader.loadmodepluginsLoad Mode for Plugins [ Default: 0 ]
--melonloader.loadmodemodsLoad Mode for Mods [ Default: 0 ]
--melonloader.basedirChanges the Proxy's Load Directory for the Bootstrap
--melonloader.disablestartscreenDisable the Start Screen
  • These ones below are Unity Engine specific Launch Options.
ArgumentDescription
--melonloader.unityversionAllows you to Specify the Version of Unity Engine
--melonloader.agfofflineForces Assembly Generator to Run without Contacting the Remote API
--melonloader.agfregenerateForces Regeneration of Assembly
--melonloader.agfregexForces Assembly Generator to use a Specified Regex
--melonloader.agfvdumperForces Assembly Generator to use a Specified Version of Dumper
--melonloader.disableunityclcDisable Unity Console Log Cleaner
  • These ones below are Cpp2IL specific Launch Options.
ArgumentDescription
--cpp2il.callanalyzerEnables CallAnalyzer processor
--cpp2il.nativemethoddetectorEnables NativeMethodDetector processor

PROXIES:

MelonLoader uses a proxy DLL to trick the game into loading itself on startup. This only applies for Windows.

  • The Proxy DLL is able to be Renamed to the Compatible File Names below.
  • By Default the Proxy is named as "version.dll".
  • For most Games the Default File Name should work perfectly fine.
  • Some Games may have you use a different Proxy File Name depending on the Architecture, Operating System, version of the Engine used by the Game, etc.
File Names:
version.dll
winhttp.dll
winmm.dll
dinput.dll
dinput8.dll
dsound.dll
d3d8.dll
d3d9.dll
d3d10.dll
d3d11.dll
d3d12.dll
ddraw.dll
msacm32.dll

LICENSING & CREDITS:

MelonLoader is licensed under the Apache License, Version 2.0. See LICENSE for the full License.

Third-party Libraries used as Source Code and/or bundled in Binary Form:

External Libraries and Tools that are downloaded and used at Runtime:

See MelonLoader Wiki for the full Credits.

MelonLoader is not sponsored by, affiliated with or endorsed by Unity Technologies or its affiliates.
"Unity" is a trademark or a registered trademark of Unity Technologies or its affiliates in the U.S. and elsewhere.