BepInEx配置管理器使用指南与开发教程

BepInEx配置管理器使用指南与开发教程

【免费下载链接】BepInEx.ConfigurationManagerPlugin configuration manager for BepInEx项目地址: https://gitcode.com/gh_mirrors/be/BepInEx.ConfigurationManager

BepInEx配置管理器是BepInEx插件系统的强大配置工具，让用户无需编写自定义GUI即可轻松调整插件行为。通过简单的快捷键操作，玩家就能在游戏中实时修改插件设置，极大提升了用户体验。

项目概述与核心功能

BepInEx配置管理器为BepInEx插件系统提供了一个直观的配置界面，用户可以通过按下默认的F1键来访问和管理所有插件的设置。该工具支持多种配置类型，包括普通设置、键盘快捷键、高级设置和调试模式。

快速安装配置方法

环境准备要求

• BepInEx 5版本：需要5.4.20或更新的版本（仅限mono）
• BepInEx 6版本：需要夜间构建版本664或更新的版本（仅限IL2CPP）

安装步骤

1. 确保游戏已安装兼容版本的BepInEx框架
2. 下载对应BepInEx版本的最新发布包
3. 将插件直接解压到游戏目录中，确保.dll文件位于BepInEx\Plugins文件夹内
4. 启动游戏并使用F1键打开配置界面

插件兼容性开发指南

基础配置类设计

配置管理器会自动显示插件Config中的所有设置。所有元数据（如描述、值范围）都会被配置管理器用来向用户展示设置信息。

在大多数情况下，您无需引用ConfigurationManager.dll或对设置进行特殊处理。只需确保添加尽可能多的元数据，这将帮助所有用户，即使他们直接使用配置文件。

滑块设置实现

在创建设置时指定AcceptableValueRange。如果范围是0f - 1f或0 - 100，滑块将显示为百分比。

CaptureWidth = Config.Bind("Section", "Key", 1, new ConfigDescription("Description", new AcceptableValueRange<int>(0, 100)));

下拉列表设置实现

在创建设置时指定AcceptableValueList。如果使用枚举，则无需指定AcceptableValueList，所有枚举值都会显示。如果要隐藏某些值，需要使用属性。

可以在枚举项上添加System.ComponentModel.DescriptionAttribute来覆盖它们的显示名称：

public enum MyEnum { // Entry1将在组合框中显示为Entry1 Entry1, [Description("Entry2将在组合框中显示为此字符串")] Entry2 }

键盘快捷键配置

添加KeyboardShortcut类型的设置。在Update方法中使用此设置的值来检查输入（推荐使用IsDown）。

KeyboardShortcut类支持修饰键 - Shift、Control和Alt。它们被正确处理，防止了常见问题，如K+Shift+Control在不应该触发时触发了K+Shift。

private ConfigEntry<KeyboardShortcut> ShowCounter { get; set; } public Constructor() { ShowCounter = Config.Bind("Hotkeys", "Show FPS counter", new KeyboardShortcut(KeyCode.U, KeyCode.LeftShift)); } private void Update() { if (ShowCounter.Value.IsDown()) { // 处理按键按下 } }

高级配置管理技巧

覆盖默认行为

您可以通过将特殊类的实例作为设置的标签来更改设置在配置管理器窗口中的显示方式。

示例：覆盖设置顺序并将一个设置标记为高级：

// 覆盖IsAdvanced和Order Config.Bind("X", "1", 1, new ConfigDescription("", null, new ConfigurationManagerAttributes { IsAdvanced = true, Order = 3 })); // 仅覆盖Order，IsAdvanced保持ConfigManager分配的默认值 Config.Bind("X", "2", 2, new ConfigDescription("", null, new ConfigurationManagerAttributes { Order = 1 })); Config.Bind("X", "3", 3, new ConfigDescription("", null, new ConfigurationManagerAttributes { Order = 2 }));

自定义设置编辑器

如果使用配置管理器不支持的类型，可以为其添加绘制器Action。该Action将在OnGUI内部执行，使用GUILayout来绘制您的设置。

要为单个设置使用自定义设置绘制器，在属性类中使用CustomDrawer字段。

void Start() { // 将绘制器作为标签添加到此设置 Config.Bind("Section", "Key", "Some value" new ConfigDescription("Desc", null, new ConfigurationManagerAttributes{ CustomDrawer = MyDrawer }); } static void MyDrawer(BepInEx.Configuration.ConfigEntryBase entry) { // 确保使用GUILayout.ExpandWidth(true)来使用所有可用空间 GUILayout.Label(entry.BoxedValue, GUILayout.ExpandWidth(true)); }

全局自定义编辑器

您可以为某种设置类型的所有设置指定绘制器。通过使用ConfigurationManager.RegisterCustomSettingDrawer(Type, Action<SettingEntryBase>)来实现。

警告：这需要您在项目中引用ConfigurationManager.dll，除非您确定所有用户都已安装，否则不推荐使用。通常最好使用上述方法将自定义绘制器单独添加到每个设置。

void Start() { ConfigurationManager.RegisterCustomSettingDrawer(typeof(MyType), CustomDrawer); } static void CustomDrawer(SettingEntryBase entry) { GUILayout.Label((MyType)entry.Get(), GUILayout.ExpandWidth(true)); }

常见问题解决方案

界面无文本显示问题

如果在RUE窗口中任何地方都看不到文本，很可能是系统缺少Arial.ttf字体（Unity UI默认字体，某些游戏中可能不同）。在Linux上使用配置不当的wine运行游戏时可能会发生这种情况。

IL2CPP版本兼容性

IL2CPP版本目前仅在某些具有未剥离UnityEngine.IMGUIModule.dll的游戏中工作。某些游戏的支持可以通过恢复缺失成员的补丁程序来添加。

最佳实践建议

1. 描述性命名：始终添加描述性的部分和键名、描述以及可接受的值列表或范围（在适用的情况下）
2. 元数据完整性：为所有设置提供完整的元数据，包括描述和值约束
3. 错误处理：在自定义绘制器中包含适当的错误处理机制
4. 性能优化：避免在Update方法中进行复杂的键盘快捷键检查

通过遵循本指南中的步骤和技巧，开发者和用户都能够充分利用BepInEx配置管理器的强大功能，创建和管理高质量的插件配置。

【免费下载链接】BepInEx.ConfigurationManagerPlugin configuration manager for BepInEx项目地址: https://gitcode.com/gh_mirrors/be/BepInEx.ConfigurationManager