BepInEx：强大的 Unity 游戏插件框架

2025-12-01
福建
本文字数：3723 字
阅读完需：约 12 分钟

BepInEx：强大的 Unity 游戏插件框架

项目描述

BepInEx（Bepis Injector Extensible）是一个专业的 Unity 游戏插件/模组框架，支持 Unity Mono、IL2CPP 以及.NET 框架游戏（包括 XNA、FNA、MonoGame 等）。该项目提供了完整的插件加载系统、配置管理、日志记录和运行时修补功能，为游戏模组开发者提供稳定可靠的开发环境。

功能特性

🎯 多平台支持

Unity Mono: Windows、OSX、Linux 全面支持
Unity IL2CPP: Windows 和 Linux 支持
.NET 框架: 兼容 XNA、FNA、MonoGame 等框架

🔧 核心功能

插件自动加载: 自动发现和加载插件程序集
配置系统: 强大的配置文件管理，支持数据验证和事件通知
日志系统: 多源日志记录，支持控制台、文件和 Unity 日志输出
运行时修补: 基于 Harmony 的程序集修补功能
依赖管理: 完整的插件依赖关系解析

🛠 开发工具

插件元数据: 通过属性标记插件信息和依赖关系
类型转换器: 支持多种数据类型的序列化和反序列化
控制台管理: 跨平台控制台支持，包含颜色和编码处理
缓存系统: 程序集缓存加速加载过程

安装指南

系统要求

Windows 7+ / macOS 10.12+ / Linux (各主要发行版)
.NET Framework 4.0+ 或 .NET Core 3.1+
支持的 Unity 游戏

安装步骤

下载最新版本

   # 从GitHub Releases页面下载对应版本   https://github.com/BepInEx/BepInEx/releases

复制代码

     Game/     ├── BepInEx/     │   ├── core/          # 核心库     │   ├── plugins/       # 插件目录     │   └── config/        # 配置文件     ├── doorstop_config.ini     └── winhttp.dll        # Windows注入器

复制代码

验证安装
启动游戏，查看 BepInEx 控制台输出
检查BepInEx/LogOutput.log文件确认运行状态

使用说明

基础插件开发

using BepInEx;using BepInEx.Configuration;using BepInEx.Logging;using HarmonyLib;
[BepInPlugin("com.author.pluginname", "My Plugin", "1.0.0")][BepInProcess("game.exe")]public class MyPlugin : BasePlugin{    internal static ManualLogSource Logger;        private ConfigEntry<bool> ConfigExample;
    public override void Load()    {        Logger = Log;                // 配置绑定        ConfigExample = Config.Bind("General", "EnableFeature", true,             "是否启用特定功能");                // Harmony补丁        Harmony.CreateAndPatchAll(typeof(MyPatches));                Logger.LogInfo("插件加载完成！");    }        [HarmonyPatch(typeof(GameManager))]    class MyPatches    {        [HarmonyPostfix, HarmonyPatch("Start")]        static void PostfixStart()        {            Logger.LogInfo("游戏已启动！");        }    }}

复制代码

配置系统使用

// 创建配置项ConfigEntry<int> numberSetting = Config.Bind(    "Section",     "Key",     42,     new ConfigDescription("数值设置示例",         new AcceptableValueRange<int>(0, 100)));
// 监听配置变化numberSetting.SettingChanged += (sender, args) => {    Logger.LogInfo($"配置已更改: {numberSetting.Value}");};

复制代码

日志记录

// 不同级别的日志记录Log.LogDebug("调试信息");Log.LogInfo("普通信息");Log.LogWarning("警告信息");Log.LogError("错误信息");Log.LogFatal("严重错误");

复制代码

核心代码

插件加载系统

/// <summary>/// 链式加载器核心类，负责插件的发现、加载和初始化/// </summary>public abstract class BaseChainloader<TPlugin>{    protected static readonly string CurrentAssemblyName =         Assembly.GetExecutingAssembly().GetName().Name;        /// <summary>    /// 分析类型定义并转换为插件信息    /// </summary>    public static PluginInfo ToPluginInfo(TypeDefinition type, string assemblyLocation)    {        if (type.IsInterface || type.IsAbstract)            return null;
        try        {            if (!type.IsSubtypeOf(typeof(TPlugin)))                return null;        }        catch (AssemblyResolutionException)        {            return null;        }
        var metadata = BepInPlugin.FromCecilType(type);        if (metadata == null)        {            Logger.Log(LogLevel.Warning,                 $"跳过类型 [{type.FullName}]，未指定元数据属性");            return null;        }
        if (string.IsNullOrEmpty(metadata.GUID) ||             !allowedGuidRegex.IsMatch(metadata.GUID))        {            Logger.Log(LogLevel.Error,                 $"插件GUID无效: {metadata.GUID}");            return null;        }
        return new PluginInfo        {            Metadata = metadata,            Location = assemblyLocation,            TypeName = type.FullName        };    }}

复制代码

配置管理系统

/// <summary>/// 配置文件管理类，支持线程安全的配置操作/// </summary>public class ConfigFile : IDictionary<ConfigDefinition, ConfigEntryBase>{    private readonly BepInPlugin _ownerMetadata;    protected Dictionary<ConfigDefinition, ConfigEntryBase> Entries { get; } = new();        /// <summary>    /// 创建新的配置文件    /// </summary>    public ConfigFile(string configPath, bool saveOnInit, BepInPlugin ownerMetadata)    {        _ownerMetadata = ownerMetadata;        ConfigFilePath = Path.GetFullPath(configPath);
        if (File.Exists(ConfigFilePath))            Reload();        else if (saveOnInit)             Save();    }        /// <summary>    /// 绑定配置项    /// </summary>    public ConfigEntry<T> Bind<T>(string section, string key, T defaultValue,         ConfigDescription configDescription = null)    {        var definition = new ConfigDefinition(section, key);        var entry = new ConfigEntry<T>(this, definition, defaultValue,             configDescription ?? ConfigDescription.Empty);                Entries[definition] = entry;        return entry;    }}

复制代码

路径管理系统

/// <summary>/// BepInEx使用的路径管理静态类/// </summary>public static class Paths{    /// <summary>    /// BepInEx版本信息    /// </summary>    public static Version BepInExVersion { get; } =        Version.Parse(MetadataHelper.GetAttributes<AssemblyInformationalVersionAttribute>(            typeof(Paths).Assembly)[0].InformationalVersion);
    /// <summary>    /// 包含主要托管程序集的Managed文件夹路径    /// </summary>    public static string ManagedPath { get; private set; }
    /// <summary>    /// 当前运行的Unity游戏的游戏数据文件夹路径    /// </summary>    public static string GameDataPath { get; private set; }
    /// <summary>    /// 核心BepInEx DLL所在的目录    /// </summary>    public static string BepInExAssemblyDirectory { get; private set; }
    /// <summary>    /// 主要BepInEx文件夹的路径    /// </summary>    public static string BepInExRootPath { get; private set; }}

复制代码

日志系统架构

/// <summary>/// 手动日志源，提供简单的API来手动发出日志/// </summary>public class ManualLogSource : ILogSource{    private readonly string _sourceName;        public ManualLogSource(string sourceName)    {        _sourceName = sourceName;    }
    public string SourceName => _sourceName;    public event EventHandler<LogEventArgs> LogEvent;
    /// <summary>    /// 使用指定的日志级别记录消息    /// </summary>    public void Log(LogLevel level, object data) =>         LogEvent?.Invoke(this, new LogEventArgs(data, level, this));
    /// <summary>    /// 记录插值字符串消息    /// </summary>    public void Log(LogLevel level,        [InterpolatedStringHandlerArgument("level")]        BepInExLogInterpolatedStringHandler logHandler)    {        if (logHandler.Enabled)            LogEvent?.Invoke(this,                 new LogEventArgs(logHandler.ToString(), level, this));    }}

复制代码

BepInEx 框架通过这些核心组件提供了完整的插件开发解决方案，使得开发者可以专注于业务逻辑而不必担心底层基础设施的实现。更多精彩内容请关注我的个人公众号公众号（办公 AI 智能小助手）对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）

公众号二维码

办公AI智能小助手

公众号二维码

网络安全技术点滴分享

发布于: 刚刚阅读数: 5

qife122

关注

还未添加个人签名 2021-05-19 加入

还未添加个人简介

发布

暂无评论

创作场景

BepInEx：强大的 Unity 游戏插件框架

BepInEx：强大的 Unity 游戏插件框架

项目描述

功能特性

🎯 多平台支持

🔧 核心功能

🛠 开发工具

安装指南

系统要求

安装步骤

使用说明

基础插件开发

配置系统使用

日志记录

核心代码

插件加载系统

配置管理系统

路径管理系统

日志系统架构

qife122

评论