1. 项目概述为什么BepInEx是Unity模组开发的“终极”选择如果你是一个Unity游戏的深度玩家或者是一个对游戏修改、功能扩展充满热情的开发者那么“模组”这个词对你来说一定不陌生。从《我的世界》到《星露谷物语》再到《英灵神殿》无数游戏的寿命和乐趣都被玩家社区创造的模组极大地延长了。而在Unity游戏模组开发的世界里BepInEx这个名字几乎就是“稳定”、“强大”和“社区标准”的代名词。它不是一个具体的模组而是一个插件框架一个允许你安全、便捷地向已编译的Unity游戏中注入自定义代码的底层平台。简单来说BepInEx就像是为一个已经建好的房子游戏安装了一套标准化的水电管道和插座系统。有了这套系统你模组开发者就可以轻松地“插上”各种电器插件比如新的灯光、智能家居新功能而无需去砸墙改线直接修改游戏原始文件。对于玩家而言它则是一个可靠的“模组加载器”确保你从网上下载的各种插件能够和谐共处不会让游戏崩溃。那么为什么说它是“终极”框架这源于它的几个核心优势。首先兼容性极强。它通过精巧的运行时补丁和依赖管理能够适配从远古的Unity 5.x到最新的Unity 2022.3 LTS的众多游戏版本解决了不同Unity版本底层差异带来的适配噩梦。其次对开发者友好。它提供了一套清晰的API和事件系统开发者可以专注于功能逻辑而不用操心如何把代码“塞”进游戏里。最后对玩家安全。BepInEx的插件通常以独立的.dll文件形式存在与游戏本体分离卸载干净大大降低了因安装模组而导致游戏本体损坏的风险。本指南的目标就是带你绕过晦涩的文档和复杂的配置在5分钟内理解BepInEx的核心并完成一个能让任何Unity游戏“焕然一新”的插件从零到一的搭建。无论你是想为心爱的游戏添加一个便捷的UI按钮还是修改核心的游戏机制这里都将是你坚实的起点。2. BepInEx核心架构与工作原理深度拆解要熟练使用一个工具理解其内部如何运转至关重要。BepInEx并非魔法它的强大建立在几个清晰且高效的设计理念之上。2.1 核心组件四驾马车驱动插件生态BepInEx的运行时主要由四个核心组件构成它们各司其职共同搭建了插件运行的舞台。BepInEx Bootstrapper (引导程序)这是最先执行的部分通常是一个名为winhttp.dll或doorstop_config.ini配合UnityDoorstop的组件。它的任务是在游戏主程序UnityPlayer.dll加载之前抢先一步接管程序的控制流。你可以把它想象成音乐会开始前提前进场调试音响设备的工程师为后续的演出插件加载准备好环境。BepInEx Core (核心库)引导程序成功后会加载BepInEx.Core.dll。这是框架的心脏负责最核心的初始化工作管理插件的发现、加载、依赖解析以及提供最基础的日志和配置系统。它建立了插件与游戏通信的基本规则。BepInEx Harmony (补丁库)这是BepInEx的“超级武器”——BepInEx.Harmony.dll。它封装了强大的Harmony库。Harmony是一个.NET运行时补丁库允许你在不接触原始代码的情况下修改游戏内任何方法的行为。无论是修改一个函数的返回值还是在特定函数执行前后插入你的逻辑都依赖于此。这是实现游戏功能修改的基石。BepInEx Utility Libraries (工具库)包括BepInEx.IL2CPP针对IL2CPP后端编译的游戏、BepInEx.MonoMod等。它们针对不同的Unity编译后端Mono或IL2CPP进行了适配和优化确保框架在各类游戏上都能稳定运行。2.2 插件加载流程一场精密的接力赛一个插件从被放置到文件夹到在游戏内生效经历了以下标准流程游戏启动玩家双击游戏图标。引导劫持Bootstrapper介入将执行权导向BepInEx核心库。环境初始化核心库初始化日志系统、配置文件路径并扫描BepInEx/plugins目录。插件发现与加载核心库找到所有符合规范的.dll文件即插件使用.NET的反射机制将它们加载到当前的应用域中。插件初始化对于每个插件核心库寻找其入口点一个继承自BaseUnityPlugin的类并创建其实例调用其Awake()、Start()等方法类似于Unity MonoBehaviour的生命周期。Harmony补丁应用在插件初始化过程中如果插件声明了要使用Harmony进行代码修补Harmony库会在此刻分析游戏程序集并应用开发者预先定义好的补丁。控制权交还所有插件初始化完成后控制权交还给游戏原生的启动流程游戏画面出现。此时你的插件代码已经默默地运行在游戏进程之中了。注意理解IL2CPP与Mono的区别是关键。早期和许多独立游戏使用Mono后端代码相对容易分析和修补。而现代许多为性能和安全考虑的游戏如大量使用Unity 2020的移动端或PC游戏使用IL2CPP它将C#代码预先编译成C再编译为本地机器码使得传统的反射分析变得困难。BepInEx的IL2CPP适配层就是专门为了解决这个问题而生的它通过拦截IL2CPP的运行时函数来实现类似的功能。2.3 与其他模组工具的对比在BepInEx成为主流之前Unity游戏模组领域还有像UnityModManagerUMM这样的工具。那么BepInEx胜在哪里底层与侵入性UMM更像一个高层的应用层管理器通常需要游戏有特定的支持或使用较“Hacky”的方式注入。而BepInEx工作在更底层通过标准的.NET程序集加载和Harmony补丁其原理更通用、更稳定侵入性相对可控。功能与灵活性BepInEx直接集成了Harmony给予了开发者近乎无限的代码修改能力。UMM的功能则更多由其社区提供的模板和API定义在某些深度修改上可能受限。社区与生态目前绝大多数新兴的、复杂的Unity游戏模组都优先选择基于BepInEx开发其社区活跃插件资源丰富遇到问题更容易找到解决方案。可以说BepInEx代表了当前Unity游戏模组开发的最先进生产力和最广泛接受的工业标准。3. 5分钟极速上手创建你的第一个“Hello World”插件理论说得再多不如亲手实践。我们现在就来创建一个最简单的插件目标是在游戏启动时在屏幕上打印一条“Hello from BepInEx!”的日志。这将是你的“里程碑0”。3.1 环境准备工欲善其事必先利其器你需要准备以下工具整个过程就像搭积木一样简单.NET SDKBepInEx插件本质上是.NET类库。你需要安装.NET 6.0或更高版本的SDK。去微软官网下载安装即可。安装后在命令行输入dotnet --version确认安装成功。代码编辑器Visual Studio 2022社区版免费或 JetBrains Rider 是首选。它们对C#和.NET开发的支持最完善。VS Code搭配C#插件也是一个轻量级选择。目标游戏与BepInEx选择一个你已经安装的、支持BepInEx的Unity游戏例如《Risk of Rain 2》、《Valheim》。从BepInEx的GitHub发布页下载对应游戏版本或通用版本的BepInEx包并按照其说明安装到游戏根目录。通常就是解压所有文件到游戏exe所在文件夹。3.2 项目创建与配置三步搭建脚手架打开命令行终端我们开始创建项目# 1. 创建一个新的类库项目命名为 MyFirstBepInExPlugin dotnet new classlib -n MyFirstBepInExPlugin -f net6.0 # 2. 进入项目目录 cd MyFirstBepInExPlugin # 3. 添加必要的NuGet包引用 # BepInEx核心库版本号请查询最新稳定版 dotnet add package BepInEx.Core --version 5.4.21 # BepInEx的Harmony库版本号需与核心库匹配 dotnet add package BepInEx.Harmony --version 5.4.21 # 如果你针对的是使用IL2CPP编译的游戏还需要这个 # dotnet add package BepInEx.IL2CPP --version 5.4.21接下来编辑项目文件MyFirstBepInExPlugin.csproj。我们需要将其输出类型明确为类库并确保复制依赖项到输出目录这对于插件部署至关重要。Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknet6.0/TargetFramework ImplicitUsingsenable/ImplicitUsings Nullableenable/Nullable !-- 关键输出为类库 -- OutputTypeLibrary/OutputType !-- 生成一个与项目同名的dll避免默认的“MyFirstBepInExPlugin.dll” -- AssemblyNameMyFirstBepInExPlugin/AssemblyName /PropertyGroup ItemGroup PackageReference IncludeBepInEx.Core Version5.4.21 / PackageReference IncludeBepInEx.Harmony Version5.4.21 / /ItemGroup !-- 关键发布时将所有依赖的dll复制到输出目录 -- Target NameCopyDependencies AfterTargetsBuild Copy SourceFiles(ReferenceCopyLocalPaths) DestinationFolder$(OutputPath) / /Target /Project3.3 编写核心插件代码从零到一的魔法现在打开自动生成的Class1.cs文件将其彻底重命名为更有意义的HelloWorldPlugin.cs并替换内容如下using BepInEx; using BepInEx.Logging; using UnityEngine; // 命名空间建议与插件名相关避免冲突 namespace MyFirstBepInExPlugin { // 最重要的特性BepInPlugin是插件的身份证。 // GUID必须是全球唯一的通常使用“作者名.插件名”的格式。 // Name和Version会显示在BepInEx的插件管理界面。 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 定义插件的元数据 public const string PluginGUID com.yourname.helloworld; public const string PluginName Hello World Plugin; public const string PluginVersion 1.0.0.0; // BepInEx提供的日志器用于输出信息到控制台和日志文件 internal static ManualLogSource Log; // Awake方法在插件被加载后立即执行早于游戏的任何场景加载 private void Awake() { // 初始化日志器Logger是BaseUnityPlugin自带的属性 Log Logger; // 这就是我们的“Hello World”日志级别为Info。 Log.LogInfo(Hello from BepInEx! Plugin loaded successfully!); // 我们也可以尝试做一些更“游戏内”的事情比如在游戏UI创建后打印。 // 但Awake阶段UI可能还未就绪更复杂的操作应放在Start或通过Harmony挂钩。 } // Start方法在Awake之后在第一帧更新之前执行 // private void Start() // { // // 可以在这里执行一些需要游戏对象已初始化的操作 // } // Update方法每一帧都会被调用谨慎使用避免性能开销 // private void Update() // { // } } }3.4 编译与部署让插件在游戏中跑起来编译在项目目录下执行dotnet build -c Release。这会在bin/Release/net6.0/目录下生成MyFirstBepInExPlugin.dll以及它依赖的BepInEx库文件。部署找到你安装好BepInEx的游戏根目录进入BepInEx/plugins文件夹。创建一个新的文件夹以你的插件名命名例如MyFirstPlugin然后将上一步生成的MyFirstBepInExPlugin.dll单独复制到这个新文件夹内。重要心得永远将你的插件dll放在plugins下的一个独立子文件夹里。这有利于管理、更新和卸载也符合社区规范。不要直接把dll扔在plugins根目录。测试启动游戏。如果一切顺利你应该能看到游戏正常启动。要验证插件是否生效你需要查看BepInEx的日志。进入游戏根目录的BepInEx/LogOutput.log文件。或者如果游戏支持控制台很多BepInEx安装会默认开启你可以在游戏中按F1或其他快捷键调出控制台窗口。在日志中搜索 “Hello from BepInEx!”如果看到这行信息恭喜你你的第一个BepInEx插件已经成功运行在游戏进程中了。这短短几十行代码就完成了一次从外部向一个正在运行的商业游戏注入代码并执行的全过程。虽然它现在只是打印了一行日志但这条路径一旦打通后面就是广阔的天地。4. 核心技能进阶使用Harmony实现游戏功能修改仅仅打印日志远非BepInEx的威力所在。Harmony库才是让你从“观察者”变为“改造者”的关键。它允许你修改游戏已有的方法。我们来看一个经典场景修改玩家角色的移动速度。假设我们通过反编译或查阅游戏源码如果开源得知控制玩家移动速度的方法位于PlayerController类中名为GetMoveSpeed返回一个float类型的速度值。4.1 Harmony补丁基础前缀、后缀与环绕Harmony主要通过三种类型的补丁来修改方法前缀补丁 (Prefix)在原方法执行之前运行。你可以访问方法的参数甚至可以修改它们或者通过返回false来完全阻止原方法的执行。后缀补丁 (Postfix)在原方法执行之后运行。你可以访问方法的参数、返回值__result以及实例__instance并修改返回值。环绕补丁 (Transpiler)这是高级功能它允许你直接修改方法的IL代码中间语言功能最强大也最复杂通常用于修改方法内部的逻辑流。对于修改移动速度我们使用后缀补丁是最合适的因为我们想在游戏计算完基础速度后再施加我们的修改倍率。4.2 实战实现一个“超级速度”插件让我们在之前的HelloWorldPlugin项目基础上进行扩展。首先确保已引用BepInEx.Harmony包。修改HelloWorldPlugin.cs文件using BepInEx; using BepInEx.Logging; using HarmonyLib; // 引入Harmony命名空间 using UnityEngine; namespace MyFirstBepInExPlugin { [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin { public const string PluginGUID com.yourname.helloworld; public const string PluginName Super Speed Plugin; public const string PluginVersion 1.0.1.0; // 更新版本号 internal static ManualLogSource Log; // 定义一个配置项允许玩家在游戏中调整速度倍率 private static ConfigEntryfloat SpeedMultiplier; private void Awake() { Log Logger; Log.LogInfo(Super Speed Plugin loading...); // 1. 创建配置项 // 参数配置分组可为空配置键名配置描述默认值 SpeedMultiplier Config.Bind(General, // 分组 SpeedMultiplier, // 键 2.0f, // 默认值2倍速度 The multiplier applied to player move speed.); // 描述 Log.LogInfo($Speed multiplier set to: {SpeedMultiplier.Value}); // 2. 应用Harmony补丁 // 这行代码会扫描当前程序集你的插件dll中所有带有[HarmonyPatch]特性的类并创建补丁。 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly); Log.LogInfo(Harmony patches applied.); } } // 新的类专门存放我们的Harmony补丁 [HarmonyPatch] // 声明这是一个Harmony补丁类 public static class PlayerSpeedPatch { // 确定我们要修补的目标方法。 // 这里需要你知道游戏内具体的类名和方法名。这通常通过反编译工具如dnSpy, ILSpy或游戏文档获得。 // 假设目标方法是PlayerController.GetMoveSpeed() [HarmonyPatch(typeof(PlayerController), nameof(PlayerController.GetMoveSpeed))] [HarmonyPostfix] // 指定这是一个后缀补丁 public static void GetMoveSpeed_Postfix(ref float __result, PlayerController __instance) { // __result 是原方法的返回值我们可以修改它。 // __instance 是调用该方法的PlayerController实例。 // 通过ref关键字我们可以修改__result的值。 // 获取插件实例有多种方式这里展示通过查找BepInEx插件对象的方式 var plugin BepInEx.Bootstrap.Chainloader.PluginInfos[HelloWorldPlugin.PluginGUID].Instance as HelloWorldPlugin; if (plugin ! null) { // 应用配置的倍率 __result * plugin.SpeedMultiplier.Value; // 可选记录日志调试时使用正式版建议关闭以避免性能损耗 // HelloWorldPlugin.Log.LogDebug($Speed modified: {__result}); } } } }4.3 配置与热重载让插件更友好上面的代码引入了Config.Bind。BepInEx内置了配置文件系统。编译部署新插件后在BepInEx/config目录下会生成一个以你的PluginGUID命名的.cfg文件例如com.yourname.helloworld.cfg。玩家可以用文本编辑器打开它修改SpeedMultiplier的值。更神奇的是BepInEx支持部分配置的热重载。对于像ConfigEntryfloat这样的简单类型在游戏中修改配置文件并保存后插件下次读取这个值时比如玩家下一次移动时调用GetMoveSpeed就会使用新的倍率无需重启游戏实操心得如何找到正确的类和方法名这是Harmony补丁开发中最具挑战性的一步。你需要借助反编译工具。工具准备使用dnSpy或ILSpy。它们可以打开游戏的主程序集通常是GameAssembly.dll(IL2CPP) 或Assembly-CSharp.dll(Mono)让你浏览所有C#类和方法。搜索关键词在反编译器中搜索你认为可能的关键词如 “MoveSpeed”, “Player”, “Controller”, “Update”。分析调用找到疑似方法后查看谁调用了它以及它内部调用了什么结合游戏行为进行验证。社区与文档许多热门游戏都有活跃的模组社区在GitHub或Discord上经常能找到已有的补丁示例这是最快的入门方式。谨慎测试最初的补丁可能因方法签名参数类型、返回类型不匹配而失败。务必查看BepInEx的日志文件LogOutput.logHarmony会详细报告补丁失败的原因。5. 打造实用插件从UI到存档的完整功能案例让我们整合前面所学创建一个更复杂、更实用的插件一个简单的游戏内图形界面GUI允许玩家实时开关“超级速度”功能并显示当前速度倍率。我们将使用BepInEx社区一个非常流行的UI库BepInEx.ConfigurationManager。不过为了展示原理我们先从最基础的Unity IMGUI开始。5.1 创建可开关的GUI功能我们需要在插件中启用Unity的IMGUI渲染并绘制一个简单的窗口。修改HelloWorldPlugin.cs增加GUI相关逻辑using BepInEx; using BepInEx.Logging; using HarmonyLib; using UnityEngine; namespace MyFirstBepInExPlugin { [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin { public const string PluginGUID com.yourname.helloworld; public const string PluginName Super Speed Plugin with GUI; public const string PluginVersion 1.0.2.0; internal static ManualLogSource Log; private static ConfigEntryfloat SpeedMultiplier; private static ConfigEntrybool SpeedEnabled; // 新增是否启用加速的配置 private static ConfigEntryKeyboardShortcut ToggleUIKey; // 新增切换UI显示的快捷键 // GUI相关变量 private static bool _isWindowVisible false; private static Rect _windowRect new Rect(20, 20, 250, 150); private void Awake() { Log Logger; Log.LogInfo(Super Speed Plugin with GUI loading...); // 初始化配置 SpeedMultiplier Config.Bind(General, SpeedMultiplier, 2.0f, The multiplier applied to player move speed.); SpeedEnabled Config.Bind(General, SpeedEnabled, true, Whether the speed modifier is active.); ToggleUIKey Config.Bind(Hotkeys, ToggleUI, new KeyboardShortcut(KeyCode.F7), // 默认F7开关UI Key to show/hide the plugin GUI.); Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly); } // 我们需要在Unity的渲染循环中绘制GUI // 使用Harmony给Unity的OnGUI方法打补丁是一种方式但更简单的是利用MonoBehaviour的Update和OnGUI。 // 由于BaseUnityPlugin本身也是MonoBehaviour我们可以直接添加这些方法。 private void Update() { // 检查快捷键是否被按下 if (ToggleUIKey.Value.IsDown()) { _isWindowVisible !_isWindowVisible; Log.LogDebug($GUI visibility toggled: {_isWindowVisible}); } } private void OnGUI() { if (!_isWindowVisible) return; // 创建一个IMGUI窗口 _windowRect GUI.Window(0, _windowRect, DrawPluginWindow, Super Speed Control Panel); } private static void DrawPluginWindow(int windowId) { GUILayout.Label($Plugin: {PluginName} v{PluginVersion}); GUILayout.Space(10); // 开关控件 bool newEnabled GUILayout.Toggle(SpeedEnabled.Value, Enable Speed Boost); if (newEnabled ! SpeedEnabled.Value) { SpeedEnabled.Value newEnabled; Log.LogInfo($Speed boost {(newEnabled ? ENABLED : DISABLED)}); } GUILayout.Space(5); GUILayout.Label($Current Multiplier: {SpeedMultiplier.Value:F1}x); // 滑块控件调整倍率 float newMultiplier GUILayout.HorizontalSlider(SpeedMultiplier.Value, 0.5f, 5.0f); if (Mathf.Abs(newMultiplier - SpeedMultiplier.Value) 0.01f) { SpeedMultiplier.Value newMultiplier; // 这里可以立即生效因为我们的Harmony补丁每次都会读取这个值 } GUILayout.Space(10); if (GUILayout.Button(Close)) { _isWindowVisible false; } // 允许窗口被拖动 GUI.DragWindow(new Rect(0, 0, 10000, 20)); } } [HarmonyPatch] public static class PlayerSpeedPatch { [HarmonyPatch(typeof(PlayerController), nameof(PlayerController.GetMoveSpeed))] [HarmonyPostfix] public static void GetMoveSpeed_Postfix(ref float __result, PlayerController __instance) { var plugin BepInEx.Bootstrap.Chainloader.PluginInfos[HelloWorldPlugin.PluginGUID].Instance as HelloWorldPlugin; if (plugin ! null plugin.SpeedEnabled.Value) // 检查是否启用 { __result * plugin.SpeedMultiplier.Value; } } } }现在你的插件拥有了一个可通过F7键开关的图形界面可以实时启用/禁用加速功能并通过滑块调整倍率。所有设置都会自动保存到配置文件中。5.2 使用ConfigurationManager提供更专业的配置界面手动绘制GUI对于简单功能足够但对于复杂的配置项管理起来很麻烦。社区项目BepInEx.ConfigurationManager提供了一个自动生成的、美观的配置窗口。安装在你的插件项目中通过NuGet添加对BepInEx.ConfigurationManager的引用或者让玩家手动将ConfigurationManager.dll放入BepInEx/plugins目录。使用你几乎不需要做任何额外工作只要你使用了Config.Bind()创建的ConfigEntryT对象ConfigurationManager插件就会自动在游戏中默认按F1键的配置管理器里为你的插件生成一个配置页面包含描述、输入框、滑块、下拉菜单等完全自动。这是社区最佳实践极大地提升了插件的用户体验和可维护性。5.3 与其他插件交互与存档安全一个成熟的插件还需要考虑更多依赖管理如果你的插件需要另一个插件例如一个通用的工具库才能运行你可以在你的插件类上添加[BepInDependency]特性来声明依赖BepInEx会在加载你的插件前确保依赖已加载。[BepInDependency(com.other.author.toolkit, BepInDependency.DependencyFlags.HardDependency)] [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class MyPlugin : BaseUnityPlugin { ... }存档兼容性永远记住通过Harmony修改游戏状态如玩家属性、物品数据可能会影响存档。如果你的修改是持久的例如永久增加了背包大小你需要考虑修改是否应该随存档保存如果是你可能需要挂钩游戏的保存/加载方法将自定义数据序列化进去。这非常复杂且极易导致存档损坏。最安全的做法是让所有修改都是临时的、运行时生效的就像我们的速度倍率插件一样关闭插件或重启游戏一切恢复原样。这保证了存档的纯净性和兼容性。如果必须修改存档务必提供明确的警告并做好备份。6. 调试、打包与发布全流程指南开发完成后你需要测试、打包并分享你的作品。6.1 调试技巧定位问题的火眼金睛日志是你的第一朋友Logger.LogDebug/Info/Warning/Error是基本操作。在关键分支、循环开始结束处打上日志能清晰追踪程序流。控制台与日志文件BepInEx/LogOutput.log包含所有BepInEx和插件的日志。游戏内控制台如果启用可以实时查看。使用Debug构建开发时使用dotnet build -c Debug。这会生成调试符号.pdb文件当游戏崩溃时日志能给出具体的代码行号而不是模糊的偏移地址。Harmony Debug模式在Awake中创建Harmony实例时可以传入一个唯一的ID并启用调试var harmony new Harmony(com.yourname.plugin); harmony.PatchAll();。同时确保BepInEx.cfg中[Logging]下的UnityLogListening和DiskWriteEnabled设为trueLogLevels包含All。这会让Harmony输出详细的补丁应用信息。6.2 插件打包规范让分享更轻松一个规范的插件包应该让玩家“解压即用”。通常的目录结构如下YourAwesomePlugin_v1.0.0.zip │ ├── README.md // 说明文档介绍功能、安装方法、快捷键等 ├── CHANGELOG.md // 更新日志 │ └── BepInEx └── plugins └── YourAwesomePlugin // 以插件名命名的文件夹 ├── YourAwesomePlugin.dll // 主插件文件 ├── YourAwesomePlugin.dll.config // 可选配置文件模板 ├── YourAwesomePlugin.pdb // 可选调试符号文件 └── manifest.json // 推荐Thunderstore等模组平台需要的元数据文件manifest.json是模组平台如Thunderstore的标准包含插件名、版本号、作者、依赖、下载链接等。使用r2modman或Thunderstore的打包工具可以自动生成。6.3 发布与版本管理本地测试在多个游戏场景、存档中充分测试确保没有崩溃、内存泄漏和严重的性能问题。版本号语义化遵循主版本号.次版本号.修订号.构建号如1.2.3.456的规则。重大不兼容更新升主版本新增功能升次版本修复Bug升修订号。选择发布平台GitHub Releases适合技术用户便于跟踪issue和代码。Thunderstore当前最流行的《英灵神殿》、《雨中冒险2》等游戏的模组集散地有方便的模组管理器集成。Nexus Mods老牌模组网站用户基数大。游戏专属社区如Discord频道、贴吧、Reddit版块。编写清晰的文档在README.md中必须包含功能简介安装步骤一步步来配置说明如何修改设置已知问题常见问题解答FAQ致谢与引用7. 避坑指南与最佳实践实录在多年的BepInEx插件开发中我踩过无数坑也总结出一些让插件更稳定、更受欢迎的经验。7.1 性能与安全稳定性的基石慎用Update方法除非必要不要在插件的Update方法里写逻辑尤其是每帧执行的复杂计算。这会给游戏带来不必要的性能开销。如果需要检测按键或定时执行考虑使用协程StartCoroutine或InvokeRepeating并降低频率。缓存引用避免重复查找例如不要在每个Update里用GameObject.Find或GetComponent去查找对象。在Start或Awake中找到并缓存它们。Harmony补丁要精准尽量使用最具体的方法签名进行补丁。避免使用[HarmonyPatchAll]这种全局补丁它可能会意外修补到你不希望修改的方法导致不稳定。处理异常在Harmony补丁和可能出错的地方使用try-catch块并将异常记录到日志而不是让游戏崩溃。[HarmonyPostfix] public static void MyPatch(ref float __result) { try { // 你的逻辑 } catch (System.Exception e) { MyPlugin.Log.LogError($Patch failed: {e}); } }7.2 兼容性与协作社区生存法则命名空间和GUID必须唯一这是铁律。使用反向域名格式的GUID如com.yourname.modname能最大程度避免冲突。声明依赖与冲突使用[BepInDependency]和[BepInIncompatibility]特性清晰地表明你的插件与其他插件的关系。避免“暴力”修改有些插件会直接覆盖游戏的核心文件或使用过于激进的Harmony补丁这极易与其他模组冲突。优先使用事件、回调等非侵入式方式或者与社区协商建立公共的API接口。关注游戏更新游戏每次更新都可能改变类和方法的结构导致你的Harmony补丁失效。建立快速的测试和修复流程并在插件页面明确标注支持的游戏版本号。7.3 常见问题速查表问题现象可能原因排查步骤插件未加载日志无信息1. DLL未放在BepInEx/plugins/子文件夹下。2. DLL依赖项缺失。3. 插件目标.NET框架与游戏不匹配。1. 检查文件路径。2. 使用ILSpy打开你的DLL查看引用的依赖是否都存在。3. 确保插件编译目标与游戏运行的.NET版本兼容通常为.NET Framework 4.x或.NET Standard 2.0。游戏启动时崩溃1. Harmony补丁目标方法签名错误。2. 在Awake中访问了尚未初始化的游戏对象。3. 插件代码存在未处理的异常。1. 查看LogOutput.log末尾的堆栈跟踪定位崩溃点。2. 检查Harmony补丁的类名、方法名、参数类型是否完全正确。3. 将代码分段注释定位问题代码。功能不生效但插件已加载1. Harmony补丁未成功应用。2. 配置项未正确绑定或读取。3. 条件判断逻辑有误如SpeedEnabled为false。1. 在日志中搜索“Harmony”字样查看补丁应用报告。2. 在插件初始化时打印配置值到日志。3. 在补丁方法入口处添加日志确认是否被执行。与其他模组冲突1. 修改了同一游戏方法。2. 全局事件监听冲突。3. 使用了相同的单例或静态资源。1. 禁用其他模组逐一启用定位冲突对象。2. 检查冲突模组的描述看是否有已知兼容性问题。3. 尝试调整插件加载顺序通过依赖声明。配置修改不生效1. 未使用ConfigEntryT.Value属性。2. 配置项是值类型且插件缓存了旧值。3. 配置文件路径错误或只读。1. 确保通过Config.Bind创建ConfigEntry并读写其Value属性。2. 每次使用配置时都直接读取Value不要用局部变量缓存。3. 检查BepInEx/config目录下是否正确生成了.cfg文件。开发BepInEx插件的旅程就像是在一个精密的机械手表内部添加自己设计的齿轮。你需要耐心、细致并对原有结构充满敬畏。但一旦你掌握了这套工具就获得了重塑游戏体验的惊人能力。从简单的功能调整到复杂的系统重写边界只在于你的想象力与对游戏的理解深度。记住强大的力量也意味着责任始终以不破坏他人游戏体验和存档安全为前提进行创作你的插件才会在社区中走得更远。现在启动你的IDE选择一个你热爱的游戏开始你的模组开发之旅吧。
Unity游戏模组开发入门：BepInEx插件框架核心原理与实战指南
1. 项目概述为什么BepInEx是Unity模组开发的“终极”选择如果你是一个Unity游戏的深度玩家或者是一个对游戏修改、功能扩展充满热情的开发者那么“模组”这个词对你来说一定不陌生。从《我的世界》到《星露谷物语》再到《英灵神殿》无数游戏的寿命和乐趣都被玩家社区创造的模组极大地延长了。而在Unity游戏模组开发的世界里BepInEx这个名字几乎就是“稳定”、“强大”和“社区标准”的代名词。它不是一个具体的模组而是一个插件框架一个允许你安全、便捷地向已编译的Unity游戏中注入自定义代码的底层平台。简单来说BepInEx就像是为一个已经建好的房子游戏安装了一套标准化的水电管道和插座系统。有了这套系统你模组开发者就可以轻松地“插上”各种电器插件比如新的灯光、智能家居新功能而无需去砸墙改线直接修改游戏原始文件。对于玩家而言它则是一个可靠的“模组加载器”确保你从网上下载的各种插件能够和谐共处不会让游戏崩溃。那么为什么说它是“终极”框架这源于它的几个核心优势。首先兼容性极强。它通过精巧的运行时补丁和依赖管理能够适配从远古的Unity 5.x到最新的Unity 2022.3 LTS的众多游戏版本解决了不同Unity版本底层差异带来的适配噩梦。其次对开发者友好。它提供了一套清晰的API和事件系统开发者可以专注于功能逻辑而不用操心如何把代码“塞”进游戏里。最后对玩家安全。BepInEx的插件通常以独立的.dll文件形式存在与游戏本体分离卸载干净大大降低了因安装模组而导致游戏本体损坏的风险。本指南的目标就是带你绕过晦涩的文档和复杂的配置在5分钟内理解BepInEx的核心并完成一个能让任何Unity游戏“焕然一新”的插件从零到一的搭建。无论你是想为心爱的游戏添加一个便捷的UI按钮还是修改核心的游戏机制这里都将是你坚实的起点。2. BepInEx核心架构与工作原理深度拆解要熟练使用一个工具理解其内部如何运转至关重要。BepInEx并非魔法它的强大建立在几个清晰且高效的设计理念之上。2.1 核心组件四驾马车驱动插件生态BepInEx的运行时主要由四个核心组件构成它们各司其职共同搭建了插件运行的舞台。BepInEx Bootstrapper (引导程序)这是最先执行的部分通常是一个名为winhttp.dll或doorstop_config.ini配合UnityDoorstop的组件。它的任务是在游戏主程序UnityPlayer.dll加载之前抢先一步接管程序的控制流。你可以把它想象成音乐会开始前提前进场调试音响设备的工程师为后续的演出插件加载准备好环境。BepInEx Core (核心库)引导程序成功后会加载BepInEx.Core.dll。这是框架的心脏负责最核心的初始化工作管理插件的发现、加载、依赖解析以及提供最基础的日志和配置系统。它建立了插件与游戏通信的基本规则。BepInEx Harmony (补丁库)这是BepInEx的“超级武器”——BepInEx.Harmony.dll。它封装了强大的Harmony库。Harmony是一个.NET运行时补丁库允许你在不接触原始代码的情况下修改游戏内任何方法的行为。无论是修改一个函数的返回值还是在特定函数执行前后插入你的逻辑都依赖于此。这是实现游戏功能修改的基石。BepInEx Utility Libraries (工具库)包括BepInEx.IL2CPP针对IL2CPP后端编译的游戏、BepInEx.MonoMod等。它们针对不同的Unity编译后端Mono或IL2CPP进行了适配和优化确保框架在各类游戏上都能稳定运行。2.2 插件加载流程一场精密的接力赛一个插件从被放置到文件夹到在游戏内生效经历了以下标准流程游戏启动玩家双击游戏图标。引导劫持Bootstrapper介入将执行权导向BepInEx核心库。环境初始化核心库初始化日志系统、配置文件路径并扫描BepInEx/plugins目录。插件发现与加载核心库找到所有符合规范的.dll文件即插件使用.NET的反射机制将它们加载到当前的应用域中。插件初始化对于每个插件核心库寻找其入口点一个继承自BaseUnityPlugin的类并创建其实例调用其Awake()、Start()等方法类似于Unity MonoBehaviour的生命周期。Harmony补丁应用在插件初始化过程中如果插件声明了要使用Harmony进行代码修补Harmony库会在此刻分析游戏程序集并应用开发者预先定义好的补丁。控制权交还所有插件初始化完成后控制权交还给游戏原生的启动流程游戏画面出现。此时你的插件代码已经默默地运行在游戏进程之中了。注意理解IL2CPP与Mono的区别是关键。早期和许多独立游戏使用Mono后端代码相对容易分析和修补。而现代许多为性能和安全考虑的游戏如大量使用Unity 2020的移动端或PC游戏使用IL2CPP它将C#代码预先编译成C再编译为本地机器码使得传统的反射分析变得困难。BepInEx的IL2CPP适配层就是专门为了解决这个问题而生的它通过拦截IL2CPP的运行时函数来实现类似的功能。2.3 与其他模组工具的对比在BepInEx成为主流之前Unity游戏模组领域还有像UnityModManagerUMM这样的工具。那么BepInEx胜在哪里底层与侵入性UMM更像一个高层的应用层管理器通常需要游戏有特定的支持或使用较“Hacky”的方式注入。而BepInEx工作在更底层通过标准的.NET程序集加载和Harmony补丁其原理更通用、更稳定侵入性相对可控。功能与灵活性BepInEx直接集成了Harmony给予了开发者近乎无限的代码修改能力。UMM的功能则更多由其社区提供的模板和API定义在某些深度修改上可能受限。社区与生态目前绝大多数新兴的、复杂的Unity游戏模组都优先选择基于BepInEx开发其社区活跃插件资源丰富遇到问题更容易找到解决方案。可以说BepInEx代表了当前Unity游戏模组开发的最先进生产力和最广泛接受的工业标准。3. 5分钟极速上手创建你的第一个“Hello World”插件理论说得再多不如亲手实践。我们现在就来创建一个最简单的插件目标是在游戏启动时在屏幕上打印一条“Hello from BepInEx!”的日志。这将是你的“里程碑0”。3.1 环境准备工欲善其事必先利其器你需要准备以下工具整个过程就像搭积木一样简单.NET SDKBepInEx插件本质上是.NET类库。你需要安装.NET 6.0或更高版本的SDK。去微软官网下载安装即可。安装后在命令行输入dotnet --version确认安装成功。代码编辑器Visual Studio 2022社区版免费或 JetBrains Rider 是首选。它们对C#和.NET开发的支持最完善。VS Code搭配C#插件也是一个轻量级选择。目标游戏与BepInEx选择一个你已经安装的、支持BepInEx的Unity游戏例如《Risk of Rain 2》、《Valheim》。从BepInEx的GitHub发布页下载对应游戏版本或通用版本的BepInEx包并按照其说明安装到游戏根目录。通常就是解压所有文件到游戏exe所在文件夹。3.2 项目创建与配置三步搭建脚手架打开命令行终端我们开始创建项目# 1. 创建一个新的类库项目命名为 MyFirstBepInExPlugin dotnet new classlib -n MyFirstBepInExPlugin -f net6.0 # 2. 进入项目目录 cd MyFirstBepInExPlugin # 3. 添加必要的NuGet包引用 # BepInEx核心库版本号请查询最新稳定版 dotnet add package BepInEx.Core --version 5.4.21 # BepInEx的Harmony库版本号需与核心库匹配 dotnet add package BepInEx.Harmony --version 5.4.21 # 如果你针对的是使用IL2CPP编译的游戏还需要这个 # dotnet add package BepInEx.IL2CPP --version 5.4.21接下来编辑项目文件MyFirstBepInExPlugin.csproj。我们需要将其输出类型明确为类库并确保复制依赖项到输出目录这对于插件部署至关重要。Project SdkMicrosoft.NET.Sdk PropertyGroup TargetFrameworknet6.0/TargetFramework ImplicitUsingsenable/ImplicitUsings Nullableenable/Nullable !-- 关键输出为类库 -- OutputTypeLibrary/OutputType !-- 生成一个与项目同名的dll避免默认的“MyFirstBepInExPlugin.dll” -- AssemblyNameMyFirstBepInExPlugin/AssemblyName /PropertyGroup ItemGroup PackageReference IncludeBepInEx.Core Version5.4.21 / PackageReference IncludeBepInEx.Harmony Version5.4.21 / /ItemGroup !-- 关键发布时将所有依赖的dll复制到输出目录 -- Target NameCopyDependencies AfterTargetsBuild Copy SourceFiles(ReferenceCopyLocalPaths) DestinationFolder$(OutputPath) / /Target /Project3.3 编写核心插件代码从零到一的魔法现在打开自动生成的Class1.cs文件将其彻底重命名为更有意义的HelloWorldPlugin.cs并替换内容如下using BepInEx; using BepInEx.Logging; using UnityEngine; // 命名空间建议与插件名相关避免冲突 namespace MyFirstBepInExPlugin { // 最重要的特性BepInPlugin是插件的身份证。 // GUID必须是全球唯一的通常使用“作者名.插件名”的格式。 // Name和Version会显示在BepInEx的插件管理界面。 [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 定义插件的元数据 public const string PluginGUID com.yourname.helloworld; public const string PluginName Hello World Plugin; public const string PluginVersion 1.0.0.0; // BepInEx提供的日志器用于输出信息到控制台和日志文件 internal static ManualLogSource Log; // Awake方法在插件被加载后立即执行早于游戏的任何场景加载 private void Awake() { // 初始化日志器Logger是BaseUnityPlugin自带的属性 Log Logger; // 这就是我们的“Hello World”日志级别为Info。 Log.LogInfo(Hello from BepInEx! Plugin loaded successfully!); // 我们也可以尝试做一些更“游戏内”的事情比如在游戏UI创建后打印。 // 但Awake阶段UI可能还未就绪更复杂的操作应放在Start或通过Harmony挂钩。 } // Start方法在Awake之后在第一帧更新之前执行 // private void Start() // { // // 可以在这里执行一些需要游戏对象已初始化的操作 // } // Update方法每一帧都会被调用谨慎使用避免性能开销 // private void Update() // { // } } }3.4 编译与部署让插件在游戏中跑起来编译在项目目录下执行dotnet build -c Release。这会在bin/Release/net6.0/目录下生成MyFirstBepInExPlugin.dll以及它依赖的BepInEx库文件。部署找到你安装好BepInEx的游戏根目录进入BepInEx/plugins文件夹。创建一个新的文件夹以你的插件名命名例如MyFirstPlugin然后将上一步生成的MyFirstBepInExPlugin.dll单独复制到这个新文件夹内。重要心得永远将你的插件dll放在plugins下的一个独立子文件夹里。这有利于管理、更新和卸载也符合社区规范。不要直接把dll扔在plugins根目录。测试启动游戏。如果一切顺利你应该能看到游戏正常启动。要验证插件是否生效你需要查看BepInEx的日志。进入游戏根目录的BepInEx/LogOutput.log文件。或者如果游戏支持控制台很多BepInEx安装会默认开启你可以在游戏中按F1或其他快捷键调出控制台窗口。在日志中搜索 “Hello from BepInEx!”如果看到这行信息恭喜你你的第一个BepInEx插件已经成功运行在游戏进程中了。这短短几十行代码就完成了一次从外部向一个正在运行的商业游戏注入代码并执行的全过程。虽然它现在只是打印了一行日志但这条路径一旦打通后面就是广阔的天地。4. 核心技能进阶使用Harmony实现游戏功能修改仅仅打印日志远非BepInEx的威力所在。Harmony库才是让你从“观察者”变为“改造者”的关键。它允许你修改游戏已有的方法。我们来看一个经典场景修改玩家角色的移动速度。假设我们通过反编译或查阅游戏源码如果开源得知控制玩家移动速度的方法位于PlayerController类中名为GetMoveSpeed返回一个float类型的速度值。4.1 Harmony补丁基础前缀、后缀与环绕Harmony主要通过三种类型的补丁来修改方法前缀补丁 (Prefix)在原方法执行之前运行。你可以访问方法的参数甚至可以修改它们或者通过返回false来完全阻止原方法的执行。后缀补丁 (Postfix)在原方法执行之后运行。你可以访问方法的参数、返回值__result以及实例__instance并修改返回值。环绕补丁 (Transpiler)这是高级功能它允许你直接修改方法的IL代码中间语言功能最强大也最复杂通常用于修改方法内部的逻辑流。对于修改移动速度我们使用后缀补丁是最合适的因为我们想在游戏计算完基础速度后再施加我们的修改倍率。4.2 实战实现一个“超级速度”插件让我们在之前的HelloWorldPlugin项目基础上进行扩展。首先确保已引用BepInEx.Harmony包。修改HelloWorldPlugin.cs文件using BepInEx; using BepInEx.Logging; using HarmonyLib; // 引入Harmony命名空间 using UnityEngine; namespace MyFirstBepInExPlugin { [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin { public const string PluginGUID com.yourname.helloworld; public const string PluginName Super Speed Plugin; public const string PluginVersion 1.0.1.0; // 更新版本号 internal static ManualLogSource Log; // 定义一个配置项允许玩家在游戏中调整速度倍率 private static ConfigEntryfloat SpeedMultiplier; private void Awake() { Log Logger; Log.LogInfo(Super Speed Plugin loading...); // 1. 创建配置项 // 参数配置分组可为空配置键名配置描述默认值 SpeedMultiplier Config.Bind(General, // 分组 SpeedMultiplier, // 键 2.0f, // 默认值2倍速度 The multiplier applied to player move speed.); // 描述 Log.LogInfo($Speed multiplier set to: {SpeedMultiplier.Value}); // 2. 应用Harmony补丁 // 这行代码会扫描当前程序集你的插件dll中所有带有[HarmonyPatch]特性的类并创建补丁。 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly); Log.LogInfo(Harmony patches applied.); } } // 新的类专门存放我们的Harmony补丁 [HarmonyPatch] // 声明这是一个Harmony补丁类 public static class PlayerSpeedPatch { // 确定我们要修补的目标方法。 // 这里需要你知道游戏内具体的类名和方法名。这通常通过反编译工具如dnSpy, ILSpy或游戏文档获得。 // 假设目标方法是PlayerController.GetMoveSpeed() [HarmonyPatch(typeof(PlayerController), nameof(PlayerController.GetMoveSpeed))] [HarmonyPostfix] // 指定这是一个后缀补丁 public static void GetMoveSpeed_Postfix(ref float __result, PlayerController __instance) { // __result 是原方法的返回值我们可以修改它。 // __instance 是调用该方法的PlayerController实例。 // 通过ref关键字我们可以修改__result的值。 // 获取插件实例有多种方式这里展示通过查找BepInEx插件对象的方式 var plugin BepInEx.Bootstrap.Chainloader.PluginInfos[HelloWorldPlugin.PluginGUID].Instance as HelloWorldPlugin; if (plugin ! null) { // 应用配置的倍率 __result * plugin.SpeedMultiplier.Value; // 可选记录日志调试时使用正式版建议关闭以避免性能损耗 // HelloWorldPlugin.Log.LogDebug($Speed modified: {__result}); } } } }4.3 配置与热重载让插件更友好上面的代码引入了Config.Bind。BepInEx内置了配置文件系统。编译部署新插件后在BepInEx/config目录下会生成一个以你的PluginGUID命名的.cfg文件例如com.yourname.helloworld.cfg。玩家可以用文本编辑器打开它修改SpeedMultiplier的值。更神奇的是BepInEx支持部分配置的热重载。对于像ConfigEntryfloat这样的简单类型在游戏中修改配置文件并保存后插件下次读取这个值时比如玩家下一次移动时调用GetMoveSpeed就会使用新的倍率无需重启游戏实操心得如何找到正确的类和方法名这是Harmony补丁开发中最具挑战性的一步。你需要借助反编译工具。工具准备使用dnSpy或ILSpy。它们可以打开游戏的主程序集通常是GameAssembly.dll(IL2CPP) 或Assembly-CSharp.dll(Mono)让你浏览所有C#类和方法。搜索关键词在反编译器中搜索你认为可能的关键词如 “MoveSpeed”, “Player”, “Controller”, “Update”。分析调用找到疑似方法后查看谁调用了它以及它内部调用了什么结合游戏行为进行验证。社区与文档许多热门游戏都有活跃的模组社区在GitHub或Discord上经常能找到已有的补丁示例这是最快的入门方式。谨慎测试最初的补丁可能因方法签名参数类型、返回类型不匹配而失败。务必查看BepInEx的日志文件LogOutput.logHarmony会详细报告补丁失败的原因。5. 打造实用插件从UI到存档的完整功能案例让我们整合前面所学创建一个更复杂、更实用的插件一个简单的游戏内图形界面GUI允许玩家实时开关“超级速度”功能并显示当前速度倍率。我们将使用BepInEx社区一个非常流行的UI库BepInEx.ConfigurationManager。不过为了展示原理我们先从最基础的Unity IMGUI开始。5.1 创建可开关的GUI功能我们需要在插件中启用Unity的IMGUI渲染并绘制一个简单的窗口。修改HelloWorldPlugin.cs增加GUI相关逻辑using BepInEx; using BepInEx.Logging; using HarmonyLib; using UnityEngine; namespace MyFirstBepInExPlugin { [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class HelloWorldPlugin : BaseUnityPlugin { public const string PluginGUID com.yourname.helloworld; public const string PluginName Super Speed Plugin with GUI; public const string PluginVersion 1.0.2.0; internal static ManualLogSource Log; private static ConfigEntryfloat SpeedMultiplier; private static ConfigEntrybool SpeedEnabled; // 新增是否启用加速的配置 private static ConfigEntryKeyboardShortcut ToggleUIKey; // 新增切换UI显示的快捷键 // GUI相关变量 private static bool _isWindowVisible false; private static Rect _windowRect new Rect(20, 20, 250, 150); private void Awake() { Log Logger; Log.LogInfo(Super Speed Plugin with GUI loading...); // 初始化配置 SpeedMultiplier Config.Bind(General, SpeedMultiplier, 2.0f, The multiplier applied to player move speed.); SpeedEnabled Config.Bind(General, SpeedEnabled, true, Whether the speed modifier is active.); ToggleUIKey Config.Bind(Hotkeys, ToggleUI, new KeyboardShortcut(KeyCode.F7), // 默认F7开关UI Key to show/hide the plugin GUI.); Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly); } // 我们需要在Unity的渲染循环中绘制GUI // 使用Harmony给Unity的OnGUI方法打补丁是一种方式但更简单的是利用MonoBehaviour的Update和OnGUI。 // 由于BaseUnityPlugin本身也是MonoBehaviour我们可以直接添加这些方法。 private void Update() { // 检查快捷键是否被按下 if (ToggleUIKey.Value.IsDown()) { _isWindowVisible !_isWindowVisible; Log.LogDebug($GUI visibility toggled: {_isWindowVisible}); } } private void OnGUI() { if (!_isWindowVisible) return; // 创建一个IMGUI窗口 _windowRect GUI.Window(0, _windowRect, DrawPluginWindow, Super Speed Control Panel); } private static void DrawPluginWindow(int windowId) { GUILayout.Label($Plugin: {PluginName} v{PluginVersion}); GUILayout.Space(10); // 开关控件 bool newEnabled GUILayout.Toggle(SpeedEnabled.Value, Enable Speed Boost); if (newEnabled ! SpeedEnabled.Value) { SpeedEnabled.Value newEnabled; Log.LogInfo($Speed boost {(newEnabled ? ENABLED : DISABLED)}); } GUILayout.Space(5); GUILayout.Label($Current Multiplier: {SpeedMultiplier.Value:F1}x); // 滑块控件调整倍率 float newMultiplier GUILayout.HorizontalSlider(SpeedMultiplier.Value, 0.5f, 5.0f); if (Mathf.Abs(newMultiplier - SpeedMultiplier.Value) 0.01f) { SpeedMultiplier.Value newMultiplier; // 这里可以立即生效因为我们的Harmony补丁每次都会读取这个值 } GUILayout.Space(10); if (GUILayout.Button(Close)) { _isWindowVisible false; } // 允许窗口被拖动 GUI.DragWindow(new Rect(0, 0, 10000, 20)); } } [HarmonyPatch] public static class PlayerSpeedPatch { [HarmonyPatch(typeof(PlayerController), nameof(PlayerController.GetMoveSpeed))] [HarmonyPostfix] public static void GetMoveSpeed_Postfix(ref float __result, PlayerController __instance) { var plugin BepInEx.Bootstrap.Chainloader.PluginInfos[HelloWorldPlugin.PluginGUID].Instance as HelloWorldPlugin; if (plugin ! null plugin.SpeedEnabled.Value) // 检查是否启用 { __result * plugin.SpeedMultiplier.Value; } } } }现在你的插件拥有了一个可通过F7键开关的图形界面可以实时启用/禁用加速功能并通过滑块调整倍率。所有设置都会自动保存到配置文件中。5.2 使用ConfigurationManager提供更专业的配置界面手动绘制GUI对于简单功能足够但对于复杂的配置项管理起来很麻烦。社区项目BepInEx.ConfigurationManager提供了一个自动生成的、美观的配置窗口。安装在你的插件项目中通过NuGet添加对BepInEx.ConfigurationManager的引用或者让玩家手动将ConfigurationManager.dll放入BepInEx/plugins目录。使用你几乎不需要做任何额外工作只要你使用了Config.Bind()创建的ConfigEntryT对象ConfigurationManager插件就会自动在游戏中默认按F1键的配置管理器里为你的插件生成一个配置页面包含描述、输入框、滑块、下拉菜单等完全自动。这是社区最佳实践极大地提升了插件的用户体验和可维护性。5.3 与其他插件交互与存档安全一个成熟的插件还需要考虑更多依赖管理如果你的插件需要另一个插件例如一个通用的工具库才能运行你可以在你的插件类上添加[BepInDependency]特性来声明依赖BepInEx会在加载你的插件前确保依赖已加载。[BepInDependency(com.other.author.toolkit, BepInDependency.DependencyFlags.HardDependency)] [BepInPlugin(PluginGUID, PluginName, PluginVersion)] public class MyPlugin : BaseUnityPlugin { ... }存档兼容性永远记住通过Harmony修改游戏状态如玩家属性、物品数据可能会影响存档。如果你的修改是持久的例如永久增加了背包大小你需要考虑修改是否应该随存档保存如果是你可能需要挂钩游戏的保存/加载方法将自定义数据序列化进去。这非常复杂且极易导致存档损坏。最安全的做法是让所有修改都是临时的、运行时生效的就像我们的速度倍率插件一样关闭插件或重启游戏一切恢复原样。这保证了存档的纯净性和兼容性。如果必须修改存档务必提供明确的警告并做好备份。6. 调试、打包与发布全流程指南开发完成后你需要测试、打包并分享你的作品。6.1 调试技巧定位问题的火眼金睛日志是你的第一朋友Logger.LogDebug/Info/Warning/Error是基本操作。在关键分支、循环开始结束处打上日志能清晰追踪程序流。控制台与日志文件BepInEx/LogOutput.log包含所有BepInEx和插件的日志。游戏内控制台如果启用可以实时查看。使用Debug构建开发时使用dotnet build -c Debug。这会生成调试符号.pdb文件当游戏崩溃时日志能给出具体的代码行号而不是模糊的偏移地址。Harmony Debug模式在Awake中创建Harmony实例时可以传入一个唯一的ID并启用调试var harmony new Harmony(com.yourname.plugin); harmony.PatchAll();。同时确保BepInEx.cfg中[Logging]下的UnityLogListening和DiskWriteEnabled设为trueLogLevels包含All。这会让Harmony输出详细的补丁应用信息。6.2 插件打包规范让分享更轻松一个规范的插件包应该让玩家“解压即用”。通常的目录结构如下YourAwesomePlugin_v1.0.0.zip │ ├── README.md // 说明文档介绍功能、安装方法、快捷键等 ├── CHANGELOG.md // 更新日志 │ └── BepInEx └── plugins └── YourAwesomePlugin // 以插件名命名的文件夹 ├── YourAwesomePlugin.dll // 主插件文件 ├── YourAwesomePlugin.dll.config // 可选配置文件模板 ├── YourAwesomePlugin.pdb // 可选调试符号文件 └── manifest.json // 推荐Thunderstore等模组平台需要的元数据文件manifest.json是模组平台如Thunderstore的标准包含插件名、版本号、作者、依赖、下载链接等。使用r2modman或Thunderstore的打包工具可以自动生成。6.3 发布与版本管理本地测试在多个游戏场景、存档中充分测试确保没有崩溃、内存泄漏和严重的性能问题。版本号语义化遵循主版本号.次版本号.修订号.构建号如1.2.3.456的规则。重大不兼容更新升主版本新增功能升次版本修复Bug升修订号。选择发布平台GitHub Releases适合技术用户便于跟踪issue和代码。Thunderstore当前最流行的《英灵神殿》、《雨中冒险2》等游戏的模组集散地有方便的模组管理器集成。Nexus Mods老牌模组网站用户基数大。游戏专属社区如Discord频道、贴吧、Reddit版块。编写清晰的文档在README.md中必须包含功能简介安装步骤一步步来配置说明如何修改设置已知问题常见问题解答FAQ致谢与引用7. 避坑指南与最佳实践实录在多年的BepInEx插件开发中我踩过无数坑也总结出一些让插件更稳定、更受欢迎的经验。7.1 性能与安全稳定性的基石慎用Update方法除非必要不要在插件的Update方法里写逻辑尤其是每帧执行的复杂计算。这会给游戏带来不必要的性能开销。如果需要检测按键或定时执行考虑使用协程StartCoroutine或InvokeRepeating并降低频率。缓存引用避免重复查找例如不要在每个Update里用GameObject.Find或GetComponent去查找对象。在Start或Awake中找到并缓存它们。Harmony补丁要精准尽量使用最具体的方法签名进行补丁。避免使用[HarmonyPatchAll]这种全局补丁它可能会意外修补到你不希望修改的方法导致不稳定。处理异常在Harmony补丁和可能出错的地方使用try-catch块并将异常记录到日志而不是让游戏崩溃。[HarmonyPostfix] public static void MyPatch(ref float __result) { try { // 你的逻辑 } catch (System.Exception e) { MyPlugin.Log.LogError($Patch failed: {e}); } }7.2 兼容性与协作社区生存法则命名空间和GUID必须唯一这是铁律。使用反向域名格式的GUID如com.yourname.modname能最大程度避免冲突。声明依赖与冲突使用[BepInDependency]和[BepInIncompatibility]特性清晰地表明你的插件与其他插件的关系。避免“暴力”修改有些插件会直接覆盖游戏的核心文件或使用过于激进的Harmony补丁这极易与其他模组冲突。优先使用事件、回调等非侵入式方式或者与社区协商建立公共的API接口。关注游戏更新游戏每次更新都可能改变类和方法的结构导致你的Harmony补丁失效。建立快速的测试和修复流程并在插件页面明确标注支持的游戏版本号。7.3 常见问题速查表问题现象可能原因排查步骤插件未加载日志无信息1. DLL未放在BepInEx/plugins/子文件夹下。2. DLL依赖项缺失。3. 插件目标.NET框架与游戏不匹配。1. 检查文件路径。2. 使用ILSpy打开你的DLL查看引用的依赖是否都存在。3. 确保插件编译目标与游戏运行的.NET版本兼容通常为.NET Framework 4.x或.NET Standard 2.0。游戏启动时崩溃1. Harmony补丁目标方法签名错误。2. 在Awake中访问了尚未初始化的游戏对象。3. 插件代码存在未处理的异常。1. 查看LogOutput.log末尾的堆栈跟踪定位崩溃点。2. 检查Harmony补丁的类名、方法名、参数类型是否完全正确。3. 将代码分段注释定位问题代码。功能不生效但插件已加载1. Harmony补丁未成功应用。2. 配置项未正确绑定或读取。3. 条件判断逻辑有误如SpeedEnabled为false。1. 在日志中搜索“Harmony”字样查看补丁应用报告。2. 在插件初始化时打印配置值到日志。3. 在补丁方法入口处添加日志确认是否被执行。与其他模组冲突1. 修改了同一游戏方法。2. 全局事件监听冲突。3. 使用了相同的单例或静态资源。1. 禁用其他模组逐一启用定位冲突对象。2. 检查冲突模组的描述看是否有已知兼容性问题。3. 尝试调整插件加载顺序通过依赖声明。配置修改不生效1. 未使用ConfigEntryT.Value属性。2. 配置项是值类型且插件缓存了旧值。3. 配置文件路径错误或只读。1. 确保通过Config.Bind创建ConfigEntry并读写其Value属性。2. 每次使用配置时都直接读取Value不要用局部变量缓存。3. 检查BepInEx/config目录下是否正确生成了.cfg文件。开发BepInEx插件的旅程就像是在一个精密的机械手表内部添加自己设计的齿轮。你需要耐心、细致并对原有结构充满敬畏。但一旦你掌握了这套工具就获得了重塑游戏体验的惊人能力。从简单的功能调整到复杂的系统重写边界只在于你的想象力与对游戏的理解深度。记住强大的力量也意味着责任始终以不破坏他人游戏体验和存档安全为前提进行创作你的插件才会在社区中走得更远。现在启动你的IDE选择一个你热爱的游戏开始你的模组开发之旅吧。
