public final class PluginDescriptionFile extends Object
When Bukkit loads a plugin, it needs to know some basic information about it. It reads this information from a YAML file, 'plugin.yml'. This file consists of a set of attributes, each defined on a new line and with no indentation.
Every (almost* every) method corresponds with a specific entry in the plugin.yml. These are the required entries for every plugin.yml:
getName()
- name
getVersion()
- version
getMain()
- main
Failing to include any of these items will throw an exception and cause the server to ignore your plugin.
This is a list of the possible yaml keys, with specific details included in the respective method documentations:
Node | Method | Summary |
---|---|---|
name |
getName() |
The unique name of plugin |
provides |
getProvides() |
The plugin APIs which this plugin provides |
version |
getVersion() |
A plugin revision identifier |
main |
getMain() |
The plugin's initial class file |
author authors |
getAuthors() |
The plugin contributors |
description |
getDescription() |
Human readable plugin summary |
website |
getWebsite() |
The URL to the plugin's site |
prefix |
getPrefix() |
The token to prefix plugin log entries |
load |
getLoad() |
The phase of server-startup this plugin will load during |
depend |
getDepend() |
Other required plugins |
softdepend |
getSoftDepend() |
Other plugins that add functionality |
loadbefore |
getLoadBefore() |
The inverse softdepend |
commands |
getCommands() |
The commands the plugin will register |
permissions |
getPermissions() |
The permissions the plugin will register |
default-permission |
getPermissionDefault() |
The default default permission
state for defined permissions the plugin
will register |
awareness |
getAwareness() |
The concepts that the plugin acknowledges |
api-version |
getAPIVersion() |
The API version which this plugin was programmed against |
A plugin.yml example:
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] website: http://www.curse.com/server-mods/minecraft/myplugin main: com.captaininflamo.bukkit.inferno.Inferno depend: [NewFire, FlameWire] api-version: 1.13 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
Constructor | Description |
---|---|
PluginDescriptionFile(@NotNull InputStream stream) |
|
PluginDescriptionFile(@NotNull Reader reader) |
Loads a PluginDescriptionFile from the specified reader
|
PluginDescriptionFile(@NotNull String pluginName,
@NotNull String pluginVersion,
@NotNull String mainClass) |
Creates a new PluginDescriptionFile with the given detailed
|
Modifier and Type | Method | Description |
---|---|---|
@Nullable String |
getAPIVersion() |
Gives the API version which this plugin is designed to support.
|
@NotNull List<String> |
getAuthors() |
Gives the list of authors for the plugin.
|
@NotNull Set<PluginAwareness> |
getAwareness() |
Gives a set of every
PluginAwareness for a plugin. |
@Nullable String |
getClassLoaderOf() |
Deprecated.
unused
|
@NotNull Map<String,Map<String,Object>> |
getCommands() |
Gives the map of command-name to command-properties.
|
@NotNull List<String> |
getDepend() |
Gives a list of other plugins that the plugin requires.
|
@Nullable String |
getDescription() |
Gives a human-friendly description of the functionality the plugin
provides.
|
@NotNull String |
getFullName() |
Returns the name of a plugin, including the version.
|
@NotNull PluginLoadOrder |
getLoad() |
Gives the phase of server startup that the plugin should be loaded.
|
@NotNull List<String> |
getLoadBefore() |
Gets the list of plugins that should consider this plugin a
soft-dependency.
|
@NotNull String |
getMain() |
Gives the fully qualified name of the main class for a plugin.
|
@NotNull String |
getName() |
Gives the name of the plugin.
|
@NotNull PermissionDefault |
getPermissionDefault() |
Gives the default
default state of
permissions registered for the plugin. |
@NotNull List<Permission> |
getPermissions() |
Gives the list of permissions the plugin will register at runtime,
immediately proceding enabling.
|
@Nullable String |
getPrefix() |
Gives the token to prefix plugin-specific logging messages with.
|
@NotNull List<String> |
getProvides() |
Gives the list of other plugin APIs which this plugin provides.
|
@NotNull String |
getRawName() |
Deprecated.
Internal use
|
@NotNull List<String> |
getSoftDepend() |
Gives a list of other plugins that the plugin requires for full
functionality.
|
@NotNull String |
getVersion() |
Gives the version of the plugin.
|
@Nullable String |
getWebsite() |
Gives the plugin's or plugin's author's website.
|
void |
save(@NotNull Writer writer) |
Saves this PluginDescriptionFile to the given writer
|
public PluginDescriptionFile(@NotNull @NotNull InputStream stream) throws InvalidDescriptionException
InvalidDescriptionException
public PluginDescriptionFile(@NotNull @NotNull Reader reader) throws InvalidDescriptionException
reader
- The readerInvalidDescriptionException
- If the PluginDescriptionFile is
invalidpublic PluginDescriptionFile(@NotNull @NotNull String pluginName, @NotNull @NotNull String pluginVersion, @NotNull @NotNull String mainClass)
pluginName
- Name of this pluginpluginVersion
- Version of this pluginmainClass
- Full location of the main class of this plugin@NotNull public @NotNull String getName()
Plugin.getDataFolder()
should be used to reference the data folder.
getDepend()
, getSoftDepend()
, and getLoadBefore()
.
In the plugin.yml, this entry is named name
.
Example:
name: MyPlugin
@NotNull public @NotNull List<String> getProvides()
getDepend()
,
getSoftDepend()
, and getLoadBefore()
.
provides
must be in YAML list
format.
In the plugin.yml, this entry is named provides
.
Example:
provides: - OtherPluginName - OldPluginName
@NotNull public @NotNull String getVersion()
/version PluginName
In the plugin.yml, this entry is named version
.
Example:
version: 1.4.1
@NotNull public @NotNull String getMain()
ClassLoader.loadClass(String)
syntax
to successfully be resolved at runtime. For most plugins, this is the
class that extends JavaPlugin
.
org.bukkit.plugin
, and your class
file is called MyPlugin
then this must be
org.bukkit.plugin.MyPlugin
org.bukkit.
as a base package for
any class, including the main class.
In the plugin.yml, this entry is named main
.
Example:
main: org.bukkit.plugin.MyPlugin
@Nullable public @Nullable String getDescription()
/version PluginName
In the plugin.yml, this entry is named description
.
Example:
description: This plugin is so 31337. You can set yourself on fire.
@NotNull public @NotNull PluginLoadOrder getLoad()
PluginLoadOrder
.
PluginLoadOrder.POSTWORLD
.
getDepend()
, getSoftDepend()
, and
getLoadBefore()
become relative in order loaded per-phase.
If a plugin loads at STARTUP
, but a dependency loads
at POSTWORLD
, the dependency will not be loaded before
the plugin is loaded.
In the plugin.yml, this entry is named load
.
Example:
load: STARTUP
@NotNull public @NotNull List<String> getAuthors()
/version PluginName
authors
must be in YAML list
format.
In the plugin.yml, this has two entries, author
and
authors
.
Single author example:
Multiple author example:author: CaptainInflamo
When both are specified, author will be the first entry in the list, so this example:authors: [Cogito, verrier, EvilSeph]
Is equivilant to this example:author: Grum authors: - feildmaster - amaranth
authors: [Grum, feildmaster, aramanth]
@Nullable public @Nullable String getWebsite()
/version PluginName
In the plugin.yml, this entry is named website
.
Example:
website: http://www.curse.com/server-mods/minecraft/myplugin
@NotNull public @NotNull List<String> getDepend()
getName()
of the target plugin to
specify the dependency.
depend
,
creating a network with no individual plugin does not list another
plugin in the network,
all plugins in that network will fail.
depend
must be in YAML list
format.
In the plugin.yml, this entry is named depend
.
Example:
depend: - OnePlugin - AnotherPlugin
@NotNull public @NotNull List<String> getSoftDepend()
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.
getName()
of the target plugin to
specify the dependency.
softdepend
must be in YAML list
format.
In the plugin.yml, this entry is named softdepend
.
Example:
softdepend: [OnePlugin, AnotherPlugin]
@NotNull public @NotNull List<String> getLoadBefore()
getName()
of the target plugin to
specify the dependency.
getSoftDepend()
include this plugin
.
loadbefore
must be in YAML list
format.
In the plugin.yml, this entry is named loadbefore
.
Example:
loadbefore: - OnePlugin - AnotherPlugin
@Nullable public @Nullable String getPrefix()
Plugin.getLogger()
.
name
.
In the plugin.yml, this entry is named prefix
.
Example:
prefix: ex-why-zee
@NotNull public @NotNull Map<String,Map<String,Object>> getCommands()
PluginCommand
and are defined here only as a convenience.
Node | Method | Type | Description | Example |
---|---|---|---|---|
description |
Command.setDescription(String) |
String | A user-friendly description for a command. It is useful for documentation purposes as well as in-game help. | description: Set yourself on fire |
aliases |
Command.setAliases(List) |
String or List of strings | Alternative command names, with special usefulness for commands
that are already registered. Aliases are not effective when
defined at runtime, so the plugin description file is the
only way to have them properly defined.
Note: Command aliases may not have a colon in them. |
Single alias format:
or multiple alias format:aliases: combust_me aliases: [combust_me, combustMe] |
permission |
Command.setPermission(String) |
String | The name of the Permission required to use the command.
A user without the permission will receive the specified
message (see below), or a
standard one if no specific message is defined. Without the
permission node, no CommandExecutor or
PluginCommand.setTabCompleter(TabCompleter) will be called. |
permission: inferno.flagrate |
permission-message |
Command.setPermissionMessage(String) |
String |
|
permission-message: You do not have /<permission> |
usage |
Command.setUsage(String) |
String | This message is displayed to a player when the PluginCommand.setExecutor(CommandExecutor) returns false.
<command> is a macro that is replaced the command issued. |
It is worth noting that to use a colon in a yaml, likeusage: Syntax error! Perhaps you meant /<command> PlayerName? `usage: Usage: /god [player]' , you need to
surround
the message with double-quote:
usage: "Usage: /god [player]" |
commands
', while each individual command name is
indented, indicating it maps to some value (in our case, the
properties of the table above).
Here is an example bringing together the piecemeal examples above, as well as few more definitions:
Note: Command names may not have a colon in their name.commands: flagrate: description: Set yourself on fire. aliases: [combust_me, combustMe] permission: inferno.flagrate permission-message: You do not have /<permission> usage: Syntax error! Perhaps you meant /<command> PlayerName? 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 # The next command has no description, aliases, etc. defined, but is still valid # Having an empty declaration is useful for defining the description, permission, and messages from a configuration dynamically apocalypse:
@NotNull public @NotNull List<Permission> getPermissions()
{}
) may be used (as a null value is not
accepted, unlike the commands
above).
A list of optional properties for permissions:
Node | Description | Example |
---|---|---|
description |
Plaintext (user-friendly) description of what the permission is for. | description: Allows you to set yourself on fire |
default |
The default state for the permission, as defined by Permission.getDefault() . If not defined, it will be set to
the value of getPermissionDefault() .
For reference:
|
default: true |
children |
Allows other permissions to be set as a relation to the parent permission.
When a parent permissions is assigned, child permissions are
respectively assigned as well.
Child permissions may be defined in a number of ways:
|
As a list:
Or as a mapping:children: [inferno.flagrate, inferno.burningdeaths] An additional example showing basic nested values can be seen here.children: inferno.flagrate: true inferno.burningdeaths: true |
permissions
', while each individual permission name is
indented, indicating it maps to some value (in our case, the
properties of the table above).
Here is an example using some of the properties:
Another example, with nested definitions, can be found here.permissions: inferno.*: description: Gives access to all Inferno commands children: inferno.flagrate: true inferno.burningdeaths: true inferno.flagate: 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
@NotNull public @NotNull PermissionDefault getPermissionDefault()
default
state of
permissions
registered for the plugin.
PermissionDefault.OP
.
PermissionDefault.getByName(String)
default
node.
PermissionDefault
.
In the plugin.yml, this entry is named default-permission
.
Example:
default-permission: NOT_OP
@NotNull public @NotNull Set<PluginAwareness> getAwareness()
PluginAwareness
for a plugin. An awareness
dictates something that a plugin developer acknowledges when the plugin
is compiled. Some implementions may define extra awarenesses that are
not included in the API. Any unrecognized
awareness (one unsupported or in a future version) will cause a dummy
object to be created instead of failing.
PluginAwareness.Flags
.
!@
).
awareness
must be in YAML list
format.
In the plugin.yml, this entry is named awareness
.
Example:
awareness: - !@UTF8
Note: Although unknown versions of some future awareness are gracefully substituted, previous versions of Bukkit (ones prior to the first implementation of awareness) will fail to load a plugin that defines any awareness.
@NotNull public @NotNull String getFullName()
getName()
and getVersion()
entries.@Nullable public @Nullable String getAPIVersion()
In the plugin.yml, this entry is named api-version
.
Example:
api-version: 1.13
@Deprecated @Nullable public @Nullable String getClassLoaderOf()
public void save(@NotNull @NotNull Writer writer)
writer
- Writer to output this file to@Deprecated @NotNull public @NotNull String getRawName()
Copyright © 2020. All rights reserved.