How to Create a plugin.yml File for a Minecraft Paper Plugin

How to Create a "plugin.yml" File for a Minecraft Paper Plugin

If you're starting Minecraft plugin development, one of the first files you'll need to understand is "plugin.yml". It tells your Minecraft server important information about your plugin, including its name, version, main Java class, and commands.

A plugin can contain perfectly valid Java code and still fail to load if its configuration is incorrect. That's why it's worth learning how this file works before moving on to more complicated features.

What is "plugin.yml"?

The "plugin.yml" file is a YAML configuration file placed in the root of your plugin's JAR file. Paper and Bukkit use it to identify and load traditional Java plugins.

For example, a basic plugin project might look like this:

MyPlugin/
├── src/
│ └── main/
│ ├── java/
│ │ └── com/example/myplugin/
│ │ └── MyPlugin.java
│ └── resources/
│ └── plugin.yml
└── build.gradle

When you build the project, your build tool should package "plugin.yml" into the root of the resulting JAR.

Step 1: Write a basic plugin.yml

Here is a simple example for a plugin called WelcomePlugin:

name: WelcomePlugin
version: '1.0.0'
main: com.example.myplugin.MyPlugin
api-version: '1.21'

description: A simple welcome message plugin
author: ExampleDev

commands:
welcome:
description: Displays a welcome message
usage: /welcome
permission: welcome.use

permissions:
welcome.use:
description: Allows the player to use /welcome
default: true

This is an example configuration, not a complete working plugin by itself. Your Java class and package must match the "main" value, and the command must be implemented in your code.

Step 2: Understand the important fields

"name" — The plugin's display name.

"version" — The version of your plugin. Quoting the version is a useful habit when writing YAML.

"main" — The fully qualified name of your plugin's main Java class. If your class is "MyPlugin.java" inside the package "com.example.myplugin", the value should be "com.example.myplugin.MyPlugin".

"api-version" — Specifies the Minecraft API version your plugin targets. Choose a version supported by the Paper/Bukkit API you are developing against.

"commands" — Declares commands your plugin provides. Declaring a command doesn't implement its behavior; you must also register its handler in your Java code.

"permissions" — Defines permissions that can be assigned to players or groups. Make sure the permission names match the checks in your code.

Step 3: Create the main Java class

For a basic Bukkit-compatible plugin, the Java class could look like this:

package com.example.myplugin;

import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyPlugin extends JavaPlugin {

@Override
public void onEnable() {
    getLogger().info("WelcomePlugin has been enabled!");
}

@Override
public boolean onCommand(
        CommandSender sender,
        Command command,
        String label,
        String[] args
) {
    if (command.getName().equalsIgnoreCase("welcome")) {
        sender.sendMessage("Welcome to the server!");
        return true;
    }

    return false;
}

}

This example demonstrates the basic command-handling approach. For a production plugin, you may prefer separate command classes and explicit permission checks. The permission declaration in "plugin.yml" alone does not enforce every permission check in your custom code.

Step 4: Validate your configuration

Before uploading your plugin to a server, check the following:

• The "main" class points to the correct package and class.
• The YAML indentation uses spaces consistently.
• The command names in "plugin.yml" match those used by your code.
• Your "api-version" is compatible with the API you target.
• The compiled JAR contains "plugin.yml" at its root.
• You test the plugin on a compatible Paper server and inspect the console for errors.

YAML indentation matters. For example, "description" under "welcome" must be indented beneath the command. Incorrect indentation or invalid YAML syntax can prevent the configuration from being parsed correctly.

Step 5: Generate a configuration more quickly

If you're unsure how to structure your configuration, you can write it manually or use a generator as a starting point.

QuarryAI provides a Paper plugin YAML generator that can help developers create a "plugin.yml" draft without writing every field from scratch:

Try it here: https://quarryai.dpdns.org/tools/paper-plugin-yml-generator

You should still review the generated YAML, verify the main class and API version, and test the finished plugin. A generator can save time on boilerplate, but it cannot replace compatibility checks or testing.

Final thoughts

Learning "plugin.yml" is a small but important step toward building Minecraft server plugins. Once you understand the metadata, commands, permissions, and main class fields, you can move on to more advanced features such as event listeners, custom items, configuration files, and database integration.

The best approach is to understand the configuration, validate it, and test your plugin before deploying it to a live server.