Bukkit-API  1.7.9-R0.2
The inofficial Bukkit-API
org.bukkit.plugin.PluginDescriptionFile Class Reference

Public Member Functions

 PluginDescriptionFile (final InputStream stream) throws InvalidDescriptionException
 
 PluginDescriptionFile (final Reader reader) throws InvalidDescriptionException
 
 PluginDescriptionFile (final String pluginName, final String pluginVersion, final String mainClass)
 
String getName ()
 
String getVersion ()
 
String getMain ()
 
String getDescription ()
 
PluginLoadOrder getLoad ()
 
List< String > getAuthors ()
 
String getWebsite ()
 
boolean isDatabaseEnabled ()
 
List< String > getDepend ()
 
List< String > getSoftDepend ()
 
List< String > getLoadBefore ()
 
String getPrefix ()
 
Map< String, Map< String, Object > > getCommands ()
 
List< PermissiongetPermissions ()
 
PermissionDefault getPermissionDefault ()
 
Set< PluginAwarenessgetAwareness ()
 
String getFullName ()
 
String getClassLoaderOf ()
 
void setDatabaseEnabled (boolean database)
 
void save (Writer writer)
 
String getRawName ()
 

Detailed Description

This type is the runtime-container for the information in the plugin.yml. All plugins must have a respective plugin.yml. For plugins written in java using the standard plugin loader, this file must be in the root of the jar file.

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:

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
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
database isDatabaseEnabled() Indicator to enable database support
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

A plugin.yml example:

name: Inferno
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
database: false
depend: [NewFire, FlameWire]
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

Definition at line 177 of file PluginDescriptionFile.java.

Constructor & Destructor Documentation

org.bukkit.plugin.PluginDescriptionFile.PluginDescriptionFile ( final Reader  reader) throws InvalidDescriptionException

Loads a PluginDescriptionFile from the specified reader

Parameters
readerThe reader
Exceptions
InvalidDescriptionExceptionIf the PluginDescriptionFile is invalid

Definition at line 242 of file PluginDescriptionFile.java.

242  {
243  loadMap(asMap(YAML.get().load(reader)));
244  }
org.bukkit.plugin.PluginDescriptionFile.PluginDescriptionFile ( final String  pluginName,
final String  pluginVersion,
final String  mainClass 
)

Creates a new PluginDescriptionFile with the given detailed

Parameters
pluginNameName of this plugin
pluginVersionVersion of this plugin
mainClassFull location of the main class of this plugin

Definition at line 253 of file PluginDescriptionFile.java.

253  {
254  name = pluginName.replace(' ', '_');
255  version = pluginVersion;
256  main = mainClass;
257  }

Member Function Documentation

List<String> org.bukkit.plugin.PluginDescriptionFile.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 bukkit.org 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 and authors.

Single author example:

author: CaptainInflamo

Multiple author example:

authors: [Cogito, verrier, EvilSeph]

When both are specified, author will be the first entry in the list, so this example:

author: Grum
authors:

  • feildmaster
  • amaranth

Is equivilant to this example:

authors: [Grum, feildmaster, aramanth]

 
Returns
an immutable list of the plugin's authors

Definition at line 407 of file PluginDescriptionFile.java.

407  {
408  return authors;
409  }
Set<PluginAwareness> org.bukkit.plugin.PluginDescriptionFile.getAwareness ( )

Gives a set of every 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.

  • Currently only supports the enumerated values in PluginAwareness.Flags.
  • Each awareness starts the identifier with bang-at (!</code>).
  • 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:

  • !

 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

Definition at line 848 of file PluginDescriptionFile.java.

848  {
849  return awareness;
850  }
String org.bukkit.plugin.PluginDescriptionFile.getClassLoaderOf ( )
Deprecated:
unused

Definition at line 867 of file PluginDescriptionFile.java.

867  {
868  return classLoaderOf;
869  }
Map<String, Map<String, Object> > org.bukkit.plugin.PluginDescriptionFile.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 in PluginCommand and are defined here only as a convenience.

Node Method Type Description Example
description PluginCommand#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 PluginCommand#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:
aliases: combust_me
or multiple alias format:
aliases: [combust_me, combustMe]
permission PluginCommand#setPermission(String) String The name of the Permission required to use the command. A user without the permission will receive the specified message (see PluginCommand::setPermissionMessage(String) below}), or a standard one if no specific message is defined. Without the permission node, no CommandExecutor or TabCompleter will be called.
permission: inferno.flagrate
permission-message PluginCommand#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 PluginCommand#setUsage(String) String This message is displayed to a player when the PluginCommand#setExecutor(CommandExecutor) CommandExecutor::onCommand(CommandSender,Command,String,String[]) returns false}. <command> is a macro that is replaced the command issued.
usage: Syntax error! Perhaps you meant /<command> PlayerName?
It is worth noting that to use a colon in a yaml, like `usage: Usage: /god [player]', you need to surround the message with double-quote:
usage: "Usage: /god [player]"

The commands are structured as a hiearchy of nested mappings. The primary (top-level, no intendentation) node is `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:

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:

Note: Command names may not have a colon in their name.

 
Returns
the commands this plugin will register

Definition at line 671 of file PluginDescriptionFile.java.

671  {
672  return commands;
673  }
List<String> org.bukkit.plugin.PluginDescriptionFile.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 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

Definition at line 475 of file PluginDescriptionFile.java.

Referenced by org.bukkit.plugin.SimplePluginManager.loadPlugins().

475  {
476  return depend;
477  }
String org.bukkit.plugin.PluginDescriptionFile.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.
Returns
description of this plugin, or null if not specified

Definition at line 349 of file PluginDescriptionFile.java.

349  {
350  return description;
351  }
String org.bukkit.plugin.PluginDescriptionFile.getFullName ( )

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

Returns
a descriptive name of the plugin and respective version

Definition at line 859 of file PluginDescriptionFile.java.

Referenced by org.bukkit.permissions.PermissibleBase.addAttachment(), org.bukkit.plugin.java.JavaPluginLoader.disablePlugin(), org.bukkit.command.PluginCommand.execute(), org.bukkit.WorldCreator.getGeneratorForName(), org.bukkit.plugin.PluginDescriptionFile.getPermissions(), org.bukkit.plugin.SimplePluginManager.loadPlugins(), and org.bukkit.command.PluginCommand.tabComplete().

859  {
860  return name + " v" + version;
861  }
PluginLoadOrder org.bukkit.plugin.PluginDescriptionFile.getLoad ( )

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

In the plugin.yml, this entry is named load.

Example:

load: STARTUP
Returns
the phase when the plugin should be loaded

Definition at line 372 of file PluginDescriptionFile.java.

372  {
373  return order;
374  }
List<String> org.bukkit.plugin.PluginDescriptionFile.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() include this 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

Definition at line 533 of file PluginDescriptionFile.java.

Referenced by org.bukkit.plugin.SimplePluginManager.loadPlugins().

533  {
534  return loadBefore;
535  }
String org.bukkit.plugin.PluginDescriptionFile.getMain ( )

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.

  • This must contain the full namespace including the class file itself.
  • If your namespace is org.bukkit.plugin, and your class file is called MyPlugin then this must be org.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

Definition at line 330 of file PluginDescriptionFile.java.

330  {
331  return main;
332  }
String org.bukkit.plugin.PluginDescriptionFile.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(), and getLoadBefore().
  • Using spaces in the plugin's name is deprecated.

In the plugin.yml, this entry is named name.

Example:

name: MyPlugin
Returns
the name of the plugin

Definition at line 284 of file PluginDescriptionFile.java.

Referenced by org.bukkit.plugin.java.JavaPluginLoader.disablePlugin(), org.bukkit.plugin.java.JavaPlugin.getCommand(), org.bukkit.plugin.PluginBase.getName(), org.bukkit.plugin.SimplePluginManager.loadPlugin(), org.bukkit.plugin.SimplePluginManager.loadPlugins(), and org.bukkit.plugin.PluginLogger.PluginLogger().

284  {
285  return name;
286  }
PermissionDefault org.bukkit.plugin.PluginDescriptionFile.getPermissionDefault ( )

Gives the default default state of permissions registered for the plugin.

In the plugin.yml, this entry is named default-permission.

Example:

default-permission: NOT_OP
Returns
the default value for the plugin's permissions

Definition at line 809 of file PluginDescriptionFile.java.

809  {
810  return defaultPerm;
811  }
List<Permission> org.bukkit.plugin.PluginDescriptionFile.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 ( &#123;&#125; ) 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 PluginDescriptionFile#getPermissionDefault().

For reference:

default: true
children

Allows other permissions to be set as a Permission::getChildren() 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 ( &#123;&#125; ) 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:
children: [inferno.flagrate, inferno.burningdeaths]
Or as a mapping:
children:
  inferno.flagrate: true
  inferno.burningdeaths: true
An additional example showing basic nested values can be seen here.

The permissions are structured as a hiearchy of nested mappings. The primary (top-level, no intendentation) node is `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:

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

Another example, with nested definitions, can be found here.

Definition at line 780 of file PluginDescriptionFile.java.

References org.bukkit.plugin.PluginDescriptionFile.getFullName(), and org.bukkit.permissions.Permission.loadPermissions().

780  {
781  if (permissions == null) {
782  if (lazyPermissions == null) {
783  permissions = ImmutableList.<Permission>of();
784  } else {
785  permissions = ImmutableList.copyOf(Permission.loadPermissions(lazyPermissions, "Permission node '%s' in plugin description file for " + getFullName() + " is invalid", defaultPerm));
786  lazyPermissions = null;
787  }
788  }
789  return permissions;
790  }
String org.bukkit.plugin.PluginDescriptionFile.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

Definition at line 552 of file PluginDescriptionFile.java.

Referenced by org.bukkit.plugin.PluginLogger.PluginLogger().

552  {
553  return prefix;
554  }
String org.bukkit.plugin.PluginDescriptionFile.getRawName ( )
Deprecated:
Internal use

Definition at line 1107 of file PluginDescriptionFile.java.

1107  {
1108  return rawName;
1109  }
List<String> org.bukkit.plugin.PluginDescriptionFile.getSoftDepend ( )

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.

  • 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

Definition at line 504 of file PluginDescriptionFile.java.

Referenced by org.bukkit.plugin.SimplePluginManager.loadPlugins().

504  {
505  return softDepend;
506  }
String org.bukkit.plugin.PluginDescriptionFile.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
Returns
the version of the plugin

Definition at line 304 of file PluginDescriptionFile.java.

304  {
305  return version;
306  }
String org.bukkit.plugin.PluginDescriptionFile.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
Returns
description of this plugin, or null if not specified

Definition at line 426 of file PluginDescriptionFile.java.

426  {
427  return website;
428  }
boolean org.bukkit.plugin.PluginDescriptionFile.isDatabaseEnabled ( )

Gives if the plugin uses a database.

  • Using a database is non-trivial.
  • Valid values include true and false

In the plugin.yml, this entry is named database.

Example:

database: false
Returns
if this plugin requires a database
See also
Plugin::getDatabase()

Definition at line 445 of file PluginDescriptionFile.java.

445  {
446  return database;
447  }
void org.bukkit.plugin.PluginDescriptionFile.save ( Writer  writer)

Saves this PluginDescriptionFile to the given writer

Parameters
writerWriter to output this file to

Definition at line 880 of file PluginDescriptionFile.java.

880  {
881  YAML.get().dump(saveMap(), writer);
882  }

The documentation for this class was generated from the following file: