Unity游戏模组开发入门：BepInEx框架原理与Harmony实战指南

1. 项目概述：为什么BepInEx是Unity模组开发的基石？

如果你是一名Unity游戏玩家，尤其是对《雨中冒险2》、《英灵神殿》、《星露谷物语》这类支持模组的游戏情有独钟，那你大概率听说过BepInEx。它不是一个游戏，而是一个强大的、开源的插件框架，专门为Unity引擎开发的游戏提供模组加载支持。简单来说，它就像一座桥梁，一端连接着游戏本体，另一端连接着无数由社区开发者创造的、千奇百怪的模组（Mod）。没有这座桥，模组就无法被游戏识别和运行。

我最初接触BepInEx，是因为想在某个游戏里添加一个简单的UI调整功能。当时尝试了各种“注入”方法，过程繁琐且极不稳定，一个游戏更新就能让所有努力白费。直到用了BepInEx，我才发现模组开发可以如此规范、高效和可持续。它的核心价值在于提供了一套标准化的“协议”，让模组开发者无需再与游戏底层代码“肉搏”，而是通过一个清晰、稳定的接口进行交互。这不仅降低了开发门槛，更极大地提升了模组的兼容性和可维护性。无论你是想修改游戏数值、添加新物品、还是彻底改变游戏机制，BepInEx都是你绕不开的起点。

本指南的目标，就是带你从零开始，彻底掌握BepInEx。我们不仅会一步步完成安装和配置，更会深入其内部机制，理解它是如何工作的，并最终让你能够独立开发、调试和发布自己的Unity游戏模组。无论你是刚入门的爱好者，还是有一定编程基础想涉足模组领域的开发者，这篇指南都将提供一条从“安装”到“精通”的清晰路径。

2. BepInEx核心架构与工作原理深度解析

在动手安装之前，理解BepInEx是如何“嵌入”并“运作”于一个Unity游戏中的，至关重要。这能帮助你在后续开发中避开许多坑，并在出现问题时快速定位。

2.1 启动流程与“预加载器”机制

Unity游戏的标准启动流程是：游戏启动器（如.exe）加载Unity Player，然后Unity Player加载游戏的核心数据文件（如GameAssembly.dll、UnityPlayer.dll等），最后执行游戏逻辑。BepInEx的核心魔法，就发生在这个流程被“劫持”的瞬间。

BepInEx的核心组件是一个名为winhttp.dll（在Windows上）的“预加载器”（Preloader）。这个文件被放置在游戏根目录下，与游戏主程序同名但扩展名是.dll。当操作系统启动游戏时，它会按照一定的顺序加载程序所依赖的动态链接库（DLL）。BepInEx利用了这个机制，确保它的winhttp.dll会在游戏自己的核心库之前被加载。

一旦BepInEx的预加载器被加载，它就会立即接管控制权。它的工作包括：

  1. 初始化内部环境：准备BepInEx自己的日志系统、配置系统。
  2. 加载核心库：从BepInEx/core目录加载BepInEx.dll等核心文件。
  3. 修补游戏程序集：这是最关键的一步。BepInEx使用类似Mono.Cecil这样的库，在内存中读取、修改游戏的主程序集（通常是GameAssembly.dll或Assembly-CSharp.dll）。它会在游戏的启动方法（如Awake、Start）中插入自己的“钩子”（Hook），为后续加载插件代码创造执行时机。
  4. 移交控制权：完成修补后，将控制权交还给游戏原本的启动流程。此时，游戏本身几乎感知不到任何变化，但它的代码里已经埋下了BepInEx的“伏笔”。

注意：这种“DLL注入”方式是非侵入式的。它不修改游戏的任何原始磁盘文件，所有操作都在内存中进行。这意味着它相对安全，且通常不会被简单的反作弊系统误判（但联机游戏仍需谨慎，遵守游戏规则）。游戏更新后，BepInEx只需要重新运行一次这个流程即可，你的模组文件（.dll）通常无需改动。

2.2 插件加载与生命周期管理

当游戏完成启动，进入Unity的运行时环境后，BepInEx核心便开始执行它的第二阶段任务：加载插件。

  1. 扫描插件目录：BepInEx会扫描游戏根目录下的BepInEx/plugins文件夹及其子文件夹。
  2. 识别插件：它会寻找所有有效的.NET程序集（.dll文件），并检查其中是否包含继承了BaseUnityPlugin的类。这个类是BepInEx插件的唯一标识。
  3. 实例化与初始化：对于找到的每一个插件类，BepInEx会创建其实例，并依次调用其生命周期方法：
    • Awake(): 当插件被加载时立即调用。这是进行一次性初始化操作（如读取配置、订阅事件）的最佳位置。
    • Start(): 在所有插件的Awake方法都执行完毕后调用。适合进行需要依赖其他插件初始化的操作。
    • Update(),FixedUpdate(),OnGUI(): 如果插件需要每帧更新或进行GUI绘制，可以重写这些方法，它们会对应Unity引擎的同名消息。
  4. 依赖管理与排序：BepInEx支持通过插件的元数据（[BepInDependency]特性）来声明依赖关系，确保被依赖的插件先加载。这对于大型模组生态非常重要。

2.3 核心服务：配置、日志与 Harmony 补丁

除了加载插件，BepInEx还内置了三个对开发者至关重要的服务：

  • 配置系统 (BepInEx.Configuration)：提供了一个简单易用的API，让插件可以定义、保存和加载用户配置。配置会自动保存为BepInEx/config目录下的.cfg文件，格式清晰可读。开发者可以定义整数、浮点数、字符串、布尔值甚至枚举和自定义类的配置项，并为其提供描述、默认值和范围约束。

  • 日志系统 (BepInEx.Logging)：一个统一的日志门面。插件可以通过它记录信息、警告和错误。所有日志会同时输出到控制台（如果启用）和BepInEx/LogOutput.log文件中。这比Unity原生的Debug.Log更强大，便于调试和问题追踪。

  • Harmony 集成：这是BepInEx的灵魂所在。Harmony是一个强大的.NET库，用于在运行时对已编译的方法进行“打补丁”（Patch）。BepInEx无缝集成了Harmony，让插件开发者能够：

    • 前缀补丁 (Prefix)：在目标方法执行前运行你的代码。你可以修改方法的参数，甚至可以完全阻止原方法的执行。
    • 后缀补丁 (Postfix)：在目标方法执行后运行你的代码。你可以读取和修改方法的返回值，或者访问执行后的状态。
    • 中转补丁 (Transpiler)：这是最强大的功能，允许你直接修改目标方法的IL指令（中间语言）。这可以用来实现极其复杂的修改，比如改变循环逻辑、插入新的判断等。

正是通过Harmony，模组开发者才能在不拥有游戏源代码的情况下，改变游戏几乎任何部分的行为。理解Harmony是进阶模组开发的关键。

3. 从零开始：BepInEx的安装与配置详解

理论说再多，不如动手装一遍。这里我们以Windows平台下最常见的Unity游戏为例，演示最通用的安装流程。

3.1 环境准备与文件获取

首先，你需要确定两件事：

  1. 目标游戏：选择一个你熟悉且支持BepInEx的Unity游戏。通常，游戏在Nexus Mods、GitHub等社区的模组页面会注明所需框架。例如，《雨中冒险2》（Risk of Rain 2）就是BepInEx的“明星”应用。
  2. 游戏版本：确保你下载的BepInEx版本与游戏版本兼容。通常，BepInEx的GitHub发布页会说明其支持的Unity引擎版本范围。

步骤一：下载BepInEx前往BepInEx的官方GitHub仓库（通常是https://github.com/BepInEx/BepInEx/releases）。不要从不明来源下载，以免包含恶意软件。

  • 对于大多数x64架构的Unity游戏，下载BepInEx_x64_VERSION.zip。
  • 对于较旧的x86游戏，则下载BepInEx_x86_VERSION.zip。
  • 下载后，将其解压到一个临时文件夹。

步骤二：定位游戏根目录找到你的游戏安装位置。例如，在Steam上，你可以在游戏库中右键点击游戏 -> “管理” -> “浏览本地文件”。这个打开的文件夹就是“游戏根目录”，里面应该能看到游戏的主执行文件（.exe）和一些核心DLL。

3.2 标准安装流程与验证

安装操作：

  1. 将解压后的BepInEx临时文件夹里的所有文件和文件夹，直接复制到你的游戏根目录。
  2. 当系统询问是否合并或替换文件时，选择“是”。首次安装通常不会有冲突。

首次运行与验证：

  1. 像平常一样，通过Steam或游戏启动器启动游戏。
  2. 游戏启动时，你可能会看到一个控制台窗口一闪而过（这是BepInEx的日志输出）。如果游戏正常启动并进入主菜单，说明安装基本成功。
  3. 退出游戏。
  4. 再次查看游戏根目录，你应该会看到一个新的BepInEx文件夹已经生成。进入该文件夹，检查以下子目录是否已存在：
    • core/: 存放BepInEx核心库，切勿手动修改。
    • plugins/:这是你未来放置自己或他人开发的模组.dll文件的地方。初始为空。
    • config/: 存放各个插件的配置文件（.cfg）。
    • patchers/: 用于存放特殊的“补丁器”插件（较少使用）。
    • LogOutput.log: 这是最重要的日志文件。如果安装或运行有任何问题，首先查看这个文件。

打开LogOutput.log，你应该能看到类似以下的日志，这表明BepInEx已成功加载：

[Info : BepInEx] BepInEx 5.4.21.0 - {游戏名} [Message: BepInEx] Running under Unity v2019.4.40.XXXX [Info : BepInEx] Preloader started [Info : BepInEx] 1 patcher plugin loaded [Info : BepInEx] Patching [游戏程序集]... [Info : BepInEx] Preloader finished [Info : BepInEx] Chainloader started [Info : BepInEx] 0 plugins to load [Info : BepInEx] Chainloader finished

3.3 高级配置与疑难排查

BepInEx文件夹下还有一个重要的文件：BepInEx.cfg。这是BepInEx自身的配置文件，用文本编辑器打开即可修改。

常用配置项：

  • [Logging.Console]下的Enabled: 设置为true可以保持控制台窗口开启，方便调试时实时查看日志。发布给玩家时建议关闭。
  • [Logging.File]下的Enabled: 是否启用文件日志，始终建议保持true。
  • [Chainloader]下的DoorstopEnabled: 这是控制预加载器是否启用的总开关。如果设置为false，BepInEx将完全不起作用。可用于临时禁用所有模组。

常见安装问题排查：

  1. 游戏无法启动或瞬间闪退：

    • 首先检查日志：查看LogOutput.log的最后几行错误信息。
    • 版本不匹配：最常见的原因。确认BepInEx版本是否支持游戏的Unity版本。游戏大更新后，可能需要等待BepInEx更新。
    • 防病毒软件误报：某些杀毒软件会将注入行为的winhttp.dll视为威胁。将游戏目录添加到杀软的白名单中。
    • 文件位置错误：确保所有BepInEx文件直接在游戏根目录，而不是在某个子文件夹里。

  2. BepInEx文件夹未生成：

    • 说明预加载器未能成功运行。检查winhttp.dll（或doorstop_config.ini）是否存在且位置正确。
    • 对于某些使用Mono后端而非IL2CPP的Unity老游戏，可能需要使用UnityInjector等不同版本的BepInEx或安装器。

  3. 插件未加载：

    • 检查插件.dll文件是否放在了BepInEx/plugins目录下（或其子目录）。
    • 查看日志，确认插件是否被识别。如果插件有依赖项未满足，也会导致加载失败。

4. 开发环境搭建与第一个“Hello World”插件

现在，BepInEx已经在你的游戏里跑起来了。是时候创建我们的第一个插件了。我们将使用Visual Studio 2022（社区版免费）和.NET Framework进行开发。

4.1 创建插件项目与配置依赖

  1. 新建项目：打开Visual Studio，选择“创建新项目” -> “类库(.NET Framework)”。项目名称可以叫MyFirstBepInExPlugin，目标框架选择.NET Framework 4.7.2或.NET Framework 4.8。这是与大多数Unity游戏运行时兼容的版本。
  2. 安装必要的NuGet包：在解决方案资源管理器中右键点击项目 -> “管理NuGet程序包”。浏览并安装以下两个包：
    • BepInEx.Core：这是BepInEx插件的核心接口和基类。
    • BepInEx.Harmony：这是集成Harmony库所必需的。如果你确定你的插件不需要打补丁（只做简单的配置或GUI），可以不装。但绝大多数模组都需要它。
  3. 引用游戏程序集：为了调用游戏内部的类和方法，我们需要引用游戏的程序集。在游戏根目录的{游戏名}_Data/Managed文件夹下，找到Assembly-CSharp.dll（对于Mono游戏）或解包后得到的DLL（对于IL2CPP游戏，需要使用工具如Il2CppDumper）。在VS项目中，右键“引用” -> “添加引用” -> “浏览”，找到并添加这个DLL文件。

    实操心得：对于IL2CPP游戏，直接引用GameAssembly.dll是没用的，因为它是C++编译的。必须使用专门的解包工具获取可引用的C#程序集。这个过程稍复杂，建议先从Mono架构的游戏开始练习。

4.2 编写插件主类与基础生命周期

删除VS自动创建的Class1.cs，新建一个类文件，例如HelloWorldPlugin.cs。

using BepInEx; using BepInEx.Logging; using UnityEngine; // 最重要的特性：标识这是一个BepInEx插件。 // GUID必须是全球唯一的，通常使用“作者名.插件名”的格式。 // 插件名和版本号会显示在BepInEx的日志中。 [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)] public class HelloWorldPlugin : BaseUnityPlugin // 必须继承BaseUnityPlugin { // 内部日志记录器，用于向BepInEx的日志系统输出信息。 internal static ManualLogSource Log; // Awake方法是插件的入口点，在插件被加载时调用一次。 private void Awake() { // 将本类的Logger实例赋值给静态变量，方便其他方法调用。 Log = Logger; // 使用BepInEx的日志系统，而不是Unity的Debug.Log。 Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 已加载！"); // 订阅Unity的日志消息，方便捕获游戏本身的错误（可选）。 Application.logMessageReceived += OnUnityLog; // 示例：创建一个简单的配置项。 var myConfigEntry = Config.Bind("通用设置", // 配置章节 "欢迎信息", // 配置项键名 "你好，世界！", // 默认值 "这是显示在屏幕上的欢迎语"); // 描述 // 我们可以在这里调用一个方法，在游戏屏幕上显示这个配置项的值。 // 但UI绘制通常在OnGUI中进行，这里我们先打印到日志。 Log.LogInfo($"配置的欢迎信息是：{myConfigEntry.Value}"); } private void OnUnityLog(string condition, string stackTrace, LogType type) { // 可以将Unity的日志转发到BepInEx日志，便于统一查看。 if (type == LogType.Error || type == LogType.Exception) { Log.LogError($"[Unity] {condition}\n{stackTrace}"); } } // 如果插件需要每帧更新，可以重写Update方法。 // private void Update() { ... } // 当插件被卸载时（游戏退出），会调用OnDestroy。 private void OnDestroy() { Application.logMessageReceived -= OnUnityLog; Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 已卸载。"); } } // 通常将元信息放在一个单独的静态类中，保持主类整洁。 public static class PluginInfo { public const string PLUGIN_GUID = "com.yourname.helloworld"; public const string PLUGIN_NAME = "你好世界插件"; public const string PLUGIN_VERSION = "1.0.0"; }

4.3 编译、部署与测试

  1. 编译项目：在Visual Studio中，选择“生成” -> “生成解决方案”。如果一切顺利，会在项目的bin/Debug或bin/Release文件夹下生成一个.dll文件（例如MyFirstBepInExPlugin.dll）。
  2. 部署插件：将这个生成的.dll文件，复制到你的游戏目录下的BepInEx/plugins文件夹中。你可以为你的插件单独创建一个子文件夹，如BepInEx/plugins/MyFirstPlugin/，这样更整洁。
  3. 测试运行：
    • 启动游戏。
    • 观察BepInEx的控制台窗口或打开LogOutput.log文件。
    • 你应该能看到类似这样的日志，证明你的插件已被成功加载并执行了Awake()方法：
      [Info : BepInEx] Loading [你好世界插件 1.0.0] [Info : BepInEx] Loading [HarmonyX 2.10.1] [Info : BepInEx] Loading completed [Info : com.yourname.helloworld] 插件 你好世界插件 已加载！ [Info : com.yourname.helloworld] 配置的欢迎信息是：你好，世界！
  4. 验证配置：退出游戏，检查BepInEx/config目录。你应该会看到一个以你的插件GUID命名的.cfg文件，例如com.yourname.helloworld.cfg。用文本编辑器打开，可以看到我们定义的配置项已经被持久化保存了。

至此，你已经成功创建并运行了第一个BepInEx插件！它虽然还没对游戏产生任何实际影响，但已经具备了完整的生命周期、日志和配置功能，这是所有复杂模组的基础。

5. 深入实战：使用Harmony修改游戏行为

“Hello World”只是开始，模组的真正力量在于改变游戏。接下来，我们将使用Harmony来实际修改一个游戏行为。假设我们想修改一个游戏：让玩家每次跳跃的高度变为原来的两倍。

5.1 分析目标与定位方法

首先，我们需要知道游戏里控制玩家跳跃的方法是哪个。这通常需要一些“侦查”工作：

  1. 使用反编译工具：如dnSpy或ILSpy，打开游戏的Assembly-CSharp.dll。搜索与“Jump”、“Player”、“Character”相关的类和方法名。这需要一些耐心和对游戏代码结构的猜测。
  2. 观察与假设：通常，跳跃逻辑会在PlayerController、CharacterMotor或FirstPersonController这样的类中。方法名可能是Jump、DoJump、PerformJump等。
  3. 找到目标：假设我们找到了一个名为PlayerController的类，里面有一个public void Jump()方法。我们的目标就是修改这个方法。

5.2 创建Harmony补丁类

在插件项目中，新建一个类文件JumpPatch.cs。

using HarmonyLib; // 引入Harmony命名空间 using UnityEngine; namespace MyFirstBepInExPlugin.Patches { // HarmonyPatch特性用于指定要修补的类和方法。 // 第一个参数是目标类，第二个参数是目标方法。 // 如果方法有重载，可能需要指定方法参数类型。 [HarmonyPatch(typeof(PlayerController))] [HarmonyPatch(nameof(PlayerController.Jump))] // 使用nameof更安全 internal static class JumpPatch { // Prefix补丁：在原方法执行前运行。 // 返回类型为bool，如果返回false，则会阻止原方法执行。 // 通常使用原方法的参数（如果有）作为自己的参数。 // 这里原方法无参数，我们也不阻止它执行。 static void Prefix(PlayerController __instance) { // __instance 是Harmony自动提供的，代表调用该方法的PlayerController实例。 // 我们可以在这里访问和修改实例的字段。 // 假设PlayerController有一个public float jumpForce字段。 // 我们将其值翻倍。 __instance.jumpForce *= 2f; // 使用我们插件主类的日志器记录一下 HelloWorldPlugin.Log.LogInfo($"跳跃力已被修改为：{__instance.jumpForce}"); } // Postfix补丁：在原方法执行后运行。 // 适合在游戏执行了跳跃物理计算后，再进行一些操作。 // static void Postfix(PlayerController __instance) { ... } } }

5.3 在插件启动时应用补丁

仅仅定义补丁类是不够的，我们需要在插件加载时创建一个Harmony实例并应用这些补丁。修改HelloWorldPlugin.cs的Awake方法：

private void Awake() { Log = Logger; Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 已加载！"); // 应用所有用[HarmonyPatch]标记的补丁 // 参数是你的插件的GUID，通常用于在Harmony内部标识这一组补丁。 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly, PluginInfo.PLUGIN_GUID); Log.LogInfo("Harmony补丁已应用！"); }

Harmony.CreateAndPatchAll会扫描当前程序集（即你的插件dll）中所有带有[HarmonyPatch]特性的类，并自动为它们创建和应用补丁。

5.4 测试与调试

  1. 重新编译并部署插件dll。
  2. 启动游戏，进入一个可以跳跃的场景。
  3. 尝试跳跃。你应该会跳得比平时高很多。
  4. 查看游戏日志，确认看到了我们添加的日志信息：跳跃力已被修改为：...。

重要注意事项与心得：

  1. 字段名是猜测的：上面的jumpForce字段名是示例。实际开发中，你必须通过反编译工具精确确认字段或属性的名称和类型。拼写错误或类型不匹配会导致游戏崩溃或补丁无效。
  2. 补丁的副作用：直接修改jumpForce这样的字段可能会产生连锁反应，比如影响动画、音效或其他依赖于该字段值的系统。最稳妥的做法是使用**后缀补丁(Postfix)**来修改跳跃后的速度向量。例如，找到实际给玩家角色施加垂直速度的方法（可能是Rigidbody.AddForce或修改velocity），在那个方法之后去修改速度值。
  3. 使用Transpiler进行精细控制：如果简单的Prefix/Postfix无法满足需求（例如需要修改方法内部的逻辑判断），就需要学习使用Transpiler。它操作IL指令，学习曲线陡峭，但功能最强大。网上有很多Harmony Transpiler的教程和示例。
  4. 兼容性：你的补丁修改了游戏代码。如果游戏更新，目标方法签名（参数、返回类型）或内部逻辑发生了变化，你的补丁可能会失效甚至导致游戏崩溃。这是模组开发者的常态，需要持续维护。

6. 构建完整模组：配置、本地化与用户交互

一个成熟的模组不仅仅是功能，还需要良好的用户体验。这包括可配置性、可能的本地化支持以及清晰的用户交互（UI）。

6.1 实现复杂的配置系统

BepInEx的配置系统非常灵活。让我们扩展之前的跳跃模组，让倍增系数可由用户配置。

在HelloWorldPlugin.cs的Awake方法中，更完善地定义配置：

public static ConfigEntry<float> JumpMultiplier; public static ConfigEntry<KeyboardShortcut> ToggleKey; // 使用KeyboardShortcut类型支持快捷键 public static ConfigEntry<bool> EnableDoubleJump; private void Awake() { Log = Logger; Log.LogInfo($"插件 {PluginInfo.PLUGIN_NAME} 已加载！"); // 1. 定义跳跃力乘数配置 JumpMultiplier = Config.Bind("游戏性调整", "跳跃高度乘数", 2.0f, new ConfigDescription("调整玩家跳跃高度的倍数。", new AcceptableValueRange<float>(0.5f, 5.0f))); // 定义可接受范围 // 2. 定义开关快捷键 ToggleKey = Config.Bind("控制", "功能开关快捷键", new KeyboardShortcut(KeyCode.F10), // 默认F10 "按此快捷键可开启/关闭跳跃修改功能。"); // 3. 定义是否启用二段跳 EnableDoubleJump = Config.Bind("游戏性调整", "启用二段跳", false, "是否允许玩家在空中进行第二次跳跃。"); // 应用补丁 Harmony.CreateAndPatchAll(typeof(HelloWorldPlugin).Assembly, PluginInfo.PLUGIN_GUID); }

然后，修改我们的JumpPatch类，使用配置值：

[HarmonyPatch(typeof(PlayerController))] [HarmonyPatch(nameof(PlayerController.Jump))] internal static class JumpPatch { // 假设一个静态变量来控制功能开关 public static bool IsModEnabled = true; static void Prefix(PlayerController __instance) { // 检查功能是否开启 if (!IsModEnabled) return; // 使用配置的乘数，而不是写死的2f __instance.jumpForce *= HelloWorldPlugin.JumpMultiplier.Value; HelloWorldPlugin.Log.LogInfo($"跳跃力已被修改为：{__instance.jumpForce} (乘数: {HelloWorldPlugin.JumpMultiplier.Value})"); } // 可以再写一个补丁来监听按键，用于开关功能 // 例如，补丁游戏的Update方法，检查ToggleKey是否被按下 }

用户现在可以在游戏外的BepInEx/config/com.yourname.helloworld.cfg文件中修改这些值，或者使用专门的“配置管理器”模组在游戏内图形化修改。

6.2 添加简单的游戏内GUI（使用IMGUI）

对于需要在游戏内显示状态或提供简单交互的模组，可以使用Unity的即时模式GUI（IMGUI）。在插件的OnGUI方法中实现。

首先，在HelloWorldPlugin类中添加：

private void OnGUI() { if (!ShowGUI) return; // 用一个配置项控制是否显示GUI // 创建一个简单的窗口 GUI.Window(0, new Rect(20, 20, 200, 150), DrawModWindow, "我的模组控制面板"); } private void DrawModWindow(int windowID) { GUILayout.Label($"跳跃乘数: {JumpMultiplier.Value:F1}"); GUILayout.Label($"功能状态: {(JumpPatch.IsModEnabled ? "开启" : "关闭")}"); if (GUILayout.Button("切换开关")) { JumpPatch.IsModEnabled = !JumpPatch.IsModEnabled; } // 一个简单的滑块，用于实时调整乘数（注意：这修改的是内存中的值，需要手动保存到配置） float newMultiplier = GUILayout.HorizontalSlider(JumpMultiplier.Value, 0.5f, 5.0f); if (Mathf.Abs(newMultiplier - JumpMultiplier.Value) > 0.01f) { JumpMultiplier.Value = newMultiplier; // 如果需要立即生效，可以在这里触发一些更新逻辑 } if (GUILayout.Button("保存配置")) { // 将修改后的配置写回文件 // BepInEx的ConfigEntry在赋值后通常会自动保存，但强制保存更安全 // Config.Save(); 或者直接访问Config文件 } GUI.DragWindow(); // 允许拖动窗口 }

别忘了在配置中添加一个ShowGUI的ConfigEntry来控制GUI显示。

6.3 模组打包与发布指南

当你完成开发并测试无误后，就可以打包分享了。

  1. 发布配置：在Visual Studio中，将项目生成配置切换到“Release”，然后重新生成。使用Release版本的dll，它经过了优化，体积更小，且不包含调试符号。
  2. 组织文件结构：创建一个清晰的文件夹结构来打包你的模组。
    MyAwesomeMod/ ├── README.md // 说明文档，包含安装、配置、功能介绍 ├── CHANGELOG.md // 更新日志 ├── manifest.json // 如果发布到Thunderstore等模组平台，需要此文件 ├── icon.png // 模组图标 └── plugins/ └── MyAwesomeMod/ ├── MyAwesomeMod.dll // 主插件文件 ├── MyAwesomeMod.dll.config // 如果有特殊依赖配置 └── (其他依赖的dll，如果有)
  3. 编写说明文档：README.md至关重要。应包含：
    • 模组名称和简短描述。
    • 安装方法（直接拖放plugins/MyAwesomeMod文件夹到游戏的BepInEx/plugins下）。
    • 配置说明（每个配置项是做什么的）。
    • 已知问题或与其他模组的兼容性说明。
    • 如何获取帮助或报告Bug。
  4. 选择发布平台：
    • GitHub：适合开源项目，便于版本管理和问题追踪。
    • Nexus Mods：最大的模组社区之一，有完善的分类、图片展示和下载统计。
    • Thunderstore：特别是对于支持r2modman等模组管理器的游戏，Thunderstore集成度很高。
  5. 版本管理：使用语义化版本控制（如主版本.次版本.修订号）。每次发布新版本时，更新插件代码中的PLUGIN_VERSION常量，并在CHANGELOG.md中说明更改内容。

7. 高级主题与性能调优

当你的模组变得越来越复杂，或者你开始开发影响范围更大的模组时，就需要关注以下高级主题。

7.1 处理IL2CPP游戏

现代Unity游戏越来越多地使用IL2CPP后端来编译，它将C#代码转换为C++，再进行编译，极大地提高了性能和安全性，但也让模组开发变得更复杂。

关键变化：

  • 没有Assembly-CSharp.dll：你无法直接引用游戏程序集。取而代之的是一个巨大的GameAssembly.dll（Windows上）或libil2cpp.so（Linux/Android上），这是原生的二进制文件。
  • 需要解包：你必须使用如Il2CppDumper、MelonLoader中的Il2CppAssemblyUnhollower等工具，从原生二进制文件中“恢复”出可供C#引用的“伪”程序集（例如Assembly-CSharp.dll）。这个过程称为“Unhollowing”。
  • 补丁目标不同：你补丁的类和方法，实际上是工具生成的“外壳”类。Harmony补丁的原理不变，但目标方法所在的程序集变了。

开发流程调整：

  1. 使用Il2CppDumper对游戏的GameAssembly.dll和global-metadata.dat进行处理，生成dump.cs（所有类和方法的信息）和script.json。
  2. 使用Il2CppAssemblyUnhollower，以上述文件为输入，生成一个可以添加到VS项目中的Assembly-CSharp.dll文件。
  3. 后续的Harmony补丁开发流程，与Mono版本基本一致，但需要确保你使用的BepInEx版本支持IL2CPP（BepInEx 5.x 通常通过BepInEx.Unity.IL2CPP包来支持）。

7.2 性能考量与优化技巧

不恰当的模组代码可能导致游戏卡顿或崩溃。

  1. 避免在Update中执行重型操作：Update每帧调用。如果你需要在其中检查某些条件，使用简单的布尔判断或计时器，避免每帧进行复杂的计算、查找对象（GameObject.Find）或分配新内存（如new List<>()）。
    private float _nextCheckTime; private void Update() { if (Time.time < _nextCheckTime) return; _nextCheckTime = Time.time + 1.0f; // 每1秒检查一次 // ... 执行你的检查逻辑 }
  2. 缓存引用：对于需要频繁访问的游戏对象或组件，在Awake或Start中获取它们的引用并保存到字段中，而不是每次使用时都去查找。
  3. 谨慎使用OnGUI：IMGUI本身性能开销较大。确保只在必要时绘制GUI，并且GUI逻辑尽可能简单。对于复杂UI，社区有更高效的解决方案，如使用UnityEngine.UI构建Canvas UI（但这需要更多设置）。
  4. Harmony补丁的粒度：尽量让补丁方法轻量。特别是在Prefix/Postfix中，避免长时间运行的操作。如果必须进行复杂操作，考虑使用协程（IEnumerator）或在单独的线程中处理（注意Unity API的非线程安全性）。
  5. 内存管理：注意解除事件订阅（-=），在OnDestroy中清理自己创建的对象，防止内存泄漏。

7.3 与其他模组的兼容与协作

在活跃的游戏模组社区，你的模组很可能需要与其他模组共存。

  1. 声明依赖：如果你的模组必须运行在另一个模组之后，或者需要另一个模组提供的API，使用[BepInDependency]特性。
    [BepInPlugin(...)] [BepInDependency("com.other.author.theirmod", BepInDependency.DependencyFlags.SoftDependency)] // 软依赖，可选 //[BepInDependency("com.other.author.requiredmod", BepInDependency.DependencyFlags.HardDependency)] // 硬依赖，必须 public class MyPlugin : BaseUnityPlugin { ... }
  2. 避免“硬编码”补丁：尽量不要补丁那些其他流行模组也可能修改的通用方法（如Player.Update）。如果不可避免，考虑使用Harmony的优先级特性，或者设计你的模组逻辑时，能与其他模组的修改共存。
  3. 提供API：如果你的模组功能强大，考虑暴露一个简单的公共API（例如一个静态类和方法），让其他模组开发者可以调用你的功能，而不是让他们也去补丁同样的地方。这能极大提升生态健康度。
  4. 测试与沟通：在发布前，尽量在装有其他主流模组的环境下测试。在模组页面明确列出已知的兼容/不兼容模组列表。

模组开发是一个持续学习、调试和与社区互动的过程。从修改一个简单的数值开始，到构建一个拥有复杂交互和配置的系统，每一步都会带来新的挑战和成就感。BepInEx和Harmony为你提供了强大的工具，但真正的魔法来自于你对游戏的理解和创造力。希望这篇指南能成为你模组开发之旅的一块坚实垫脚石。如果在实践中遇到具体问题，多查阅BepInEx和Harmony的官方文档，以及目标游戏模组社区的讨论，你会发现无数志同道合的人和宝贵的经验分享。