程序包 org.bukkit.plugin

类 PluginDescriptionFile

java.lang.Object
org.bukkit.plugin.PluginDescriptionFile
public final class PluginDescriptionFile extends Object
这个类是用于储存插件plugin.yml内的数据. 所有的插件都必须有自己的plugin.yml.对于插件来说 plguin.yml是必须使用的标准 这个文件必须位于jar的根目录下.

当Bukkit加载插件时,它必须知道一些基础的关于这个插件的信息. Bukkit从plugin.yml读取数据. plugin.yml由一组属性构成,每个属性位于单独的一行并且没有缩进.

每一个方法(几乎每一个) 都在plugin.yml有其对应的条目. 下面是每一个插件所需的条目.

未能填写以上条目,将导致一个异常并且使Bukkit忽视你的插件.

下面是plugin.yml可能拥有的条目表格,具体细节包括各自的方法:

plugin.yml 布局说明
条目 方法 概要
name getName() 该插件的名字
provides getProvides() 此插件提供的插件 API
version getVersion() 插件的版本
main getMain() 插件主类的位置
author
authors		 getAuthors() 插件的作者们
contributors getContributors() 插件的贡献者们
description getDescription() 可读的插件描述
website getWebsite() 插件的网址
prefix getPrefix() 用于控制台的插件前缀
load getLoad() 载入插件的时机
depend getDepend() 必须的前置插件
softdepend getSoftDepend() 非必须的前置插件
loadbefore getLoadBefore() 反softdepend,可理解为在某些插件前加载
commands getCommands() 插件将被注册的命令
permissions getPermissions() 插件将被注册的权限
default-permission getPermissionDefault() 插件将注册的基本的default 权限 permissions
awareness getAwareness() 插件的概念
api-version getAPIVersion() 开发插件时针对的API版本
libraries () 插件使用到的类库

一个plugin.yml的例子:

name: Inferno
provides: [Hell]
version: 1.4.1
description: This plugin is so 31337. You can set yourself on fire.
# We could place every author in the authors list, but chose not to for illustrative purposes
# Also, having an author distinguishes that person as the project lead, and ensures their
# name is displayed first
author: CaptainInflamo
authors: [Cogito, verrier, EvilSeph]
contributors: [Choco, md_5]
website: http://www.curse.com/server-mods/minecraft/myplugin

main: com.captaininflamo.bukkit.inferno.Inferno
depend: [NewFire, FlameWire]
api-version: 1.13
libraries:
    - com.squareup.okhttp3:okhttp:4.9.0

commands:
  flagrate:
    description: Set yourself on fire.
    aliases: [combust_me, combustMe]
    permission: inferno.flagrate
    usage: Syntax error! Simply type /<command> to ignite yourself.
  burningdeaths:
    description: List how many times you have died by fire.
    aliases: [burning_deaths, burningDeaths]
    permission: inferno.burningdeaths
    usage: |
      /<command> [player]
      Example: /<command> - see how many times you have burned to death
      Example: /<command> CaptainIce - see how many times CaptainIce has burned to death

permissions:
  inferno.*:
    description: Gives access to all Inferno commands
    children:
      inferno.flagrate: true
      inferno.burningdeaths: true
      inferno.burningdeaths.others: true
  inferno.flagrate:
    description: Allows you to ignite yourself
    default: true
  inferno.burningdeaths:
    description: Allows you to see how many times you have burned to death
    default: true
  inferno.burningdeaths.others:
    description: Allows you to see how many times others have burned to death
    default: op
    children:
      inferno.burningdeaths: true

  • 构造器详细资料

  • 方法详细资料

    • getName

      @NotNull public @NotNull String getName()
      获取插件的名称. 此名称是插件的唯一标识符.
      • 必须由字母数字字符、下划线、连字符和句点 (a-z,A-Z,0-9, _.-) 组成. 任何其他字符将导致 plugin.yml 加载失败.
      • 用于确定插件数据文件夹的名称. 数据文件夹默认放置在 ./plugins/ 目录下, 但不应依赖此行为. 应使用 Plugin.getDataFolder() 来引用数据文件夹.
      • 建议将 jar 文件命名与此一致, 例如 'MyPlugin.jar'.
      • 区分大小写.
      • 这是在 getDepend(), getSoftDepend() 和 getLoadBefore() 中引用的标识.
      • 在插件名称中使用空格已被弃用.

      原文： Gives the name of the plugin. This name is a unique identifier for plugins.

      返回:
      插件的名称

    • getProvides

      @NotNull public @NotNull List<String> getProvides()
      获取此插件提供的其他插件 API 列表. 其他插件可以依赖这些 API.
      • 必须由字母数字字符、下划线、连字符和句点 (a-z,A-Z,0-9, _.-) 组成. 任何其他字符将导致 plugin.yml 加载失败.
      • 其他插件提供相同 API 或将其用作名称不会导致插件加载失败.
      • 区分大小写.
      • 此列表中的条目可在 getDepend(), getSoftDepend() 和 getLoadBefore() 中引用.
      • provides 必须使用 YAML 列表格式.

      原文： Gives the list of other plugin APIs which this plugin provides. These are usable for other plugins to depend on.

      返回:
      此插件提供的插件 API 不可变列表

    • getVersion

      @NotNull public @NotNull String getVersion()
      获取插件的版本.
      • 版本是一个任意字符串, 但最常用的格式是 主版本.次版本.构建版本 (例如: 1.4.1).
      • 通常在每次发布新功能或修复 bug 时递增版本号.
      • 当用户输入 /version PluginName 时显示.

      原文： Gives the version of the plugin.

      返回:
      插件的版本

    • getMain

      @NotNull public @NotNull String getMain()
      获取插件主类的完整限定名. 格式应遵循 ClassLoader.loadClass(String) 语法, 以便在运行时成功解析. 对于大多数插件, 这是扩展 JavaPlugin 的类.
      • 必须包含完整的命名空间, 包括类文件本身.
      • 如果命名空间是 org.bukkit.plugin, 且类文件名为 MyPlugin, 则必须为 org.bukkit.plugin.MyPlugin
      • 任何插件都不能使用 org.bukkit. 作为任何类 (包括主类) 的基础包.

      原文： Gives the fully qualified name of the main class for a plugin. The format should follow the ClassLoader#loadClass(String) syntax to successfully be resolved at runtime. For most plugins, this is the class that extends JavaPlugin.

      返回:
      插件的完整限定主类名

    • getDescription

      @Nullable public @Nullable String getDescription()
      获取插件功能的人类可读描述.
      • 描述可以有多行.
      • 当用户输入 /version PluginName 时显示.

      原文： Gives a human-friendly description of the functionality the plugin provides.

      返回:
      插件的描述, 如果未指定则返回 null

    • getLoad

      @NotNull public @NotNull PluginLoadOrder getLoad()
      获取插件应在服务器启动的哪个阶段加载.

      原文： Gives the phase of server startup that the plugin should be loaded.

      返回:
      插件应加载的阶段

    • getAuthors

      @NotNull public @NotNull List<String> getAuthors()
      获取插件的作者列表.
      • 用于标识开发者.
      • 在某些服务器错误消息中使用, 以提供有关出现错误时联系谁的有用反馈.
      • 建议使用 SpigotMC 论坛账号或电子邮件地址.
      • 当用户输入 /version PluginName 时显示.
      • authors 必须使用 YAML 列表格式.

      原文： Gives the list of authors for the plugin.

      返回:
      插件作者的不可变列表

    • getContributors

      @NotNull public @NotNull List<String> getContributors()
      获取插件的贡献者列表.
      • 用于标识对插件有贡献但不足以获得作者资格的人员.
      • 与 getAuthors() 不同, 贡献者不会在服务器错误消息中作为联系方式被提及.
      • 建议使用 SpigotMC 论坛账号或电子邮件地址.
      • 当用户输入 /version PluginName 时显示.
      • contributors 必须使用 YAML 列表格式.

      原文： Gives the list of contributors for the plugin.

      返回:
      插件贡献者的不可变列表

    • getWebsite

      @Nullable public @Nullable String getWebsite()
      获取插件或插件作者的网站.
      • 强烈建议提供包含文档和下载的 Curse 页面链接.
      • 当用户输入 /version PluginName 时显示.

      原文： Gives the plugin's or plugin's author's website.

      返回:
      插件的网站, 如果未指定则返回 null

    • getDepend

      @NotNull public @NotNull List<String> getDepend()
      获取此插件所需的其他插件列表.
      • 使用目标插件 getName() 中的值来指定依赖.
      • 如果此处列出的任何插件未找到, 你的插件将在启动时加载失败.
      • 如果多个插件在 depend 中相互引用, 形成一个没有单独插件在 网络 中列出另一个插件的循环依赖, 则该网络中的所有插件都将失败.
      • depend 必须使用 YAML 列表格式.

      原文： Gives a list of other plugins that the plugin requires.

      返回:
      插件依赖的不可变列表

    • getSoftDepend

      @NotNull public @NotNull List<String> getSoftDepend()
      获取插件完整功能所需的其他插件列表. PluginManager 会尽力将此处所有条目视为 依赖, 但不会因为这些条目中的任何一个而失败.
      • 使用目标插件 getName() 中的值来指定依赖.
      • 当列出的插件无法解析时, 它将被忽略且不影响加载顺序.
      • 当发生循环依赖 (插件网络相互依赖或软依赖) 时, 将任意选择一个在忽略软依赖时可以解析的插件.
      • softdepend 必须使用 YAML 列表格式.

      原文： Gives a list of other plugins that the plugin requires for full functionality. The PluginManager will make best effort to treat all entries here as if they were a dependency, but will never fail because of one of these entries.

      返回:
      插件首选依赖的不可变列表

    • getLoadBefore

      @NotNull public @NotNull List<String> getLoadBefore()
      获取应将此插件视为软依赖的插件列表.
      • 使用目标插件 getName() 中的值来指定依赖.
      • 此插件应在列出的所有其他插件之前加载.
      • 在此处指定另一个插件严格等同于让指定插件的 getSoftDepend() 包含 此插件.
      • loadbefore 必须使用 YAML 列表格式.

      原文： Gets the list of plugins that should consider this plugin a soft-dependency.

      返回:
      应将此插件视为软依赖的插件不可变列表

    • getPrefix

      @Nullable public @Nullable String getPrefix()
      获取用于插件特定日志消息前缀的标识.
      • 包括所有使用 Plugin.getLogger() 的消息.
      • 如果未指定, 服务器使用插件的 名称.
      • 应清楚地指示正在记录的是哪个插件.

      原文： Gives the token to prefix plugin-specific logging messages with.

      返回:
      日志前缀标识, 如果未指定则返回 null

    • getCommands

      @NotNull public @NotNull Map<String,Map<String,Object>> getCommands()
      获取命令名称到命令属性的映射. 此映射中的每个条目对应一个单独的命令, 其各自的值是该命令的属性. 除别名外, 每个属性都可以在运行时使用 PluginCommand 中的方法定义, 在此处定义仅为方便.
      命令部分描述
      节点 方法 类型 描述 示例
      description Command.setDescription(String) String 命令的用户友好描述. 适用于文档编写以及游戏内帮助. 
      description: Set yourself on fire
      aliases Command.setAliases(List) 字符串或字符串 列表 替代命令名称, 对于已注册的命令特别有用. 别名在运行时定义无效, 因此插件描述文件是正确定义别名的唯一方式.

      注意: 命令别名中不能包含冒号.

      		 单个别名格式: 
      aliases: combust_me
      或 多个别名格式: 
      aliases: [combust_me, combustMe]
      permission Command.setPermission(String) String 使用该命令所需的 Permission 名称. 没有权限的用户将收到指定消息 (见下方 Command.setPermissionMessage(String)), 如果未定义特定消息则使用标准消息. 没有权限节点, 任何 CommandExecutor 或 PluginCommand.setTabCompleter(TabCompleter) 都不会被调用. 
      permission: inferno.flagrate
      permission-message Command.setPermissionMessage(String) String
      • 显示给尝试使用命令但没有所需权限的玩家. 见上方 Command.getPermission().
      • <permission> 是一个宏, 会被替换为使用该命令所需的权限节点.
      • 使用空引号是表示不向玩家显示任何内容的有效方式. 
      permission-message: You do not have /<permission>
      usage Command.setUsage(String) String 当 PluginCommand.setExecutor(CommandExecutor) 返回 false 时显示此消息. <command> 是一个宏, 会被替换为发出的命令. 
      usage: Syntax error! Perhaps you meant /<command> PlayerName?
      值得注意的是, 要在 yaml 中使用冒号, 如 usage: Usage: /god [player], 需要 用双引号包围消息: 
      usage: "Usage: /god [player]"
      命令以 嵌套映射 层次结构组织. 主 (顶层, 无缩进) 节点是 commands, 每个单独的命令名是缩进的, 表示它映射到某个值 (即上表中的属性).

      原文： Gives the map of command-name to command-properties. Each entry in this map corresponds to a single command and the respective values are the properties of the command.

      返回:
      此插件将注册的命令

    • getPermissions

      @NotNull public @NotNull List<Permission> getPermissions()
      获取插件将在运行时注册的权限列表, 在启用后立即生效. 定义权限的格式是从权限名称到属性的映射. 要表示没有任何特定属性的映射, 可以使用空花括号 ({}) (与上面的命令不同, 不接受 null 值).

      权限的可选属性列表:

      权限部分描述
      节点 描述 示例
      description 权限用途的明文 (用户友好) 描述. 
      description: Allows you to set yourself on fire
      default 权限的默认状态, 由 Permission.getDefault() 定义. 如果未定义, 将设置为 getPermissionDefault() 的值.

      参考:

      		 
      default: true
      children 允许将其他权限设置为父权限的 关联 权限. 当父权限被赋权时, 子权限也会相应地被赋权.
      • 当父权限被负面赋权时, 子权限基于其关联关系的反转进行赋权.
      • 当父权限被正面赋权时, 子权限基于其关联关系进行赋权.

      子权限可以通过多种方式定义:

      • 子权限可以定义为名称的 列表. 使用列表将使所有子权限与其父权限正面关联.
      • 子权限可以定义为映射. 每个权限名称映射到一个布尔值 (表示关联关系) 或一个嵌套的权限定义 (就像另一个权限). 使用嵌套定义将使子权限视为正面关联.
      • 嵌套权限定义必须是这些相同属性的映射. 要定义有效的嵌套权限而不定义任何特定属性, 必须使用空花括号 ({}).
      • 嵌套权限可以拥有自己的嵌套权限作为子权限, 它们也可以有嵌套权限, 依此类推. 权限树的定义深度没有直接限制.
      		作为列表: 
      children: [inferno.flagrate, inferno.burningdeaths]
      或作为映射: 
      children:
  inferno.flagrate: true
  inferno.burningdeaths: true
      展示基本嵌套值的附加示例可在 此处 查看.
      权限以 嵌套映射 层次结构组织. 主 (顶层, 无缩进) 节点是 permissions, 每个单独的权限名是缩进的, 表示它映射到某个值 (即上表中的属性).

      原文： Gives the list of permissions the plugin will register at runtime, immediately proceding enabling. The format for defining permissions is a map from permission name to properties.

      返回:
      此插件将注册的权限

    • getPermissionDefault

      @NotNull public @NotNull PermissionDefault getPermissionDefault()
      获取插件注册权限的默认 默认 状态.

      原文： Gives the default default state of permissions registered for the plugin.

      返回:
      插件权限的默认值

    • getAwareness

      @NotNull public @NotNull Set<PluginAwareness> getAwareness()
      获取插件的每个 PluginAwareness 集合. 感知表示插件开发者在编译插件时所确认的内容. 某些实现可能定义了 API 中未包含的额外感知. 任何未识别的感知 (不支持的或未来版本中的) 将导致创建一个虚拟对象, 而不是失败.
      • 目前仅支持 PluginAwareness.Flags 中的枚举值.
      • 每个感知以 bang-at (!@) 开头作为标识符.
      • 未识别的 (未来的/未实现的) 条目会被静默替换为实现了 PluginAwareness 的通用对象.
      • 感知类型必须由运行时定义并由 API 确认, 实际上排除了任何插件类路径中的派生类型.
      • awareness 必须使用 YAML 列表格式.

      原文： Gives a set of every PluginAwareness for a plugin. An awareness dictates something that a plugin developer acknowledges when the plugin is compiled.

      返回:
      包含插件每个感知的集合

    • getFullName

      @NotNull public @NotNull String getFullName()
      返回插件的名称, 包括版本. 此方法为便捷方法, 使用 getName() 和 getVersion() 条目.

      原文： Returns the name of a plugin, including the version. This method is provided for convenience; it uses the getName() and getVersion() entries.

      返回:
      插件及其版本的描述性名称

    • getAPIVersion

      @Nullable public @Nullable String getAPIVersion()
      获取此插件设计支持的 API 版本. 不保证特定格式.
      • 有关支持的 API 版本, 请参阅发行说明.

      原文： Gives the API version which this plugin is designed to support. No specific format is guaranteed.

      返回:
      插件的 API 版本

    • getLibraries

      @NotNull public @NotNull List<String> getLibraries()
      获取此插件所需的类库. 这是一个预览功能.
      • 类库必须是 GAV 说明符, 从 Maven Central 加载.

      原文： Gets the libraries this plugin requires. This is a preview feature.

      返回:
      所需的类库

    • getClassLoaderOf

      @Deprecated(since="1.7.2") @Nullable public @Nullable String getClassLoaderOf()
      已过时。
      未使用
      未使用的方法.

      原文： unused

      返回:
      未使用

    • save

      public void save(@NotNull @NotNull Writer writer)
      将此 PluginDescriptionFile 保存到给定的 writer.

      原文： Saves this PluginDescriptionFile to the given writer

      参数:
      writer - 输出此文件的 Writer 对象

    • getRawName

      @Internal @NotNull public @NotNull String getRawName()
      获取插件的原始名称. 内部使用.

      原文： Gets the raw name of the plugin. Internal use.

      返回:
      插件的原始名称