Skip to content

BepInEx v5.0
Compare
Choose a tag to compare
@bbepis bbepis released this 12 Nov 16:22
· 858 commits to master since this release
v5.0
cb78681
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

BepInEx 5 changelog

This is a changelog between BepInEx 4 and BepInEx 5

Changes that affect users

BREAKING CHANGES

These changes break compatibility with BepInEx 4.
In order to use BepInEx 4 plugins, wait for the plugin developer to update it!
Alternatively, use BepInEx.BepInEx4Upgrader that will attempt to automatically upgrade the plugins.

  • Overhauled folder layout
    • All plugins now reside in BepInEx/plugins and its subdirectories
    • Plugins inside BepInEx folder are not loaded anymore
  • Overhauled configuration files
    • Every plugin now has its own configuration file
    • All configuration files reside in BepInEx/config
    • Configuration files now have .cfg extensions and follow TOML-like format
    • All configuration options are also documented much better
  • Updated Harmony from 1.2 to 2.0
    • Plugins that rely on older version will not work

Features

  • Added support for Unity 2017+ games
    • Correct entrypoint is picked automatically, as long as you delete the config file on the first run
  • New console logging system to make reading messages easier
  • BepInEx logs are now also duplicated into BepInEx/LogOutput.log.<num> (can be turned off in the settings)
  • Added more descriptive information about the game, .NET API version it runs and what kind of runtime patching is supported (SRE/Harmony or Cecil/MonoMod)

Fixes

  • More descriptive error messages when a plugin cannot be loaded or why its loading is skipped
  • Log messages now include the source and are padded for more clarity
  • Preloader crashes no longer create empty crash logs
  • Running patcher plugins, and what assemblies they target are now specified in the log
  • Fixed some Unicode characters not being displayed correctly in the console

Changes that affect developers and advanced users

BREAKING CHANGES

Review the full new API listing on BepInEx API Docs.
You will have to update your plugins in order to work with BepInEx 5.

  • /plugins directory is now used to store plugins, use the Paths class to reference paths instead of hardcoding to alleviate this
    • All default assembly resolvers have been updated to recursively search the new directory
    • Plugins can now be put into subdirectories for better organization
  • /config directory is now used to store configuration, use the Paths class to reference paths instead of hardcoding to alleviate this
    • All configurations are now per-plugin
  • BaseUnityPlugin
    • Removed static Config and Logger classes and instead added Config and Logger properties to each plugin
  • BepInPlugin
    • Attribute information is much more strict, such as only allowing the regex [a-zA-Z0-9\._\-] in the GUID field
  • Logging has been completely redesigned, now split up into sources and listeners, similar to the System.Diagnostics.Trace class
    • BepInEx 4 API has been fully removed
  • Configuration system has been redesigned, now allowing for comments, value ranges and keyboard shortcuts
    • BepInEx 4 API has been either fully removed or obsoleted
  • Replaced Harmony 1.2 with 2.0
    • Causes big API changes, like Harmony.HarmonyInstance is now HarmonyLib.Harmony

Features

  • XML documentation is now shipped with all releases for IntelliSense support
  • Chainloader
    • Added PluginInfos property that lists all currently loaded BepInEx plugins by their GUID
    • In addition, old Plugins property is now deprecated in favour of PluginInfos
  • BaseUnityPlugin
    • Added Info property that contains all plugin metadata (GUID, version, dependencies, DLL location, etc)
  • BepInEx now finds plugins and preloader patches without load them into the game first
    • This is done using Cecil. As such, some type loaded API was changed or added.
    • You can now include non-plugin DLLs into the plugins folder without the fear of BepInEx forcing it to be loaded
    • In addition, only plugin types inside the assembly are resolved by BepInEx, reducing the chance of load exceptions
  • All plugins are now loaded deterministically by GUID
    • i.e. load order will not change if you put plugin assemblies into different folders
  • Added BepInEx.Harmony assembly that has features from the old modified Harmony 1.2
    • HarmonyWrapper.PatchAll(Type) now does what HarmonyInstance.PatchAll(Type) did in BepInEx 4
  • Better support for debugging with dnSpy
    • Ability to debug assemblies patched with preloader
    • (On Unity 2017+) Ability to break execution before patched assemblies are loaded
  • MonoMod's RuntimeDetour 19.11.05.01 is now shipped with BepInEx
    • Provides ability to apply runtime patches in cases where Harmony is not available (e.g. missing System.Reflection.Emit namespace)
    • BepInEx attempts to automatically patch Harmony to use RuntimeDetour when possible
  • BepInEx repository on GitHub now includes CakeBuild scripts for packaging and building
    • Refer to the building guide on how to build BepInEx from source with CakeBuild
  • Updated Mono.Cecil to 0.10.4
  • Updated Doorstop to 2.12.0.0

Fixes

  • Fixed Unity not allowing to read the game's output to stdout in some games (e.g. Rust Dedicated Server)
  • Assembly.Location and Assembly.Codebase now work with assemblies modified by preloader patchers
  • Implemented better caching for configuration values

Changes between 5.0-RC1 and 5.0

If you use RC1, the following important changes have been made:

  • Mono.Cecil, Doorstop and MonoMod have been updated to latest verions (see above changelogs)
  • ConfigFile.Wrap has been obsoleted and replaced with ConfigFile.Bind
  • Configuration system now includes support for value ranges and keyboard shortcuts, see changelogs above
  • Preloader logs are now being written to output_log.txt again
  • (Unity 2017+) BepInEx will try to automatically patch Harmony to use RuntimeDetour instead whenever System.Reflection.Emit is not available
  • Added caching for plugin loading, see changelogs above
  • Added BaseUnityPlugin.PluginInfo and Chainloader.PluginInfos properties, see changelogs above
  • Made plugin load order deterministic by GUID, see changelogs above
  • Unity 2017+ and legacy builds have been merged into one binary

For other minor features and fixes refer to the changelog above.

Other

We now have a Discord server! Feel free to join and ask about your problems.

Special thanks to Horse, ManlyMarco and Keelhauled for doing a significant amount of work for this release.
Thanks to the Risk of Rain 2 modding team as well, for doing beta-testing of this release.
This could not have been done without you guys.

Assets 4