MDB Framework

Runtime IL2CPP modding framework for Unity games. Dumps metadata, generates C# wrappers, builds an SDK, and loads mods — all automatically from a single DLL injection.

Encrypted global-metadata.dat? Don’t care.

What is MDB Framework?

MDB Framework is a powerful runtime modding solution for Unity IL2CPP games. It eliminates the complexity of traditional IL2CPP modding by automating the entire workflow:

  1. Proxy DLL Injection - Ships as a version.dll proxy — just drop it in the game folder, no external injector needed
  2. Automatic Metadata Dumping - Extracts all classes, methods, and fields from the IL2CPP runtime
  3. C# Wrapper Generation - Creates type-safe C# wrappers for all game types
  4. SDK Auto-Building - Compiles a complete modding SDK using MSBuild
  5. CLR Hosting - Hosts .NET Framework 4.7.2 via COM-based CLR hosting
  6. MonoBehaviour Injection - Fabricates an IL2CPP MonoBehaviour subclass in memory for main-thread callbacks
  7. Mod Loading - Auto-discovers and loads mods from the Mods/ folder
  8. Harmony-Style Patching - Declarative method hooking with [Patch] attributes
  9. ImGui Integration - Built-in Dear ImGui overlay with input capture (DX11/DX12)

All of this happens automatically on first injection. Subsequent launches are instant if nothing has changed.

Key Features

🚀 Zero-Configuration Setup

Rename MDB_Bridge.dll to version.dll, drop it in the game folder, and launch the game — no injector required. MDB also supports direct DLL injection for development. No manual dumping, no external tools, no complex setup.

🎯 Harmony-Style Patching

[Patch("GameNamespace", "Player")]
[PatchMethod("TakeDamage", 1)]
public static class PlayerPatch
{
    [Prefix]
    public static bool Prefix(IntPtr __instance, int damage)
    {
        // Named parameters map positionally to native args
        // Return false to skip original method
        return true;
    }
}

🎨 Built-in ImGui UI

public override void OnLoad()
{
    ImGuiManager.RegisterCallback(DrawUI, "My Window");
}

private void DrawUI()
{
    if (ImGui.Begin("My Window"))
    {
        ImGui.Text("Hello from MDB!");
    }
    ImGui.End();
}

🔧 Full IL2CPP Bridge Access

IntPtr playerClass = Il2CppBridge.mdb_find_class("Assembly-CSharp", "", "Player");
IntPtr healthField = Il2CppBridge.mdb_get_field(playerClass, "health");
float health = Il2CppBridge.mdb_field_get_value<float>(playerInstance, healthField);

🧬 Generic Type Resolution

Unlike traditional dumpers that erase generics to object, MDB resolves actual type arguments:

How It Works

MDB supports two injection modes: proxy mode (recommended) and direct injection (for development).

In proxy mode, MDB_Bridge.dll is renamed to version.dll and placed in the game folder. Windows loads it automatically at startup via DLL search order — no external injector needed.

Game.exe launches
  → Windows loads version.dll (our proxy) from game directory
  → DllMain spawns background initialization thread
  → Proxy forwards all 17 version API calls to the real System32 version.dll
  → Background thread polls for GameAssembly.dll (up to 30s)
  → Resolves 50+ IL2CPP function exports (with obfuscation fallback)
  → Dumps all IL2CPP metadata (classes, methods, fields, properties)
  → Generates C# wrapper source files with full generic type resolution
  → Invokes MSBuild to compile GameSDK.ModHost.dll
  → Hosts .NET Framework 4.7.2 CLR via COM (ICLRRuntimeHost)
  → Calls ModManager.Initialize() → discovers and loads mods
  → Fabricates MDBRunner MonoBehaviour in IL2CPP memory
  → Attaches to Unity player loop for Update/FixedUpdate/LateUpdate callbacks
  → Mods run on Unity's main thread via MDBRunner dispatch

See the Architecture Guide for a detailed explanation of each step, the Proxy DLL Injection Guide for the version.dll proxy system, and the Class Injection Guide for the MonoBehaviour fabrication system.

Supported Platforms

Example Mods

The framework includes four example mods demonstrating every major API:

Example Difficulty Description
HelloWorld 🟢 Simple Lifecycle, Logger, basic ImGui
UnityDebugInterceptor 🟢 Simple Declarative patching, hooking Debug.Log
GameStats 🟡 Medium Advanced patching, IL2CPP Bridge
MDB_Explorer_ImGui 🔴 Complex Full IL2CPP reflection, scene traversal

All examples target universal Unity types and work across any Unity IL2CPP game.

Guides

In-depth technical guides covering MDB’s internal architecture and design:

Guide Description
Architecture Full injection chain, initialization sequence, and component overview
Proxy DLL Injection How the version.dll proxy works — DLL search order, forwarding, loader lock safety
Class Injection MonoBehaviour fabrication — IL2CPP memory layouts, hooks, negative tokens

Get Started

Ready to start modding? Head to the Getting Started guide to:

  1. Prepare your environment
  2. Deploy MDB to a Unity game (proxy or direct injection)
  3. Create and load your first mod
  4. Learn the mod lifecycle and APIs

Disclaimer

This framework is provided “as-is” for educational and research purposes only.

See the full Disclaimer for important legal information.

Acknowledgments

MDB Framework builds upon the excellent work of:

Full Disclaimer

The author(s) of MDB Framework are not responsible for any consequences resulting from the use or misuse of this software. This includes but is not limited to:

Before using MDB Framework:

  1. Read the game’s Terms of Service - Respect the rules
  2. Never use in online/multiplayer - This ruins experiences for others
  3. Use only for single-player - Or games that explicitly allow modding
  4. Understand the risks - You are solely responsible

By using this framework, you acknowledge that you understand these risks and agree to use it responsibly and ethically.