# lavagang/melonloader architecture

> Architecture diagram of the GitHub repository lavagang/melonloader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lavagang/melonloader
- Repository: https://github.com/lavagang/melonloader

## Overview

##### Project Type & Purpose
- This is a native-plus-managed “mod loader” framework for Unity games (MelonLoader).
- It injects itself into Unity player processes (both Mono and IL2CPP), generates/interprets assemblies, applies patches via Harmony, and loads user plugins/mods.

A. Proxy DLL & Native Bootstrap
- version.dll (or renamed proxy) + plthook/Dobby libs
- Entrypoint: intercepts game’s DLL load, initializes environment
B. Runtime Handlers
- MonoHandler (for Mono games)
- Il2CppHandler + Il2CppAssemblyGenerator (for IL2CPP games)
C. Managed Core (C#)
- MelonLoader.Core – central API, plugin/mod discovery & loading
- SupportModules & CompatibilityLayers – shims for IPA, Demeo, MuseDash, etc.
- Harmony & patching logic
- Configuration (Loader.cfg) & Logging
D. Plugin/Mod Ecosystem
- “Plugins” folder → user assemblies implementing IPlugin / MelonMod interfaces
- “Mods” folder → IL2CPP mods or other content
E. External Services
- Cpp2IL Remote API (optional)
- Local assembly dump & deobfuscation packages under Dependencies/Il2CppAssemblyGenerator

1. Game EXE loads Proxy DLL → Native Bootstrap
2. Bootstrap (Native) chooses Mono vs IL2CPP handler
3. Handler loads core managed assemblies (MelonLoader.NativeHost → MelonLoader.Core)
4. Core reads config, sets up Logging → writes logs to GameDir/MelonLoader/Logs
5. If IL2CPP: assembly generator runs (offline or remote) → dumps Unity types → loads into AppDomain
6. Core initializes SupportModules & CompatibilityLayers
7. Core scans Plugins/Mods folder → resolves assemblies, applies Harmony patches
8. Patches hook Unity engine methods → user mods execute at runtime

##### Architectural Patterns & Design Principles
- Native-to-Managed bootstrap (C++/C# interop via Dobby & plthook)
- Strategy pattern for runtime handlers (Mono vs IL2CPP)
- Plugin architecture (IPlugin, MelonMod interfaces)
- Dependency Injection / Reflection for module discovery
- Separation of concerns: native hooking vs managed logic vs plugin loading

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Native Components
    subgraph "Native Layer" 
        direction TB
        Proxy["Proxy DLL (version.dll)"]:::native
        Bootstrap["Native Bootstrap"]:::native
        subgraph "MelonLoader.Bootstrap"
            direction TB
            CoreBB["Core.cs"]:::native
            ProxyDir["Proxy"]:::native
            Deps["Deps (win-x86, win-x64, linux-x64, osx-x64)"]:::native
            UtilsDobby["Utils/Dobby.cs"]:::native
            UtilsNative["Utils/NativeFunc.cs"]:::native
        end
    end

    %% Handlers
    subgraph "Runtime Handlers" 
        direction TB
        Mono["MonoHandler"]:::native
        MonoLib["MonoLib.cs"]:::native
        subgraph "MelonLoader.Bootstrap/RuntimeHandlers/Mono"
            direction TB
            MH["MonoHandler.cs"]:::native
            ML["MonoLib.cs"]:::native
        end
        Il2Cpp["Il2CppHandler"]:::native
        Il2CppLib["Il2CppLib.cs"]:::native
        DotnetInst["DotnetInstaller.cs"]:::native
        DotnetCore["Dotnet.cs"]:::native
        subgraph "MelonLoader.Bootstrap/RuntimeHandlers/Il2Cpp"
            direction TB
            IH["Il2CppHandler.cs"]:::native
            ILib["Il2CppLib.cs"]:::native
            DI["DotnetInstaller.cs"]:::native
            DC["Dotnet.cs"]:::native
        end
    end

    %% Managed Core
    subgraph "Managed Core" 
        direction TB
        NH["NativeEntryPoint.cs"]:::managed
        CoreAPI["Core.cs"]:::managed
        Config["LoaderConfig.cfg"]:::storage
        Logger["MelonLogger.cs"]:::storage
        subgraph "MelonLoader.NativeHost"
            NEP["NativeEntryPoint.cs"]:::managed
        end
        subgraph "MelonLoader"
            CoreMain["Core.cs"]:::managed
            LoaderCfg["LoaderConfig.cs"]:::managed
            MelonLogger["Utils/MelonLogger.cs"]:::managed
        end
        subgraph "InternalUtils"
            HL["HarmonyLogger.cs"]:::managed
            Il2CppGen["Il2CppAssemblyGenerator.cs"]:::managed
        end
        subgraph "Dependencies/CompatibilityLayers"
            Demeo["Demeo"]:::managed
            IPA["IPA"]:::managed
            Muse["Muse_Dash_Mono"]:::managed
            SLZ["Stress_Level_Zero_Il2Cpp"]:::managed
        end
        SubMods["Dependencies/SupportModules"]:::managed
    end

    %% Plugin Ecosystem
    subgraph "Plugin & Mod Ecosystem" 
        direction TB
        PluginsDir["Plugins folder"]:::plugins
        ModsDir["Mods folder"]:::plugins
        subgraph "MelonLoader/Melons"
            MM["MelonMod.cs"]:::plugins
            MP["MelonPlugin.cs"]:::plugins
            MHAND["MelonHandler.cs"]:::plugins
        end
        subgraph "Resolver"
            AM["AssemblyManager.cs"]:::plugins
            MAR["MelonAssemblyResolver.cs"]:::plugins
        end
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        Il2CppAG["Il2CppAssemblyGenerator"]:::external
        RemoteAPI["RemoteAPI.cs"]:::external
        Cpp2IL["Dependencies/Il2CppAssemblyGenerator/Packages/Cpp2IL*"]:::external
    end

    %% Storage
    ConfigLog["GameDir/MelonLoader/Logs"]:::storage
    DumpStorage["Dumped Assemblies"]:::storage

    %% Connections
    GameEXE["Game EXE"] -->|loads| Proxy
    Proxy -->|initializes| Bootstrap
    Bootstrap -->|choose handler| Mono
    Bootstrap -->|choose handler| Il2Cpp

    Mono -->|load managed| NH
    Il2Cpp -->|load managed| NH

    NH -->|invoke| CoreAPI
    CoreAPI -->|read| Config
    CoreAPI -->|setup| Logger
    CoreAPI -->|write logs| ConfigLog

    Il2Cpp -->|run generator| Il2CppGen
    Il2CppGen -->|dump types| DumpStorage
    Il2CppGen -->|optional remote| RemoteAPI
    RemoteAPI -.->|remote API| Cpp2IL

    CoreAPI -->|init| Demeo
    CoreAPI -->|init| IPA
    CoreAPI -->|init| Muse
    CoreAPI -->|init| SLZ
    CoreAPI -->|init| SubMods

    CoreAPI -->|scan| PluginsDir
    CoreAPI -->|scan| ModsDir
    PluginsDir -->|uses| MM
    PluginsDir -->|uses| MP
    PluginsDir -->|uses| MHAND
    CoreAPI -->|resolve| AM
    CoreAPI -->|resolve| MAR

    CoreAPI -->|apply patches| HL
    CoreAPI -->|apply patches| Il2CppGen

    %% Click Events
    click ProxyDir "https://github.com/lavagang/melonloader/tree/master/MelonLoader.Bootstrap/Proxy"
    click CoreBB "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/Core.cs"
    click Deps "https://github.com/lavagang/melonloader/tree/master/MelonLoader.Bootstrap/Deps"
    click UtilsDobby "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/Utils/Dobby.cs"
    click UtilsNative "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/Utils/NativeFunc.cs"
    click MH "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Mono/MonoHandler.cs"
    click ML "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Mono/MonoLib.cs"
    click IH "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Il2Cpp/Il2CppHandler.cs"
    click ILib "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Il2Cpp/Il2CppLib.cs"
    click DI "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Il2Cpp/DotnetInstaller.cs"
    click DC "https://github.com/lavagang/melonloader/blob/master/MelonLoader.Bootstrap/RuntimeHandlers/Il2Cpp/Dotnet.cs"
    click NEP "https://github.com/lavagang/melonloader/blob/master/MelonLoader.NativeHost/NativeEntryPoint.cs"
    click CoreMain "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Core.cs"
    click LoaderCfg "https://github.com/lavagang/melonloader/blob/master/MelonLoader/LoaderConfig.cs"
    click MelonLogger "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Utils/MelonLogger.cs"
    click HL "https://github.com/lavagang/melonloader/blob/master/MelonLoader/InternalUtils/HarmonyLogger.cs"
    click Il2CppGen "https://github.com/lavagang/melonloader/blob/master/MelonLoader/InternalUtils/Il2CppAssemblyGenerator.cs"
    click Demeo "https://github.com/lavagang/melonloader/tree/master/Dependencies/CompatibilityLayers/Demeo"
    click IPA "https://github.com/lavagang/melonloader/tree/master/Dependencies/CompatibilityLayers/IPA"
    click Muse "https://github.com/lavagang/melonloader/tree/master/Dependencies/CompatibilityLayers/Muse_Dash_Mono"
    click SLZ "https://github.com/lavagang/melonloader/tree/master/Dependencies/CompatibilityLayers/Stress_Level_Zero_Il2Cpp"
    click SubMods "https://github.com/lavagang/melonloader/tree/master/Dependencies/SupportModules"
    click MM "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Melons/MelonMod.cs"
    click MP "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Melons/MelonPlugin.cs"
    click MHAND "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Melons/MelonHandler.cs"
    click AM "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Resolver/AssemblyManager.cs"
    click MAR "https://github.com/lavagang/melonloader/blob/master/MelonLoader/Resolver/MelonAssemblyResolver.cs"
    click Il2CppAG "https://github.com/lavagang/melonloader/blob/master/Dependencies/Il2CppAssemblyGenerator/Il2CppAssemblyGenerator.csproj"
    click RemoteAPI "https://github.com/lavagang/melonloader/blob/master/Dependencies/Il2CppAssemblyGenerator/RemoteAPI.cs"
    click Cpp2IL "https://github.com/lavagang/melonloader/tree/master/Dependencies/Il2CppAssemblyGenerator/Packages/Cpp2IL*"

    %% Styles
    classDef native fill:#c6f6d5,stroke:#333,stroke-width:1px
    classDef managed fill:#bee3f8,stroke:#333,stroke-width:1px
    classDef plugins fill:#fed7aa,stroke:#333,stroke-width:1px
    classDef external fill:#e2e8f0,stroke:#333,stroke-width:1px
    classDef storage fill:#fff5b1,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
