Getting Started with MDB Framework

This guide will walk you through installing MDB Framework and creating your first mod for a Unity IL2CPP game.

---

Table of Contents

1. Prerequisites
2. Building MDB Framework
3. Deploying to a Game
4. Creating Your First Mod
5. Testing Your Mod
6. Next Steps

---

Prerequisites

Before you begin, ensure you have:

• Windows 10/11 (x64) - MDB is Windows-only
• Visual Studio 2022 with:
  • C++ desktop development workload (for MDB_Bridge)
  • .NET desktop development workload (for MDB_Core and mods)
• MSBuild - Installed with Visual Studio
• .NET Framework 4.7.2 SDK or higher
• A Unity IL2CPP game (x64)
• DLL injector - Such as Extreme Injector

Supported Games

MDB works with any Unity game using IL2CPP runtime (x64 only). To check if a game uses IL2CPP:

1. Navigate to <GameFolder>/GameName_Data/
2. Look for GameAssembly.dll - This indicates IL2CPP
3. Look for global-metadata.dat - Additional confirmation

If you see mono.dll instead, the game uses Mono runtime and MDB won’t work.

---

Building MDB Framework

1. Clone the Repository

git clone https://github.com/Zaclin-GIT/MDB.git
cd MDB

2. Build MDB_Bridge (C++ Component)

The bridge is the native DLL that gets injected into the game.

cd MDB_Bridge
msbuild MDB_Bridge.vcxproj /p:Configuration=Release /p:Platform=x64

Output: MDB_Bridge/x64/Release/MDB_Bridge.dll

Note: MDB_Bridge depends on vcpkg packages (MinHook, Dear ImGui). The build process will automatically restore these dependencies.

3. Build MDB_Core (C# Component)

The core contains the modding SDK and runtime.

cd ../MDB_Core
dotnet build MDB_Core.csproj -c Release

Output: MDB_Core/bin/Release/net48/MDB_Core.dll

Note: MDB_Core is normally built automatically by the bridge at runtime. Manual building is only needed for development.

---

Deploying to a Game

Directory Structure

MDB requires a specific folder layout in your game directory:

<GameFolder>/
├── GameName.exe
├── MDB_Bridge.dll          ← Place the built bridge DLL here
├── MDB/
│   ├── Logs/               ← Auto-created for logs
│   ├── Managed/            ← Auto-created for SDK
│   └── Mods/
└── MDB_Core                ← Place the core project here

Setup Steps

1. Copy MDB_Bridge.dll to the game’s root folder (where the .exe is)

2. Copy MDB_Core folder from the repository to the game folder:

   xcopy /E /I MDB_Core <GameFolder>\MDB_Core
   

First Launch

1. Inject MDB_Bridge.dll using your DLL injector of choice
   • Target process: GameName.exe
   • DLL to inject: <GameFolder>/MDB_Bridge.dll
2. Wait for initialization - First launch takes 30-60 seconds:
   • Dumps IL2CPP metadata
   • Generates C# wrappers (~10,000+ files)
   • Compiles GameSDK.ModHost.dll via MSBuild
   • Loads any mods from MDB/Mods/
3. Check the logs:
   • MDB/Logs/MDB.log - Framework initialization and errors
   • MDB/Logs/Mods.log - Mod loading and output

Subsequent Launches

After the first successful injection, subsequent launches are instant. The framework detects that nothing has changed and skips the dump/build phase.

To force a full rebuild, delete MDB/Managed/GameSDK.ModHost.dll & all of the generated files in MDB_Core/Managed/.

---

Creating Your First Mod

Now that MDB is installed, let’s create a simple mod.

1. Clone the Mod Skeleton

MDB provides a skeleton project you can clone to get started quickly:

git clone -b mdbmod https://github.com/Zaclin-GIT/MDB.Templates.git MyFirstMod

This gives you a ready-to-build project with:

• A .csproj targeting .NET Framework 4.8.1
• A Mod.cs entry point with lifecycle methods
• An ImGuiWindow.cs with a starter UI window

2. Add the SDK

The SDK (GameSDK.MDBUnityStandard.dll) is generated on first injection. You must inject MDB into the game at least once before you can build mods.

Once the SDK has been generated, copy it into the mod project’s folder

3. Build Your Mod

cd MyFirstMod
dotnet build -c Release

Output: bin\Release\net481\MyFirstMod.dll

4. Deploy Your Mod

Copy the built DLL to the game’s mod folder

---

Next Steps

Congratulations! You’ve created and loaded your first MDB mod. Here’s what to explore next:

Learn the APIs

• Mod Lifecycle - Understanding OnLoad, OnUpdate, and other callbacks
• Logger System - Advanced logging features
• ImGui UI - Creating complex user interfaces

Explore Examples

• HelloWorld - Simple mod with ImGui
• UnityDebugInterceptor - Method patching basics
• GameStats - Advanced patching and IL2CPP Bridge
• MDB_Explorer_ImGui - Full-featured runtime inspector

Advanced Topics

• Patch Attributes - Declarative method hooking (recommended approach)
• HookManager - Advanced fallback for dynamic runtime hook management
• IL2CPP Bridge - Direct IL2CPP runtime access

---

Troubleshooting

MDB_Bridge.dll fails to inject

• Ensure the game is x64 (not 32-bit)
• Try running the game and injector as administrator
• Check if anti-cheat is blocking injection

Build fails: SDK not found

• You must inject MDB once to generate the SDK
• Copy GameSDK.MDBUnityStandard.dll from <GameFolder>/MDB/Managed/ into your project’s deps/ folder
• Verify the HintPath in your .csproj points to deps\GameSDK.MDBUnityStandard.dll

Mod doesn’t load

• Check MDB/Logs/Mods.log for errors
• Ensure the DLL is in MDB/Mods/ folder
• Verify your mod class has the [Mod] attribute
• Ensure your mod inherits from ModBase

ImGui window doesn’t appear

• Press F2 to toggle input capture (enabled by default)
• Verify RegisterCallback was called in OnLoad

Game crashes on injection

• Check MDB/Logs/MDB.log for errors
• Ensure MDB_Core folder is present and complete
• Try deleting MDB/Managed/ and regenerating
• Some games may not be compatible

---

Getting Help

If you’re still stuck:

1. Look at the Example Mods
2. Browse the API Reference
3. Open an issue on GitHub

---

← Back to Home

API Reference →