BepInEx

Unity / XNA Game Patcher and Plugin Framework

BepInEx (Bepis Injector Extensible) is a plugin / modding framework for Unity Mono, IL2CPP and .NET framework games (XNA, FNA, MonoGame, etc.)

Introduction

Bepis Injector Extensible is a patcher/plug-in framework for Unity games that use C#/Mono as their scripting backend. BepInEx (short for “Bepis Plugin Framework Extended”) is a popular open-source modding framework primarily used in the context of video games.

It is widely employed in games built on the Unity game engine to enable modders to create and manage plugins that enhance gameplay, add new features, or modify existing elements. BepInEx provides a robust and flexible environment for modding, and its features can vary slightly depending on the specific game and version being modded.

Features

BepInEx provides a robust and flexible environment for modding, and its features can vary slightly depending on the specific game and version being modded. However, I’ll cover the general features that are commonly associated with BepInEx:

  1. Plugin Loading and Management: It allows you to load and manage plugins (also known as mods) at runtime. Plugins are written in C# and compiled into .dll files. These plugins can be placed in designated folders within the game’s directory, and BepInEx will automatically load and initialize them when the game starts.
  2. Dependency Injection: It uses a dependency injection system to manage plugin dependencies and provide services to plugins. This enables modders to easily access game-related services and components without having to worry about complex initialization processes.
  3. Configuration System: It includes a configuration system that allows modders to define and expose customizable settings for their plugins. Users can modify these settings through configuration files generated by BepInEx. This system helps modders and users tailor the mod’s behavior without needing to modify the source code.
  4. Logging and Debugging: It provides a logging system that allows modders to output messages, warnings, and errors to the game’s log files. This is especially useful for debugging and troubleshooting plugin behavior.
  5. Hooks and Patches: It supports hooking into the game’s methods and events, allowing modders to intercept and modify game behavior. This enables them to add new functionality, fix bugs, or alter existing game mechanics.
  6. Asset Injection: It supports injecting custom assets, such as textures, models, and sounds, into the game. This allows modders to introduce new visual and audio elements to enhance the gaming experience.
  7. Unity Debug Console: It includes a Unity debug console that modders can use to interact with the game in real-time. This console facilitates testing and debugging by providing a way to execute commands and scripts without restarting the game.
  8. Version Compatibility: It often provides updates to maintain compatibility with different game versions. This ensures that mods created with BepInEx can continue to work even as the game receives updates or patches.
  9. Community Support: It has an active modding community that provides resources, tutorials, and assistance to modders. This community collaboration helps modders learn and share their creations effectively.
  10. Extensibility: BepInEx is designed to be extensible, allowing for the addition of new features through its plugin framework. This means that as the framework evolves, more features can be integrated to enhance the modding experience.

Download BepInEx

File NameBepInEx
Latest Release5.4.21 [Latest]
File Size650 Kb
Supported OSWindows OS (both x86 and x64 are supported), Linux, macOS 10.13 High Sierra or newer
Supported Unity gamesUnity 3 or newer
Developer Bepis and other
Last UpdateAug 17, 2023

Download one of the following versions:

  • x86 for games with 32-bit executablesDownload
  • x64 for games with 64-bit executablesDownload
  • For Linux – Download

How to Install BepInEx ?

  1. Download any of above related version of BepInEx
  2. Extract the contents into the game root.
  3. After you have downloaded the correct game version, extract the contents of the archive into the game folder.
  4. The game root folder is where the game executable is located.
  5. Do a first run to generate configuration files
    • Simply run the game executable. This should generate BepInEx configuration file into BepInEx/config folder and an initial log file BepInEx/LogOutput.txt.
    • Configure to suit your needs. Open BepInEx/config/BepInEx.cfg in a text editor of your choice. All options are documented directly in the configuration file.
BepInEx download

Getting started with BepInEx

Here is comprehensive overview of various terms and concepts related to BepInEx to help you transition from a beginner to an expert modder. This information will help you understand the core concepts and terminology.

  1. Modding: Modding refers to the practice of creating and adding modifications (mods) to a video game to alter its gameplay, features, visuals, or other aspects.
  2. Plugin: A plugin is a piece of code (usually compiled into a .dll file) that adds or changes functionality within the game. BepInEx allows you to create and manage plugins.
  3. Dependency Injection: Dependency injection is a design pattern used in BepInEx to provide plugins with access to game services and components without needing to instantiate them explicitly.
  4. Configuration: Configuration refers to customizable settings exposed by mods. BepInEx’s configuration system lets you define and manage these settings so that users can adjust mod behavior.
  5. Logger: A logger is a tool provided by BepInEx that allows you to output messages, warnings, and errors to log files for debugging and troubleshooting.
  6. Hooks and Patches: Hooks and patches refer to the process of intercepting and modifying game functions and events. BepInEx lets you hook into these parts of the game to alter behavior.
  7. Asset Injection: Asset injection involves adding custom assets (like textures, models, or sounds) to the game. BepInEx lets you inject these assets to enhance visuals and audio.
  8. Unity Debug Console: This is a console provided by BepInEx that lets you interact with the game in real-time, allowing you to execute commands and scripts for testing and debugging.
  9. Mod Loader: BepInEx functions as a mod loader, which means it loads and manages mods during the game’s runtime.
  10. Harmony: Harmony is a library used by BepInEx for hooking into and patching game methods. It provides a way to modify game behavior without directly altering the game’s source code.
  11. Assembly-CSharp.dll: This is the main game assembly that contains the game’s code. BepInEx often uses Harmony to modify methods within this assembly.
  12. Patch: A patch is a piece of code that modifies or extends the behavior of existing game methods.
  13. Preloader: The BepInEx preloader is responsible for initializing BepInEx and setting up the modding environment before the game starts.
  14. Plugin Folder: This is a designated directory where you place your compiled plugin (.dll) files for BepInEx to load.
  15. BepInEx Configuration Files: BepInEx generates configuration files where you can define settings for your mods. These files can be edited to customize mod behavior.
  16. BepInEx Configuration Manager: This is a tool that lets you manage and edit configuration files more conveniently.
  17. Attributes: Attributes are used in BepInEx to mark methods, classes, or fields as special, indicating how they should be treated by BepInEx.
  18. Patching Process: This refers to the steps involved in modifying and extending game behavior using hooks and patches.
  19. Event Handler: An event handler is a method or function that responds to specific events triggered within the game. BepInEx allows you to create event handlers in your plugins.
  20. Mod Compatibility: Ensuring your mods work well together without conflicts or unexpected behavior is essential for a smooth gaming experience.

Remember that while BepInEx provides powerful tools for modding, becoming an expert involves practice, learning from others in the modding community, and exploring the specific documentation and resources related to the game you are modding. The terms mentioned here provide a solid foundation to build upon as you delve deeper into the world of BepInEx and modding.

Getting started with BepInEx can be an exciting journey into the world of modding. Here’s a step-by-step guide to help you begin your adventure:

  1. Select a Game: First, choose a game that is compatible with BepInEx. Typically, BepInEx is used with games built on the Unity engine. Research and find out if the game you’re interested in supports BepInEx modding.
  2. Download BepInEx
  3. Backup Your Game: Before you start modding, it’s a good practice to create a backup of your game files. This ensures that you can restore your game to its original state if anything goes wrong.
  4. Install BepInEx: Follow the installation instructions provided on our site.
  5. Launch the Game with BepInEx: Run the game executable with BepInEx. If everything is set up correctly, you should see BepInEx-related messages in the game’s console window. This confirms that BepInEx is properly loaded.
  6. Create a Basic Plugin: Start small by creating a basic plugin to understand the process. To create a plugin, you’ll need some knowledge of C# programming. Here’s a simple example:
    • Create a new folder named “plugins” inside your game’s BepInEx folder.
    • Inside the “plugins” folder, create a new subfolder for your plugin (e.g., “MyFirstPlugin”).
    • Inside your plugin’s folder, create a C# script file (e.g., “MyPlugin.cs”).
      using BepInEx;
      using UnityEngine;

      [BepInPlugin("com.yourname.myplugin", "My First Plugin", "1.0.0")] public class MyPlugin : BaseUnityPlugin
      {
      void Awake()
      {
      Logger.LogInfo("Hello from MyPlugin!");
      }
      }
  7. Compile and Place Your Plugin: Compile your C# script using a C# compiler (like Visual Studio or Visual Studio Code). Once compiled into a .dll file, place it in the “plugins” folder you created earlier.
  8. Launch the Game Again: Run the game with BepInEx once more. If your plugin is set up correctly, you should see your log message in the game’s console.
  9. Explore Documentation and Resources: Dive into the official BepInEx documentation and community resources. These resources provide in-depth guides, tutorials, and examples that can help you create more advanced plugins and understand BepInEx’s features.
  10. Experiment and Learn: The best way to become an expert with BepInEx is through experimentation and practice. Try creating more complex plugins, exploring hooks and patches, and diving deeper into the modding community. Be prepared for trial and error, and don’t hesitate to ask questions on modding forums or community platforms.

FAQs