1. 这不是“插件加载器”而是Unity游戏修改的底层操作系统你有没有试过想改一改《Risk of Rain 2》里某个角色的初始血量或者给《Valheim》加个无限耐力开关结果点开游戏目录只看到一堆.dll和.exe完全不知道从哪下手我第一次遇到这种需求时也是在Steam社区翻了两小时帖子最后靠一个叫“BepInEx”的压缩包解压到游戏根目录双击BepInExPack.exe——然后游戏就启动了控制台窗口里刷出一串绿色日志写着“Loaded plugin: HealthTweaker v1.0”。那一刻我才意识到原来我们一直缺的不是功能而是一套能让普通玩家真正“接管”Unity游戏运行时的基础设施。BepInEx不是传统意义上的“MOD加载器”它更像Unity游戏世界的BIOS驱动框架应用商店三合一。它不依赖游戏开发者预留的MOD接口比如《RimWorld》的XML配置或《Stardew Valley》的SMAPI而是通过IL织入IL weaving和运行时程序集重定向Assembly Redirection在Unity引擎加载C#脚本的瞬间把你的自定义逻辑“缝”进游戏主流程里。这意味着哪怕是一款完全没考虑MOD支持的Unity单机游戏只要它用的是标准Unity Mono/.NET Runtime绝大多数2018年后的Unity游戏都符合BepInEx就能工作。它解决的核心问题从来不是“怎么加个新功能”而是“如何让非Unity工程师也能安全、稳定、可调试地干预一个黑盒游戏的内存状态与执行流”。这个指南里的“5步”不是流水线式的安装步骤而是构建一个可持续演进的修改环境所必须跨越的五个认知门槛从理解BepInEx在Unity生命周期中的锚定点到亲手写出第一行能真正改变游戏变量的C#代码从处理Unity版本碎片化带来的API断层到建立本地调试闭环再到最终把零散脚本封装成用户可一键启用的插件包。它面向的不是Unity开发者而是那些已经会用C#写控制台程序、能看懂Unity API文档、但从未接触过Unity底层Hook机制的中级技术爱好者。如果你刚学完C#基础语法建议先用《Oxide》或《SMAPI》这类高封装度框架练手但如果你已经能用Visual Studio调试Unity Editor的PlayerLoop那BepInEx就是你该跨过的下一道门——它不隐藏复杂性而是把复杂性变成可管理的模块。提示BepInEx本身不提供任何游戏功能它只提供“功能得以存在的土壤”。所有实际效果比如无敌、加速、透视都由你写的插件实现。这决定了它的学习曲线陡峭但回报极高一旦掌握你面对的不是某一款游戏而是整个Unity游戏生态的修改可能性。2. BepInEx的底层机制为什么它能在Unity黑盒里“动手术”要真正用好BepInEx必须先拆开它的外壳看清它如何在Unity引擎的缝隙中安营扎寨。很多人以为BepInEx只是“替换了一个dll”这是最大的误解。它的核心能力来自三层精密协作的机制每一层都针对Unity运行时的特定弱点设计。2.1 Unity启动链路的劫持点从GameAssembly.dll到BepInEx.dllUnity打包后的Windows游戏其主程序如RiskOfRain2.exe本质是一个轻量级启动器真正的游戏逻辑全部封装在GameAssembly.dllUnity 2018.3或Assembly-CSharp.dll旧版中。BepInEx的突破口正是这个DLL的加载过程。它不修改游戏主程序而是利用Windows的DLL搜索顺序劫持在游戏目录下放置一个名为winhttp.dll或wininet.dll取决于Unity版本的伪装DLL这个DLL内部嵌入了BepInEx的初始化代码。当Unity引擎尝试加载系统网络库时会优先加载同名的本地DLL从而触发BepInEx的入口函数。这个入口函数做的第一件事是定位并加载真正的GameAssembly.dll然后在它被Unity CLRCommon Language Runtime加载前用MonoMod.RuntimeDetour对其中的关键方法进行IL级重写。例如Unity的PlayerLoop主循环函数UpdateBepInEx会在其开头插入一段跳转指令指向自己注册的PreUpdate钩子在结尾插入另一段指向PostLateUpdate钩子。这就相当于在Unity引擎的心脏上接了两个监测探头所有游戏逻辑都在这两个探头之间运行。2.2 插件生命周期管理BaseUnityPlugin与[BepInPlugin]属性的真相当你创建一个继承自BaseUnityPlugin的类并打上[BepInPlugin(com.yourname.mod, Your Mod Name, 1.0.0)]特性时你并不是在“声明一个插件”而是在向BepInEx的插件管理器注册一个可执行的生命周期对象。这个对象的实例化、初始化、启用、禁用、卸载全部由BepInEx在Unity主线程中按严格顺序调度。关键在于BaseUnityPlugin的四个核心虚方法OnEnable()在插件被启用时调用此时Unity场景已加载UnityEngine.Object.FindObjectOfTypeT()可以安全使用。这是你注入Hook、初始化UI、读取配置的最佳时机。OnDisable()在插件被禁用时调用必须在此处清理所有Hook、注销事件监听、释放资源。漏掉这里会导致游戏崩溃或内存泄漏。OnDestroy()在插件对象被GC回收前调用极少使用仅用于极底层的资源释放。OnGUI()如果需要绘制IMGUI界面如调试面板在此方法中编写。注意它每帧调用性能敏感。[BepInPlugin]特性中的GUID第一个参数绝非随意字符串。它是插件的唯一身份标识BepInEx用它来在BepInEx/config/目录下生成对应的配置文件如com.yourname.mod.cfg管理插件间的依赖关系[BepInDependency(other.plugin.guid)]防止不同插件因GUID冲突导致加载失败2.3 IL织入如何让“修改游戏变量”变成一行代码最让新手震撼的功能——直接修改游戏内PlayerHealth.currentHealth——其背后是MonoMod的IL织入技术。假设游戏原始代码是public class PlayerHealth : MonoBehaviour { public float currentHealth 100f; private void Update() { if (currentHealth 0) Die(); } }你想把它改成“currentHealth永不小于100”传统做法是反编译、修改、再编译。BepInEx的做法是在运行时用MonoMod扫描PlayerHealth.Update方法的IL指令找到ldfld加载字段值和ble小于等于跳转指令的位置然后动态插入新的IL指令序列// 原始IL片段简化 ldarg.0 ldfld float32 PlayerHealth::currentHealth ldc.r4 0 ble IL_001a // 织入后在ble前插入 ldarg.0 ldc.r4 100 stfld float32 PlayerHealth::currentHealth这行stfld指令就是你C#代码中playerHealth.currentHealth 100f;的底层实现。BepInEx通过Harmony库一个更高级的补丁框架封装了这一过程让你只需写var harmony new Harmony(com.yourname.healthpatch); harmony.Patch( AccessTools.Method(typeof(PlayerHealth), Update), prefix: new HarmonyMethod(typeof(HealthPatcher), nameof(HealthPatcher.PreventDeath)) );而PreventDeath方法里你甚至可以用C#直接操作__instance即当前PlayerHealth对象的字段。这种能力让BepInEx超越了所有基于配置文件的MOD框架。注意IL织入是“运行时”行为每次游戏启动都会重新执行。这意味着你修改的代码不会写入硬盘游戏更新后无需重新打补丁——只要目标方法签名不变补丁依然有效。但这也意味着如果游戏更新时重构了PlayerHealth.Update你的补丁就会失效需要手动适配。3. 5步实操从零开始构建你的第一个可调试插件现在让我们把理论落地。以下5步是我为上百个BepInEx插件项目总结出的最小可行路径。每一步都包含“为什么必须这么做”和“不做会怎样”的硬核解释而非简单罗列命令。3.1 第一步精准匹配BepInEx版本与Unity引擎版本90%崩溃的根源BepInEx不是“向下兼容”的工具。它的每个大版本如5.x, 6.x都深度绑定特定范围的Unity引擎版本。例如BepInEx 5.4.x 支持 Unity 2018.4 - 2020.3BepInEx 6.0.x 支持 Unity 2021.1 - 2022.3BepInEx 6.2.x 开始支持 Unity 2023.1匹配错误的后果极其严重轻则插件加载失败、日志报Could not load file or assembly UnityEngine.CoreModule重则游戏启动瞬间崩溃连错误日志都不输出。这不是配置问题而是.NET运行时ABIApplication Binary Interface不兼容。实操步骤进入游戏安装目录找到UnityPlayer.dllWindows或UnityPlayer.dylibmacOS。右键属性 → “详细信息”选项卡 → 查看“产品版本”。例如《Valheim》v0.227.10对应Unity 2020.3.30f1。访问 BepInEx官方GitHub Releases页面 按Unity版本筛选。不要选最新版选该Unity版本范围内最新且标记为Stable的BepInEx。例如Unity 2020.3应选BepInEx_pack_5.4.2100而非5.4.2200后者可能为预发布版。下载ZIP包解压到游戏根目录与RiskOfRain2.exe同级。确保解压后目录结构为BepInEx/core/,BepInEx/plugins/,BepInEx/config/。踩坑实录我曾为《Phasmophobia》Unity 2020.3.31f1强行安装BepInEx 6.0结果游戏启动后黑屏3秒直接退出。查BepInEx/LogOutput.log发现关键错误Failed to resolve type UnityEngine.PlayerLoopSystem。回退到5.4.2100后问题消失。根本原因是BepInEx 6.0移除了对旧版PlayerLoop API的支持。3.2 第二步创建VS项目并配置引用避免“找不到UnityEngine”地狱BepInEx插件是标准的.NET Standard 2.1类库但它的引用必须严格指向游戏运行时的Unity DLL而非你本地安装的Unity编辑器DLL。否则编译通过运行时报TypeLoadException。正确配置流程在Visual Studio中新建项目 → “类库(.NET Standard)” → 命名如MyFirstMod。右键项目 → “编辑项目文件”将TargetFramework改为netstandard2.1。删除自动生成的Class1.cs添加新类MyFirstPlugin.cs。最关键的一步添加对游戏Unity DLL的引用进入游戏目录找到BepInEx/core/下的UnityEngine.dll、UnityEngine.CoreModule.dll等通常有10个。在VS中右键项目 → “添加” → “引用” → “浏览” → 选择这些DLL。重要勾选“复制本地”为False。这些DLL由BepInEx在运行时提供插件中只需引用不可打包。安装NuGet包BepInEx.BaseLibrary核心框架、BepInEx.Configuration配置管理、HarmonyX推荐替代原Harmony兼容性更好。项目文件.csproj应类似Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknetstandard2.1/TargetFramework /PropertyGroup ItemGroup PackageReference IncludeBepInEx.BaseLibrary Version5.4.2100 / PackageReference IncludeBepInEx.Configuration Version5.4.2100 / PackageReference IncludeHarmonyX Version2.8.0 / /ItemGroup ItemGroup Reference IncludeUnityEngine HintPath..\..\game\BepInEx\core\UnityEngine.dll/HintPath Privatefalse/Private /Reference /ItemGroup /Project3.3 第三步编写你的第一个“Hello World”插件验证环境是否正常不要一上来就写无敌或透视。先写一个能证明整个链路打通的最小插件using BepInEx; using BepInEx.Configuration; using BepInEx.Logging; using HarmonyLib; using UnityEngine; namespace MyFirstMod { [BepInPlugin(com.myfirstmod.hello, Hello World Mod, 1.0.0)] public class MyFirstPlugin : BaseUnityPlugin { private readonly Harmony _harmony new Harmony(com.myfirstmod.hello); public static new ManualLogSource Logger; public void Awake() { Logger base.Logger; Logger.LogInfo(Hello World Mod loaded!); // 注册一个简单的Update Hook每秒打印一次 _harmony.Patch( AccessTools.Method(typeof(GameObject), GetComponent), postfix: new HarmonyMethod(typeof(MyFirstPlugin), nameof(OnGetComponent)) ); } public static void OnGetComponent(GameObject __instance, ref Component __result) { // 每次调用GetComponent时检查是否是Player对象 if (__instance ! null __instance.name Player) { Debug.Log($[MyMod] GetComponent called on {__instance.name}); } } public void OnDestroy() { _harmony.UnpatchSelf(); // 必须卸载否则下次加载会冲突 } } }编译与测试编译项目生成MyFirstMod.dll。将DLL放入BepInEx/plugins/目录。启动游戏观察BepInEx/LogOutput.log。成功时你会看到[Info : MyFirstMod] Hello World Mod loaded! [Info : BepInEx] Patching method: GameObject.GetComponent如果没看到日志检查BepInEx/LogOutput.log顶部是否有Failed to load plugin错误。实测心得OnDestroy()中调用_harmony.UnpatchSelf()是强制要求。我曾漏掉这行导致第二次启动游戏时Harmony尝试对已被卸载的方法再次打补丁引发NullReferenceException。BepInEx日志只会显示Plugin failed to load根本看不出原因必须用VS附加到进程调试才能定位。3.4 第四步接入Visual Studio实时调试告别“改一行编译重启游戏”循环没有调试BepInEx开发就是盲人摸象。你需要让VS能直接附加到游戏进程设置断点查看__instance的实时字段值。配置步骤在VS中项目右键 → “属性” → “调试”选项卡。“启动”设置为“外部程序”路径指向你的游戏主程序如RiskOfRain2.exe。“工作目录”设为游戏根目录与BepInEx文件夹同级。“环境变量”添加BEPINEX_DEBUG1启用BepInEx调试模式。在MyFirstPlugin.Awake()第一行设置断点。按F5启动。VS会自动启动游戏并在断点处暂停。此时你可以在“即时窗口”中输入Debug.Log(Test)消息会输出到Unity控制台。查看Logger对象确认日志系统工作正常。展开__instance参数实时查看Player对象的所有字段如transform.position。关键技巧如果VS无法附加大概率是游戏启动太快。在游戏主程序前加一个批处理脚本debug_start.batecho off echo Waiting for debugger... pause start RiskOfRain2.exe然后在VS调试设置中启动程序改为这个BAT文件。按任意键后游戏才启动给你充足的附加时间。3.5 第五步封装为用户友好的插件包配置、图标、依赖声明一个成熟的插件不能只丢一个DLL。用户需要清晰的配置界面调整数值、开关功能图标显示在BepInEx控制台明确的依赖提示如“需先安装QModManager”添加配置在MyFirstPlugin类中声明一个ConfigEntrypublic ConfigEntrybool EnableHelloLog { get; private set; } public ConfigEntryfloat HealthMultiplier { get; private set; } public void Awake() { // ... 其他代码 EnableHelloLog Config.Bind(General, Enable Hello Log, true, 是否启用Hello World日志); HealthMultiplier Config.Bind(Player, Health Multiplier, 2.0f, 玩家生命值倍率); }编译后BepInEx/config/com.myfirstmod.hello.cfg会自动生成内容为INI格式用户可直接编辑。添加图标在项目中添加一个PNG图标文件如icon.png尺寸256x256右键属性 → “生成操作”设为Embedded Resource。在[BepInPlugin]特性后添加[BepInProcess(RiskOfRain2.exe)] // 指定目标进程名 [BepInPlugin(com.myfirstmod.hello, Hello World Mod, 1.0.0)] [BepInDependency(com.bepis.bepinex.configuration)] // 声明依赖 public class MyFirstPlugin : BaseUnityPlugin { // ... }BepInEx控制台会显示你的图标和描述。最终打包创建一个ZIP包含plugins/MyFirstMod.dllconfig/com.myfirstmod.hello.cfg可选提供默认配置README.md说明功能、配置项、已知问题用户解压到游戏目录即可使用。4. 高阶实战从“改血量”到“造世界”的能力跃迁当你熟练完成上述5步你就拥有了修改任何Unity游戏的“基本盘”。但真正的“神器”价值在于如何用这套能力解决更复杂的场景。以下是三个典型高阶案例展示BepInEx的扩展边界。4.1 案例一动态修改Unity UI文本绕过TextMeshPro限制很多游戏用TextMeshProTMP渲染UI其文本存储在TextMeshProUGUI.text字段但直接赋值常无效因为TMP有复杂的富文本解析缓存。正确做法是Hook TMP的SetAllDirty()方法// Hook TMP的刷新逻辑 var tmpType AccessTools.TypeByName(TMPro.TextMeshProUGUI); var setAllDirty AccessTools.Method(tmpType, SetAllDirty); _harmony.Patch( setAllDirty, postfix: new HarmonyMethod(typeof(TMPFixer), nameof(TMPFixer.OnSetAllDirty)) ); public static void OnSetAllDirty(TextMeshProUGUI __instance) { // 检查是否是主菜单标题 if (__instance.transform?.parent?.name MainMenuCanvas) { // 强制更新文本绕过缓存 __instance.SetText(MODDED: __instance.text); __instance.ForceMeshUpdate(); // 立即刷新 } }原理SetAllDirty()是TMP内部标记“需要重绘”的关键方法。在此处注入能确保在UI真正刷新前完成文本修改比单纯监听Update()可靠百倍。4.2 案例二跨插件通信与状态共享构建MOD生态系统多个插件常需共享数据如“无敌插件”需知道“伤害计算插件”的当前倍率。BepInEx提供BepInEx.PluginInfo和BepInEx.Bootstrap.Chainloader来实现// 在DamagePlugin中暴露公共API public static class DamageAPI { public static float CurrentDamageMultiplier { get; set; } 1.0f; } // 在InvincibilityPlugin中获取 var damagePlugin Chainloader.PluginInfos.FirstOrDefault(x x.Metadata.GUID com.yourname.damageplugin); if (damagePlugin?.Instance is DamagePlugin damageInst) { var multiplier DamageAPI.CurrentDamageMultiplier; }关键点Chainloader.PluginInfos是BepInEx维护的全局插件注册表。通过GUID查找可安全获取其他插件实例实现松耦合通信。4.3 案例三热重载插件开发时无需重启游戏BepInEx 6.x原生支持插件热重载。在BepInEx/config/BepInEx.cfg中启用[General] # 启用热重载 HotReloadEnabled true # 监控plugins目录变化 HotReloadWatchDirectory plugins然后在VS中项目右键 → “属性” → “生成” → “输出路径”设为..\..\game\BepInEx\plugins\。每次保存代码VS自动编译并覆盖DLLBepInEx检测到文件变化自动卸载旧插件、加载新插件。整个过程2秒开发效率提升5倍以上。我的终极经验BepInEx的威力不在于它能做什么而在于它强迫你深入理解Unity引擎的运行时结构。当你能清晰说出PlayerLoop中FixedUpdate和Update的执行顺序、MonoBehaviour的Awake/Start/Update生命周期与IL织入点的关系、UnityEngine.Object的GC回收机制如何影响Hook稳定性时你已经不是在“修改游戏”而是在和Unity引擎对话。这种能力会反向提升你作为Unity开发者的工程水平——毕竟能修好别人的黑盒自然也更能写出健壮的白盒。
BepInEx原理与实战：Unity游戏运行时修改指南
发布时间：2026/5/23 23:06:37
1. 这不是“插件加载器”而是Unity游戏修改的底层操作系统你有没有试过想改一改《Risk of Rain 2》里某个角色的初始血量或者给《Valheim》加个无限耐力开关结果点开游戏目录只看到一堆.dll和.exe完全不知道从哪下手我第一次遇到这种需求时也是在Steam社区翻了两小时帖子最后靠一个叫“BepInEx”的压缩包解压到游戏根目录双击BepInExPack.exe——然后游戏就启动了控制台窗口里刷出一串绿色日志写着“Loaded plugin: HealthTweaker v1.0”。那一刻我才意识到原来我们一直缺的不是功能而是一套能让普通玩家真正“接管”Unity游戏运行时的基础设施。BepInEx不是传统意义上的“MOD加载器”它更像Unity游戏世界的BIOS驱动框架应用商店三合一。它不依赖游戏开发者预留的MOD接口比如《RimWorld》的XML配置或《Stardew Valley》的SMAPI而是通过IL织入IL weaving和运行时程序集重定向Assembly Redirection在Unity引擎加载C#脚本的瞬间把你的自定义逻辑“缝”进游戏主流程里。这意味着哪怕是一款完全没考虑MOD支持的Unity单机游戏只要它用的是标准Unity Mono/.NET Runtime绝大多数2018年后的Unity游戏都符合BepInEx就能工作。它解决的核心问题从来不是“怎么加个新功能”而是“如何让非Unity工程师也能安全、稳定、可调试地干预一个黑盒游戏的内存状态与执行流”。这个指南里的“5步”不是流水线式的安装步骤而是构建一个可持续演进的修改环境所必须跨越的五个认知门槛从理解BepInEx在Unity生命周期中的锚定点到亲手写出第一行能真正改变游戏变量的C#代码从处理Unity版本碎片化带来的API断层到建立本地调试闭环再到最终把零散脚本封装成用户可一键启用的插件包。它面向的不是Unity开发者而是那些已经会用C#写控制台程序、能看懂Unity API文档、但从未接触过Unity底层Hook机制的中级技术爱好者。如果你刚学完C#基础语法建议先用《Oxide》或《SMAPI》这类高封装度框架练手但如果你已经能用Visual Studio调试Unity Editor的PlayerLoop那BepInEx就是你该跨过的下一道门——它不隐藏复杂性而是把复杂性变成可管理的模块。提示BepInEx本身不提供任何游戏功能它只提供“功能得以存在的土壤”。所有实际效果比如无敌、加速、透视都由你写的插件实现。这决定了它的学习曲线陡峭但回报极高一旦掌握你面对的不是某一款游戏而是整个Unity游戏生态的修改可能性。2. BepInEx的底层机制为什么它能在Unity黑盒里“动手术”要真正用好BepInEx必须先拆开它的外壳看清它如何在Unity引擎的缝隙中安营扎寨。很多人以为BepInEx只是“替换了一个dll”这是最大的误解。它的核心能力来自三层精密协作的机制每一层都针对Unity运行时的特定弱点设计。2.1 Unity启动链路的劫持点从GameAssembly.dll到BepInEx.dllUnity打包后的Windows游戏其主程序如RiskOfRain2.exe本质是一个轻量级启动器真正的游戏逻辑全部封装在GameAssembly.dllUnity 2018.3或Assembly-CSharp.dll旧版中。BepInEx的突破口正是这个DLL的加载过程。它不修改游戏主程序而是利用Windows的DLL搜索顺序劫持在游戏目录下放置一个名为winhttp.dll或wininet.dll取决于Unity版本的伪装DLL这个DLL内部嵌入了BepInEx的初始化代码。当Unity引擎尝试加载系统网络库时会优先加载同名的本地DLL从而触发BepInEx的入口函数。这个入口函数做的第一件事是定位并加载真正的GameAssembly.dll然后在它被Unity CLRCommon Language Runtime加载前用MonoMod.RuntimeDetour对其中的关键方法进行IL级重写。例如Unity的PlayerLoop主循环函数UpdateBepInEx会在其开头插入一段跳转指令指向自己注册的PreUpdate钩子在结尾插入另一段指向PostLateUpdate钩子。这就相当于在Unity引擎的心脏上接了两个监测探头所有游戏逻辑都在这两个探头之间运行。2.2 插件生命周期管理BaseUnityPlugin与[BepInPlugin]属性的真相当你创建一个继承自BaseUnityPlugin的类并打上[BepInPlugin(com.yourname.mod, Your Mod Name, 1.0.0)]特性时你并不是在“声明一个插件”而是在向BepInEx的插件管理器注册一个可执行的生命周期对象。这个对象的实例化、初始化、启用、禁用、卸载全部由BepInEx在Unity主线程中按严格顺序调度。关键在于BaseUnityPlugin的四个核心虚方法OnEnable()在插件被启用时调用此时Unity场景已加载UnityEngine.Object.FindObjectOfTypeT()可以安全使用。这是你注入Hook、初始化UI、读取配置的最佳时机。OnDisable()在插件被禁用时调用必须在此处清理所有Hook、注销事件监听、释放资源。漏掉这里会导致游戏崩溃或内存泄漏。OnDestroy()在插件对象被GC回收前调用极少使用仅用于极底层的资源释放。OnGUI()如果需要绘制IMGUI界面如调试面板在此方法中编写。注意它每帧调用性能敏感。[BepInPlugin]特性中的GUID第一个参数绝非随意字符串。它是插件的唯一身份标识BepInEx用它来在BepInEx/config/目录下生成对应的配置文件如com.yourname.mod.cfg管理插件间的依赖关系[BepInDependency(other.plugin.guid)]防止不同插件因GUID冲突导致加载失败2.3 IL织入如何让“修改游戏变量”变成一行代码最让新手震撼的功能——直接修改游戏内PlayerHealth.currentHealth——其背后是MonoMod的IL织入技术。假设游戏原始代码是public class PlayerHealth : MonoBehaviour { public float currentHealth 100f; private void Update() { if (currentHealth 0) Die(); } }你想把它改成“currentHealth永不小于100”传统做法是反编译、修改、再编译。BepInEx的做法是在运行时用MonoMod扫描PlayerHealth.Update方法的IL指令找到ldfld加载字段值和ble小于等于跳转指令的位置然后动态插入新的IL指令序列// 原始IL片段简化 ldarg.0 ldfld float32 PlayerHealth::currentHealth ldc.r4 0 ble IL_001a // 织入后在ble前插入 ldarg.0 ldc.r4 100 stfld float32 PlayerHealth::currentHealth这行stfld指令就是你C#代码中playerHealth.currentHealth 100f;的底层实现。BepInEx通过Harmony库一个更高级的补丁框架封装了这一过程让你只需写var harmony new Harmony(com.yourname.healthpatch); harmony.Patch( AccessTools.Method(typeof(PlayerHealth), Update), prefix: new HarmonyMethod(typeof(HealthPatcher), nameof(HealthPatcher.PreventDeath)) );而PreventDeath方法里你甚至可以用C#直接操作__instance即当前PlayerHealth对象的字段。这种能力让BepInEx超越了所有基于配置文件的MOD框架。注意IL织入是“运行时”行为每次游戏启动都会重新执行。这意味着你修改的代码不会写入硬盘游戏更新后无需重新打补丁——只要目标方法签名不变补丁依然有效。但这也意味着如果游戏更新时重构了PlayerHealth.Update你的补丁就会失效需要手动适配。3. 5步实操从零开始构建你的第一个可调试插件现在让我们把理论落地。以下5步是我为上百个BepInEx插件项目总结出的最小可行路径。每一步都包含“为什么必须这么做”和“不做会怎样”的硬核解释而非简单罗列命令。3.1 第一步精准匹配BepInEx版本与Unity引擎版本90%崩溃的根源BepInEx不是“向下兼容”的工具。它的每个大版本如5.x, 6.x都深度绑定特定范围的Unity引擎版本。例如BepInEx 5.4.x 支持 Unity 2018.4 - 2020.3BepInEx 6.0.x 支持 Unity 2021.1 - 2022.3BepInEx 6.2.x 开始支持 Unity 2023.1匹配错误的后果极其严重轻则插件加载失败、日志报Could not load file or assembly UnityEngine.CoreModule重则游戏启动瞬间崩溃连错误日志都不输出。这不是配置问题而是.NET运行时ABIApplication Binary Interface不兼容。实操步骤进入游戏安装目录找到UnityPlayer.dllWindows或UnityPlayer.dylibmacOS。右键属性 → “详细信息”选项卡 → 查看“产品版本”。例如《Valheim》v0.227.10对应Unity 2020.3.30f1。访问 BepInEx官方GitHub Releases页面 按Unity版本筛选。不要选最新版选该Unity版本范围内最新且标记为Stable的BepInEx。例如Unity 2020.3应选BepInEx_pack_5.4.2100而非5.4.2200后者可能为预发布版。下载ZIP包解压到游戏根目录与RiskOfRain2.exe同级。确保解压后目录结构为BepInEx/core/,BepInEx/plugins/,BepInEx/config/。踩坑实录我曾为《Phasmophobia》Unity 2020.3.31f1强行安装BepInEx 6.0结果游戏启动后黑屏3秒直接退出。查BepInEx/LogOutput.log发现关键错误Failed to resolve type UnityEngine.PlayerLoopSystem。回退到5.4.2100后问题消失。根本原因是BepInEx 6.0移除了对旧版PlayerLoop API的支持。3.2 第二步创建VS项目并配置引用避免“找不到UnityEngine”地狱BepInEx插件是标准的.NET Standard 2.1类库但它的引用必须严格指向游戏运行时的Unity DLL而非你本地安装的Unity编辑器DLL。否则编译通过运行时报TypeLoadException。正确配置流程在Visual Studio中新建项目 → “类库(.NET Standard)” → 命名如MyFirstMod。右键项目 → “编辑项目文件”将TargetFramework改为netstandard2.1。删除自动生成的Class1.cs添加新类MyFirstPlugin.cs。最关键的一步添加对游戏Unity DLL的引用进入游戏目录找到BepInEx/core/下的UnityEngine.dll、UnityEngine.CoreModule.dll等通常有10个。在VS中右键项目 → “添加” → “引用” → “浏览” → 选择这些DLL。重要勾选“复制本地”为False。这些DLL由BepInEx在运行时提供插件中只需引用不可打包。安装NuGet包BepInEx.BaseLibrary核心框架、BepInEx.Configuration配置管理、HarmonyX推荐替代原Harmony兼容性更好。项目文件.csproj应类似Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknetstandard2.1/TargetFramework /PropertyGroup ItemGroup PackageReference IncludeBepInEx.BaseLibrary Version5.4.2100 / PackageReference IncludeBepInEx.Configuration Version5.4.2100 / PackageReference IncludeHarmonyX Version2.8.0 / /ItemGroup ItemGroup Reference IncludeUnityEngine HintPath..\..\game\BepInEx\core\UnityEngine.dll/HintPath Privatefalse/Private /Reference /ItemGroup /Project3.3 第三步编写你的第一个“Hello World”插件验证环境是否正常不要一上来就写无敌或透视。先写一个能证明整个链路打通的最小插件using BepInEx; using BepInEx.Configuration; using BepInEx.Logging; using HarmonyLib; using UnityEngine; namespace MyFirstMod { [BepInPlugin(com.myfirstmod.hello, Hello World Mod, 1.0.0)] public class MyFirstPlugin : BaseUnityPlugin { private readonly Harmony _harmony new Harmony(com.myfirstmod.hello); public static new ManualLogSource Logger; public void Awake() { Logger base.Logger; Logger.LogInfo(Hello World Mod loaded!); // 注册一个简单的Update Hook每秒打印一次 _harmony.Patch( AccessTools.Method(typeof(GameObject), GetComponent), postfix: new HarmonyMethod(typeof(MyFirstPlugin), nameof(OnGetComponent)) ); } public static void OnGetComponent(GameObject __instance, ref Component __result) { // 每次调用GetComponent时检查是否是Player对象 if (__instance ! null __instance.name Player) { Debug.Log($[MyMod] GetComponent called on {__instance.name}); } } public void OnDestroy() { _harmony.UnpatchSelf(); // 必须卸载否则下次加载会冲突 } } }编译与测试编译项目生成MyFirstMod.dll。将DLL放入BepInEx/plugins/目录。启动游戏观察BepInEx/LogOutput.log。成功时你会看到[Info : MyFirstMod] Hello World Mod loaded! [Info : BepInEx] Patching method: GameObject.GetComponent如果没看到日志检查BepInEx/LogOutput.log顶部是否有Failed to load plugin错误。实测心得OnDestroy()中调用_harmony.UnpatchSelf()是强制要求。我曾漏掉这行导致第二次启动游戏时Harmony尝试对已被卸载的方法再次打补丁引发NullReferenceException。BepInEx日志只会显示Plugin failed to load根本看不出原因必须用VS附加到进程调试才能定位。3.4 第四步接入Visual Studio实时调试告别“改一行编译重启游戏”循环没有调试BepInEx开发就是盲人摸象。你需要让VS能直接附加到游戏进程设置断点查看__instance的实时字段值。配置步骤在VS中项目右键 → “属性” → “调试”选项卡。“启动”设置为“外部程序”路径指向你的游戏主程序如RiskOfRain2.exe。“工作目录”设为游戏根目录与BepInEx文件夹同级。“环境变量”添加BEPINEX_DEBUG1启用BepInEx调试模式。在MyFirstPlugin.Awake()第一行设置断点。按F5启动。VS会自动启动游戏并在断点处暂停。此时你可以在“即时窗口”中输入Debug.Log(Test)消息会输出到Unity控制台。查看Logger对象确认日志系统工作正常。展开__instance参数实时查看Player对象的所有字段如transform.position。关键技巧如果VS无法附加大概率是游戏启动太快。在游戏主程序前加一个批处理脚本debug_start.batecho off echo Waiting for debugger... pause start RiskOfRain2.exe然后在VS调试设置中启动程序改为这个BAT文件。按任意键后游戏才启动给你充足的附加时间。3.5 第五步封装为用户友好的插件包配置、图标、依赖声明一个成熟的插件不能只丢一个DLL。用户需要清晰的配置界面调整数值、开关功能图标显示在BepInEx控制台明确的依赖提示如“需先安装QModManager”添加配置在MyFirstPlugin类中声明一个ConfigEntrypublic ConfigEntrybool EnableHelloLog { get; private set; } public ConfigEntryfloat HealthMultiplier { get; private set; } public void Awake() { // ... 其他代码 EnableHelloLog Config.Bind(General, Enable Hello Log, true, 是否启用Hello World日志); HealthMultiplier Config.Bind(Player, Health Multiplier, 2.0f, 玩家生命值倍率); }编译后BepInEx/config/com.myfirstmod.hello.cfg会自动生成内容为INI格式用户可直接编辑。添加图标在项目中添加一个PNG图标文件如icon.png尺寸256x256右键属性 → “生成操作”设为Embedded Resource。在[BepInPlugin]特性后添加[BepInProcess(RiskOfRain2.exe)] // 指定目标进程名 [BepInPlugin(com.myfirstmod.hello, Hello World Mod, 1.0.0)] [BepInDependency(com.bepis.bepinex.configuration)] // 声明依赖 public class MyFirstPlugin : BaseUnityPlugin { // ... }BepInEx控制台会显示你的图标和描述。最终打包创建一个ZIP包含plugins/MyFirstMod.dllconfig/com.myfirstmod.hello.cfg可选提供默认配置README.md说明功能、配置项、已知问题用户解压到游戏目录即可使用。4. 高阶实战从“改血量”到“造世界”的能力跃迁当你熟练完成上述5步你就拥有了修改任何Unity游戏的“基本盘”。但真正的“神器”价值在于如何用这套能力解决更复杂的场景。以下是三个典型高阶案例展示BepInEx的扩展边界。4.1 案例一动态修改Unity UI文本绕过TextMeshPro限制很多游戏用TextMeshProTMP渲染UI其文本存储在TextMeshProUGUI.text字段但直接赋值常无效因为TMP有复杂的富文本解析缓存。正确做法是Hook TMP的SetAllDirty()方法// Hook TMP的刷新逻辑 var tmpType AccessTools.TypeByName(TMPro.TextMeshProUGUI); var setAllDirty AccessTools.Method(tmpType, SetAllDirty); _harmony.Patch( setAllDirty, postfix: new HarmonyMethod(typeof(TMPFixer), nameof(TMPFixer.OnSetAllDirty)) ); public static void OnSetAllDirty(TextMeshProUGUI __instance) { // 检查是否是主菜单标题 if (__instance.transform?.parent?.name MainMenuCanvas) { // 强制更新文本绕过缓存 __instance.SetText(MODDED: __instance.text); __instance.ForceMeshUpdate(); // 立即刷新 } }原理SetAllDirty()是TMP内部标记“需要重绘”的关键方法。在此处注入能确保在UI真正刷新前完成文本修改比单纯监听Update()可靠百倍。4.2 案例二跨插件通信与状态共享构建MOD生态系统多个插件常需共享数据如“无敌插件”需知道“伤害计算插件”的当前倍率。BepInEx提供BepInEx.PluginInfo和BepInEx.Bootstrap.Chainloader来实现// 在DamagePlugin中暴露公共API public static class DamageAPI { public static float CurrentDamageMultiplier { get; set; } 1.0f; } // 在InvincibilityPlugin中获取 var damagePlugin Chainloader.PluginInfos.FirstOrDefault(x x.Metadata.GUID com.yourname.damageplugin); if (damagePlugin?.Instance is DamagePlugin damageInst) { var multiplier DamageAPI.CurrentDamageMultiplier; }关键点Chainloader.PluginInfos是BepInEx维护的全局插件注册表。通过GUID查找可安全获取其他插件实例实现松耦合通信。4.3 案例三热重载插件开发时无需重启游戏BepInEx 6.x原生支持插件热重载。在BepInEx/config/BepInEx.cfg中启用[General] # 启用热重载 HotReloadEnabled true # 监控plugins目录变化 HotReloadWatchDirectory plugins然后在VS中项目右键 → “属性” → “生成” → “输出路径”设为..\..\game\BepInEx\plugins\。每次保存代码VS自动编译并覆盖DLLBepInEx检测到文件变化自动卸载旧插件、加载新插件。整个过程2秒开发效率提升5倍以上。我的终极经验BepInEx的威力不在于它能做什么而在于它强迫你深入理解Unity引擎的运行时结构。当你能清晰说出PlayerLoop中FixedUpdate和Update的执行顺序、MonoBehaviour的Awake/Start/Update生命周期与IL织入点的关系、UnityEngine.Object的GC回收机制如何影响Hook稳定性时你已经不是在“修改游戏”而是在和Unity引擎对话。这种能力会反向提升你作为Unity开发者的工程水平——毕竟能修好别人的黑盒自然也更能写出健壮的白盒。
