skill/modules/unity-bepinex.md

unity-bepinex

Unity games that need BepInEx (Mono vs IL2CPP detection, install, logs).

Identity

BepInEx is a plugin framework (loader), not a game. It injects into Unity (and some other .NET) games so plugin mods can run. Games that use it need it installed first as a dependency of every plugin.

Detect whether it is needed

List the game folder with list_dir.

• Mono build: <Game>_Data/Managed/ containing Assembly-CSharp.dll, and/or a MonoBleedingEdge/ folder -> BepInEx 5.x (Mono).
• IL2CPP build: GameAssembly.dll in the root and <Game>_Data/il2cpp_data/Metadata/global-metadata.dat -> the BepInEx IL2CPP build (6.x/bleeding-edge line). Mono plugins do not work on IL2CPP games and vice versa.
• If either is present, treat BepInEx as a likely dependency, then confirm on the mod page or the game's Thunderstore community.
• Match architecture: x64 vs x86 must match the game's .exe.

Mod folder and format

Extract BepInEx into the game root next to the game .exe (you should see winhttp.dll, doorstop_config.ini, BepInEx/). Launch once so it creates BepInEx/config/ and BepInEx/plugins/. Plugin DLLs (or each mod's folder) go in BepInEx/plugins/.

Sources

Thunderstore (r2modman / Thunderstore Mod Manager automate everything), Nexus, GitHub Releases. Get the exact BepInEx build for the game from the game's Thunderstore community or the BepInEx docs: verify with web_search.

Load order

None, apart from declared plugin dependencies.

Logs

BepInEx/LogOutput.log (enable the console in BepInEx/config/BepInEx.cfg if needed). Unity Player.log under AppData/LocalLow/<Company>/<Game>/.

Common failures

Wrong Mono/IL2CPP build, wrong architecture, missing plugin dependency, plugin built for another game version, game update breaking IL2CPP interop (delete BepInEx/cache/ and interop/ and relaunch). On Linux/Proton set WINEDLLOVERRIDES="winhttp=n,b".