1. 项目概述为什么选择BepInEx作为你的模组开发起点如果你玩过一些基于Unity引擎开发的PC游戏比如《雨中冒险2》、《星露谷物语》的某些大型模组或者《英灵神殿》的社区扩展你很可能已经间接接触过BepInEx了。它不是一个直接面向玩家的工具而是几乎所有现代Unity游戏模组Mod背后那个默默无闻的“基础设施”。简单来说BepInEx是一个功能强大的插件加载框架它允许开发者在游戏启动时将自己的代码“注入”到游戏进程中从而实现对游戏功能的修改、增强或创造。为什么是BepInEx而不是其他框架在我过去几年的模组开发经历里从早期的Assembly-CSharp.dll直接反编译修改到尝试各种加载器最终BepInEx以其稳定性、社区活跃度和对Unity不同后端Mono/IL2CPP的广泛支持成为了事实上的标准。它就像给游戏世界安装了一套标准的“水电管道”模组开发者只需要按照规范接入就能确保自己的功能在绝大多数玩家的机器上稳定运行而不用操心底层复杂的注入和兼容性问题。对于想入门模组开发的新手或者希望为自己喜爱的游戏增添新玩法的爱好者掌握BepInEx是迈出实质性第一步的关键。它能让你从“使用模组”跨越到“创造模组”真正参与到游戏社区的共建中。2. 核心概念与架构拆解BepInEx是如何工作的在动手安装和开发之前花点时间理解BepInEx的运作机制至关重要。这能帮你避免很多“为什么我的模组不生效”的困惑。BepInEx的核心工作流程可以概括为“拦截、加载、执行”三步。2.1 核心组件与启动流程BepInEx的架构是模块化的主要包含以下几个核心部分Doorstop这是一个独立的、非常轻量级的注入器在Windows上是winhttp.dllLinux上是libdoorstop.so。它的唯一任务是在游戏主程序启动的瞬间抢先一步被系统加载然后根据doorstop_config.ini的配置去加载BepInEx的核心预加载器。你可以把它想象成一把“万能钥匙”负责打开游戏进程的大门。Preloader预加载器这是BepInEx自己的核心启动模块。被Doorstop加载后预加载器会在Unity引擎自身初始化之前运行。它的职责是准备BepInEx的运行环境比如设置插件搜索路径、初始化日志系统、加载核心库等。这个阶段发生在游戏任何实质性内容加载之前为后续操作铺平道路。BepInEx Core核心框架预加载器完成后控制权交给BepInEx核心。它负责扫描BepInEx/plugins/目录下的所有插件DLL文件按照依赖关系排序然后逐一加载并初始化它们。每个插件都是一个独立的.NET类库。Plugins插件这就是你将要编写的模组代码。每个插件都是一个继承自BaseUnityPlugin的类并标记有[BepInPlugin]特性。BepInEx核心会调用它们的Awake()、Start()等方法类似于Unity的MonoBehaviour从而让你的代码在游戏世界的特定时机运行。整个流程就像一场精心策划的“潜入”Doorstop是伪装骗过系统首先加载自己Preloader是内应在目标内部布置好接应点Core是指挥中心协调所有行动单位插件就位。2.2 Unity Mono vs. IL2CPP你必须知道的区别这是使用BepInEx时最重要的一个技术背景。Unity游戏最终发布时其C#脚本有两种主要的后端编译方式Mono传统的即时编译JIT方式。游戏代码被编译成.NET中间语言IL在玩家电脑上运行时再由Mono运行时编译成本地代码。这种方式下原始的.NET程序集如Assembly-CSharp.dll相对容易被分析和修改。IL2CPPUnity推出的 Ahead-of-TimeAOT编译方式。游戏代码先被转换成C代码再编译成本地二进制文件如GameAssembly.dll。这带来了更好的性能和安全性但代码被高度优化和混淆直接分析和修改变得极其困难。BepInEx对两者的支持策略不同对于Mono游戏BepInEx可以近乎完美地工作因为它可以直接与.NET/Mono运行时交互甚至能使用一些高级特性如动态代码生成。对于IL2CPP游戏BepInEx通过一个叫做“Unity Il2Cpp Interop”的层来工作。它利用IL2CPP运行时的一些内部接口来加载托管插件但功能和兼容性会受到更多限制。很多为Mono游戏编写的插件在IL2CPP游戏上可能无法直接运行。实操心得在开始为某个游戏制作模组前第一件事就是确认游戏使用的是Mono还是IL2CPP。方法很简单打开游戏安装目录找GameAssembly.dll文件。如果存在就是IL2CPP如果不存在而是有UnityPlayer.dll和一堆*.dll文件包括Assembly-CSharp.dll那就是Mono。这个判断直接影响你后续开发插件的复杂度和可行性。3. 从零开始BepInEx的安装与配置实战理论懂了我们开始动手。这里我会以最常见的Steam平台上的Unity游戏为例带你走一遍完整的安装流程。3.1 准备工作与版本选择首先你需要确定游戏目录。对于Steam游戏通常路径是C:\Program Files (x86)\Steam\steamapps\common\你的游戏名。右键Steam库中的游戏选择“管理”-“浏览本地文件”可以快速打开。接下来去BepInEx的GitHub发布页面下载。这里有个关键选择不要盲目下载最新版。你应该查看游戏社区通常是在NexusMods或GitHub的模组页面的推荐版本。很多老游戏可能只兼容BepInEx的某个特定版本如BepInEx 5。通常下载BepInEx_x64_版本号.zip这样的预编译包就足够了。3.2 标准安装步骤解压将下载的ZIP包中的所有文件和文件夹解压出来。复制将解压出的所有内容通常包括BepInEx文件夹、doorstop_config.ini和winhttp.dll直接复制到你的游戏根目录即和游戏主程序.exe文件在同一层。验证结构复制完成后你的游戏目录应该类似这样游戏根目录/ ├── Game.exe (游戏主程序) ├── UnityPlayer.dll (Mono游戏) 或 GameAssembly.dll (IL2CPP游戏) ├── doorstop_config.ini (BepInEx启动配置) ├── winhttp.dll (Doorstop注入器) └── BepInEx/ (核心框架目录) ├── core/ ├── plugins/ (空文件夹将来放你的模组) └── config/首次运行直接启动游戏。如果安装成功游戏启动时可能会有一个短暂的黑屏或停顿这是BepInEx在初始化然后正常进入游戏。第一次运行后BepInEx文件夹下会生成LogOutput.log日志文件和更多的配置文件。3.3 核心配置文件详解安装后有两个配置文件你需要了解doorstop_config.ini控制Doorstop如何启动BepInEx。对于绝大多数情况你不需要修改它。但如果你遇到启动问题可以检查以下关键项[General] enabled true ; 必须为true才能启用BepInEx target_assembly BepInEx\core\BepInEx.Preloader.dll ; 预加载器路径通常自动识别BepInEx/config/BepInEx.cfg这是BepInEx自身的配置文件。一个非常有用的设置是日志级别[Logging.Console] Enabled true ; 是否在控制台显示日志 LogLevel Info ; 日志级别: Fatal, Error, Warning, Info, Debug调试模组时可以临时将LogLevel设为Debug或Info能看到更详细的加载信息。发布给玩家时建议改回Warning或Error以减少日志输出。注意事项有些游戏的反作弊系统如Easy Anti-Cheat可能会将BepInEx的注入行为视为作弊。在安装前最好去游戏社区查看是否有相关警告。对于联机游戏使用模组前务必确认服务器规则避免账号风险。4. 开发环境搭建与你的第一个“Hello World”模组现在BepInEx已经就位是时候创造点东西了。我们将创建一个最简单的插件它在游戏加载时在游戏日志里打印一句“Hello, BepInEx!”。4.1 配置开发环境安装IDE推荐使用Visual Studio 2022社区版免费。安装时确保勾选“.NET 桌面开发”工作负载。获取BepInEx库你需要BepInEx的核心库来引用。最简单的方法是从你刚刚安装到游戏目录里的BepInEx/core/文件夹中找到BepInEx.dll和BepInEx.Harmony.dllHarmony是一个用于方法修补的库后面会用到。将它们复制到一个安全的文件夹比如D:\Dev\BepInEx_Libs\。创建项目打开VS新建一个“类库(.NET Framework)”项目命名为MyFirstMod。注意.NET目标框架的选择至关重要你必须匹配游戏所使用的.NET版本。如何知道查看游戏目录下MonoBleedingEdge文件夹如果有或者用工具查看游戏主程序的依赖。对于大多数Unity游戏选择.NET Framework 4.7.2或4.8是一个安全的起点。选错了会导致插件无法加载。4.2 编写插件代码在项目中右键“引用”-“添加引用”-“浏览”找到并添加你之前复制的BepInEx.dll。然后创建一个新的C#类文件比如MyAwesomePlugin.cs写入以下代码using BepInEx; using BepInEx.Logging; using UnityEngine; // 这是插件的元数据标识必不可少。 // GUID必须是全局唯一的建议使用“作者名.模组名”的格式。 // 名称和版本号会显示在BepInEx的日志中。 [BepInPlugin(com.yourname.myfirstmod, 我的第一个模组, 1.0.0)] public class MyAwesomePlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 创建一个日志源方便输出信息到BepInEx的日志文件和控制台。 internal static ManualLogSource Log; // Awake方法在插件被加载时立即执行早于游戏的任何场景加载。 private void Awake() { // 将基类的Logger赋值给我们的静态变量方便其他方法使用。 Log Logger; // 使用LogInfo输出一条信息级别的日志。 Log.LogInfo(Hello, BepInEx! 我的插件已加载); // 我们也可以尝试做一些更“可见”的事情比如在游戏UI加载后打印一条消息。 // 但这需要等到游戏主体初始化完成所以我们在Start里做。 } // Start方法在所有插件Awake执行完毕后游戏主循环开始前执行。 // 对于很多需要访问游戏对象的操作这里更安全。 private void Start() { Log.LogInfo(游戏主循环即将开始我的插件准备就绪); // 示例尝试修改游戏窗口标题仅适用于部分Unity游戏 // Application.productName Application.productName - 由MyFirstMod驱动; // 注意并非所有游戏都允许这样修改这只是一个示例。 } // Update方法每一帧都会被调用慎用性能杀手。 // private void Update() { } }4.3 编译与部署在Visual Studio中选择“生成”-“生成解决方案”。如果一切顺利会在项目的bin\Debug\或bin\Release\文件夹下生成一个MyFirstMod.dll文件。将这个MyFirstMod.dll文件复制到游戏目录的BepInEx/plugins/文件夹下。如果plugins文件夹不存在就自己创建一个。启动游戏。如果看到游戏正常启动打开游戏根目录下的BepInEx/LogOutput.log文件用记事本搜索“Hello, BepInEx!”。你应该能看到类似下面的日志行[Info : My Awesome Mod] Hello, BepInEx! 我的插件已加载 [Info : My Awesome Mod] 游戏主循环即将开始我的插件准备就绪恭喜你的第一个BepInEx插件已经成功运行了。它虽然什么都没改变但已经完成了从零到一的突破——你的代码在游戏进程内执行了。5. 深入核心使用Harmony进行游戏代码修补仅仅打印日志远远不够。模组的魅力在于修改游戏行为。由于我们无法直接修改游戏原始的DLL文件我们需要一种“运行时修补”的技术。这就是Harmony库的用武之地。BepInEx已经内置了Harmony即BepInEx.Harmony.dll它允许你在游戏运行时动态修改某个类的方法。5.1 Harmony基础前缀、后缀与绕道Harmony主要通过打“补丁”来工作。有三种主要的补丁类型Prefix前缀在原方法执行之前运行。可以修改传入的参数甚至可以完全跳过原方法的执行。Postfix后缀在原方法执行之后运行。可以读取或修改原方法的返回值也可以访问原方法的参数。Transpiler绕道这是最强大也是最复杂的。它直接修改方法的IL代码中间语言可以实现极其精细的控制但需要对IL有一定了解。5.2 实战修改玩家金币数量假设我们想修改一个游戏让玩家每次获得金币时实际获得双倍。我们假设游戏中有一个Player类里面有一个AddGold(int amount)方法。首先在项目中添加对BepInEx.Harmony.dll的引用。然后我们创建一个新的类GoldPatch.cs来存放我们的补丁using HarmonyLib; using BepInEx; using System; // 这个特性告诉Harmony这个类里包含补丁。 [HarmonyPatch] public class GoldPatch { // 第一步找到我们要修补的目标方法。 // 我们需要知道方法的完整签名所属类、方法名、参数类型。 // 这通常需要借助反编译工具如dnSpy, ILSpy来分析游戏的Assembly-CSharp.dll。 // 假设我们分析出目标方法是Player.AddGold(int amount) [HarmonyPatch(typeof(Player), AddGold)] // 指定目标类和方法名 [HarmonyPrefix] // 声明这是一个前缀补丁 public static bool Prefix_AddGold(ref int amount) // 参数必须与原方法匹配通过ref关键字可以修改 { // 在原方法执行前将传入的金币数量翻倍。 amount * 2; // 输出日志以便调试 MyAwesomePlugin.Log.LogInfo($玩家获得金币已修改为双倍{amount} (原为 {amount / 2})); // 返回true表示继续执行原方法。如果返回false则会跳过原方法的执行。 return true; } }接下来我们需要在插件的主类MyAwesomePlugin中安装这个补丁。修改Awake方法private void Awake() { Log Logger; Log.LogInfo(Hello, BepInEx! 我的插件已加载); // 应用所有用[HarmonyPatch]标记的补丁 // 这会扫描当前程序集即你的插件dll中的所有类寻找Harmony补丁并应用它们。 var harmony new Harmony(com.yourname.myfirstmod); harmony.PatchAll(); Log.LogInfo(Harmony补丁已应用); }重新编译插件DLL替换旧的启动游戏。现在每当游戏代码调用Player.AddGold(100)时你的前缀补丁会先将amount变为200然后再执行游戏原有的增加金币逻辑。玩家就会获得双倍金币。实操心得与避坑指南方法签名必须精确[HarmonyPatch(typeof(Player), AddGold)]假设只有一个AddGold方法。如果存在重载例如AddGold(int)和AddGold(int, bool)你需要指定参数类型来区分[HarmonyPatch(typeof(Player), AddGold, new Type[] { typeof(int) })]。使用ref或out要修改参数值必须在参数前加ref关键字。要读取返回值在后缀补丁中使用__result参数。补丁类的生命周期补丁类必须是static的补丁方法也必须是static。Harmony不会实例化你的补丁类。调试是常态Harmony补丁出错通常会导致游戏崩溃或无提示地失效。务必在你的补丁方法内部和周围添加详细的日志输出Log.LogDebug这是定位问题的生命线。将BepInEx的日志级别设为Debug可以看到更多信息。反编译工具是你的眼睛没有游戏源代码dnSpy或ILSpy是你探索游戏内部类、方法、字段结构的必备工具。熟练使用它们是高级模组开发的基础。6. 进阶技巧配置管理、游戏对象交互与UI创建一个成熟的模组通常需要可配置的选项、与游戏场景中的物体交互甚至创建新的用户界面。6.1 使用Config文件管理模组设置BepInEx提供了内置的配置系统。我们可以让玩家在不修改代码的情况下调整模组行为比如开关双倍金币、调整倍数。在MyAwesomePlugin类中添加配置项private void Awake() { Log Logger; // 1. 定义配置项 // Config.Bind(分组, 键名, 默认值, 描述) var goldMultiplier Config.Bind(General, // 分组名 GoldMultiplier, // 键名 2.0f, // 默认值2.0倍 金币获取倍数。); // 描述 var isModEnabled Config.Bind(General, Enabled, true, 是否启用本模组。); Log.LogInfo($模组配置加载Enabled{isModEnabled.Value}, Multiplier{goldMultiplier.Value}); // 2. 将配置值应用到逻辑中需要修改之前的补丁 // 我们需要一种方式将配置值传递给静态的补丁类。一个简单的办法是使用静态属性。 GoldPatch.ModEnabled isModEnabled.Value; GoldPatch.Multiplier goldMultiplier.Value; // ... 应用Harmony补丁等后续操作 }然后修改GoldPatch类public class GoldPatch { // 静态属性用于从主插件类接收配置值 public static bool ModEnabled { get; set; } true; public static float Multiplier { get; set; } 2.0f; [HarmonyPatch(typeof(Player), AddGold)] [HarmonyPrefix] public static bool Prefix_AddGold(ref int amount) { if (!ModEnabled) return true; // 如果模组禁用直接执行原方法 int originalAmount amount; amount (int)(amount * Multiplier); // 使用配置的倍数 MyAwesomePlugin.Log.LogInfo($金币修改{originalAmount} - {amount} (倍数{Multiplier})); return true; } }游戏启动后在BepInEx/config/目录下会生成一个以你插件GUID命名的.cfg文件如com.yourname.myfirstmod.cfg。玩家可以用记事本编辑这个文件来修改设置。更友好的方式是使用像BepInEx ConfigurationManager这样的社区插件它能在游戏内提供一个图形化的配置界面。6.2 与游戏世界交互查找并修改游戏对象模组常常需要获取游戏中的实例比如玩家角色、UI管理器等。这通常在Start()或Update()方法中通过Unity的GameObject.Find或Object.FindObjectOfType方法来实现。private void Start() { Log.LogInfo(开始寻找游戏对象...); // 示例找到玩家对象假设玩家标签是Player GameObject playerObject GameObject.FindWithTag(Player); if (playerObject ! null) { Log.LogInfo($找到玩家对象{playerObject.name}); // 现在你可以获取玩家身上的组件比如 Player 脚本 // Player playerScript playerObject.GetComponentPlayer(); // if (playerScript ! null) { ... } } // 示例找到游戏中的UI管理器假设类型是 UIManager // UIManager uiManager Object.FindObjectOfTypeUIManager(); // if (uiManager ! null) { ... } } // 注意在Awake中游戏场景可能还未完全加载Find可能返回null。 // 对于依赖场景对象的操作Start或更晚的时机更可靠。6.3 创建简单的游戏内UI使用IMGUI对于需要实时交互或信息显示的模组一个游戏内窗口非常有用。BepInEx允许你使用Unity的即时模式GUIIMGUI来创建简单的界面。这需要在OnGUI方法中绘制。首先在你的插件类中启用GUIusing UnityEngine; [BepInPlugin(com.yourname.myfirstmod, 我的第一个模组, 1.0.0)] public class MyAwesomePlugin : BaseUnityPlugin { internal static ManualLogSource Log; private static bool _showWindow false; // 控制窗口显示 private Rect _windowRect new Rect(20, 20, 300, 200); // 窗口位置和大小 private void Awake() { ... } private void Start() { ... } // Unity的GUI渲染回调 private void OnGUI() { if (!_showWindow) return; // 创建一个窗口 _windowRect GUI.Window(0, _windowRect, DrawWindow, 我的模组控制面板); } // 绘制窗口内容 private void DrawWindow(int windowId) { GUILayout.Label(欢迎使用我的第一个模组); GUILayout.Space(10); if (GUILayout.Button(开关双倍金币)) { GoldPatch.ModEnabled !GoldPatch.ModEnabled; Log.LogInfo($双倍金币已{(GoldPatch.ModEnabled ? 开启 : 关闭)}); } GUILayout.Label($当前金币倍数{GoldPatch.Multiplier:F1}); GoldPatch.Multiplier GUILayout.HorizontalSlider(GoldPatch.Multiplier, 1.0f, 5.0f); GUILayout.Space(20); if (GUILayout.Button(关闭窗口)) { _showWindow false; } // 允许拖动窗口 GUI.DragWindow(new Rect(0, 0, 10000, 20)); } // 你可以通过快捷键来开关这个窗口需要在Update中检测输入 private void Update() { // 例如按F1键开关窗口 if (Input.GetKeyDown(KeyCode.F1)) { _showWindow !_showWindow; } } }现在在游戏中按F1键就能调出一个简单的控制面板可以开关功能、调整倍数。IMGUI虽然古老且效率不高但对于模组调试和小型控制面板来说足够简单快捷。7. 调试、发布与社区实践7.1 调试当模组不工作时怎么办模组开发中绝大部分时间都在调试。以下是我的排查清单检查日志BepInEx/LogOutput.log是首要信息来源。确保日志级别是Info或Debug。搜索你的插件GUID或名称查看是否有加载成功的消息。如果有ERROR或Exception仔细阅读堆栈跟踪。验证加载确认你的插件DLL在正确的BepInEx/plugins/目录下并且没有嵌套在子文件夹里除非插件设计如此。版本兼容确认你的BepInEx版本、游戏版本、以及你引用的BepInEx.dll版本三者兼容。不匹配是常见失败原因。依赖项如果你的插件引用了其他库如Newtonsoft.Json需要将这些依赖DLL也放在插件目录下或者使用BepInEx的BepInEx/patchers/机制。Harmony补丁失败如果补丁没生效检查方法签名是否100%正确包括参数类型、返回类型、是否为静态方法。目标类名是否包含命名空间例如MyGame.PlayervsPlayer。游戏代码是否在运行时被混淆了导致类名和方法名发生变化。使用调试器高级开发者可以将Visual Studio调试器附加到游戏进程上进行源码级调试。这需要配置Unity调试符号和VS的“附加到进程”功能过程较复杂但极其强大。7.2 发布你的模组当你完成模组开发并测试稳定后可以考虑分享给社区。打包创建一个清晰的文件夹结构。通常包括MyAwesomeMod_v1.0.0/ ├── README.txt (说明文件含安装步骤) ├── CHANGELOG.txt (版本更新日志) ├── BepInEx/ │ └── plugins/ │ └── MyAwesomeMod.dll (你的主插件文件) └── Optional/ (可选放配置文件、资源文件等)编写说明在README中明确说明支持的游戏版本、BepInEx版本、安装方法、功能简介、配置说明以及已知问题。选择平台发布NexusMods最大的模组社区网站支持版本管理和用户反馈。GitHub Releases适合开源项目便于代码管理和问题追踪。游戏相关的Discord频道或贴吧。版本管理遵循语义化版本控制主版本.次版本.修订号。修复bug升修订号增加功能升次版本不兼容的改动升主版本。7.3 融入社区与持续学习阅读他人代码在GitHub上搜索其他为同款游戏开发的BepInEx模组是学习最佳实践和了解游戏内部结构的最快途径。使用社区工具除了ConfigurationManager还有BepInEx.Packager打包工具、UnityExplorer游戏内对象查看器等优秀社区工具能极大提升开发效率。参与讨论在相关的Discord、Reddit或论坛上提问和回答。模组开发社区通常非常友好乐于助人。从我个人的经验来看为游戏制作模组最大的成就感不仅来自于实现一个酷炫的功能更来自于看到其他玩家使用并喜欢你的创作以及在这个过程中对游戏引擎、编程和软件架构的深入理解。BepInEx为你打开了一扇门门后的世界能有多精彩取决于你的想象力和动手能力。从那个简单的“Hello World”日志开始一步步去探索和改造你喜爱的游戏世界吧。
1. 项目概述为什么选择BepInEx作为你的模组开发起点如果你玩过一些基于Unity引擎开发的PC游戏比如《雨中冒险2》、《星露谷物语》的某些大型模组或者《英灵神殿》的社区扩展你很可能已经间接接触过BepInEx了。它不是一个直接面向玩家的工具而是几乎所有现代Unity游戏模组Mod背后那个默默无闻的“基础设施”。简单来说BepInEx是一个功能强大的插件加载框架它允许开发者在游戏启动时将自己的代码“注入”到游戏进程中从而实现对游戏功能的修改、增强或创造。为什么是BepInEx而不是其他框架在我过去几年的模组开发经历里从早期的Assembly-CSharp.dll直接反编译修改到尝试各种加载器最终BepInEx以其稳定性、社区活跃度和对Unity不同后端Mono/IL2CPP的广泛支持成为了事实上的标准。它就像给游戏世界安装了一套标准的“水电管道”模组开发者只需要按照规范接入就能确保自己的功能在绝大多数玩家的机器上稳定运行而不用操心底层复杂的注入和兼容性问题。对于想入门模组开发的新手或者希望为自己喜爱的游戏增添新玩法的爱好者掌握BepInEx是迈出实质性第一步的关键。它能让你从“使用模组”跨越到“创造模组”真正参与到游戏社区的共建中。2. 核心概念与架构拆解BepInEx是如何工作的在动手安装和开发之前花点时间理解BepInEx的运作机制至关重要。这能帮你避免很多“为什么我的模组不生效”的困惑。BepInEx的核心工作流程可以概括为“拦截、加载、执行”三步。2.1 核心组件与启动流程BepInEx的架构是模块化的主要包含以下几个核心部分Doorstop这是一个独立的、非常轻量级的注入器在Windows上是winhttp.dllLinux上是libdoorstop.so。它的唯一任务是在游戏主程序启动的瞬间抢先一步被系统加载然后根据doorstop_config.ini的配置去加载BepInEx的核心预加载器。你可以把它想象成一把“万能钥匙”负责打开游戏进程的大门。Preloader预加载器这是BepInEx自己的核心启动模块。被Doorstop加载后预加载器会在Unity引擎自身初始化之前运行。它的职责是准备BepInEx的运行环境比如设置插件搜索路径、初始化日志系统、加载核心库等。这个阶段发生在游戏任何实质性内容加载之前为后续操作铺平道路。BepInEx Core核心框架预加载器完成后控制权交给BepInEx核心。它负责扫描BepInEx/plugins/目录下的所有插件DLL文件按照依赖关系排序然后逐一加载并初始化它们。每个插件都是一个独立的.NET类库。Plugins插件这就是你将要编写的模组代码。每个插件都是一个继承自BaseUnityPlugin的类并标记有[BepInPlugin]特性。BepInEx核心会调用它们的Awake()、Start()等方法类似于Unity的MonoBehaviour从而让你的代码在游戏世界的特定时机运行。整个流程就像一场精心策划的“潜入”Doorstop是伪装骗过系统首先加载自己Preloader是内应在目标内部布置好接应点Core是指挥中心协调所有行动单位插件就位。2.2 Unity Mono vs. IL2CPP你必须知道的区别这是使用BepInEx时最重要的一个技术背景。Unity游戏最终发布时其C#脚本有两种主要的后端编译方式Mono传统的即时编译JIT方式。游戏代码被编译成.NET中间语言IL在玩家电脑上运行时再由Mono运行时编译成本地代码。这种方式下原始的.NET程序集如Assembly-CSharp.dll相对容易被分析和修改。IL2CPPUnity推出的 Ahead-of-TimeAOT编译方式。游戏代码先被转换成C代码再编译成本地二进制文件如GameAssembly.dll。这带来了更好的性能和安全性但代码被高度优化和混淆直接分析和修改变得极其困难。BepInEx对两者的支持策略不同对于Mono游戏BepInEx可以近乎完美地工作因为它可以直接与.NET/Mono运行时交互甚至能使用一些高级特性如动态代码生成。对于IL2CPP游戏BepInEx通过一个叫做“Unity Il2Cpp Interop”的层来工作。它利用IL2CPP运行时的一些内部接口来加载托管插件但功能和兼容性会受到更多限制。很多为Mono游戏编写的插件在IL2CPP游戏上可能无法直接运行。实操心得在开始为某个游戏制作模组前第一件事就是确认游戏使用的是Mono还是IL2CPP。方法很简单打开游戏安装目录找GameAssembly.dll文件。如果存在就是IL2CPP如果不存在而是有UnityPlayer.dll和一堆*.dll文件包括Assembly-CSharp.dll那就是Mono。这个判断直接影响你后续开发插件的复杂度和可行性。3. 从零开始BepInEx的安装与配置实战理论懂了我们开始动手。这里我会以最常见的Steam平台上的Unity游戏为例带你走一遍完整的安装流程。3.1 准备工作与版本选择首先你需要确定游戏目录。对于Steam游戏通常路径是C:\Program Files (x86)\Steam\steamapps\common\你的游戏名。右键Steam库中的游戏选择“管理”-“浏览本地文件”可以快速打开。接下来去BepInEx的GitHub发布页面下载。这里有个关键选择不要盲目下载最新版。你应该查看游戏社区通常是在NexusMods或GitHub的模组页面的推荐版本。很多老游戏可能只兼容BepInEx的某个特定版本如BepInEx 5。通常下载BepInEx_x64_版本号.zip这样的预编译包就足够了。3.2 标准安装步骤解压将下载的ZIP包中的所有文件和文件夹解压出来。复制将解压出的所有内容通常包括BepInEx文件夹、doorstop_config.ini和winhttp.dll直接复制到你的游戏根目录即和游戏主程序.exe文件在同一层。验证结构复制完成后你的游戏目录应该类似这样游戏根目录/ ├── Game.exe (游戏主程序) ├── UnityPlayer.dll (Mono游戏) 或 GameAssembly.dll (IL2CPP游戏) ├── doorstop_config.ini (BepInEx启动配置) ├── winhttp.dll (Doorstop注入器) └── BepInEx/ (核心框架目录) ├── core/ ├── plugins/ (空文件夹将来放你的模组) └── config/首次运行直接启动游戏。如果安装成功游戏启动时可能会有一个短暂的黑屏或停顿这是BepInEx在初始化然后正常进入游戏。第一次运行后BepInEx文件夹下会生成LogOutput.log日志文件和更多的配置文件。3.3 核心配置文件详解安装后有两个配置文件你需要了解doorstop_config.ini控制Doorstop如何启动BepInEx。对于绝大多数情况你不需要修改它。但如果你遇到启动问题可以检查以下关键项[General] enabled true ; 必须为true才能启用BepInEx target_assembly BepInEx\core\BepInEx.Preloader.dll ; 预加载器路径通常自动识别BepInEx/config/BepInEx.cfg这是BepInEx自身的配置文件。一个非常有用的设置是日志级别[Logging.Console] Enabled true ; 是否在控制台显示日志 LogLevel Info ; 日志级别: Fatal, Error, Warning, Info, Debug调试模组时可以临时将LogLevel设为Debug或Info能看到更详细的加载信息。发布给玩家时建议改回Warning或Error以减少日志输出。注意事项有些游戏的反作弊系统如Easy Anti-Cheat可能会将BepInEx的注入行为视为作弊。在安装前最好去游戏社区查看是否有相关警告。对于联机游戏使用模组前务必确认服务器规则避免账号风险。4. 开发环境搭建与你的第一个“Hello World”模组现在BepInEx已经就位是时候创造点东西了。我们将创建一个最简单的插件它在游戏加载时在游戏日志里打印一句“Hello, BepInEx!”。4.1 配置开发环境安装IDE推荐使用Visual Studio 2022社区版免费。安装时确保勾选“.NET 桌面开发”工作负载。获取BepInEx库你需要BepInEx的核心库来引用。最简单的方法是从你刚刚安装到游戏目录里的BepInEx/core/文件夹中找到BepInEx.dll和BepInEx.Harmony.dllHarmony是一个用于方法修补的库后面会用到。将它们复制到一个安全的文件夹比如D:\Dev\BepInEx_Libs\。创建项目打开VS新建一个“类库(.NET Framework)”项目命名为MyFirstMod。注意.NET目标框架的选择至关重要你必须匹配游戏所使用的.NET版本。如何知道查看游戏目录下MonoBleedingEdge文件夹如果有或者用工具查看游戏主程序的依赖。对于大多数Unity游戏选择.NET Framework 4.7.2或4.8是一个安全的起点。选错了会导致插件无法加载。4.2 编写插件代码在项目中右键“引用”-“添加引用”-“浏览”找到并添加你之前复制的BepInEx.dll。然后创建一个新的C#类文件比如MyAwesomePlugin.cs写入以下代码using BepInEx; using BepInEx.Logging; using UnityEngine; // 这是插件的元数据标识必不可少。 // GUID必须是全局唯一的建议使用“作者名.模组名”的格式。 // 名称和版本号会显示在BepInEx的日志中。 [BepInPlugin(com.yourname.myfirstmod, 我的第一个模组, 1.0.0)] public class MyAwesomePlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 创建一个日志源方便输出信息到BepInEx的日志文件和控制台。 internal static ManualLogSource Log; // Awake方法在插件被加载时立即执行早于游戏的任何场景加载。 private void Awake() { // 将基类的Logger赋值给我们的静态变量方便其他方法使用。 Log Logger; // 使用LogInfo输出一条信息级别的日志。 Log.LogInfo(Hello, BepInEx! 我的插件已加载); // 我们也可以尝试做一些更“可见”的事情比如在游戏UI加载后打印一条消息。 // 但这需要等到游戏主体初始化完成所以我们在Start里做。 } // Start方法在所有插件Awake执行完毕后游戏主循环开始前执行。 // 对于很多需要访问游戏对象的操作这里更安全。 private void Start() { Log.LogInfo(游戏主循环即将开始我的插件准备就绪); // 示例尝试修改游戏窗口标题仅适用于部分Unity游戏 // Application.productName Application.productName - 由MyFirstMod驱动; // 注意并非所有游戏都允许这样修改这只是一个示例。 } // Update方法每一帧都会被调用慎用性能杀手。 // private void Update() { } }4.3 编译与部署在Visual Studio中选择“生成”-“生成解决方案”。如果一切顺利会在项目的bin\Debug\或bin\Release\文件夹下生成一个MyFirstMod.dll文件。将这个MyFirstMod.dll文件复制到游戏目录的BepInEx/plugins/文件夹下。如果plugins文件夹不存在就自己创建一个。启动游戏。如果看到游戏正常启动打开游戏根目录下的BepInEx/LogOutput.log文件用记事本搜索“Hello, BepInEx!”。你应该能看到类似下面的日志行[Info : My Awesome Mod] Hello, BepInEx! 我的插件已加载 [Info : My Awesome Mod] 游戏主循环即将开始我的插件准备就绪恭喜你的第一个BepInEx插件已经成功运行了。它虽然什么都没改变但已经完成了从零到一的突破——你的代码在游戏进程内执行了。5. 深入核心使用Harmony进行游戏代码修补仅仅打印日志远远不够。模组的魅力在于修改游戏行为。由于我们无法直接修改游戏原始的DLL文件我们需要一种“运行时修补”的技术。这就是Harmony库的用武之地。BepInEx已经内置了Harmony即BepInEx.Harmony.dll它允许你在游戏运行时动态修改某个类的方法。5.1 Harmony基础前缀、后缀与绕道Harmony主要通过打“补丁”来工作。有三种主要的补丁类型Prefix前缀在原方法执行之前运行。可以修改传入的参数甚至可以完全跳过原方法的执行。Postfix后缀在原方法执行之后运行。可以读取或修改原方法的返回值也可以访问原方法的参数。Transpiler绕道这是最强大也是最复杂的。它直接修改方法的IL代码中间语言可以实现极其精细的控制但需要对IL有一定了解。5.2 实战修改玩家金币数量假设我们想修改一个游戏让玩家每次获得金币时实际获得双倍。我们假设游戏中有一个Player类里面有一个AddGold(int amount)方法。首先在项目中添加对BepInEx.Harmony.dll的引用。然后我们创建一个新的类GoldPatch.cs来存放我们的补丁using HarmonyLib; using BepInEx; using System; // 这个特性告诉Harmony这个类里包含补丁。 [HarmonyPatch] public class GoldPatch { // 第一步找到我们要修补的目标方法。 // 我们需要知道方法的完整签名所属类、方法名、参数类型。 // 这通常需要借助反编译工具如dnSpy, ILSpy来分析游戏的Assembly-CSharp.dll。 // 假设我们分析出目标方法是Player.AddGold(int amount) [HarmonyPatch(typeof(Player), AddGold)] // 指定目标类和方法名 [HarmonyPrefix] // 声明这是一个前缀补丁 public static bool Prefix_AddGold(ref int amount) // 参数必须与原方法匹配通过ref关键字可以修改 { // 在原方法执行前将传入的金币数量翻倍。 amount * 2; // 输出日志以便调试 MyAwesomePlugin.Log.LogInfo($玩家获得金币已修改为双倍{amount} (原为 {amount / 2})); // 返回true表示继续执行原方法。如果返回false则会跳过原方法的执行。 return true; } }接下来我们需要在插件的主类MyAwesomePlugin中安装这个补丁。修改Awake方法private void Awake() { Log Logger; Log.LogInfo(Hello, BepInEx! 我的插件已加载); // 应用所有用[HarmonyPatch]标记的补丁 // 这会扫描当前程序集即你的插件dll中的所有类寻找Harmony补丁并应用它们。 var harmony new Harmony(com.yourname.myfirstmod); harmony.PatchAll(); Log.LogInfo(Harmony补丁已应用); }重新编译插件DLL替换旧的启动游戏。现在每当游戏代码调用Player.AddGold(100)时你的前缀补丁会先将amount变为200然后再执行游戏原有的增加金币逻辑。玩家就会获得双倍金币。实操心得与避坑指南方法签名必须精确[HarmonyPatch(typeof(Player), AddGold)]假设只有一个AddGold方法。如果存在重载例如AddGold(int)和AddGold(int, bool)你需要指定参数类型来区分[HarmonyPatch(typeof(Player), AddGold, new Type[] { typeof(int) })]。使用ref或out要修改参数值必须在参数前加ref关键字。要读取返回值在后缀补丁中使用__result参数。补丁类的生命周期补丁类必须是static的补丁方法也必须是static。Harmony不会实例化你的补丁类。调试是常态Harmony补丁出错通常会导致游戏崩溃或无提示地失效。务必在你的补丁方法内部和周围添加详细的日志输出Log.LogDebug这是定位问题的生命线。将BepInEx的日志级别设为Debug可以看到更多信息。反编译工具是你的眼睛没有游戏源代码dnSpy或ILSpy是你探索游戏内部类、方法、字段结构的必备工具。熟练使用它们是高级模组开发的基础。6. 进阶技巧配置管理、游戏对象交互与UI创建一个成熟的模组通常需要可配置的选项、与游戏场景中的物体交互甚至创建新的用户界面。6.1 使用Config文件管理模组设置BepInEx提供了内置的配置系统。我们可以让玩家在不修改代码的情况下调整模组行为比如开关双倍金币、调整倍数。在MyAwesomePlugin类中添加配置项private void Awake() { Log Logger; // 1. 定义配置项 // Config.Bind(分组, 键名, 默认值, 描述) var goldMultiplier Config.Bind(General, // 分组名 GoldMultiplier, // 键名 2.0f, // 默认值2.0倍 金币获取倍数。); // 描述 var isModEnabled Config.Bind(General, Enabled, true, 是否启用本模组。); Log.LogInfo($模组配置加载Enabled{isModEnabled.Value}, Multiplier{goldMultiplier.Value}); // 2. 将配置值应用到逻辑中需要修改之前的补丁 // 我们需要一种方式将配置值传递给静态的补丁类。一个简单的办法是使用静态属性。 GoldPatch.ModEnabled isModEnabled.Value; GoldPatch.Multiplier goldMultiplier.Value; // ... 应用Harmony补丁等后续操作 }然后修改GoldPatch类public class GoldPatch { // 静态属性用于从主插件类接收配置值 public static bool ModEnabled { get; set; } true; public static float Multiplier { get; set; } 2.0f; [HarmonyPatch(typeof(Player), AddGold)] [HarmonyPrefix] public static bool Prefix_AddGold(ref int amount) { if (!ModEnabled) return true; // 如果模组禁用直接执行原方法 int originalAmount amount; amount (int)(amount * Multiplier); // 使用配置的倍数 MyAwesomePlugin.Log.LogInfo($金币修改{originalAmount} - {amount} (倍数{Multiplier})); return true; } }游戏启动后在BepInEx/config/目录下会生成一个以你插件GUID命名的.cfg文件如com.yourname.myfirstmod.cfg。玩家可以用记事本编辑这个文件来修改设置。更友好的方式是使用像BepInEx ConfigurationManager这样的社区插件它能在游戏内提供一个图形化的配置界面。6.2 与游戏世界交互查找并修改游戏对象模组常常需要获取游戏中的实例比如玩家角色、UI管理器等。这通常在Start()或Update()方法中通过Unity的GameObject.Find或Object.FindObjectOfType方法来实现。private void Start() { Log.LogInfo(开始寻找游戏对象...); // 示例找到玩家对象假设玩家标签是Player GameObject playerObject GameObject.FindWithTag(Player); if (playerObject ! null) { Log.LogInfo($找到玩家对象{playerObject.name}); // 现在你可以获取玩家身上的组件比如 Player 脚本 // Player playerScript playerObject.GetComponentPlayer(); // if (playerScript ! null) { ... } } // 示例找到游戏中的UI管理器假设类型是 UIManager // UIManager uiManager Object.FindObjectOfTypeUIManager(); // if (uiManager ! null) { ... } } // 注意在Awake中游戏场景可能还未完全加载Find可能返回null。 // 对于依赖场景对象的操作Start或更晚的时机更可靠。6.3 创建简单的游戏内UI使用IMGUI对于需要实时交互或信息显示的模组一个游戏内窗口非常有用。BepInEx允许你使用Unity的即时模式GUIIMGUI来创建简单的界面。这需要在OnGUI方法中绘制。首先在你的插件类中启用GUIusing UnityEngine; [BepInPlugin(com.yourname.myfirstmod, 我的第一个模组, 1.0.0)] public class MyAwesomePlugin : BaseUnityPlugin { internal static ManualLogSource Log; private static bool _showWindow false; // 控制窗口显示 private Rect _windowRect new Rect(20, 20, 300, 200); // 窗口位置和大小 private void Awake() { ... } private void Start() { ... } // Unity的GUI渲染回调 private void OnGUI() { if (!_showWindow) return; // 创建一个窗口 _windowRect GUI.Window(0, _windowRect, DrawWindow, 我的模组控制面板); } // 绘制窗口内容 private void DrawWindow(int windowId) { GUILayout.Label(欢迎使用我的第一个模组); GUILayout.Space(10); if (GUILayout.Button(开关双倍金币)) { GoldPatch.ModEnabled !GoldPatch.ModEnabled; Log.LogInfo($双倍金币已{(GoldPatch.ModEnabled ? 开启 : 关闭)}); } GUILayout.Label($当前金币倍数{GoldPatch.Multiplier:F1}); GoldPatch.Multiplier GUILayout.HorizontalSlider(GoldPatch.Multiplier, 1.0f, 5.0f); GUILayout.Space(20); if (GUILayout.Button(关闭窗口)) { _showWindow false; } // 允许拖动窗口 GUI.DragWindow(new Rect(0, 0, 10000, 20)); } // 你可以通过快捷键来开关这个窗口需要在Update中检测输入 private void Update() { // 例如按F1键开关窗口 if (Input.GetKeyDown(KeyCode.F1)) { _showWindow !_showWindow; } } }现在在游戏中按F1键就能调出一个简单的控制面板可以开关功能、调整倍数。IMGUI虽然古老且效率不高但对于模组调试和小型控制面板来说足够简单快捷。7. 调试、发布与社区实践7.1 调试当模组不工作时怎么办模组开发中绝大部分时间都在调试。以下是我的排查清单检查日志BepInEx/LogOutput.log是首要信息来源。确保日志级别是Info或Debug。搜索你的插件GUID或名称查看是否有加载成功的消息。如果有ERROR或Exception仔细阅读堆栈跟踪。验证加载确认你的插件DLL在正确的BepInEx/plugins/目录下并且没有嵌套在子文件夹里除非插件设计如此。版本兼容确认你的BepInEx版本、游戏版本、以及你引用的BepInEx.dll版本三者兼容。不匹配是常见失败原因。依赖项如果你的插件引用了其他库如Newtonsoft.Json需要将这些依赖DLL也放在插件目录下或者使用BepInEx的BepInEx/patchers/机制。Harmony补丁失败如果补丁没生效检查方法签名是否100%正确包括参数类型、返回类型、是否为静态方法。目标类名是否包含命名空间例如MyGame.PlayervsPlayer。游戏代码是否在运行时被混淆了导致类名和方法名发生变化。使用调试器高级开发者可以将Visual Studio调试器附加到游戏进程上进行源码级调试。这需要配置Unity调试符号和VS的“附加到进程”功能过程较复杂但极其强大。7.2 发布你的模组当你完成模组开发并测试稳定后可以考虑分享给社区。打包创建一个清晰的文件夹结构。通常包括MyAwesomeMod_v1.0.0/ ├── README.txt (说明文件含安装步骤) ├── CHANGELOG.txt (版本更新日志) ├── BepInEx/ │ └── plugins/ │ └── MyAwesomeMod.dll (你的主插件文件) └── Optional/ (可选放配置文件、资源文件等)编写说明在README中明确说明支持的游戏版本、BepInEx版本、安装方法、功能简介、配置说明以及已知问题。选择平台发布NexusMods最大的模组社区网站支持版本管理和用户反馈。GitHub Releases适合开源项目便于代码管理和问题追踪。游戏相关的Discord频道或贴吧。版本管理遵循语义化版本控制主版本.次版本.修订号。修复bug升修订号增加功能升次版本不兼容的改动升主版本。7.3 融入社区与持续学习阅读他人代码在GitHub上搜索其他为同款游戏开发的BepInEx模组是学习最佳实践和了解游戏内部结构的最快途径。使用社区工具除了ConfigurationManager还有BepInEx.Packager打包工具、UnityExplorer游戏内对象查看器等优秀社区工具能极大提升开发效率。参与讨论在相关的Discord、Reddit或论坛上提问和回答。模组开发社区通常非常友好乐于助人。从我个人的经验来看为游戏制作模组最大的成就感不仅来自于实现一个酷炫的功能更来自于看到其他玩家使用并喜欢你的创作以及在这个过程中对游戏引擎、编程和软件架构的深入理解。BepInEx为你打开了一扇门门后的世界能有多精彩取决于你的想象力和动手能力。从那个简单的“Hello World”日志开始一步步去探索和改造你喜爱的游戏世界吧。
方法：调试利器还是隐藏陷阱？)
)
