Plugin.yml - Historical

Applied By Senmori: Mar 7, 2018 at 1:26 AM

Plugin.yml

Plugin.yml



The plugin.yml is a file made to contain information about your plugin. Without this file, your plugin will NOT work. It consists of a set of attributes, each defined on a new line with no indentation.
All attributes are case sensitive. Attributes in bold are required. Attributes in italics are not.


Required Attributes(top)

There are three attributes that are required for a plugin.yml file to be considered valid.

main
  • This attribute points to the class of your plugin that extends JavaPlugin.
  • This must contain the full namespace including the class file itself.
Example:
Code (yml):
main: org.spigotmc.testplugin.Test
name
  • This attribute is the name of your plugin.
  • 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.
  • It is good practice to name your jar the same as this (eg: MyPlugin.jar)
Example:
Code (yml):
name: MyPlugin
version - This is the version of this plugin
  • The version of your plugin.
  • The most common format for a version string is MajorRelease.MinorRelease.Build (eg: 1.4.1)
Example:
Code (yml):
version: 1.4.1

Optional Attributes(top)


description
  • A human friendly description of the functionality your plugin provides.
  • The description can have multiple lines.
Example:
Code (yml):
description: This plugin does so much stuff it can't be contained!
load:
  • Explicitly state when a plugin should be loaded. If not supplied will default to POSTWORLD.
  • Has two possible values: STARTUP and POSTWORLD.
Example:
Code (yml):
load: POSTWORLD


author:

  • Uniquely identifies who developed this plugin.
  • Used in some server error messages to provide helpful feedback on who to contact when an error occurs.
  • A SpigotMC.org forum handle or email address is recommended.
Example:
Code (yml):
author: md_5

authors:
  • Allows you to list multiple authors, if it is a collaborative project. See author.
  • Must be in valid YAML list format.
Example:
Code (yml):
authors: [md_5, thinkofdeath]

website:
  • The plugin's or author's website.
  • If you have no dedicated website, a link to the page where this plugin is listed is recommended.
Example:
Code (yml):
website: www.spigotmc.org

depend:
  • A list of plugins that your plugin requires to load.
  • Must be in valid YAML list format.
  • 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.
Example:
Code (yml):
depend: [WorldEdit, Towny]

prefix:
  • The name to use when logging to console instead of the plugin's name.
Example:
Code (yml):
prefix: Testing

softdepend:
  • A list of plugins that are required for your plugin to have full functionality.
  • The value must be in YAML list format.
  • Use the name attribute of the required plugin in order to specify the dependency.
  • Your plugin will load after any plugins listed here.
  • Circular soft dependencies are loaded arbitrarily.
Example:
Code (yml):
softdepend: [Essentials, AnotherPlugin]

loadbefore:
  • A list of plugins that should be loaded after your plugin.
  • The value must in valid YAML list format.
  • Treated as if the listed plugin soft depends on this plugin.
  • Use the name attribute 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.
Example:
Code (yml):
loadbefore: [OnePlugin, AnotherPlugin]

commands:
  • The name of a command the plugin wishes to register, as well as an optional list of command attributes.
  • The command name should not contain the leading '/' required to issue a command.
Example:
Code (yml):
commands:
 flagrate:
  [optional command attributes]

permissions:
  • Permission that the plugin wishes to register. Each node represents a permission to register.
  • Each permission can have multiple 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>
Example:
Code (yml):
permissions:
 inferno.*:
  [optional permission attributes]
 inferno.flagate:
  [optional permission attributes]


Commands(top)

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

description:
  • A short description of what the command does.
  • Can be used in conjunction with /help
Example:
Code (yml):
description: A simple description.

aliases:
  • Alternate command names a user may use instead.
  • You can specify any of none, one, or many aliases.
  • If you specify more than one alias, they must be in valid YAML list format.
Example:
Code (yml):
aliases: [foobar, fubar]
OR
Code (yml):
aliases: foobar


permission:
  • The most basic permission node required to use the command.
  • This permission node can be used to determine if a user should be able to see this command.
Example:
Code (yml):
permission: test.foo


permission-message:
  • A no-permission message which is displayed to a user if they do not have the required permission to use this command.
  • You may use empty quotes to indicate nothing should be displayed.
Example:
Code (yml):
permission-message: You not have have permission to use this command.

usage:
  • A short description of how to use this command.
  • 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: /test command), surround the text after the usage label with double-quotes. (eg: usage: "Usage: /test command")
Example:
Code (yml):
usage: "Usage: /<command> [test|stop]"



Permissions(top)

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

description:
  • A short description of what this permission allows.
  • Allows programmatic access, and helps server administrators.
Example:
Code (yml):
description: Allows you to use the command /test

default:
  • Sets the default value of the permission.
  • If nodes does not exist, permission defaults to op.
  • Allowed defaults are: true, false, op, not op
Example:
Code (yml):
default: true

  • true default will always grant the player the permission.
  • false default will not grant the player the permission.
  • op default will be true if the player is op.
  • not op is the opposite behavior of op.

children:

  • Allows you to set children for the permission. Child nodes are permission names.
  • Each child node must be set to either 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.
Example:
These values are not the ones used in this article. They are merely for
illustrative purposes.
Code (yml):
permissions:
children:
  inferno.flagrate: true
  inferno.burn: false


Example(top)

Code (yml):
main: org.spigotmc.annotationtest.Test
name: TestPlugin
version: '1.0'
description: A test plugin
load: POSTWORLD
author: md_5
website: spigotmc.org
prefix: Testing
depend:
- WorldEdit
- Towny
softdepend:
- FAWE
loadbefore:
- Essentials
commands:
  foo:
   description: Foo command
   aliases:
   - foobar
   - fubar
   permission: test.foo
   permission-message: You do not have permission!
   usage: /<command> [test|stop]
permissions:
  test.foo:
   description: Allows foo command
   default: op
  test.*:
   description: Wildcard permission
   default: op
   children:
     test.foo: true

Plugin Annotations(top)

TBD

Appendix(top)

YAML Introduction
YAML List Wiki