Plugin.yml

Mar 28, 2018
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
    • 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)

    If you don't want to deal with the hassle of creating a plugin.yml for every project then there is a handy little tool just for you! It's called Plugin Annotations. It is a simple annotation processor that automatically generates a correct plugin.yml for you. No hassle!

    To use it simply add it as a dependency to your project.
    Code (HTML5):
    <dependency>
      <groupId>org.spigotmc</groupId>
      <artifactId>plugin-annotations</artifactId>
      <version>1.1.0-SNAPSHOT</version>
      <scope>provided</scope>
    </dependency>
    It uses the same repository that the spigot-api repo is housed at.
    Code (HTML5):
    <repositories>
      <repository>
        <id>spigot-repo</id>
        <url>https://hub.spigotmc.org/nexus/content/repositories/snapshot/</url>
      </repository>
    </repositories>
     
    More information about this tool can be found on its wiki.

    Appendix(top)

    YAML Introduction
    YAML List Wiki
  • Loading...
  • Loading...