在上一章节中，我们已经对丝之歌mod开发的环境做了必要的准备

接下来我们以开发一个 AlwaysCompass Mod作为例子来引入，具体功能为不论是否装备罗盘，都可以在地图上显示大黄蜂的位置

---

步骤

1. 创建Mod

• 首先进入想要创建mod的空文件夹，在终端输入命令后使用模板创建mod

  # name一般为GitHub用户名
  dotnet new silksongplugin --username name

• 创建完毕后，可以看到生成一系列文件和内容，首先需要重点关注项目名+Plugin.cs，这是Mod的入口文件，在这里可以进行Mod的初始化

  using BepInEx;
  
  namespace AlwaysCompass;
  
  // TODO - adjust the plugin guid as needed
  [BepInAutoPlugin(id: "io.github.nov1ce-lee.alwaysmagnetite")]
  public partial class AlwaysCompassPlugin : BaseUnityPlugin
  {
      private void Awake()
      {
          // Put your initialization logic here
          Logger.LogInfo($"Plugin {Name} ({Id}) has loaded!");
      }
  }

• 在该Mod入口文件中，主要包含几个主要部分：
  ① 一个继承BaseUnityPlugin的类
  ② BepInAutoPlugin属性及其他元数据
  ③ 一个Awake()方法，这是Mod的初始化方法，在这里可以进行Mod的初始化

  提示

  BaseUnityPlugin 继承了 UnityEngine.MonoBehaviour
  因此，你可以使用相同的事件方法，比如 Awake, Update 等

• 打开SilksongPath.props文件，并将内部SilksongFolder对应的地址更改为自己游戏的根目录

• 执行命令尝试编译构建插件，构建成功后会生成mod文件，并自动复制到 BepInEx/plugins 目录下

  dotnet build

2. 查看代码原有逻辑

• 在dnspy中搜索CompassTool
• 分析字段的方法被调用的位置
• 点击方法 GameMap.PositionCompassAndCorpse()查看
• 可以看到map的相关方法会根据compassTool.IsEquipped判断是否装备罗盘，因此我们可以通过对这个方法进行拦截，来强制返回已装备罗盘的结果

3. 加入补丁

提示

运行时补丁是指修改方法而不进行永久补丁的过程，详情可看运行时的补丁方法

BepInEx自带HarmonyX用于执行运行时补丁，补丁的作用是不修改原有游戏代码的前提下修改方法，使其返回固定值或者执行自定义逻辑

具体作用就是，当游戏运行时调用这个方法时，会先执行补丁方法，如果返回了false，则不会执行原方法，反之则执行原方法

• 根据我们前面看的罗盘工具的判断逻辑，编写补丁代码，整体逻辑为：

  // Patch : 拦截 ToolItem.IsEquipped
  [HarmonyPatch(typeof(ToolItem), "IsEquipped", MethodType.Getter)]
  public static class ToolItemIsEquippedPatch
  {
      public static bool Prefix(ToolItem __instance, ref bool __result)
      {
  
          // 如果是罗盘
          if (__instance == Gameplay.CompassTool)
          {
              __result = true;  // 强制返回"已装备"
              return false;     // 跳过原方法
          }
          
          return true;  // 不是罗盘，执行原方法
      }
  }

• 对于罗盘的内容，其实是不需要下面的补丁的，但在代码中对于很多工具对象的状态对象，都会调用这个方法进行判断，所以会需要补丁

    // Patch : 拦截 ToolStatus.IsEquipped
    [HarmonyPatch(typeof(ToolItemManager.ToolStatus), "IsEquipped", MethodType.Getter)]
    public static class ToolStatusIsEquippedPatch
    {
        public static bool Prefix(ToolItemManager.ToolStatus __instance, ref bool __result)
        {
            // 如果这个状态对象管理的是罗盘
            if (__instance.tool == Gameplay.CompassTool)
            {
                __result = true;
                return false;
            }
            
            return true;
        }
    }

• 代码编写完成后，再次编译，此时我们已经拥有了一个可以实现永久罗盘功能的Mod了

  dotnet build

配置相关

添加配置项

那么我们该如何实现mod的开关呢，这就要在代码中添加一个配置项，更多可见BepInEx配置管理

• 在插件内部，你可以访问到 @BepInEx.BaseUnityPlugin.Config 属性，这是一个预配置的配置文件
• 文件保存在 BepInEx\config\<GUID>.cfg，其中 <GUID> 就是插件的 GUID
• 要访问和创建配置值，首先需要用 Bind<T>(String， String， T， String) 来定义它们，配置初始化通常在插件启动代码中完成

那么修改前面的插件代码如下：

private BepInEx.Configuration.ConfigEntry<bool> IsEnabled;

private void Awake()
{
    Instance = this;
    IsEnabled = Config.Bind("General",      // 配置分组
                            "Enabled",      // 配置项名称
                            true,           // 默认值
                            "Enable or disable the Always Compass mod");    // 配置项描述

    Logger.LogInfo($"Plugin {Name} ({Id}) has loaded!");

    new Harmony(Id).PatchAll();
}

当你编译插件并首次运行游戏时，配置文件就会自动生成

配置管理

1. 使用 BepInExConfigManager工具来管理mod，这是最通用且方便的方法

BepInExConfigManager

• 需要安装 BepInEx Configuration Manager 插件
• 操作方法 ：
  1. 进入游戏
  2. 按下 F5 键
  3. 在弹出的菜单中找到 AlwaysCompass
  4. 展开 General 选项卡，您会看到 Enabled 勾选框
  5. 勾选或取消勾选即可实时开启/关闭 Mod 功能（代码中是实时检查 IsEnabled.Value 的）

2. 修改配置文件（无 UI） 如果没有安装 Configuration Manager，可以通过修改文件来配置：

• 位置 ： SilksongPath/BepInEx/config/io.github.nov1ce-lee.alwayscompass.cfg
• 操作 ：用记事本打开该文件，修改 Enabled = true 或 false