Project: /heal and /feed with cooldowns

In this project you build two commands, /heal and /feed, that work on yourself or on another player, are protected by permissions, make players wait between uses, and take every message from a config file.

What you will build

Almost every server has commands like these, and they are the perfect practice project: each one is small, but together they use the things that real command plugins need. By the end you will have written a command tree with an optional player argument, permission checks, a cooldown, and messages the server owner can edit.

Here is what the finished plugin does. Steve types /heal and is healed:

Steve, who is an admin, can also heal Alex by naming him. Steve sees one message and Alex sees another:

If Steve tries again too soon, the command refuses and says how long to wait:

These are the two commands and the rules behind them:

In the usage line, square brackets such as [player] mean "optional". A player with healfeed.bypass-cooldown never has to wait. By default only server operators have these permissions, and a permissions plugin such as LuckPerms can hand them to anyone else.

The plan

The plan matters more here than in the last project, because a command does several checks before it acts, and the order of the checks decides how the plugin feels to use. Here is the path a command takes:

And here is how each requirement maps to a piece of code, with the chapter that teaches it:

The build steps are:

1. Create the project and plugin.yml permissions

   Declare who may do what before writing any code.

2. Write /heal for yourself

   The smallest working command, and the one new idea: how a Brigadier command is registered.

3. Add the optional player target

   An argument node, a second permission and the first real branch.

4. Share one design between /heal and /feed

   An enum describes the difference, so we do not copy and paste a whole class.

5. Add the cooldown

   A map from UUID to the time when the player may use the command again.

6. Put the messages in config.yml

   A small helper that sends a configured message with placeholders.

7. Register both commands and test

   Wire everything together and run a checklist with two players.

If you have not read Commands, part 2: Brigadier command trees yet, do that first. This page uses its words (literal, argument, node) without explaining them again from zero. If you are new to configs, the Welcome kit project walks through config.yml more slowly.

Step 1: create the project and the permissions

Create a project the same way as in the previous project (copy the starter or run new-plugin.cmd -Name HealFeed from the paper-templates folder) and use the package com.example.projecthealfeed. Then open plugin.yml. Besides the usual name and main class, we declare every permission the plugin will check:

1name: HealFeed2version: '1.0.0'3main: com.example.projecthealfeed.HealFeedPlugin4api-version: '26.3'5description: The /heal and /feed commands with permissions, targets, cooldowns and configurable messages.16permissions:27  healfeed.heal:8    description: Use /heal on yourself.49    default: op310  healfeed.heal.others:11    description: Use /heal on another player.12    default: op13  healfeed.feed:14    description: Use /feed on yourself.15    default: op16  healfeed.feed.others:17    description: Use /feed on another player.18    default: op519  healfeed.bypass-cooldown:20    description: Use the commands without waiting for the cooldown.21    default: op622  healfeed.*:23    description: Every HealFeed permission.24    default: op25    children:26      healfeed.heal: true27      healfeed.heal.others: true28      healfeed.feed: true29      healfeed.feed.others: true30      healfeed.bypass-cooldown: true

Step 2: /heal for yourself

Start with the smallest version that works: /heal heals the player who typed it. Here is the command class. It does not do anything by itself; it builds a description of the command, a command tree, that Paper uses later.

1package com.example.projecthealfeedstep1;2 3import com.mojang.brigadier.Command;4import com.mojang.brigadier.context.CommandContext;5import com.mojang.brigadier.tree.LiteralCommandNode;6import io.papermc.paper.command.brigadier.CommandSourceStack;7import io.papermc.paper.command.brigadier.Commands;8import org.bukkit.attribute.Attribute;9import org.bukkit.attribute.AttributeInstance;10import org.bukkit.command.CommandSender;11import org.bukkit.entity.Player;12 13final class HealCommand {14 115    private HealCommand() {16    }17 18    static LiteralCommandNode<CommandSourceStack> create() {219        return Commands.literal("heal")320            .requires(source -> source.getSender().hasPermission("healfeed.heal"))421            .executes(HealCommand::healSender)522            .build();23    }24 25    private static int healSender(CommandContext<CommandSourceStack> context) {626        CommandSender sender = context.getSource().getSender();727        if (!(sender instanceof Player player)) {28            sender.sendRichMessage("<red>Only players can heal themselves.");29            return 0;30        }31 832        AttributeInstance maxHealth = player.getAttribute(Attribute.MAX_HEALTH);933        player.setHealth(maxHealth == null ? 20.0 : maxHealth.getValue());1034        player.setFireTicks(0);35        player.sendRichMessage("<green>You feel much better.");1136        return Command.SINGLE_SUCCESS;37    }38}

Now register it. Brigadier commands are registered while the server is still starting, through a lifecycle event called COMMANDS. Paper fires it at the right moment and gives you a registrar to hand your command tree to:

1package com.example.projecthealfeedstep1;2 3import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;4import org.bukkit.plugin.java.JavaPlugin;5 6public final class HealFeedPlugin extends JavaPlugin {7 8    @Override9    public void onEnable() {110        getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event ->211            event.registrar().register(HealCommand.create(), "Restore your health"));12    }13}

Build, start the server, and make yourself an operator by typing op YourName in the server console window. Without that, you do not have the permission, and the command does not even exist for you. Hurt yourself with /damage @s 8 (a vanilla command), then type /heal:

Step 3: add the optional player target

Now the interesting part: /heal Alex. In a Brigadier tree this is a second node hanging under heal: an argument node that reads a player. Because executes is also on the heal node itself, both /heal and /heal Alex are valid. That is how Brigadier says "optional".

From here on we work with the finished project. Its command class is called CareCommand (step 4 explains the name) and it replaces HealCommand, so you can delete the old file. The code below says type.commandName() where step 2 had the fixed word "heal"; for now, simply read it as "heal". First, the top of the class, where it keeps what it needs:

16final class CareCommand {17 118    private static final String BYPASS_PERMISSION = "healfeed.bypass-cooldown";19 220    private final CareType type;321    private final Messages messages;422    private final Duration cooldownLength;523    private final Cooldowns cooldowns = new Cooldowns();24 625    CareCommand(CareType type, Messages messages, Duration cooldownLength) {26        this.type = type;27        this.messages = messages;28        this.cooldownLength = cooldownLength;29    }

Now the create() method, which has grown. Read it line by line:

31LiteralCommandNode<CommandSourceStack> create() {132    String permission = "healfeed." + type.commandName();33    return Commands.literal(type.commandName())234        .requires(source -> source.getSender().hasPermission(permission))335        .executes(this::runOnSelf)436        .then(Commands.argument("target", ArgumentTypes.player())737            .requires(source -> source.getSender().hasPermission(permission + ".others"))838            .executes(this::runOnTarget))39        .build();40}

Reading the player out of the command takes two small steps: ask for the argument by name and turn the answer into real players. Why two steps? A selector like @r ("a random player") has to be worked out at the moment the command runs, not when it was parsed. The thing you get back is called a resolver, and resolve does the working out:

151private int runOnTarget(CommandContext<CommandSourceStack> context) throws CommandSyntaxException {52    CommandSender sender = context.getSource().getSender();253    PlayerSelectorArgumentResolver resolver = context.getArgument("target", PlayerSelectorArgumentResolver.class);354    Player target = resolver.resolve(context.getSource()).getFirst();55    return care(sender, target);56}

And runOnSelf, the version without a target, needs one more decision: the console has no health, so it must name somebody.

42private int runOnSelf(CommandContext<CommandSourceStack> context) {43    CommandSender sender = context.getSource().getSender();144    if (sender instanceof Player player) {245        return care(player, player);46    }347    messages.send(sender, "console-needs-target", Placeholder.unparsed("command", type.commandName()));48    return 0;49}

Step 4: share one design between /heal and /feed

You could now copy the whole HealCommand class, rename it to FeedCommand and change two lines. It works, and it is how most beginners start. The problem arrives later: when you fix a bug or add a cooldown, you have to fix it in both copies, and one of them will be forgotten.

Look at what is really different between the two commands: the name, the permission, the description, and what happens to the player. Everything else is identical. A Java enum is a good fit: a fixed list of named choices that can carry their own details. Here are our two choices:

1package com.example.projecthealfeed;2 3import java.util.Locale;4import org.bukkit.attribute.Attribute;5import org.bukkit.attribute.AttributeInstance;6import org.bukkit.entity.Player;7 18enum CareType {9 210    HEAL("Restore your health, or the health of another player"),11    FEED("Refill your hunger bar, or the hunger bar of another player");12 313    private final String description;14 15    CareType(String description) {16        this.description = description;17    }18 19    String description() {20        return description;21    }22 23    String commandName() {424        return name().toLowerCase(Locale.ROOT);25    }26 27    void apply(Player player) {528        switch (this) {29            case HEAL -> {30                AttributeInstance maxHealth = player.getAttribute(Attribute.MAX_HEALTH);31                player.setHealth(maxHealth == null ? 20.0 : maxHealth.getValue());32                player.setFireTicks(0);33            }34            case FEED -> {635                player.setFoodLevel(20);736                player.setSaturation(20.0f);37            }38        }39    }40}

Now there is one command class, CareCommand, and the plugin creates one object of it for each value of the enum. Back in step 3 you saw that the class reads type.commandName() instead of the fixed word "heal". That is the whole trick.

Step 5: add the cooldown

A cooldown is a wait between uses. The idea is simple: when a player uses the command, we write down when they may use it again. Next time, we compare that time with the clock. The notebook where we write the times is a Map, a collection that stores a value under a key. The key is the player's UUID, a unique id that never changes, even if the player changes their name:

1package com.example.projecthealfeed;2 3import java.time.Duration;4import java.util.HashMap;5import java.util.Map;6import java.util.UUID;7 8final class Cooldowns {9 110    private final Map<UUID, Long> readyAt = new HashMap<>();11 12    long remainingMillis(UUID id) {213        Long ready = readyAt.get(id);314        if (ready == null) {15            return 0L;16        }417        long remaining = ready - System.currentTimeMillis();18        if (remaining <= 0L) {519            readyAt.remove(id);20            return 0L;21        }22        return remaining;23    }24 625    void start(UUID id, Duration length) {26        readyAt.put(id, System.currentTimeMillis() + length.toMillis());27    }28}

One Cooldowns object belongs to one command (see the field in CareCommand), so waiting for /heal does not stop you from using /feed. Using it is the first thing the care method does:

58private int care(CommandSender sender, Player target) {159    if (sender instanceof Player player && !player.hasPermission(BYPASS_PERMISSION)) {260        long remaining = cooldowns.remainingMillis(player.getUniqueId());361        if (remaining > 0L) {62            messages.send(sender, "cooldown",63                Placeholder.unparsed("command", type.commandName()),64                Placeholder.unparsed("time", formatSeconds(remaining)));65            return 0;66        }467        cooldowns.start(player.getUniqueId(), cooldownLength);68    }69 570    type.apply(target);71 72    String name = type.commandName();673    if (sender.equals(target)) {74        messages.send(sender, name + ".self");75    } else {76        messages.send(sender, name + ".other", Placeholder.unparsed("target", target.getName()));777        messages.send(target, name + ".received", Placeholder.unparsed("sender", sender.getName()));78    }79    return Command.SINGLE_SUCCESS;80}

Step 6: put the messages in config.yml

All the texts are in the config, like in the Welcome kit project. Each command has its own group, with one text for the sender, one for the sender when a target was named, and one for the target. A few shared texts sit beside them:

11cooldowns:22  heal-seconds: 603  feed-seconds: 304 5messages:6  heal:7    self: "<green>You feel much better."38    other: "<green>You healed <yellow><target></yellow>."49    received: "<green><yellow><sender></yellow> healed you."10  feed:11    self: "<green>Your hunger is gone."12    other: "<green>You fed <yellow><target></yellow>."13    received: "<green><yellow><sender></yellow> fed you."514  cooldown: "<red>You can use <yellow>/<command></yellow> again in <yellow><time></yellow>."15  console-needs-target: "<red>The console must name a player, like <yellow>/<command> Steve</yellow>."

Sending a configured message is something every command will do, so it gets a tiny helper class. It looks a text up by its path, skips it when the owner left it empty (a simple way to turn a message off), and sends it with the placeholders:

1package com.example.projecthealfeed;2 3import net.kyori.adventure.text.minimessage.tag.resolver.TagResolver;4import org.bukkit.command.CommandSender;5import org.bukkit.configuration.file.FileConfiguration;6 7final class Messages {8 9    private final FileConfiguration config;10 11    Messages(FileConfiguration config) {12        this.config = config;13    }14 115    void send(CommandSender receiver, String path, TagResolver... placeholders) {216        String text = config.getString("messages." + path);317        if (text == null || text.isEmpty()) {18            return;19        }420        receiver.sendRichMessage(text, placeholders);21    }22}

Step 7: register both commands and test

The last piece is the main class. It loads the config, builds one CareCommand for each value of the enum, and registers the command trees:

1package com.example.projecthealfeed;2 3import io.papermc.paper.plugin.lifecycle.event.types.LifecycleEvents;4import java.time.Duration;5import org.bukkit.plugin.java.JavaPlugin;6 7public final class HealFeedPlugin extends JavaPlugin {8 9    @Override10    public void onEnable() {111        saveDefaultConfig();212        Messages messages = new Messages(getConfig());13 14        getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {315            for (CareType type : CareType.values()) {416                long seconds = getConfig().getLong("cooldowns." + type.commandName() + "-seconds", 0L);517                CareCommand command = new CareCommand(type, messages, Duration.ofSeconds(seconds));618                event.registrar().register(command.create(), type.description());19            }20        });21    }22}

You can download the finished project and compare it with yours.

Testing checklist

Test with two players if you can: your own account and a friend, or a second account on the same PC. The cooldown and the "others" messages are the parts a single player cannot see. Go through these in order:

• As an operator, run /damage @s 8, then /heal. You are healed, fire is gone, and the green message appears.
• Run /effect give @s hunger 20 10 and wait until the food bar is low, then /feed. The bar fills.
• Run /heal twice quickly. The second try shows the red cooldown message with the seconds left, and counts down as you retry.
• Run /feed right after /heal: it works, because each command has its own cooldown.
• Type /heal Alex (use your friend's name). You see "You healed Alex", and your friend sees "Steve healed you".
• Type a name that is not online. Brigadier shows its own red error and nothing is healed.
• In the server console, run heal: it prints the "must name a player" message. Run heal Alex: it works with no cooldown.
• Take away operator status with deop Steve: the commands disappear from tab completion, and typing them gives "Unknown or incomplete command". Give back only healfeed.heal with a permissions plugin: /heal works, but /heal Alex does not.
• Give yourself healfeed.bypass-cooldown: there is no waiting any more.

Mistakes to avoid

• Healing above the maximum. setHealth(30) on a 20-health player throws an exception. Always read the maximum health first, as CareType does.
• Forgetting saveDefaultConfig(). Without it there is no config.yml, every message is missing and the commands feel silent.
• Checking the permission in requires but typing it differently in plugin.yml. healfeed.heal and healfeed.Heal are two different permissions.
• Putting the cooldown on the target. Then anyone could block a friend's cooldown, or dodge their own by healing a second account. The cooldown belongs to the person who typed the command.
• Storing the Player object instead of the UUID. A Player object is only valid while the player is online. Maps keyed by Player leak memory and break after a relog. Use the UUID.
• Typing message texts into the code. Hard-coded messages cannot be translated or edited by the server owner. Every text a player can read belongs in the config.

Exercises

1package com.example.projecthealfeedexercise;2 3import java.util.Locale;4import org.bukkit.attribute.Attribute;5import org.bukkit.attribute.AttributeInstance;6import org.bukkit.entity.Player;7import org.bukkit.potion.PotionEffect;8 9enum CareType {10 11    HEAL("Restore your health, or the health of another player"),12    FEED("Refill your hunger bar, or the hunger bar of another player"),113    CLEANSE("Remove every potion effect from you, or from another player");14 15    private final String description;16 17    CareType(String description) {18        this.description = description;19    }20 21    String description() {22        return description;23    }24 25    String commandName() {26        return name().toLowerCase(Locale.ROOT);27    }28 29    void apply(Player player) {30        switch (this) {31            case HEAL -> {32                AttributeInstance maxHealth = player.getAttribute(Attribute.MAX_HEALTH);33                player.setHealth(maxHealth == null ? 20.0 : maxHealth.getValue());34                player.setFireTicks(0);35            }36            case FEED -> {37                player.setFoodLevel(20);38                player.setSaturation(20.0f);39            }240            case CLEANSE -> {341                for (PotionEffect effect : player.getActivePotionEffects()) {42                    player.removePotionEffect(effect.getType());43                }44            }45        }46    }47}

1cooldowns:2  heal-seconds: 603  feed-seconds: 304  cleanse-seconds: 455 6messages:7  heal:8    self: "<green>You feel much better."9    other: "<green>You healed <yellow><target></yellow>."10    received: "<green><yellow><sender></yellow> healed you."11  feed:12    self: "<green>Your hunger is gone."13    other: "<green>You fed <yellow><target></yellow>."14    received: "<green><yellow><sender></yellow> fed you."15  cleanse:16    self: "<green>Every potion effect is gone."17    other: "<green>You cleansed <yellow><target></yellow>."18    received: "<green><yellow><sender></yellow> cleansed you."19  cooldown: "<red>You can use <yellow>/<command></yellow> again in <yellow><time></yellow>."20  console-needs-target: "<red>The console must name a player, like <yellow>/<command> Steve</yellow>."

1name: HealFeedCleanse2version: '1.0.0'3main: com.example.projecthealfeedexercise.HealFeedPlugin4api-version: '26.3'5description: The /heal and /feed commands with permissions, targets, cooldowns and configurable messages.6permissions:7  healfeed.heal:8    description: Use /heal on yourself.9    default: op10  healfeed.heal.others:11    description: Use /heal on another player.12    default: op13  healfeed.feed:14    description: Use /feed on yourself.15    default: op16  healfeed.feed.others:17    description: Use /feed on another player.18    default: op19  healfeed.cleanse:20    description: Use /cleanse on yourself.21    default: op22  healfeed.cleanse.others:23    description: Use /cleanse on another player.24    default: op25  healfeed.bypass-cooldown:26    description: Use the commands without waiting for the cooldown.27    default: op28  healfeed.*:29    description: Every HealFeed permission.30    default: op31    children:32      healfeed.heal: true33      healfeed.heal.others: true34      healfeed.feed: true35      healfeed.feed.others: true36      healfeed.cleanse: true37      healfeed.cleanse.others: true38      healfeed.bypass-cooldown: true

1cooldowns:2  heal-seconds: 3003  feed-seconds: 04 5messages:6  cooldown: "<red>Please wait <yellow><time></yellow> before using <yellow>/<command></yellow> again."

Extension ideas

• Heal everyone. Swap ArgumentTypes.player() for ArgumentTypes.players() so /heal @a works, and loop over the list. Think about which permission such a command should need.
• Sound and particles. Play a sound and spawn heart particles when somebody is healed. See Potion effects, particles and effects.
• Action bar messages. Send the "you feel much better" text to the action bar instead of the chat. See Titles, action bars and sounds.
• Cooldown cleanup. Remove expired entries from the map every few minutes with a repeating task. See The scheduler.
• A reload command. Add /healfeed reload and rebuild the messages from the new config. See Configuration files.
• Different cooldowns per rank. Add a cooldowns.vip section with shorter times and read from it when the player has a healfeed.vip permission.

The next project, Homes, saves data per player and adds teleporting with a warmup, and the cooldown idea you learned here comes back again.

Recap

• A Brigadier command is a tree: a literal node for the word, an optional argument node for the target, and executes on every node that may be the end of the command.
• requires(...) hides a command from players without a permission; declare the permissions in plugin.yml with a default.
• A second, stronger permission on the argument node protects "do it to somebody else".
• ArgumentTypes.player() gives you a resolver; resolve(source) turns it into a list of players, and a missing player produces Brigadier's own error.
• An enum can describe what differs between similar commands, so one command class serves them all.
• A cooldown is a map from UUID to the time the player may act again. Store the UUID, never the Player object.
• Put every player-facing message in config.yml and fill the names in with placeholders.

Quick quiz

Next steps

• Project: Homes: store data for every player and teleport them safely.
• Commands, part 2: more argument types, suggestions and sub-commands.
• Practice Arena: challenges for commands, permissions and cooldowns.