Plugin YAML

This page has been suggested for inclusion in the Official Documentation This page has been marked for inclusion in the Bukkit Official Documentation section, Docs. You can deliberate about its inclusion on its Talk page.

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.

Attributes

Attribute	Required	Description	Example	Notes
name	yes	The name of your plugin.	name: MyPlugin	Must consist of all alphanumeric characters and underscores (a-z,A-Z,0-9, _) Used to determine the name of the plugin's data folder. Data folders are placed in the ./plugins/ directory by default. It is good practice to name your jar the same as this, for example 'MyPlugin.jar'
version	yes	The version of this plugin.	version: 1.4.1	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
description	no	A human friendly description of the functionality your plugin provides.	description: This plugin is so 31337. You can set yourself on fire.	The description can have multiple lines. Displayed when a user types /version PluginName
load	no	Explicitly state when the plugin should be loaded. if not supplied will default to postworld	load: STARTUP	Has two possible values STARTUP POSTWORLD
author	no	Uniquely identifies who developed this plugin.	author: CaptainInflamo	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	no	Allows you to list multiple authors, if it is a collaborative project. See author.	authors: [Cogito, verrier, EvilSeph]	You can define both author and authors, however they will be merged into one list internally.
website	no	The plugin's or author's website.	website: http://forums.bukkit.org/threads/MyPlugin.31337/	If you have no dedicated website, a link to the Bukkit forum post where this plugin is listed is highly recommended. Displayed when a user types /version PluginName
main	yes	Points to the class that extends JavaPlugin	main: org.bukkit.plugin.MyPlugin	Note that 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
database	no	Set to true if this plugin uses a database.	database: false	Using a database is non-trivial. See Plugin_Databases
depend	no	A list of plugins that your plugin requires to load.	depend: [OnePlugin, AnotherPlugin]	The value must be in YAML list format (See http://en.wikipedia.org/wiki/YAML#Lists ) Use the "name" attribute of the required plugin in order to specify the dependency. If any plugin listed here is not found your plugin will fail to load. If multiple plugins list each other as a depend, so that there are no plugins without an unloadable dependency, all will fail to load. (See: Wiki: Plugin_Dependencies)
prefix	no	The name to use when logging to console instead of the plugin's name.	prefix: ex-why-zee
softdepend	no	A list of plugins that are required for your plugin to have full functionality.	softdepend: [OnePlugin, AnotherPlugin]	The value must be in YAML list format (See http://en.wikipedia.org/wiki/YAML#Lists ) Use the "name" atrribute of the desired plugin in order to specify the dependancy. Your plugin will load after any plugins listed here. Circular soft dependencies are loaded arbitrarily. (See: Wiki: Plugin_Dependencies)
loadbefore	no	A list of plugins should be loaded after your plugin.	loadbefore: [OnePlugin, AnotherPlugin]	The value must be in YAML list format (See http://en.wikipedia.org/wiki/YAML#Lists ) Treated as if the listed plugin soft depends on the specifying plugin. Use the "name" atrribute of the desired plugin in order to specify the target. Your plugin will load before any plugins listed here. Circular soft dependencies are loaded arbitrarily. (See: Wiki: Plugin_Dependencies)
commands	no	The name of a command the plugin wishes to register, as well as an optional list of command attributes.	commands: flagrate: [optional command attributes]	The command name should not contain the leading '/' required to issue a command. You can choose any command name you wish, however 'common' commands such as /kick are often already registered. Use the 'alias' command attribute to supply alternate names. @TODO: verify we're happy with this
permissions	no	Permissions that the plugin whishes to register. Each node represents a permission to register. Each permission can have additional attributes.	permissions: inferno.*: [optional permission attributes] inferno.flagate: [optional permission attributes] inferno.burningdeaths: [optional permission attributes]	Permission registration is optional, can also be done from code Permission registration allows you to set descriptions, defaults, and child parent relationships Permission names should be kept in the style of <pluginname>.[category].[category].<permission>

A command block starts with the command's name, and then has a list of attributes.

Command Attribute	Required	Description	Example	Notes
description	no	A short description of what the command does.	description: Set yourself on fire	Can be used in conjunction with /help
aliases	no	Alternate command names a user may use instead	aliases: combust_me OR aliases: [combust_me, combustMe, cm]	You can specify any of none, 1 or many aliases. If you specify more than one alias, they must be in YAML list format (See http://en.wikipedia.org/wiki/YAML#Lists )
permission	no	The most basic permission node required to use the command	permission: inferno.flagrate	This permissions node can be used to determine if a user should be able to see this command Some plugins will use this node to construct a personalized /help
permission-message	no	A no-permission message	permission-message: You do not have /<permission>	Displayed to a player that attempts to use a command but does not have the associated permission <permission> is a macro that is replaced with the permission node that is required to use the command. You may use empty quotes to indicate nothing should be displayed.
usage	no	A short description of how to use this command.	usage: Syntax error! Perhaps you meant /<command> PlayerName?	Displayed to whoever issued the command when the plugin's command handler (onCommand typically) does not return true. <command> is a macro that is replaced with the command issued wherever it occurs. To use the string "Usage:" (i.e. usage: Usage: /god [player], surround the text after the usage: label with double-quotes: usage: "Usage: /god [player]"

A permission block starts with the permission's name and is followed by nodes of attributes

Permission Attribute	Required	Description	Example	Notes
description	no	A short description of what this permission allows	description: Allows you to set yourself on fire	Allows programmatic access, and helps server administrators
default	no	Sets the default value of the permission	default: true	If node does not exist the permission defaults to op allowed defaults are: true, false, op, not op op default will be true if player is op no op default is the opposite behavior (of op)
children	no	allows you to set children for the permission. Child nodes are permission names	children: inferno.flagrate: true inferno.burningdeaths: true	Each child node must be either set to true or false a child node of true inherits the parent permission a child node of false inherits the inverse parent permission Can also contain other permission nodes {1}

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://forums.bukkit.org/threads/MyPlugin.31337/
 
 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