BepInEx生成配置文件所有示例和教程

蝼蚁梦

9个月前发布

200

BepInEx是一个用于注入Unity引擎游戏的插件框架，它可以让Mod开发者轻松地为游戏添加功能和修改内容。BepInEx还提供了一个配置文件系统，可以让Mod开发者和玩家自定义插件的设置和参数。

本文的目的是教你如何使用BepInEx生成配置文件，以及如何在插件中读取和修改配置文件的值。本文的难度适中，适合有一定C#基础和BepInEx经验的读者。

BepInEx配置文件的结构

BepInEx配置文件是一种文本文件，它遵循TOML格式，即表格化对象标记语言。TOML格式的特点是简洁、易读、易写，它可以用来表示各种数据类型，如字符串、数字、布尔值、数组、表等。

BepInEx配置文件的结构大致如下：

# 这是一个注释，以#开头，不会被解析

[Section] # 这是一个分节，以[Section]开头，表示这个分节下的所有配置项都属于Section这个分类
Key = Value # 这是一个配置项，以Key = Value的形式表示，Key是这个配置项的名称，Value是这个配置项的值
Key2 = Value2 # 这是另一个配置项

[Section.Subsection] # 这是一个子分节，以[Section.Subsection]开头，表示这个子分节下的所有配置项都属于Section.Subsection这个分类
Key3 = Value3 # 这是一个配置项

其中，分节和子分节可以用来对配置项进行分类和分组，方便管理和查找。每个分节或子分节的名称应该与插件的名称或功能相关，避免重复或冲突。每个配置项的名称应该清晰地描述其作用或含义，避免歧义或模糊。每个配置项的值应该符合其数据类型和范围，避免错误或异常。

BepInEx生成配置文件的方法

BepInEx提供了两种方法来生成配置文件：

一种是使用BepInEx.Configuration.ConfigFile类来创建和管理一个配置文件对象，然后使用该对象的Bind方法来绑定一个配置项，并指定其分节、名称、默认值、描述等参数。这种方法需要在插件的代码中编写相应的语句，并在插件加载时执行。
另一种是使用BepInEx.Configuration.ConfigEntry特性来标记一个字段或属性，并指定其分节、名称、默认值、描述等参数。这种方法不需要在插件的代码中编写额外的语句，只需要在字段或属性上添加特性即可。BepInEx会自动扫描所有带有该特性的字段或属性，并生成相应的配置项。

两种方法都可以实现相同的效果，但是使用特性的方法更简洁和方便。下面我们将分别介绍两种方法的具体用法和示例。

使用ConfigFile类生成配置文件

要使用ConfigFile类生成配置文件，首先需要引入以下命名空间：

using BepInEx;
using BepInEx.Configuration;

然后需要创建一个ConfigFile对象，并指定其路径和类型：

ConfigFile config = new ConfigFile("config.cfg", true); // 创建一个ConfigFile对象，路径为config.cfg，类型为TOML

接着需要使用ConfigFile对象的Bind方法来绑定一个或多个配置项，并指定其分节、名称、默认值、描述等参数：

ConfigEntry<string> name = config.Bind("General", "Name", "Bing", "The name of the assistant"); // 绑定一个字符串类型的配置项，分节为General，名称为Name，默认值为Bing，描述为The name of the assistant
ConfigEntry<int> age = config.Bind("General", "Age", 1, new ConfigDescription("The age of the assistant", new AcceptableValueRange<int>(1, 100))); // 绑定一个整数类型的配置项，分节为General，名称为Age，默认值为1，描述为The age of the assistant，并指定其可接受的值范围为1到100
ConfigEntry<bool> enabled = config.Bind("General", "Enabled", true, "Whether the assistant is enabled or not"); // 绑定一个布尔类型的配置项，分节为General，名称为Enabled，默认值为true，描述为Whether the assistant is enabled or not

最后需要在插件的Awake或Start方法中调用ConfigFile对象的Save方法来保存配置文件：

config.Save(); // 保存配置文件

这样就可以生成一个名为config.cfg的配置文件，其内容如下：

[General]

## The name of the assistant
# Setting type: String
# Default value: Bing
Name = "Bing"

## The age of the assistant
# Setting type: Int32
# Default value: 1
# Acceptable values: 1 - 100
Age = 1

## Whether the assistant is enabled or not
# Setting type: Boolean
# Default value: true
Enabled = true

使用ConfigEntry特性生成配置文件

要使用ConfigEntry特性生成配置文件，首先需要引入以下命名空间：

using BepInEx;
using BepInEx.Configuration;

然后需要在插件类中定义一个或多个字段或属性，并在其上添加ConfigEntry特性，并指定其分节、名称、默认值、描述等参数：

[ConfigEntry("General")] // 指定分节为General
public string Name { get; set; } = "Bing"; // 定义一个字符串类型的属性，名称为Name，默认值为Bing

[ConfigEntry("General")] // 指定分节为General
[ConfigDescription("The age of the assistant", new AcceptableValueRange<int>(1, 100))] // 指定描述和可接受的值范围
public int Age { get; set; } = 1; // 定义一个整数类型的属性，名称为Age，默认值为1

[ConfigEntry("General")] // 指定分节为General
public bool Enabled { get; set; } = true; // 定义一个布尔类型的属性，名称为Enabled，默认值为true

这样就可以生成一个名为<插件ID>.cfg的配置文件，其内容如下：

[General]

## 
# Setting type: String
# Default value: Bing
Name = "Bing"

## The age of the assistant
# Setting type: Int32
# Default value: 1
# Acceptable values: 1 - 100
Age = 1

## 
# Setting type: Boolean
# Default value: true
Enabled = true

BepInEx读取和修改配置文件的方法

BepInEx读取和修改配置文件的方法与生成配置文件的方法相对应：

如果使用ConfigFile类生成配置文件，则可以使用ConfigFile对象的GetEntry方法来获取一个或多个配置项的对象，并使用其Value属性来读取或修改其值。
如果使用ConfigEntry特性生成配置文件，则可以直接使用带有该特性的字段或属性来读取或修改其值。

下面我们将分别介绍两种方法的具体用法和示例。

使用ConfigFile类读取和修改配置文件

要使用ConfigFile类读取和修改配置文件，首先需要引入以下命名空间：

using BepInEx;
using BepInEx.Configuration;

然后需要创建一个ConfigFile对象，并指定其路径和类型：

ConfigFile config = new ConfigFile("config.cfg", true); // 创建一个ConfigFile对象，路径为config.cfg，类型为TOML

接着需要使用ConfigFile对象的GetEntry方法来获取一个或多个配置项的对象，并使用其Value属性来读取和修改配置文件，然后使用其Value属性来读取或修改其值，例如：

ConfigEntry<string> name = config.GetEntry<string>("General", "Name"); // 获取一个字符串类型的配置项对象，分节为General，名称为Name
ConfigEntry<int> age = config.GetEntry<int>("General", "Age"); // 获取一个整数类型的配置项对象，分节为General，名称为Age
ConfigEntry<bool> enabled = config.GetEntry<bool>("General", "Enabled"); // 获取一个布尔类型的配置项对象，分节为General，名称为Enabled

string nameValue = name.Value; // 读取Name配置项的值
int ageValue = age.Value; // 读取Age配置项的值
bool enabledValue = enabled.Value; // 读取Enabled配置项的值

name.Value = "Alice"; // 修改Name配置项的值
age.Value = 2; // 修改Age配置项的值
enabled.Value = false; // 修改Enabled配置项的值

最后需要在插件的OnDisable或OnDestroy方法中调用ConfigFile对象的Save方法来保存配置文件：

config.Save(); // 保存配置文件

这样就可以读取和修改config.cfg配置文件的内容，其内容如下：

[General]

## The name of the assistant
# Setting type: String
# Default value: Bing
Name = "Alice"

## The age of the assistant
# Setting type: Int32
# Default value: 1
# Acceptable values: 1 - 100
Age = 2

## Whether the assistant is enabled or not
# Setting type: Boolean
# Default value: true
Enabled = false

使用ConfigEntry特性读取和修改配置文件

要使用ConfigEntry特性读取和修改配置文件，首先需要引入以下命名空间：

using BepInEx;
using BepInEx.Configuration;

然后需要在插件类中定义一个或多个字段或属性，并在其上添加ConfigEntry特性，并指定其分节、名称、默认值、描述等参数：

[ConfigEntry("General")] // 指定分节为General
public string Name { get; set; } = "Bing"; // 定义一个字符串类型的属性，名称为Name，默认值为Bing

[ConfigEntry("General")] // 指定分节为General
[ConfigDescription("The age of the assistant", new AcceptableValueRange<int>(1, 100))] // 指定描述和可接受的值范围
public int Age { get; set; } = 1; // 定义一个整数类型的属性，名称为Age，默认值为1

[ConfigEntry("General")] // 指定分节为General
public bool Enabled { get; set; } = true; // 定义一个布尔类型的属性，名称为Enabled，默认值为true

接着可以直接使用带有ConfigEntry特性的字段或属性来读取或修改其值，例如：

string nameValue = Name; // 读取Name属性的值
int ageValue = Age; // 读取Age属性的值
bool enabledValue = Enabled; // 读取Enabled属性的值

Name = "Alice"; // 修改Name属性的值
Age = 2; // 修改Age属性的值
Enabled = false; // 修改Enabled属性的值

这样就可以读取和修改<插件ID>.cfg配置文件的内容，其内容如下：

[General]

## 
# Setting type: String
# Default value: Bing
Name = "Alice"

## The age of the assistant
# Setting type: Int32
# Default value: 1
# Acceptable values: 1 - 100
Age = 2

## 
# Setting type: Boolean
# Default value: true
Enabled = false

评分

欢迎为Ta评分

赞赏