Patterns: cooldowns, toggles and player state

Almost every plugin feature needs a little memory: "when can this player use the ability again?", "is this player in build mode?", "is this player still playing?". On this page you will build three small tools for exactly that: a reusable cooldown class, an on/off toggle and a state tracker, and learn to clean them up so your plugin never leaks memory.

Why plugins need a memory for players

Your event handlers and commands run for a moment and finish. Nothing in a handler remembers what happened the last time it ran. So when a player types /dash twice in a row and you want the second one refused, something has to keep a note between the two commands: "Steve dashed 3 seconds ago".

The place for that note is a field in one of your classes: a variable that belongs to an object and lives as long as the object does. Three kinds of notes come up again and again, and each has a Java collection that fits it perfectly:

If Map, Set and UUID are new to you, skim Lists, sets and maps and Time, UUIDs and randomness first. The short version: a map is a lookup table (a key leads to a value), a set is a bag where each thing is either in or out, and a UUID is the unique id every player has.

Cooldowns: remember when it is ready

The trick behind every cooldown is to not count down at all. Instead, store the moment when the player may act again, and compare it with the clock when they try. When the ability is used at second 0 with an 8-second cooldown, you store "ready at second 8". Any attempt before that is refused, and the number of seconds left is simply the ready time minus now.

Here is the idea as a plain Java program with a pretend clock, so you can run it and watch the logic without a server. The "now" is passed in as a number of milliseconds:

11Map<String, Long> readyAt = new HashMap<>();2 3boolean tryUse(String player, long now, long cooldownMillis) {24    Long ready = readyAt.get(player);35    if (ready != null && now < ready) {6        IO.println(player + " must wait " + (ready - now) + " more milliseconds.");7        return false;8    }49    readyAt.put(player, now + cooldownMillis);10    IO.println(player + " used the ability.");11    return true;12}13 14void main() {15    long cooldown = 5000;16    tryUse("Steve", 0, cooldown);517    tryUse("Steve", 2000, cooldown);18    tryUse("Alex", 2000, cooldown);19    tryUse("Steve", 5000, cooldown);20}

Why UUID and not the player

Notice the map keys are UUIDs, not Player objects and not names. A Player object stands for one login session. If the player leaves and comes back, you get a different object, and a map that holds the old one keeps it in memory for nothing. Names can change. A UUID belongs to the player for good: player.getUniqueId() gives it to you.

Why not a repeating task that counts down?

You could start a task that counts down every second for every player, as the scheduler page does for a countdown. That works, but you would run code every second for every player even when nobody is on cooldown, and each timer is one more thing to cancel when a player leaves. A stored timestamp costs nothing while it sits there and is checked only when the player actually tries something. For cooldowns, the timestamp is almost always the better tool.

A reusable Cooldowns class

You will want cooldowns in many places: a dash, a heal command, a kit. Writing the map logic each time invites mistakes, so put it in one small class and reuse it. Each ability gets its own Cooldowns object, and you ask it three questions: how long is left, start one, clear one.

1package com.example.cooldownsdemo;2 3import java.time.Duration;4import java.util.HashMap;5import java.util.Map;6import java.util.UUID;7 8public final class Cooldowns {9 110    private final Map<UUID, Long> readyAt = new HashMap<>();11 212    public long remainingMillis(UUID id) {13        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    public boolean isReady(UUID id) {26        return remainingMillis(id) == 0L;27    }28 29    public void start(UUID id, Duration duration) {730        readyAt.put(id, System.currentTimeMillis() + duration.toMillis());31    }32 833    public void clear(UUID id) {34        readyAt.remove(id);35    }36}

Showing the time left nicely

"Wait 8000 milliseconds" is not friendly, and "Wait 0.99 seconds" looks odd. Players want "8s", "1m 30s" or "1h 2m 5s". This small function turns milliseconds into that. Run it and look at the output, especially the first line: 400 ms shows as 1s, because rounding up means the player never sees "0s" while still blocked.

1String format(long millis) {12    long totalSeconds = (millis + 999) / 1000;3    long hours = totalSeconds / 3600;24    long minutes = totalSeconds % 3600 / 60;5    long seconds = totalSeconds % 60;6 37    StringBuilder text = new StringBuilder();8    if (hours > 0) {9        text.append(hours).append("h ");10    }11    if (minutes > 0) {12        text.append(minutes).append("m ");13    }414    if (seconds > 0 || text.isEmpty()) {15        text.append(seconds).append("s");16    }517    return text.toString().strip();18}19 20void main() {21    long[] waits = {400, 1000, 4200, 60_000, 90_000, 3_725_000};22    for (long wait : waits) {23        IO.println(wait + " ms is shown as " + format(wait));24    }25}

The plugin uses the same function, as a static method in a class called TimeFormat. Its body is identical, so it is not repeated here; you can see it in the downloadable project.

Example: a /dash ability

Now put the pieces together. The ability lives in its own class, DashAbility, so that more than one thing can trigger it: a command and a right-click with a feather. It owns the cooldown rules, and the command and listener just call it.

22public boolean tryDash(Player player) {123    long remaining = cooldowns.remainingMillis(player.getUniqueId());224    if (remaining > 0L) {25        player.sendRichMessage("<red>Dash is recharging: <white><time></white> left.",326            Placeholder.unparsed("time", TimeFormat.remaining(remaining)));27        return false;28    }29 430    Vector direction = player.getLocation().getDirection();531    player.setVelocity(direction.multiply(SPEED).setY(LIFT));632    player.playSound(player, Sound.ENTITY_BREEZE_WIND_BURST, 1.0f, 1.0f);33 734    cooldowns.start(player.getUniqueId(), COOLDOWN);835    player.setCooldown(Material.FEATHER, (int) (COOLDOWN.toMillis() / 50));36    return true;37}

15@Override16public void execute(CommandSourceStack source, String[] args) {117    if (!(source.getExecutor() instanceof Player player)) {18        source.getSender().sendRichMessage("<red>Only players can dash.");19        return;20    }221    dash.tryDash(player);22}

Cooldown visuals are not cooldown logic

Minecraft has its own cooldown display: the gray sweep that covers an ender pearl or a shield after use. Paper lets you trigger it with player.setCooldown(Material.FEATHER, ticks), where the time is in ticks, not milliseconds. The DashAbility above uses it, so right after a dash every feather in the player's hotbar shows the sweep.

That sweep is a picture. For items that already do something in vanilla, like pearls, Minecraft respects it by itself. For an item like a feather that does nothing on its own, the sweep only tells the player to wait; your code must still refuse a dash during the cooldown. That is why DashAbility keeps its own Cooldowns object as the real rule and uses setCooldown only as decoration. The best result uses both: the player sees the sweep and your logic enforces it.

This is the listener that lets a right-click with a feather start the same ability:

19@EventHandler20public void onInteract(PlayerInteractEvent event) {121    if (event.getHand() != EquipmentSlot.HAND) {22        return;23    }224    if (event.getAction() != Action.RIGHT_CLICK_AIR && event.getAction() != Action.RIGHT_CLICK_BLOCK) {25        return;26    }327    if (event.getItem() == null || event.getItem().getType() != Material.FEATHER) {28        return;29    }30    Player player = event.getPlayer();431    if (!player.hasPermission("cooldownsdemo.dash")) {32        return;33    }534    event.setCancelled(true);35    dash.tryDash(player);36}

Toggles: on and off with a Set

A toggle is a switch that a player flips: build mode, a particle trail, vanish. You only need to remember who has it on, which is exactly what a Set is for: a collection where a thing is either inside or not, with no duplicates.

1package com.example.cooldownsdemo;2 3import java.util.HashSet;4import java.util.Set;5import java.util.UUID;6 7public final class BuildMode {8 19    private final Set<UUID> active = new HashSet<>();10 11    public boolean toggle(UUID id) {212        if (active.remove(id)) {13            return false;14        }315        active.add(id);16        return true;17    }18 19    public boolean isActive(UUID id) {420        return active.contains(id);21    }22 23    public void remove(UUID id) {24        active.remove(id);25    }26}

15@Override16public void execute(CommandSourceStack source, String[] args) {17    if (!(source.getExecutor() instanceof Player player)) {18        source.getSender().sendRichMessage("<red>Only players can build.");19        return;20    }121    boolean nowOn = buildMode.toggle(player.getUniqueId());22    if (nowOn) {23        player.sendRichMessage("<green>Build mode is on. Broken blocks no longer drop items.");24    } else {25        player.sendRichMessage("<yellow>Build mode is off.");26    }27}

The switch itself does nothing until some other code reads it. Here a listener reads the set: in build mode, broken blocks leave no item drops, so builders do not flood the ground with dirt.

15@EventHandler16public void onBreak(BlockBreakEvent event) {117    if (buildMode.isActive(event.getPlayer().getUniqueId())) {218        event.setDropItems(false);19    }20}

Clean up when players leave

Every note you keep is a little memory. A player who used /dash once and never returned still has an entry in your map. Multiply that by months of players and the map grows forever. This is called a memory leak: memory that nobody needs any more but that nothing ever frees.

For toggles it is worse: a player who logs out with build mode on and logs in tomorrow would still be in build mode, even though they never asked for it. The fix is a tiny listener that forgets the player on PlayerQuitEvent. If you forgot what that is, see Events and listeners.

18@EventHandler119public void onQuit(PlayerQuitEvent event) {20    UUID id = event.getPlayer().getUniqueId();221    dashCooldowns.clear(id);322    buildMode.remove(id);23}

One rule: every time you write map.put(...) or set.add(...) for a player, ask yourself "where does this entry get removed?" If you cannot answer, you have a leak.

States: what is the player doing?

Some things are not on or off but one of several. In a minigame, a player is in the lobby, playing, or spectating after being knocked out. Using three separate sets would let a player be in two at once by mistake. A cleaner idea is a state machine: each player has exactly one state, and your code changes it when something happens.

In Java, a fixed list of options is an enum. An enum can even carry rules. Here each state knows whether its players take damage, so no other code needs a list of "if state is LOBBY or SPECTATING":

1package com.example.cooldownstimersstates;2 3public enum ArenaState {14    LOBBY(false),5    PLAYING(true),6    SPECTATING(false);7 28    private final boolean takesDamage;9 310    ArenaState(boolean takesDamage) {11        this.takesDamage = takesDamage;12    }13 14    public boolean takesDamage() {15        return takesDamage;16    }17}

11public ArenaState get(UUID id) {112    return states.getOrDefault(id, ArenaState.LOBBY);13}

The listener then reads the state to decide what to do:

1package com.example.cooldownstimersstates;2 3import org.bukkit.entity.Player;4import org.bukkit.event.EventHandler;5import org.bukkit.event.Listener;6import org.bukkit.event.entity.EntityDamageEvent;7import org.bukkit.event.entity.PlayerDeathEvent;8import org.bukkit.event.player.PlayerQuitEvent;9 10final class ArenaListener implements Listener {11 12    private final ArenaPlayers players;13 14    ArenaListener(ArenaPlayers players) {15        this.players = players;16    }17 18    @EventHandler19    public void onDamage(EntityDamageEvent event) {120        if (!(event.getEntity() instanceof Player player)) {21            return;22        }223        if (!players.get(player.getUniqueId()).takesDamage()) {24            event.setCancelled(true);25        }26    }27 28    @EventHandler29    public void onDeath(PlayerDeathEvent event) {30        Player player = event.getPlayer();331        if (players.get(player.getUniqueId()) == ArenaState.PLAYING) {432            players.set(player.getUniqueId(), ArenaState.SPECTATING);33            player.sendRichMessage("<gray>You are out. You are now spectating.");34        }35    }36 37    @EventHandler38    public void onQuit(PlayerQuitEvent event) {539        players.remove(event.getPlayer().getUniqueId());40    }41}

Try it: join your test server, type /arena playing, then let a zombie hit you, and then type /arena lobby and notice that damage stops. You can download the state example as a Gradle project.

When memory is not enough

Everything on this page lives in memory, so it disappears when the server restarts. For a dash cooldown that is fine. If a cooldown must survive a restart, such as "one daily reward per player", store the ready time in a file, a database or on the player with PersistentDataContainer, and see Saving player data. The same idea works: a long ready time.

The whole demo plugin

8@Override9public void onEnable() {110    Cooldowns dashCooldowns = new Cooldowns();211    DashAbility dash = new DashAbility(dashCooldowns);12    BuildMode buildMode = new BuildMode();13 14    getServer().getPluginManager().registerEvents(new DashFeatherListener(dash), this);15    getServer().getPluginManager().registerEvents(new BuildModeListener(buildMode), this);316    getServer().getPluginManager().registerEvents(new QuitCleanupListener(dashCooldowns, buildMode), this);17 18    getLifecycleManager().registerEventHandler(LifecycleEvents.COMMANDS, event -> {19        event.registrar().register("dash", "Dash forward (also: right-click a feather)", new DashCommand(dash));20        event.registrar().register("buildmode", "Turn build mode on or off", new BuildModeCommand(buildMode));21    });22}

Download the cooldowns demo as a Gradle project. As an operator, try /dash twice in a row, then /buildmode and break a few blocks.

Mistakes to avoid

• Storing Player objects in a map or set that lives a long time. Use the UUID.
• Never removing entries. Remove players on quit, and remove expired cooldowns when you notice them.
• Starting the cooldown before the action can fail. Check that the player is allowed, do the thing, then start the cooldown.
• Mixing milliseconds and ticks. The clock gives milliseconds; Minecraft's item cooldown and the scheduler use ticks (50 ms each).
• Using a name as a key. A player can change their name. The UUID never changes.
• Forgetting that PlayerInteractEvent fires once per hand. Check getHand().
• Showing no message. A command that silently does nothing looks broken. Always say what is happening and how long to wait.

22@Override23public void execute(CommandSourceStack source, String[] args) {24    if (!(source.getExecutor() instanceof Player player)) {25        source.getSender().sendRichMessage("<red>Only players can boost.");26        return;27    }128    long remainingSeconds = (cooldowns.remainingMillis(player.getUniqueId()) + 999) / 1000;29    if (remainingSeconds > 0) {30        player.sendRichMessage("<red>Boost is recharging: <white><seconds>s</white> left.",31            Placeholder.unparsed("seconds", String.valueOf(remainingSeconds)));32        return;33    }234    player.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, BOOST_TICKS, 1));335    cooldowns.start(player.getUniqueId(), COOLDOWN);36    player.sendRichMessage("<green>Boost! You run faster for 10 seconds.");37}

1private final Set<Player> rewarded = new HashSet<>();2 3public void giveReward(Player player) {4    if (rewarded.add(player)) {5        player.getInventory().addItem(ItemStack.of(Material.DIAMOND));6    }7}

Recap

• Plugins remember things per player in fields: a Map for values, a Set for yes/no, and an enum-valued map for states.
• Key everything by UUID, never by Player or name.
• A cooldown stores the time when the player is ready. Remaining time is "ready time minus now". Start it only after the action succeeded.
• Round remaining time up and format it as "1m 30s" for players.
• player.setCooldown(Material, ticks) draws the gray sweep, but only your own logic enforces a cooldown for custom items.
• Remove entries when players quit, or the maps grow forever and toggles stick across sessions.
• All of this is lost on restart. Save to disk when it must last.

Quick quiz

Next steps

• Permissions: decide who gets to use your dash and build mode, and give ranks different cooldowns.
• Project: /heal and /feed with cooldowns: use the Cooldowns class in a full small project.
• Saving data on things: PersistentDataContainer: make state survive restarts.