ModConfigManager API 使用说明

本文档面向第三方模组作者，说明如何在 不直接引用 ModConfigManager.dll 的前提下，通过反射调用公开 API，把自己的模组名称、版本、作者与描述注册到 ModConfigManager 中。

English version is provided below the Chinese section.

中文

适用场景

如果你的模组希望在 ModConfigManager 的模组列表和详情区域中显示更完整的信息，可以使用这个 API 注册以下内容：

• 显示名称
• 版本号
• 作者名
• 模组描述

这套方式适合：

• 你不想让自己的模组在编译期强依赖 ModConfigManager.dll
• 你希望在用户安装了 ModConfigManager 时显示更友好的模组信息
• 你希望在用户未安装 ModConfigManager 时，自己的模组依然能正常运行

API 信息

当前公开 API 的真实信息如下：

• 插件 GUID：IceBoxStudio.RoadsideResearch.ModConfigManager
• 插件名称：ModConfigManager
• 类型全名：ModConfigManager.Api.ModConfigManagerAPI
• 方法名：RegisterPluginInfo

方法签名如下：

public static void RegisterPluginInfo(
    string guid,
    string name = null,
    string version = null,
    string author = null,
    string description = null)

参数说明：

• guid：你的插件 GUID，必须与 [BepInPlugin] 中声明的一致
• name：显示名称；不提供时会继续使用插件原始名称
• version：显示版本号
• author：显示作者名
• description：显示描述，支持多行文本

ModConfigManager 会如何显示这些信息

注册成功后，ModConfigManager 会读取并显示以下字段：

• name：用于左侧列表和详情标题
• version：用于详情元信息
• author：用于详情元信息
• description：用于详情描述文本

如果同一个 GUID 重复注册，后一次注册的内容会覆盖前一次内容。

推荐做法

建议在自己的主插件类上添加一个 软依赖：

[BepInDependency("IceBoxStudio.RoadsideResearch.ModConfigManager", BepInDependency.DependencyFlags.SoftDependency)]

这样做的好处：

• 用户安装了 ModConfigManager 时，你的模组可以更稳定地完成注册
• 用户没有安装 ModConfigManager 时，你的模组不会因为缺少该 DLL 而报错

推荐注册时机

如果你的模组是 BepInEx IL2CPP 模组，建议在 Load() 中完成注册。

原因如下：

• 这是 BasePlugin 常用的初始化入口
• 这时通常已经可以访问当前进程中已加载的程序集
• 可以尽早完成注册，方便配置管理器在打开界面时直接读取到信息

无需引用 DLL 的调用方式

不要在自己的项目中直接引用 ModConfigManager.dll，也不要写：

• using ModConfigManager.Api;
• 对 ModConfigManager 项目的编译引用

推荐使用反射调用，示例如下：

using System;
using System.Linq;
using System.Reflection;
using BepInEx;
using BepInEx.Unity.IL2CPP;

namespace YourModNamespace
{
    [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)]
    [BepInDependency("IceBoxStudio.RoadsideResearch.ModConfigManager", BepInDependency.DependencyFlags.SoftDependency)]
    public class YourMod : BasePlugin
    {
        private const string ModConfigManagerApiTypeName = "ModConfigManager.Api.ModConfigManagerAPI";
        private const string ModConfigManagerRegisterMethodName = "RegisterPluginInfo";

        public override void Load()
        {
            RegisterToModConfigManager();
        }

        private static void RegisterToModConfigManager()
        {
            Type apiType = AppDomain.CurrentDomain.GetAssemblies()
                .FirstOrDefault(assembly => assembly.GetType(ModConfigManagerApiTypeName) != null)
                ?.GetType(ModConfigManagerApiTypeName);
            if (apiType == null)
            {
                return;
            }

            MethodInfo registerMethod = apiType.GetMethod(ModConfigManagerRegisterMethodName, BindingFlags.Public | BindingFlags.Static);
            if (registerMethod == null)
            {
                return;
            }

            registerMethod.Invoke(null, new object[]
            {
                PluginInfo.PLUGIN_GUID,
                "你的模组显示名称",
                PluginInfo.PLUGIN_VERSION,
                "你的作者名",
                "你的模组描述"
            });
        }
    }
}

参数顺序

调用时请严格按照以下顺序传参：

1. guid
2. name
3. version
4. author
5. description

顺序传错后，配置管理器中显示的字段也会错位。

可选字段说明

除 guid 外，其余参数都可以传 null。

常见用法：

• 只覆盖显示名称：传 guid 和 name
• 只补充描述：其余参数传 null
• 同时注册名称、版本、作者和描述：五个参数全部传入

示例：

registerMethod.Invoke(null, new object[]
{
    PluginInfo.PLUGIN_GUID,
    "我的模组名",
    null,
    null,
    "这是一个自定义描述"
});

使用建议

• 描述尽量简洁明确，优先说明模组核心功能
• 如果是联机相关模组，可以直接写清是否影响联机
• 如果模组包含配置项，也可以在描述中简单提示
• 如果你的模组有多语言系统，建议传入当前语言下的名称和描述

常见问题

1. 如果用户没有安装 ModConfigManager 会怎样

反射查找不到 API 类型时，注册方法会直接返回，不会影响你自己的模组主体功能。

2. 为什么不建议直接引用 ModConfigManager.dll

直接引用会让你的模组在编译期依赖该程序集，增加发布和兼容成本。
使用反射后，你的模组在用户未安装 ModConfigManager 时也能正常工作。

3. 如果传入空的 guid 会怎样

API 内部会直接忽略这次注册，因此 guid 必须是有效的插件 GUID。

4. 如果重复调用 RegisterPluginInfo 会怎样

同一个 GUID 的注册信息会被最新一次调用覆盖。你可以在语言切换后或信息更新后重新注册。

English

When to Use It

This API is intended for third-party mod authors who want ModConfigManager to display richer metadata for their mods without adding a compile-time reference to ModConfigManager.dll.

You can register:

• display name
• version
• author
• description

This approach is useful when:

• you want to avoid a hard compile-time dependency on ModConfigManager.dll
• you want better mod information to appear when ModConfigManager is installed
• you still want your mod to run normally when ModConfigManager is not installed

API Information

The actual public API is:

• Plugin GUID: IceBoxStudio.RoadsideResearch.ModConfigManager
• Plugin name: ModConfigManager
• Type name: ModConfigManager.Api.ModConfigManagerAPI
• Method name: RegisterPluginInfo

Method signature:

public static void RegisterPluginInfo(
    string guid,
    string name = null,
    string version = null,
    string author = null,
    string description = null)

Parameter details:

• guid: your plugin GUID; it should match the value declared in [BepInPlugin]
• name: display name; if omitted, ModConfigManager keeps the plugin's original name
• version: display version
• author: display author
• description: display description; multiline text is supported

How ModConfigManager Uses the Data

After registration, ModConfigManager reads and displays:

• name for the left-side list and detail title
• version for the detail metadata
• author for the detail metadata
• description for the detail description text

If the same GUID is registered more than once, the latest registration replaces the previous one.

Recommended Setup

It is recommended to add a soft dependency on your plugin entry class:

[BepInDependency("IceBoxStudio.RoadsideResearch.ModConfigManager", BepInDependency.DependencyFlags.SoftDependency)]

Benefits:

• your mod can register more reliably when ModConfigManager is installed
• your mod will not fail if the user does not have ModConfigManager installed

Recommended Registration Timing

For a BepInEx IL2CPP mod, the recommended place to register is inside Load().

Why:

• this is the standard initialization entry for BasePlugin
• loaded assemblies are typically available at this point
• registration happens early, so ModConfigManager can pick up the info when its UI opens

Reflection Example Without Referencing the DLL

Do not directly reference ModConfigManager.dll, and do not write:

• using ModConfigManager.Api;
• a project reference to the ModConfigManager assembly

Use reflection instead:

using System;
using System.Linq;
using System.Reflection;
using BepInEx;
using BepInEx.Unity.IL2CPP;

namespace YourModNamespace
{
    [BepInPlugin(PluginInfo.PLUGIN_GUID, PluginInfo.PLUGIN_NAME, PluginInfo.PLUGIN_VERSION)]
    [BepInDependency("IceBoxStudio.RoadsideResearch.ModConfigManager", BepInDependency.DependencyFlags.SoftDependency)]
    public class YourMod : BasePlugin
    {
        private const string ModConfigManagerApiTypeName = "ModConfigManager.Api.ModConfigManagerAPI";
        private const string ModConfigManagerRegisterMethodName = "RegisterPluginInfo";

        public override void Load()
        {
            RegisterToModConfigManager();
        }

        private static void RegisterToModConfigManager()
        {
            Type apiType = AppDomain.CurrentDomain.GetAssemblies()
                .FirstOrDefault(assembly => assembly.GetType(ModConfigManagerApiTypeName) != null)
                ?.GetType(ModConfigManagerApiTypeName);
            if (apiType == null)
            {
                return;
            }

            MethodInfo registerMethod = apiType.GetMethod(ModConfigManagerRegisterMethodName, BindingFlags.Public | BindingFlags.Static);
            if (registerMethod == null)
            {
                return;
            }

            registerMethod.Invoke(null, new object[]
            {
                PluginInfo.PLUGIN_GUID,
                "Your Mod Display Name",
                PluginInfo.PLUGIN_VERSION,
                "Your Author Name",
                "Your mod description"
            });
        }
    }
}

Parameter Order

Pass arguments in this exact order:

1. guid
2. name
3. version
4. author
5. description

If the order is wrong, the displayed fields will also be wrong.

Optional Fields

All parameters except guid can be null.

Common cases:

• only override the display name
• only provide a description
• provide all five values for the full display experience

Example:

registerMethod.Invoke(null, new object[]
{
    PluginInfo.PLUGIN_GUID,
    "My Mod Name",
    null,
    null,
    "This is a custom description"
});

Best Practices

• keep the description concise and focused on the mod's core purpose
• mention multiplayer impact directly if relevant
• mention configuration support if the mod exposes editable settings
• if your mod already has localization, register the current language's name and description

FAQ

1. What happens if the user does not install ModConfigManager

If reflection cannot find the API type, your registration code simply returns and your mod continues to work normally.

2. Why avoid directly referencing ModConfigManager.dll

A direct reference creates a compile-time dependency and increases packaging and compatibility costs.
Reflection keeps your mod optional-compatible with ModConfigManager.

3. What happens if guid is null or empty

The API ignores that registration call, so guid must be a valid plugin GUID.

4. What happens if RegisterPluginInfo is called multiple times

For the same GUID, the newest call replaces the previous registration. This can be useful if you need to refresh localized text later.