Skip to content

Releases: TheHolyOneZ/ZModManager

ZModManager v0.1.0

28 Mar 21:32
@TheHolyOneZ TheHolyOneZ
v0.1.0
b3fd420
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
ZModManager v0.1.0 Latest
Latest
ZModManager Logo

ZModManager

A modern, open-source mod manager and injector for Unity games

License: MIT
.NET
Platform
Runtime
Made by TheHolyOneZ

Inject Mono assemblies at runtime. Deploy IL2CPP mods to MelonLoader, BepInEx or your own bootstrap — all from one clean dark UI.

Table of Contents

Features

🎮 Game Management

  • Add unlimited game profiles
  • Auto-detect Unity Mono vs. IL2CPP (+ Unreal, Godot)
  • Per-game mod lists with enable/disable toggles
  • Bulk enable / disable all mods at once
  • Mod search & filter
  • Optional launch arguments per game
  • Open game folder directly from UI

💉 Injection Engine

  • Direct x64 shellcode injection for Mono games
  • Framework-mediated deployment for IL2CPP games
  • Wait-for-window gate (no more "too early" crashes)
  • Mono stabilization delay (waits for Assembly-CSharp)
  • Compatible with MelonLoader, BepInEx 6 and ZModBootstrap
  • Per-mod injection with individual success/fail results

🛡️ Smart Compatibility

  • Auto-detects mod framework from DLL metadata (no loading)
  • Warns when a mod targets the wrong framework (⚠ badge)
  • Auto-disables incompatible mods before launch
  • Three-phase framework status: Not Installed → Installing → Installed
  • Blocks mismatched deploy (MelonLoader mod on BepInEx, etc.)

⚙️ Framework Management

  • One-click install of MelonLoader or BepInEx 6 from GitHub
  • Detects existing installations automatically
  • Reinstall / uninstall without leaving the app
  • ZModBootstrap: custom version.dll proxy for earliest injection
  • Version badge after install

🖥️ Modern UI

  • Custom dark WPF theme (no system chrome)
  • Semi-transparent settings & about dialogs
  • Minimize to system tray after launch
  • Real-time injection log with copy button
  • Game-running indicator in title bar
  • DLL version tooltip on hover
  • Mod notes field

📦 Profile System

  • Export/import game profiles as JSON
  • Settings persisted in %AppData%\ZModManager\settings.json
  • Last selected game remembered across sessions
  • Window position & size saved
  • Per-session cancellable launch

How It Works

ZModManager routes mod loading through two completely different pipelines depending on the Unity build type it detects.

Mono Games — Direct Injection

User clicks Launch
       │
       ▼
  Game process starts
       │
       ▼
  Wait: OS process appears   (30 s timeout)
       │
       ▼
  Wait: game window ≥ 200×150 px   (120 s timeout)
  ← prevents "too early" Mono domain errors
       │
       ▼
  Wait: mono.dll loaded in process   (30 s timeout)
       │
       ▼
  Stabilise 4 s   ← waits for Assembly-CSharp to finish loading
       │
       ▼
  Inject each enabled mod via x64 shellcode

The shellcode chain executed inside the target process:

Step Mono API called
1 mono_get_root_domain()
2 mono_thread_attach(domain)
3 mono_domain_assembly_open(path)
4 mono_assembly_get_image()
5 mono_class_from_name(namespace, class)
6 mono_class_get_method_from_name(method, 0)
7 mono_runtime_invoke()

Export addresses are resolved by locally loading mono.dll, computing the offset against its base, then remapping to the remote base — no hardcoded addresses, works across Unity versions.

Note

ZModManager handles all three Mono DLL variants automatically: mono.dll, mono-2.0-bdwgc.dll and mono-2.0.dll.

IL2CPP Games — Framework-Mediated

IL2CPP games compile all managed code to native machine code — there is no Mono domain to inject into. Mods must be loaded by a native host framework before the game runs.

User clicks Launch
       │
       ▼
  Detect installed framework
  ┌────────────┬──────────────┬────────────────┐
  │ MelonLoader│   BepInEx 6  │ ZModBootstrap  │
  └─────┬──────┴──────┬───────┴───────┬────────┘
        ▼             ▼               ▼
  Copy mods to   Copy mods to   Write mods.cfg
  /Mods/         /BepInEx/      (config-driven)
                 plugins/
       │
       ▼
  Launch game — framework loads mods on startup

Important

For IL2CPP games you must have at least one framework installed. Use the Install buttons in the IL2CPP panel, or install MelonLoader / BepInEx manually first.

Mod sync is automatic: every time you click Launch, enabled mods are copied in and disabled mods are removed from the framework folder. What's in the folder always exactly matches your enabled list.

Supported Frameworks

Framework Detection Mod Folder Mod Type Install
MelonLoader MelonLoader/ directory <game>/Mods/ Managed .NET ✅ Auto
BepInEx 6 BepInEx/core/BepInEx*.dll <game>/BepInEx/plugins/ Managed .NET ✅ Auto
ZModBootstrap ZModManager/zmodmanager.marker Config-driven Native DLL only ✅ Auto

Tip

Which framework should I use?

  • Most IL2CPP mods target MelonLoader — install it unless you have a reason not to.
  • BepInEx 6 is the alternative; some mods target it instead.
  • ZModBootstrap is ZModManager's built-in fallback. Use it only for native (C++) mods when you have no other framework.

Getting Started

Requirements

Component Version
OS Windows 10 / 11 (x64)
.NET Desktop Runtime 8.0 or later
Games Unity (Mono or IL2CPP)
Privileges Administrator (required for CreateRemoteThread)

Caution

ZModManager allocates executable memory in remote processes and calls CreateRemoteThread. Run it as Administrator, otherwise injection will silently fail.

Installation

  1. Go to Releases and download the latest ZModManager.zip.
  2. Extract anywhere (no installer required).
  3. Run ZModManager.exe as Administrator.

Note

If Windows SmartScreen blocks the executable, click More info → Run anyway. ZModManager is not code-signed yet.

Quick Start

Adding your first game:

  1. Click + Add Game in the sidebar.
  2. Browse to your game's .exe file.
  3. ZModManager auto-detects whether it's a Mono or IL2CPP game.

Adding a mod (Mono game):

  1. Select your game profile.
  2. Click + Add Mod.
  3. Browse to the mod .dll.
  4. Set the Namespace, Class and Method (the parameterless static entry point).
  5. Click Save.

Adding a mod (IL2CPP game):

  1. If no framework is shown as installed, click Install MelonLoader or Install BepInEx.
  2. Click + Add Mod and browse to the mod .dll.
  3. ZModManager auto-detects whether it's a MelonLoader or BepInEx mod and warns you if it doesn't match.

Launching:

  • Click Launch — for Mono games this injects all enabled mods; for IL2CPP it deploys mods then starts the game.
  • Click ▷ No Mods to launch the game clean (removes all deployed mods first).

Tip

Enable Minimize to tray after launch in Settings (⚙) to keep ZModManager running in the background while you play. Double-click the tray icon to reopen it.

Building from Source

Prerequisites

Tool Purpose
Visual Studio 2022 C++ and C# build
Desktop development with C++ workload For ZModManager.Bootstrap
.NET 8.0 SDK For the main C# app
Windows 10 SDK For native Windows headers

Steps

1. Clone the repository

git clone https://github.com/TheHolyOneZ/ZModManager.git
cd ZModManager

2. Build the C++ Bootstrap DLL (required for ZModBootstrap support)

build_bootstrap.bat
# or manually:
msbuild ZModManager.sln /p:Configuration=Release /p:Platform=x64 /t:"ZModManager_Bootstrap:Rebuild"

This produces ZModManager/Resources/Bootstrap/version.dll which is embedded as a managed resource in the final executable.

Note

If you skip this step the app still builds and runs — ZModBootstrap install will be disabled with a user-friendly error. MelonLoader and BepInEx support is unaffected.

3. Build the C# application

dotnet build ZModManager/ZModManager.csproj --configuration Release
# Output: ZModManager/bin/Release/net8.0-windows/ZModManager.exe

Or open ZModManager.sln in Vis...

Read more
Assets 4
Loading