Class PluginDescriptionFile
- All Implemented Interfaces:
PluginMeta
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 authors |
contributors |
getContributors() |
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 |
libraries |
() |
The libraries to be linked with this plugin |
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] 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
-
Constructor Summary
ConstructorDescriptionPluginDescriptionFile
(@NotNull InputStream stream) PluginDescriptionFile
(@NotNull Reader reader) Loads a PluginDescriptionFile from the specified readerPluginDescriptionFile
(@NotNull String pluginName, @NotNull String pluginVersion, @NotNull String mainClass) Creates a new PluginDescriptionFile with the given detailedPluginDescriptionFile
(String rawName, String name, List<String> provides, String main, String classLoaderOf, List<String> depend, List<String> softDepend, List<String> loadBefore, String version, Map<String, Map<String, Object>> commands, String description, List<String> authors, List<String> contributors, String website, String prefix, PluginLoadOrder order, List<Permission> permissions, PermissionDefault defaultPerm, Set<PluginAwareness> awareness, String apiVersion, List<String> libraries) Don't use this. -
Method Summary
Modifier and TypeMethodDescriptionGives the API version which this plugin is designed to support.Gives the list of authors for the plugin.Gives a set of everyPluginAwareness
for a plugin.Deprecated.unusedGives the map of command-name to command-properties.Gives the list of contributors for the plugin.Gives a list of other plugins that the plugin requires.Gives a human-friendly description of the functionality the plugin provides.Returns the name of a plugin, including the version.Gets the libraries this plugin requires.getLoad()
Gives the phase of server startup that the plugin should be loaded.Gets the list of plugins that should consider this plugin a soft-dependency.Provides a list of plugins that should be loaded before this plugin is loaded.Returns the phase of the server startup logic that the plugin should be loaded.Provides the prefix that should be used for the plugin logger.getMain()
Gives the fully qualified name of the main class for a plugin.Provides the fully qualified class name of the main class for the plugin.getName()
Gives the name of the plugin.Gives the defaultdefault
state ofpermissions
registered for the plugin.Gives the list of permissions the plugin will register at runtime, immediately proceding enabling.Provides a list of dependencies that are required for this plugin to load.Provides a list of dependencies that are used but not required by this plugin.Gives the token to prefix plugin-specific logging messages with.Returns the list of plugins/dependencies that this plugin provides.Gives the list of other plugin APIs which this plugin provides.Gives a list of other plugins that the plugin requires for full functionality.Gives the version of the plugin.Gives the plugin's or plugin's author's website.void
Saves this PluginDescriptionFile to the given writerMethods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface io.papermc.paper.plugin.configuration.PluginMeta
getDisplayName
-
Constructor Details
-
PluginDescriptionFile
@Internal public PluginDescriptionFile(String rawName, String name, List<String> provides, String main, String classLoaderOf, List<String> depend, List<String> softDepend, List<String> loadBefore, String version, Map<String, Map<String, Object>> commands, String description, List<String> authors, List<String> contributors, String website, String prefix, PluginLoadOrder order, List<Permission> permissions, PermissionDefault defaultPerm, Set<PluginAwareness> awareness, String apiVersion, List<String> libraries) Don't use this. -
PluginDescriptionFile
public PluginDescriptionFile(@NotNull @NotNull InputStream stream) throws InvalidDescriptionException - Throws:
InvalidDescriptionException
-
PluginDescriptionFile
Loads a PluginDescriptionFile from the specified reader- Parameters:
reader
- The reader- Throws:
InvalidDescriptionException
- If the PluginDescriptionFile is invalid
-
PluginDescriptionFile
public PluginDescriptionFile(@NotNull @NotNull String pluginName, @NotNull @NotNull String pluginVersion, @NotNull @NotNull String mainClass) Creates a new PluginDescriptionFile with the given detailed- Parameters:
pluginName
- Name of this pluginpluginVersion
- Version of this pluginmainClass
- Full location of the main class of this plugin
-
-
Method Details
-
getPaperPluginLoader
-
getMainClass
Description copied from interface:PluginMeta
Provides the fully qualified class name of the main class for the plugin. A subtype ofJavaPlugin
is expected at this location.- Specified by:
getMainClass
in interfacePluginMeta
- Returns:
- the fully qualified class name of the plugin's main class.
-
getLoadOrder
Description copied from interface:PluginMeta
Returns the phase of the server startup logic that the plugin should be loaded.- Specified by:
getLoadOrder
in interfacePluginMeta
- Returns:
- the plugin load order
- See Also:
-
getLoggerPrefix
Description copied from interface:PluginMeta
Provides the prefix that should be used for the plugin logger. The logger prefix allows plugins to overwrite the usual default of the logger prefix, which is the name of the plugin.- Specified by:
getLoggerPrefix
in interfacePluginMeta
- Returns:
- the specific overwrite of the logger prefix as defined by the plugin. If the plugin did not define a custom logger prefix, this method will return null
-
getPluginDependencies
Description copied from interface:PluginMeta
Provides a list of dependencies that are required for this plugin to load. The list holds the unique identifiers, following the constraints laid out inPluginMeta.getName()
, of the dependencies.If any of the dependencies defined by this list are not installed on the server, this plugin will fail to load.
- Specified by:
getPluginDependencies
in interfacePluginMeta
- Returns:
- an immutable list of required dependency names
-
getPluginSoftDependencies
Description copied from interface:PluginMeta
Provides a list of dependencies that are used but not required by this plugin. The list holds the unique identifiers, following the constraints laid out inPluginMeta.getName()
, of the soft dependencies.If these dependencies are installed on the server, they will be loaded first and supplied as dependencies to this plugin, however the plugin will load even if these dependencies are not installed.
- Specified by:
getPluginSoftDependencies
in interfacePluginMeta
- Returns:
- immutable list of soft dependencies
-
getLoadBeforePlugins
Description copied from interface:PluginMeta
Provides a list of plugins that should be loaded before this plugin is loaded. The list holds the unique identifiers, following the constraints laid out inPluginMeta.getName()
, of the plugins that should be loaded before the plugin described by this plugin meta.The plugins referenced in the list provided by this method are not considered dependencies of this plugin and are hence not available to the plugin at runtime. They merely load before this plugin.
- Specified by:
getLoadBeforePlugins
in interfacePluginMeta
- Returns:
- immutable list of plugins to load before this plugin
-
getProvidedPlugins
Description copied from interface:PluginMeta
Returns the list of plugins/dependencies that this plugin provides. The list holds the unique identifiers, following the constraints laid out inPluginMeta.getName()
, for each plugin it provides the expected classes for.- Specified by:
getProvidedPlugins
in interfacePluginMeta
- Returns:
- immutable list of provided plugins/dependencies
-
getName
Gives the name of the plugin. This name is a unique identifier for plugins.- Must consist of all alphanumeric characters, underscores, hyphon, and period (a-z,A-Z,0-9, _.-). Any other character will cause the plugin.yml to fail loading.
- Used to determine the name of the plugin's data folder. Data
folders are placed in the ./plugins/ directory by default, but this
behavior should not be relied on.
Plugin.getDataFolder()
should be used to reference the data folder. - It is good practice to name your jar the same as this, for example 'MyPlugin.jar'.
- Case sensitive.
- The is the token referenced in
getDepend()
,getSoftDepend()
, andgetLoadBefore()
. - Using spaces in the plugin's name is deprecated.
In the plugin.yml, this entry is named
name
.Example:
name: MyPlugin
- Specified by:
getName
in interfacePluginMeta
- Returns:
- the name of the plugin
-
getProvides
Gives the list of other plugin APIs which this plugin provides. These are usable for other plugins to depend on.- Must consist of all alphanumeric characters, underscores, hyphon, and period (a-z,A-Z,0-9, _.-). Any other character will cause the plugin.yml to fail loading.
- A different plugin providing the same one or using it as their name will not result in the plugin to fail loading.
- Case sensitive.
- An entry of this list can be referenced in
getDepend()
,getSoftDepend()
, andgetLoadBefore()
. provides
must be in YAML list format.
In the plugin.yml, this entry is named
provides
.Example:
provides: - OtherPluginName - OldPluginName
- Returns:
- immutable list of the plugin APIs which this plugin provides
-
getVersion
Gives the version of the plugin.- Version is an arbitrary string, however the most common format is MajorRelease.MinorRelease.Build (eg: 1.4.1).
- Typically you will increment this every time you release a new feature or bug fix.
- Displayed when a user types
/version PluginName
In the plugin.yml, this entry is named
version
.Example:
version: 1.4.1
- Specified by:
getVersion
in interfacePluginMeta
- Returns:
- the version of the plugin
-
getMain
Gives the fully qualified name of the main class for a plugin. The format should follow theClassLoader.loadClass(String)
syntax to successfully be resolved at runtime. For most plugins, this is the class that extendsJavaPlugin
.- This must contain the full namespace including the class file itself.
- If your namespace is
org.bukkit.plugin
, and your class file is calledMyPlugin
then this must beorg.bukkit.plugin.MyPlugin
- No plugin can use
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
- Returns:
- the fully qualified main class for the plugin
-
getDescription
Gives a human-friendly description of the functionality the plugin provides.- The description can have multiple lines.
- Displayed when a user types
/version PluginName
In the plugin.yml, this entry is named
description
.Example:
description: This plugin is so 31337. You can set yourself on fire.
- Specified by:
getDescription
in interfacePluginMeta
- Returns:
- description of this plugin, or null if not specified
-
getLoad
Gives the phase of server startup that the plugin should be loaded.- Possible values are in
PluginLoadOrder
. - Defaults to
PluginLoadOrder.POSTWORLD
. - Certain caveats apply to each phase.
- When different,
getDepend()
,getSoftDepend()
, andgetLoadBefore()
become relative in order loaded per-phase. If a plugin loads atSTARTUP
, but a dependency loads atPOSTWORLD
, the dependency will not be loaded before the plugin is loaded.
In the plugin.yml, this entry is named
load
.Example:
load: STARTUP
- Returns:
- the phase when the plugin should be loaded
- Possible values are in
-
getAuthors
Gives the list of authors for the plugin.- Gives credit to the developer.
- Used in some server error messages to provide helpful feedback on who to contact when an error occurs.
- A SpigotMC forum handle or email address is recommended.
- Is displayed when a user types
/version PluginName
authors
must be in YAML list format.
In the plugin.yml, this has two entries,
author
andauthors
.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]
- Specified by:
getAuthors
in interfacePluginMeta
- Returns:
- an immutable list of the plugin's authors
-
getContributors
Gives the list of contributors for the plugin.- Gives credit to those that have contributed to the plugin, though not enough so to warrant authorship.
- Unlike
getAuthors()
, contributors will not be mentioned in server error messages as a means of contact. - A SpigotMC forum handle or email address is recommended.
- Is displayed when a user types
/version PluginName
contributors
must be in YAML list format.
Example:
authors: [Choco, md_5]
- Specified by:
getContributors
in interfacePluginMeta
- Returns:
- an immutable list of the plugin's contributors
-
getWebsite
Gives the plugin's or plugin's author's website.- A link to the Curse page that includes documentation and downloads is highly recommended.
- Displayed when a user types
/version PluginName
In the plugin.yml, this entry is named
website
.Example:
website: http://www.curse.com/server-mods/minecraft/myplugin
- Specified by:
getWebsite
in interfacePluginMeta
- Returns:
- description of this plugin, or null if not specified
-
getDepend
Gives a list of other plugins that the plugin requires.- Use the value in the
getName()
of the target plugin to specify the dependency. - If any plugin listed here is not found, your plugin will fail to load at startup.
- If multiple plugins list each other in
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
- Returns:
- immutable list of the plugin's dependencies
- Use the value in the
-
getSoftDepend
Gives a list of other plugins that the plugin requires for full functionality. ThePluginManager
will make best effort to treat all entries here as if they were adependency
, but will never fail because of one of these entries.- Use the value in the
getName()
of the target plugin to specify the dependency. - When an unresolvable plugin is listed, it will be ignored and does not affect load order.
- When a circular dependency occurs (a network of plugins depending or soft-dependending each other), it will arbitrarily choose a plugin that can be resolved when ignoring soft-dependencies.
softdepend
must be in YAML list format.
In the plugin.yml, this entry is named
softdepend
.Example:
softdepend: [OnePlugin, AnotherPlugin]
- Returns:
- immutable list of the plugin's preferred dependencies
- Use the value in the
-
getLoadBefore
Gets the list of plugins that should consider this plugin a soft-dependency.- Use the value in the
getName()
of the target plugin to specify the dependency. - The plugin should load before any other plugins listed here.
- Specifying another plugin here is strictly equivalent to having the
specified plugin's
getSoftDepend()
includethis plugin
. loadbefore
must be in YAML list format.
In the plugin.yml, this entry is named
loadbefore
.Example:
loadbefore: - OnePlugin - AnotherPlugin
- Returns:
- immutable list of plugins that should consider this plugin a soft-dependency
- Use the value in the
-
getPrefix
Gives the token to prefix plugin-specific logging messages with.- This includes all messages using
Plugin.getLogger()
. - If not specified, the server uses the plugin's
name
. - This should clearly indicate what plugin is being logged.
In the plugin.yml, this entry is named
prefix
.Example:
prefix: ex-why-zee
- Returns:
- the prefixed logging token, or null if not specified
- This includes all messages using
-
getCommands
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. Each property, with the exception of aliases, can be defined at runtime using methods inPluginCommand
and are defined here only as a convenience.The command section's description 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, noCommandExecutor
orPluginCommand.setTabCompleter(TabCompleter)
will be called.permission: inferno.flagrate
permission-message
Command.setPermissionMessage(String)
String - Displayed to a player that attempts to use a command, but
does not have the required permission. See
above
. - <permission> is a macro that is replaced with the permission node required to use the command.
- Using empty quotes is a valid way to indicate nothing should be displayed to a player.
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:
- Returns:
- the commands this plugin will register
- Displayed to a player that attempts to use a command, but
does not have the required permission. See
-
getPermissions
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. To represent a map without any specific property, empty curly-braces ({}
) may be used (as a null value is not accepted, unlike thecommands
above).A list of optional properties for permissions:
The permission section's description 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 ofgetPermissionDefault()
.For reference:
true
- Represents a positive assignment topermissibles
.false
- Represents no assignment topermissibles
.op
- Represents a positive assignment tooperator permissibles
.notop
- Represents a positive assignment tonon-operator permissibiles
.
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. - When a parent permission is assigned negatively, child permissions are assigned based on an inversion of their association.
- When a parent permission is assigned positively, child permissions are assigned based on their association.
Child permissions may be defined in a number of ways:
- Children may be defined as a list of names. Using a list will treat all children associated positively to their parent.
- Children may be defined as a map. Each permission name maps to either a boolean (representing the association), or a nested permission definition (just as another permission). Using a nested definition treats the child as a positive association.
- A nested permission definition must be a map of these same
properties. To define a valid nested permission without
defining any specific property, empty curly-braces (
{}
) must be used. - A nested permission may carry it's own nested permissions as children, as they may also have nested permissions, and so forth. There is no direct limit to how deep the permission tree is defined.
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
- Specified by:
getPermissions
in interfacePluginMeta
- Returns:
- the permissions this plugin will register
-
getPermissionDefault
Gives the defaultdefault
state ofpermissions
registered for the plugin.- If not specified, it will be
PermissionDefault.OP
. - It is matched using
PermissionDefault.getByName(String)
- It only affects permissions that do not define the
default
node. - It may be any value in
PermissionDefault
.
In the plugin.yml, this entry is named
default-permission
.Example:
default-permission: NOT_OP
- Specified by:
getPermissionDefault
in interfacePluginMeta
- Returns:
- the default value for the plugin's permissions
- See Also:
- If not specified, it will be
-
getAwareness
Gives a set of everyPluginAwareness
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.- Currently only supports the enumerated values in
PluginAwareness.Flags
. - Each awareness starts the identifier with bang-at
(
!@
). - Unrecognized (future / unimplemented) entries are quietly replaced by a generic object that implements PluginAwareness.
- A type of awareness must be defined by the runtime and acknowledged by the API, effectively discluding any derived type from any plugin's classpath.
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.
- Returns:
- a set containing every awareness for the plugin
- Currently only supports the enumerated values in
-
getFullName
Returns the name of a plugin, including the version. This method is provided for convenience; it uses thegetName()
andgetVersion()
entries.- Returns:
- a descriptive name of the plugin and respective version
-
getAPIVersion
Gives the API version which this plugin is designed to support. No specific format is guaranteed.- Refer to release notes for supported API versions.
In the plugin.yml, this entry is named
api-version
.Example:
api-version: 1.13
- Specified by:
getAPIVersion
in interfacePluginMeta
- Returns:
- the version of the plugin
-
getLibraries
Gets the libraries this plugin requires. This is a preview feature.- Libraries must be GAV specifiers and are loaded from Maven Central.
Example:
libraries: - com.squareup.okhttp3:okhttp:4.9.0
- Returns:
- required libraries
-
getClassLoaderOf
Deprecated.unused- Returns:
- unused
-
save
Saves this PluginDescriptionFile to the given writer- Parameters:
writer
- Writer to output this file to
-
getRawName
- Returns:
- internal use
- API Note:
- Internal use
-