Plugin.yml

Jul 23, 2019
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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    description: This plugin does so much stuff it can't be contained!
    api-version
    • The version of the API you want to use.
    • 1.13 and 1.14 are available versions
    • This will signal to the server that your plugin has been coded with a specific server version in mind, and that it should not apply any sort of backwards compatibility measures. As a result you will also need to make sure that you have programmed your code to account for reading of older configurations, data, etc... .Each server version can decide how compatibility is achieved, unknown or future versions will prevent the plugin from enabling. As of the 1.14 release, the api-version 1.13 is still allowed - however future versions may drop backwards support based on this version.
    Example:
    Code (YAML):
    api-version: 1.13
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    depend: [WorldEdit, Towny]

    prefix:
    • The name to use when logging to console instead of the plugin's name.
    Example:
    Code (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    aliases: [foobar, fubar]
    OR
    Code (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    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 (YAML):
    permissions:
    children
    :
      inferno.flagrate
    : true
      inferno.burn
    : false


    Example(top)

    Code (YAML):
    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 (XML):
    <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 (XML):
    <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...