# 深入plugin.yml

plugin.yml文件是Bukkit及其衍生服务端识别插件的重要文件.

在服务端加载插件时, 服务端加载完毕Jar文件后做的第一件事就是读取该Jar文件的plugin.yml文件.
如果把任一可正常工作的插件的Jar文件用相应的ZIP压缩软件打开, 删除plugin.yml文件后再启动服务端, 会抛出错误.

Could not load 'plugins\[YOUR_PLUGIN].jar' in folder 'plugins'  
org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml

可发现, 服务端将会因为没有plugin.yml文件而抛出InvalidDescriptionException错误.

在plugin.yml文件中, 目前我们已知的有name、version、main、author四个项目可以设置.
事实上, plugin.yml文件中还有许多可以设置的项目, 部分项目是本节的内容, 其余可以在SpigotMC的官方文档中查阅到.

目前BukkitAPI主要由SpigotMC维护, 因此大量的BukkitAPI文档都在 SpigotMC 网站上.
有关plugin.yml文件的官方文档在这里:
https://www.spigotmc.org/wiki/plugin-yml/

# 必要设置项

plugin.yml文件中, name、main、version三项必须存在.
这也意味着, 前面的实例中, 我们使用的plugin.yml文件, 删去author键仍可被服务端正常加载.

不妨来认识一下这三个设置项.

顾名思义, 它定义了插件的名称.

对于名称, 官方WIKI中给出了严格的要求, 即只能由 英文小写或大写字符、阿拉伯数字或下划线 构成. 决不能出现中文字符、空格等.
在后续生成插件配置文件夹时, 该项设置的插件名将会是插件配置文件夹的名称.

起名的时候应该注意, 尽可能起一个“个性”的名称, 防止与其他插件重名.

指插件的版本号.
该键理论上可以在后面填写任意String内容. 但是官方WIKI要求尽可能使用X.X.X格式的版本号表示(例如: 2.3.3).
关于版本号规则，可以参考语义化版本 (opens new window)

指插件的主类名.

在插件中, 主类有且只有一个, 且需要继承JavaPlugin类. 主类是插件的“入口”, 这里的main即意在说明主类的名称.
这里需填写主类的全名, 也就是精确到主类所在的具体包. 说白了就是不只是需要把主类名带上, 还要把包名带上.

plugin.yml文件只需要存在必要设置项的三个键即可.
下面的键可选, 可有可无. 但有一些在一些特定的情况下必须要有.

有时候你的插件可能需要调用Vault（用来获取玩家货币余额）或其他的插件, 即依赖其他插件.
这时候需要在plugin.yml文件中进行设置告知服务端, 从而保证所依赖的插件在本插件之前被加载.

你可以在plugin.yml文件中加入depend键或softdepend键来控制依赖.

depend键或softdepend键接的值必须是数组. 例如这样:

depend: [Vault, WorldEdit]
softdepend: [Essentials]

两个键设置的内容区别如下：

后面设置的数组内的内容都是所依赖插件的名称, 此处名称应与所依赖的插件的plugin.yml文件的name键的值相同.

depend与softdepend可以实现插件在某个插件之后加载. 但也许有时你的插件可能需要实现在某个插件之前被加载.
此时你可以使用loadbefore设置, 用法类似. 例如:

loadbefore: [Essentials, WorldEdit]

在上面的例子中, 可保证插件在WorldEdit与Essentials插件之前被加载.

如果你的插件定义了新指令, 你第一步就需要设置该项告知服务端.
此处仅做示范:

commands:
  test:
    description: "Hello World!"

这可以告知服务端注册了指令test, 并且描述为Hello World!字符串, 该描述字符串将会在/help指令中被显示.

此处不再赘述其作用. 如果你想表示多名作者, 你可以设置authors项, 值需为一个数组.

authors: [tdiant, Seraph_JACK]

如果同时存在author与authors, 将忽略author.

进阶

15分钟