|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.bukkit.plugin.PluginDescriptionFile
public final 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:
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 |
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 |
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
Constructor Summary | |
---|---|
PluginDescriptionFile(InputStream stream)
|
|
PluginDescriptionFile(Reader reader)
Loads a PluginDescriptionFile from the specified reader |
|
PluginDescriptionFile(String pluginName,
String pluginVersion,
String mainClass)
Creates a new PluginDescriptionFile with the given detailed |
Method Summary | |
---|---|
List<String> |
getAuthors()
Gives the list of authors for the plugin. |
String |
getClassLoaderOf()
|
Map<String,Map<String,Object>> |
getCommands()
Gives the map of command-name to command-properties. |
List<String> |
getDepend()
Gives a list of other plugins that the plugin requires. |
String |
getDescription()
Gives a human-friendly description of the functionality the plugin provides. |
String |
getFullName()
Returns the name of a plugin, including the version. |
PluginLoadOrder |
getLoad()
Gives the phase of server startup that the plugin should be loaded. |
List<String> |
getLoadBefore()
Gets the list of plugins that should consider this plugin a soft-dependency. |
String |
getMain()
Gives the fully qualified name of the main class for a plugin. |
String |
getName()
Gives the name of the plugin. |
PermissionDefault |
getPermissionDefault()
Gives the default default state of
permissions registered for the plugin. |
List<Permission> |
getPermissions()
Gives the list of permissions the plugin will register at runtime, immediately proceding enabling. |
String |
getPrefix()
Gives the token to prefix plugin-specific logging messages with. |
List<String> |
getSoftDepend()
Gives a list of other plugins that the plugin requires for full functionality. |
String |
getVersion()
Gives the version of the plugin. |
String |
getWebsite()
Gives the plugin's or plugin's author's website. |
boolean |
isDatabaseEnabled()
Gives if the plugin uses a database. |
void |
save(Writer writer)
Saves this PluginDescriptionFile to the given writer |
void |
setDatabaseEnabled(boolean database)
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public PluginDescriptionFile(InputStream stream) throws InvalidDescriptionException
InvalidDescriptionException
public PluginDescriptionFile(Reader reader) throws InvalidDescriptionException
reader
- The reader
InvalidDescriptionException
- If the PluginDescriptionFile is
invalidpublic PluginDescriptionFile(String pluginName, String pluginVersion, String mainClass)
pluginName
- Name of this pluginpluginVersion
- Version of this pluginmainClass
- Full location of the main class of this pluginMethod Detail |
---|
public 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
public String getVersion()
/version PluginName
In the plugin.yml, this entry is named version
.
Example:
version: 1.4.1
public 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
public 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.
public 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
public 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]
public String getWebsite()
/version PluginName
In the plugin.yml, this entry is named website
.
Example:
website: http://www.curse.com/server-mods/minecraft/myplugin
public boolean isDatabaseEnabled()
true
and false
In the plugin.yml, this entry is named database
.
Example:
database: false
Plugin.getDatabase()
public 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 must be in YAML list
format.
In the plugin.yml, this entry is named depend
.
Example:
depend: - OnePlugin - AnotherPlugin
public 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]
public 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
public String getPrefix()
Plugin.getLogger()
.
name
.
In the plugin.yml, this entry is named prefix
.
Example:
prefix: ex-why-zee
public 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. | 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
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:
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:
public 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
public 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
public String getFullName()
getName()
and getVersion()
entries.
public String getClassLoaderOf()
public void setDatabaseEnabled(boolean database)
public void save(Writer writer)
writer
- Writer to output this file to
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |