Class PluginDescriptionFile

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:

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

Method Detail

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'.

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.

When different, 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.

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.

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.

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.

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
TabCompleter will be called.

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

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 the commands above).

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.

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

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.

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.