plugin.yml explained: every field a Minecraft plugin needs

Every Bukkit-based plugin has a file called plugin.yml inside its jar. The server reads it first to learn the plugin name, which class to start and which commands it adds. If the file is wrong, the plugin does not load, so it is worth knowing.

The required fields

• name: the plugin name. Letters, numbers and underscores are safest.
• version: any text, such as 1.0.0.
• main: the full class name of the main class, for example dev.example.homes.HomesPlugin. It must extend JavaPlugin.

api-version

From Minecraft 1.13 on, api-version tells the server which API level the plugin was written for, for example '1.21'. Without it the server assumes a legacy plugin and applies compatibility handling. Before 1.13 the field does not exist and should be left out.

A complete example

name: Homes
version: 1.0.0
main: dev.example.homes.HomesPlugin
api-version: '1.21'
description: Set and use homes
commands:
  sethome:
    description: Save a home
    usage: /sethome <name>
    permission: homes.use
  home:
    description: Teleport to a home
    usage: /home <name>
    permission: homes.use
permissions:
  homes.use:
    description: Lets a player use homes
    default: true
  homes.admin:
    description: Manage homes of other players
    default: op

Commands

Every command a plugin adds must be listed under commands. Each can have a description, a usage text, aliases and a permission. The code then connects a command executor to the name with getCommand("sethome"). A command that is in the code but not in plugin.yml simply does not exist.

Permissions and defaults

Declaring permissions here gives them a default. true means everyone has it, false means nobody until it is granted, op means operators only, not op the opposite. A permissions plugin such as LuckPerms can then grant or remove them per group.

Other useful fields

• depend and softdepend list other plugins that must or may be loaded first.
• load can be STARTUP or POSTWORLD to decide when the plugin starts.
• authors and website are shown in plugin lists.

Mistakes that stop a plugin loading

• The main value does not match the real package and class name.
• Tabs instead of spaces. YAML only accepts spaces.
• A colon or a leading special character in a value that is not quoted.
• The file sits in the wrong place. It must be at the top level of the jar.

A minimal plugin.yml to compare with

name: Hello
version: 1.0.0
main: dev.example.hello.HelloPlugin
api-version: '1.21'

These four lines are enough for a plugin that only reacts to events. The server finds the main class, enables it, and nothing else is needed. Add the commands and permissions sections only when the plugin has any.

How the generator handles plugin.yml for you

When you create a plugin, the tool writes plugin.yml, sets the name and version, and puts in the api-version that fits the Minecraft version you picked. For versions before 1.13 it leaves api-version out, because it does not exist there. If the code imports an optional integration such as Vault, it also adds a softdepend entry so the server loads that plugin first.

Frequently asked questions

Where is plugin.yml in the jar?

At the top level of the jar, not inside a folder. In a Maven project it lives in src/main/resources, and the build copies it to the right place.

What happens if two plugins have the same name?

The server loads one and complains about the other. Give every plugin a unique name.

Can I change the plugin version later?

Yes. The version is text and has no effect on loading, but a clear version helps you know which build runs on the server.