主题

配置 API ​

配置文件用来存配置信息——开关功能、存数据、改参数。Bukkit 提供了配置 API 读写 YAML 配置，这是插件开发最常用的 API 之一。

目前配置 API 只有 YAML 可用（这也是大多数插件配置是 .yml 的原因）。相关类在 org.bukkit.configuration 和 org.bukkit.configuration.file 包下。

YAML 基础 ​

YAML 用缩进表示层级，靠空格看所属关系。看这个例子：

yaml
Settings:
  DebugMode: true
  Time:
    CoolDown: 10
Data:
  player1:
    NickName: HandsomeBoy
    Score: 50
    Title:
      - Toilet Protector
      - Widow Maker

键的命名 ​

用 . 连接层级称呼一个键：

  • Settings 是键
  • Settings.DebugMode 是 Settings 下的子键
  • Settings.Time.CoolDown 对应值 10
  • Data.player1.Score 对应值 50

缩进必须用空格

YAML 不能用 Tab，只能用空格缩进，且同级缩进必须一致。这是新手最常踩的坑。

数据类型 ​

配置可存：基本类型（int/double/boolean）、String、List、以及实现了 ConfigurationSerializable 的对象（如 ItemStack、Player）。

读写配置 ​

默认配置 config.yml ​

在资源目录放一个 config.yml 作为默认配置。插件首次启动会把它复制到 plugins/<插件名>/config.yml。

yaml
# config.yml
welcome:
  enabled: true
  message: "&a欢迎来到服务器！"
max-players: 20

读取 ​

主类里直接用 getConfig()：

java
public void onEnable() {
    boolean enabled = getConfig().getBoolean("welcome.enabled");
    String msg = getConfig().getString("welcome.message");
    int max = getConfig().getInt("max-players");
    List<String> list = getConfig().getStringList("some.list");

    if (enabled) {
        getLogger().info("欢迎功能已开启：" + msg);
    }
}

常用 getter：

方法返回类型
getBoolean(path)boolean
getInt(path)int
getDouble(path)double
getString(path)String
getStringList(path)List<String>
get(path)Object（任意）

带默认值的 getter

键不存在时返回默认值（getBoolean 返回 false、getString 返回 null）。也可指定默认：

java
int max = getConfig().getInt("max-players", 50); // 键不存在则用 50

写入与保存 ​

java
getConfig().set("Data.player1.Score", 80);
saveConfig(); // 写入磁盘

改完要 saveConfig

set 只改内存里的配置，不写盘。必须调 saveConfig() 才会持久化到 config.yml。重启不丢数据全靠它。

重载配置 ​

java
reloadConfig(); // 从磁盘重新读入内存

改了配置文件想让插件重新读取时用。

路径用法 ​

路径用 . 分隔层级，支持任意深度：

java
// 读 Data.player1.NickName
String nick = getConfig().getString("Data.player1.NickName");

// 写 Data.player2.Score
getConfig().set("Data.player2.Score", 100);

不存在路径时 set 会自动创建中间层级。

单独的配置文件 ​

config.yml 是主类自带的。若需要多个配置文件（如玩家数据、语言文件），用 YamlConfiguration：

java
File file = new File(getDataFolder(), "players.yml");
FileConfiguration cfg = YamlConfiguration.loadConfiguration(file);

cfg.set("player1.coins", 500);
cfg.save(file); // 保存到 players.yml

int coins = cfg.getInt("player1.coins");

getDataFolder()

getDataFolder() 返回 plugins/<插件名>/ 目录。首次运行可能不存在，用前确保创建：getDataFolder().mkdirs()。

配置 API 让插件可配置、可持久化。下一篇命令执行器让玩家能主动触发插件功能。