Commands, part 1: simple commands

Commands are how players talk to your plugin. On this page you will build /hello, a /fly toggle and a /paylevels command that reads a player name and a number, with friendly error messages and tab completion, all with Paper's simple BasicCommand.

What is a command?

You already know commands from vanilla Minecraft: /give, /tp, /gamemode. A command is a word that starts with a slash, plus some optional words after it. When someone runs it, the server finds the code that belongs to that word and runs it.

Plugins can add their own commands. Once your plugin registers /hello, typing /hello in chat runs a method you wrote, exactly like events run your event handlers. The difference is who decides when it happens: an event fires when something happens in the game, a command runs when someone asks for it.

Players are not the only ones who can run commands. Whoever runs a command is called the sender, and there are a few kinds:

All of them are a CommandSender: something that can run commands and receive messages. That matters, because your command must work (or fail politely) no matter who runs it. The console cannot fly, and a command block has no levels to pay with.

Paper gives you three ways to make commands. This page teaches the simplest one; the next two pages cover the others:

• BasicCommand (this page): you get the typed words as a list of text and decide what to do. Easy to learn.
• Brigadier (part 2): you describe the command's shape, and Minecraft checks the arguments for you, colors them while you type and suggests values.
• The classic plugin.yml way (part 3): what most older tutorials use. It still works, but Paper recommends the first two for new code.

Your first command: /hello

A command needs exactly three pieces, the same pattern as a listener:

1. Write a class that implements BasicCommand

   BasicCommand is an interface from Paper. By writing implements BasicCommand, your class promises to have an execute method, and Paper knows how to run it.

2. Fill in the execute method

   Paper calls execute every time someone runs the command. Whatever you put inside it is what the command does.

3. Register the command in onEnable

   Tell Paper "the word hello belongs to this class". Until you register it, typing /hello gives an "Unknown command" error.

This is the whole command class. Read the notes, then hover any word in the code to see what it is.

1package com.example.commandsbasichello;2 13import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;6import org.bukkit.command.CommandSender;7 28public final class HelloCommand implements BasicCommand {9 310    @Override411    public void execute(CommandSourceStack source, String[] args) {512        CommandSender sender = source.getSender();613        sender.sendRichMessage("<green>Hello, <name>!",714            Placeholder.unparsed("name", sender.getName()));15    }16}

And this is the main class, which registers the command when the plugin starts:

1package com.example.commandsbasichello;2 3import java.util.List;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class HelloPlugin extends JavaPlugin {7 8    @Override19    public void onEnable() {210        registerCommand("hello", "Says hello to you", List.of("hi"), new HelloCommand());11    }12}

Notice what is missing: plugin.yml has no commands: section. Old tutorials always add one, but commands registered in code do not need it. This is the whole file:

11name: HelloCommands2version: '1.0.0'3main: com.example.commandsbasichello.HelloPlugin4api-version: '26.3'5description: Adds a /hello command that greets whoever runs it.

Build the plugin and start your test server with Run Paper Server (see Build, install and test). Join with localhost and type /hello:

Now type hello in the server console window. The console is a sender too, and its name is CONSOLE:

$ hello[14:05:03 INFO]: Hello, CONSOLE!

Who ran the command? The source

The first parameter of execute is a CommandSourceStack. The name is long, but the idea is simple: it is a little bundle of facts about where the command came from. You will use three of its methods:

Why are there two, sender and executor? Because of vanilla's /execute command. An admin in the console can type execute as Alex run fly. The console started it (the sender), but the command should act on Alex (the executor). This small command prints both, so you can see the difference:

1package com.example.commandsbasic;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;6import org.bukkit.command.BlockCommandSender;7import org.bukkit.command.CommandSender;8import org.bukkit.command.ConsoleCommandSender;9import org.bukkit.entity.Entity;10import org.bukkit.entity.Player;11 12public final class WhoAmICommand implements BasicCommand {13 14    @Override15    public void execute(CommandSourceStack source, String[] args) {16        CommandSender sender = source.getSender();117        Entity executor = source.getExecutor();18        sender.sendRichMessage("<gray>Sender: <white><name></white> (<kind>)",19            Placeholder.unparsed("name", sender.getName()),220            Placeholder.unparsed("kind", describe(sender)));321        if (executor == null) {22            sender.sendRichMessage("<gray>Executor: <white>none</white> (no entity is running this command)");23        } else {24            sender.sendRichMessage("<gray>Executor: <white><name></white>",25                Placeholder.unparsed("name", executor.getName()));26        }27    }28 429    private static String describe(CommandSender sender) {530        if (sender instanceof Player) {31            return "a player";32        }33        if (sender instanceof ConsoleCommandSender) {34            return "the server console";35        }36        if (sender instanceof BlockCommandSender) {37            return "a command block";38        }39        return "something else";40    }41}

Here is what /whoami shows when Steve types it, and then when an admin types execute as Steve run whoami in the console (the console sees the reply in its window):

$ execute as Steve run whoami[14:06:41 INFO]: Sender: CONSOLE (the server console)[14:06:41 INFO]: Executor: Steve

A simple rule covers almost every command: reply to the sender, act on the executor. In everyday use both are the same player, so you rarely notice the difference, but following the rule makes your commands work with /execute and command blocks too.

Only players can fly: checking with instanceof

Many commands only make sense for a player. The console cannot fly or hold items. So before doing anything, check that the executor really is a player:

1package com.example.commandsbasic;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import org.bukkit.entity.Player;6 7public final class FlyCommand implements BasicCommand {8 9    @Override10    public void execute(CommandSourceStack source, String[] args) {111        if (!(source.getExecutor() instanceof Player player)) {312            source.getSender().sendRichMessage("<red>Only players can fly.");13            return;14        }415        boolean flightOn = !player.getAllowFlight();516        player.setAllowFlight(flightOn);17        if (flightOn) {18            player.sendRichMessage("<green>Flight on. Double-tap jump to take off.");19        } else {20            player.sendRichMessage("<yellow>Flight off.");21        }22    }23 24    @Override625    public String permission() {26        return "commandsbasic.fly";27    }28}

Why does the check use the variable player afterwards, not source.getExecutor()? Because getExecutor() returns an Entity, and an Entity has no setAllowFlight method. Only Player has it. The pattern match gives you the same object, already treated as a Player.

The permission is declared in plugin.yml, so Paper knows that server operators have it by default:

1name: CommandsBasic2version: '1.0.0'3main: com.example.commandsbasic.CommandsBasicPlugin4api-version: '26.3'5description: Simple BasicCommand examples, /hello, /fly, /paylevels and /whoami.6permissions:17  commandsbasic.fly:8    description: Lets a player turn flying on and off with /fly.29    default: op

When a player with the permission runs /fly twice:

A player without the permission does not even see /fly in tab completion. If they type it anyway, Minecraft treats it like a command that does not exist:

And when the console types fly, the guard clause answers:

$ fly[14:07:15 INFO]: Only players can fly.

Arguments: the words after the command

The words a player types after the command name are its arguments. Paper hands them to execute as String[] args: an array of text. Paper removes the slash, takes the first word as the command's name (the label), and splits the rest at every space:

This small Java program does the same splitting, so you can watch it happen. Press Run, then try your own commands with Edit:

1void main() {2    show("/hello");3    show("/hello Alex");4    show("/paylevels Alex 5");5}6 7void show(String typed) {18    String withoutSlash = typed.substring(1);29    String[] words = withoutSlash.split(" ");10    String label = words[0];311    String[] args = Arrays.copyOfRange(words, 1, words.length);12 13    IO.println("You typed: " + typed);14    IO.println("  label = " + label);415    IO.println("  args.length = " + args.length);516    for (int i = 0; i < args.length; i++) {17        IO.println("  args[" + i + "] = " + args[i]);18    }19    IO.println("");20}

Three facts about args that every plugin developer learns, often the hard way:

• Counting starts at 0. The first argument is args[0]. Paper also ignores extra spaces, so /hello   Alex still gives args[0] = Alex.
• Everything is text. Even when a player types 5, you get the String "5", not the number 5. You have to turn it into a number yourself (see below).
• The array can be shorter than you expect. Players forget arguments all the time. Reading args[0] when args.length is 0 crashes your command.

1Player target = Bukkit.getPlayerExact(args[0]);

If a player types just /hello, the array is empty, and asking for args[0] throws an ArrayIndexOutOfBoundsException. The player sees a generic error and the console fills with a stack trace. Always check args.length first.

Reading a player name

Here is the upgraded /hello from the demo plugin. With no arguments it greets you; with a name, it waves at that player:

14@Override15public void execute(CommandSourceStack source, String[] args) {16    CommandSender sender = source.getSender();117    if (args.length == 0) {18        sender.sendRichMessage("<green>Hello, <name>!",19            Placeholder.unparsed("name", sender.getName()));220        return;21    }322    Player target = Bukkit.getPlayerExact(args[0]);423    if (target == null) {24        sender.sendRichMessage("<red>No online player is called <name>.",25            Placeholder.unparsed("name", args[0]));26        return;27    }528    target.sendRichMessage("<yellow><name> waves at you!",29        Placeholder.unparsed("name", sender.getName()));30    sender.sendRichMessage("<gray>You waved at <name>.",31        Placeholder.unparsed("name", target.getName()));32}

And Alex, on the other side, sees:

Reading numbers, with friendly errors

To turn the text "5" into the number 5, Java has Integer.parseInt. If the text is not a whole number, such as "abc" or "2.5", it does not return anything. Instead it throws a NumberFormatException: an exception is Java's way of saying "I cannot do this". You catch it with try and catch and turn it into a helpful message. Run this to see what happens with different inputs:

1void main() {12    String[] typedAmounts = {"5", "abc", "-3", "2.5", "99999999999"};3    for (String typed : typedAmounts) {4        IO.println("/paylevels Alex " + typed + "  ->  " + check(typed));5    }6}7 8String check(String typed) {9    int amount;210    try {311        amount = Integer.parseInt(typed);412    } catch (NumberFormatException exception) {13        return typed + " is not a whole number.";14    }515    if (amount < 1) {16        return "The amount must be at least 1.";17    }18    return "OK, paying " + amount + " levels.";19}

See Null, exceptions and stack traces if you want to know more about exceptions. Now put it all together in /paylevels <player> <levels>, which gives some of your experience levels to another player. It is a good model for any command with arguments, because it checks every way the input can be wrong, one step at a time:

16@Override17public void execute(CommandSourceStack source, String[] args) {18    CommandSender sender = source.getSender();119    if (!(source.getExecutor() instanceof Player payer)) {20        sender.sendRichMessage("<red>Only players have levels to pay with.");21        return;22    }223    if (args.length != 2) {324        sender.sendMessage(Component.text("Usage: /paylevels <player> <levels>", NamedTextColor.RED));25        return;26    }27 28    Player target = Bukkit.getPlayerExact(args[0]);29    if (target == null) {30        sender.sendRichMessage("<red>No online player is called <name>.",31            Placeholder.unparsed("name", args[0]));32        return;33    }434    if (target.equals(payer)) {35        sender.sendRichMessage("<red>You cannot pay yourself.");36        return;37    }38 539    int levels;40    try {641        levels = Integer.parseInt(args[1]);42    } catch (NumberFormatException exception) {43        sender.sendRichMessage("<red><amount> is not a whole number.",44            Placeholder.unparsed("amount", args[1]));45        return;46    }47    if (levels < 1) {48        sender.sendRichMessage("<red>You have to pay at least 1 level.");49        return;50    }751    if (payer.getLevel() < levels) {52        sender.sendRichMessage("<red>You only have <have> levels.",53            Placeholder.unparsed("have", String.valueOf(payer.getLevel())));54        return;55    }56 857    payer.setLevel(payer.getLevel() - levels);58    target.setLevel(target.getLevel() + levels);59    payer.sendRichMessage("<green>You paid <white><levels></white> levels to <white><name></white>.",60        Placeholder.unparsed("levels", String.valueOf(levels)),61        Placeholder.unparsed("name", target.getName()));962    target.sendRichMessage("<green><name> paid you <white><levels></white> levels!",63        Placeholder.unparsed("name", payer.getName()),64        Placeholder.unparsed("levels", String.valueOf(levels)));65}

Notice the shape: a ladder of checks, each with its own message and a return, and the real work at the very bottom. When you write your own commands, copy this shape. Here is what players see for a few attempts:

Tab completion with suggest()

When a player presses Tab or simply types, Minecraft shows a little list of suggestions above the chat box. A BasicCommand fills that list with its suggest method. It gets the same source and args as execute, but it runs while the player is still typing, and it returns the words to suggest.

The trick is knowing which argument the player is typing right now. While typing, the last item in args is the word in progress:

67@Override168public Collection<String> suggest(CommandSourceStack source, String[] args) {269    if (args.length <= 1) {370        String typed = args.length == 0 ? "" : args[0];471        return PlayerNames.startingWith(typed);72    }573    if (args.length == 2) {74        return List.of("1", "5", "10");75    }676    return List.of();77}

Paper shows the suggestions you return, so filter them to match what the player has typed. That is the job of the helper class:

1package com.example.commandsbasic;2 3import java.util.ArrayList;4import java.util.List;5import java.util.Locale;6import org.bukkit.Bukkit;7import org.bukkit.entity.Player;8 19final class PlayerNames {10 211    private PlayerNames() {12    }13 14    static List<String> startingWith(String typed) {315        String typedLower = typed.toLowerCase(Locale.ROOT);16        List<String> names = new ArrayList<>();417        for (Player player : Bukkit.getOnlinePlayers()) {18            if (player.getName().toLowerCase(Locale.ROOT).startsWith(typedLower)) {19                names.add(player.getName());20            }21        }22        return names;23    }24}

Registering several commands

registerCommand is a shortcut. Inside, it uses Paper's lifecycle event for commands, LifecycleEvents.COMMANDS. Most real plugins use that event directly, because it can register many commands in one place, and because it is the same way you register the Brigadier commands in part 2. This is the demo plugin's main class:

1package com.example.commandsbasic;2 3import io.papermc.paper.command.brigadier.Commands;4import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;5import java.util.List;6import org.bukkit.plugin.java.JavaPlugin;7 8public final class CommandsBasicPlugin extends JavaPlugin {9 10    @Override11    public void onEnable() {112        getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {413            Commands commands = event.registrar();514            commands.register("hello", "Say hello, or wave at another player", new HelloCommand());15            commands.register("fly", "Turn flying on or off", new FlyCommand());16            commands.register("paylevels", "Give some of your experience levels to another player",617                List.of("paylvl"), new PayLevelsCommand());18            commands.register("whoami", "Show who is running this command", new WhoAmICommand());19        });20    }21}

You can download the demo plugin as a Gradle project, or open it in the Compile Lab to change it and compile it in your browser.

Mistakes to avoid

• Forgetting to register the command. The class compiles, but the game says "Unknown or incomplete command". Check onEnable first.
• Reading args[0] without checking args.length. The command crashes the moment someone types it with no arguments.
• Casting the sender with (Player) sender without a check. It crashes when the console runs the command. Use instanceof Player player.
• Calling Integer.parseInt without try/catch. The first player who types a word instead of a number causes an error.
• Silent failures. Every return before the real work should send a message that says what was wrong and how to fix it.
• Adding a commands: section to plugin.yml as well. Commands registered in code do not need it. Mixing both ways for the same command name confuses everyone, including you.

1package com.example.commandsbasicexercise;2 3import io.papermc.paper.command.brigadier.BasicCommand;4import io.papermc.paper.command.brigadier.CommandSourceStack;5import java.util.Collection;6import java.util.List;7import java.util.concurrent.ThreadLocalRandom;8import net.kyori.adventure.text.minimessage.tag.resolver.Placeholder;9import org.bukkit.command.CommandSender;10 11public final class RollCommand implements BasicCommand {12 13    @Override14    public void execute(CommandSourceStack source, String[] args) {15        CommandSender sender = source.getSender();116        int sides = 6;217        if (args.length >= 1) {18            try {19                sides = Integer.parseInt(args[0]);20            } catch (NumberFormatException exception) {21                sender.sendRichMessage("<red><typed> is not a whole number.",22                    Placeholder.unparsed("typed", args[0]));23                return;24            }25        }326        if (sides < 2 || sides > 100) {27            sender.sendRichMessage("<red>A die needs between 2 and 100 sides.");28            return;29        }430        int result = ThreadLocalRandom.current().nextInt(1, sides + 1);31        sender.sendRichMessage("<gray>You rolled a <gold><result></gold> on a <sides>-sided die.",32            Placeholder.unparsed("result", String.valueOf(result)),33            Placeholder.unparsed("sides", String.valueOf(sides)));34    }35 36    @Override37    public Collection<String> suggest(CommandSourceStack source, String[] args) {38        if (args.length <= 1) {39            return List.of("6", "20", "100");40        }41        return List.of();42    }43}

1package com.example.commandsbasicexercise;2 3import java.util.List;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class RollPlugin extends JavaPlugin {7 8    @Override9    public void onEnable() {10        registerCommand("roll", "Roll a die with any number of sides", List.of("dice"), new RollCommand());11    }12}

1commands.register("hello", "Say hello, or wave at another player", List.of("hey"), new HelloCommand());

When to move to Brigadier

BasicCommand is perfect for small commands. As commands grow, its limits start to show:

• You parse everything yourself. Every number, every player name, every check is your code. Brigadier has ready-made argument types for players, numbers, items, worlds, game modes and more.
• The game does not know your arguments. To Minecraft, everything after /paylevels is just text. With Brigadier, the game colors wrong arguments red while the player types, and even understands selectors like @a and @p.
• Subcommands get messy. /team create, /team join, /team leave turn into a big if/else on args[0]. Brigadier makes each subcommand its own branch of a tree.

A good rule: one or two simple arguments, use BasicCommand. Typed arguments, selectors or subcommands, use Brigadier. Both are modern Paper, and one plugin can mix them freely.

Recap

• A command runs your code when a player, the console or a command block asks for it. Whoever runs it is the sender.
• A BasicCommand has an execute(source, args) method, and optionally suggest and permission.
• Register commands in onEnable, with registerCommand(...) or with the LifecycleEvents.COMMANDS event. No plugin.yml entry is needed.
• source.getSender() is who to reply to; source.getExecutor() is who to act on. Check instanceof Player player before doing player things.
• args is an array of text that starts at index 0. Check args.length before reading, and parse numbers with Integer.parseInt inside try/catch.
• Check every way the input can be wrong, send a helpful message for each, and do the real work last.

Quick quiz

Next steps

• Commands, part 2: Brigadier command trees: typed arguments, selectors and subcommands.
• Commands, part 3: the classic plugin.yml way: read older tutorials with confidence.
• Permissions: decide who may use which command.
• Cooldowns, toggles and player state: stop players from spamming your commands.