BepInEx Android Launcher

English | 简体中文 | 繁體中文 | Português (BR) | Русский | 日本語

Generic BepInEx Android launcher with modpack management for any Unity IL2CPP game.

Features

• One-tap BepInEx injection into Unity IL2CPP games
• Auto-detect installed Unity IL2CPP games
• Modpack management: create, import/export (.rhp/.zip), activate/deactivate mod combinations
• Per-game settings: floating log, unstripped libunity, Unity Kill blocking
• Built-in config file editor with JSON/Lua syntax highlighting
• Game log viewer with logcat integration
• Crash detection with diagnostic export
• Material You dynamic theming with Monet support
• Desktop shortcut creation
• 18 language support

Target

• Launcher package: com.bepinex.android.launcher
• ABI: arm64-v8a
• Min SDK: 28 (Android 9)

Credits

Projects Used & Referenced

• BepInEx — Unity IL2CPP modding framework, the core plugin loader
• FusionCore — Android Unity IL2CPP Runtime Container by Starlight team
• NextBep (BepInEx.Android) — Custom BepInEx fork for Android
• dotnet/runtime — .NET Runtime, built from source with OpenSSL crypto backend
• OpenSSL — OpenSSL 3.4.0, replacing BoringSSL for ARM64 Android crypto
• Pine — ART Java method hook framework
• Dobby — Native hook framework for ARM64
• Cpp2IL — IL2CPP reverse engineering tool

Lead Developers

HayashiUme · Gaoshu · NextBep

©2026 NextBep

Guide

• Documentation — Full usage guide
• Contributing — How to contribute to the project
• Translate — Help translate the launcher into your language
• Troubleshooting — Common issues and fixes

Build

There is a CI build in the GitHub Actions page.

Run from this directory:

.\gradlew.bat assembleDebug

The APK is written to:

app/build/outputs/apk/debug/app-debug.apk

Each build increments ci-version.txt and sets the APK version to:

0.0.1-ci.<number>

Install

For a clean test installation:

$adb = "C:\path\to\platform-tools\adb.exe"
$apk = "path\to\app-debug.apk"
& $adb uninstall com.bepinex.android.launcher
& $adb install $apk

Uninstalling removes launcher-private data and settings. It does not remove the external per-game data directories.

External Data

Runtime BepInEx data is stored per-game under:

/storage/emulated/0/BepInEx_Launcher/<game-package>/

Each game directory contains BepInEx/, plugins, configuration, logs, modpacks, and vanilla state.

Internal data (libunity cache, Unity version data) is stored under:

/data/user/0/com.bepinex.android.launcher/files/<game-package>/

Injection Model

The launcher injects BepInEx into the game process via native bootstrap libraries and Pine (Java method hooking framework):

1. createPackageContext() for the target game to obtain its class loader and DEX access.
2. Install Pine hooks: bidirectional ClassLoader, Instrumentation, PackageManager, native library, and UnityPlayer.
3. Redirect the game activity to a manifest-registered StubActivity via Instrumentation.execStartActivity hook.
4. Instrumentation.newActivity restores the real game activity class and original Intent.
5. Activity.attachBaseContext hook wraps the Context with a three-way GameContextWrapper:
   • Game resources (Assets, Resources, Theme) → game package context
   • File/storage (getFilesDir, SharedPreferences) → launcher Application
   • Window services (getDisplay, getSystemService) → original Activity base Context
6. ClassLoader.findLibrary() hook redirects native .so loading: game libs from game APK, BepInEx libs from launcher, .NET/il2cpp/unity libs from data directory.
7. UnityPlayer constructor hook sets the activity field.
8. UnityPlayer.kill() hook optionally blocks the first call for 5 seconds (per-game opt-in).

All hooks are installed from Kotlin/Java via Pine — with native libmain.so/libfusion.so controlling dlopen order and CoreCLR bootstrap.

Debug Snapshots

After a crash, the next launcher start saves diagnostics under:

/data/user/0/com.bepinex.android.launcher/files/debug/<timestamp>/

Snapshots include launcher logs, logcat, crash logcat, package/activity state, process exit information, and available BepInEx logs.