Tutorial Creating player cooldowns

A lot of people seem to think that in order to simulate a cooldown for players (a length of time one must wait in order to repeat a certain action), they have to use the BukkitScheduler's runTaskLater method. The issue with this is that, although it will work, it is extremely inefficient and there is a much cleaner way of going about it. This tutorial is going to teach you how to properly store and use cooldowns for players.

The first thing we'll do is create an abstract class which can be used to store the name and cooldown we want to apply.

Delayable.java:

Code:java

import org.bukkit.configuration.serialization.ConfigurationSerializable;
 
import java.util.UUID;
 
public abstract class Delayable implements ConfigurationSerializable {
 
    private UUID uniqueId;
 
    private String name;
    private long cooldown;
 
    public Delayable(String name, long cooldown) {
        this(name, cooldown, UUID.randomUUID());
    }
 
    public Delayable(String name, long cooldown, UUID uniqueId) {
        setName(name);
        setCooldown(cooldown);
        setUniqueId(uniqueId);
    }
 
    public UUID getUniqueId() {
        return uniqueId;
    }
 
    private void setUniqueId(UUID uniqueId) {
        this.uniqueId = uniqueId;
    }
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
 
    public long getCooldown() {
        return cooldown;
    }
 
    public void setCooldown(long cooldown) {
        this.cooldown = cooldown;
    }
}
 

Because it's abstract, we can't instantiate it. The Delayable class is merely a base class that is used to store information that all subclasses will have, for example, a name and a cooldown. I've also included a UUID, which will be extremely useful to store in our HashMap of cooldowns. I've even made it implement ConfigurationSerializable, since it would come in handy for this tutorial anyways. ConfigurationSerializable lets us store and retrieve information related to a custom object via .yml configuration files.

The next thing we want to do is create our Kit class. The reason I'm using a Kit is because it's a fairly common topic within the Bukkit community. You can easily adapt this to suit your needs, and create a DelayedCommand class for example, instead.

Kit.java:

Code:java

import org.bukkit.inventory.ItemStack;
 
import java.util.*;
 
public class Kit extends Delayable {
 
    private ItemStack[] contents;
 
    public Kit(String name, long cooldown, ItemStack[] contents) {
        super(name, cooldown);
        setContents(contents);
    }
 
    public Kit(String name, long cooldown, ItemStack[] contents, UUID uuid) {
        super(name, cooldown, uuid);
        setContents(contents);
    }
 
    public ItemStack[] getContents() {
        return contents;
    }
 
    public void setContents(ItemStack[] contents) {
        this.contents = contents;
    }
 
    @Override
    public Map<String, Object> serialize() {
        Map<String, Object> result = new HashMap<String, Object>();
 
        result.put("uuid", getUniqueId());
        result.put("name", getName());
        result.put("cooldown", getCooldown());
        result.put("contents", getContents());
 
        return result;
    }
 
    public static Kit deserialize(Map<String, Object> args) {
        String name = (String) args.get("name");
        Long cooldown = (Long) args.get("cooldown");
 
        List<ItemStack> itemList = (ArrayList<ItemStack>) args.get("contents");
        ItemStack[] contents = itemList.toArray(new ItemStack[itemList.size()]);
 
        UUID uniqueId = UUID.fromString((String) args.get("uuid"));
 
        return new Kit(name, cooldown, contents, uniqueId);
    }
}
 

As you can see, it's a really basic class which stores an ItemStack array. Since the abstract class Delayable implements ConfigurationSerializable, we need to implement the methods here.

The next thing we need to do is create a class for Players that stores all of their current cooldowns.

DelayedPlayer.java:

Code:java

import org.bukkit.configuration.serialization.ConfigurationSerializable;
import org.bukkit.entity.Player;
 
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
 
public class DelayedPlayer implements ConfigurationSerializable{
 
    private UUID playerUniqueId;
 
    private HashMap<UUID, Long> delays;
 
    public DelayedPlayer(Player player) {
        playerUniqueId = player.getUniqueId();
        delays = new HashMap<UUID, Long>();
    }
 
    public DelayedPlayer(UUID uuid, HashMap<UUID, Long> delays) {
        this.playerUniqueId = uuid;
        this.delays = new HashMap<UUID, Long>(delays);
    }
 
    public UUID getUniqueId() {
        return playerUniqueId;
    }
 
    public HashMap<UUID, Long> getDelays() {
        return delays;
    }
 
    public void addDelay(Delayable delayable) {
        getDelays().put(delayable.getUniqueId(), System.currentTimeMillis());
    }
 
    public void removeDelay(Delayable delayable) {
        if (getDelays().containsKey(delayable.getUniqueId())) {
            getDelays().remove(delayable.getUniqueId());
        }
    }
 
    public boolean isPlayerDelayed(Delayable delayable) {
        boolean delayed = false;
 
        if (getDelays().containsKey(delayable.getUniqueId())) {
            delayed = System.currentTimeMillis() - getDelays().get(delayable.getUniqueId()) < delayable.getCooldown();
 
            if (!delayed) {
                removeDelay(delayable);
            }
        }
 
        return delayed;
    }
 
    public Long getRemainingTime(Delayable delayable){
        if (!isPlayerDelayed(delayable)) return 0L;
 
        return delayable.getCooldown() - (System.currentTimeMillis() - getDelays().get(delayable.getUniqueId()));
    }
 
    @Override
    public Map<String, Object> serialize() {
        Map<String, Object> result = new HashMap<String, Object>();
 
        Map<String, Long> delays = new HashMap<String, Long>();
 
        for (UUID uuid : getDelays().keySet()) {
            delays.put(uuid.toString(), getDelays().get(uuid));
        }
 
        result.put("uuid", getUniqueId());
        result.put("delays", delays);
 
        return result;
    }
 
    public static DelayedPlayer deserialize(Map<String, Object> args) {
        UUID uniqueId = UUID.fromString((String) args.get("uuid"));
 
        HashMap<String, Long> stringDelays = args.get("delays") != null && args.get("delays") instanceof HashMap
                ? (HashMap<String, Long>) args.get("delays")
                : new HashMap<String, Long>();
        HashMap<UUID, Long> delays = new HashMap<UUID, Long>();
 
        for (String uuid : stringDelays.keySet()) {
            delays.put(UUID.fromString(uuid), stringDelays.get(uuid));
        }
 
        return new DelayedPlayer(uniqueId, delays);
    }
}
 

Since ConfigurationSerialization won't allow us to store raw UUIDs, we have to store the delays with the key as a String using uuid.toString(). This class is designed so that we can easily store and retrieve a list of DelayedPlayers via the ConfigurationSerializable interface, which will come in useful when you want cooldowns to persist through server reloads and restarts.

The final thing we need to do is create a class to manage all of our delayed players.

CooldownManager.java:

Code:java

import org.bukkit.entity.Player;
import org.bukkit.plugin.java.JavaPlugin;
 
import java.util.ArrayList;
import java.util.List;
 
public class CooldownManager {
 
    private JavaPlugin plugin;
 
    private List<DelayedPlayer> delayedPlayers;
 
    @SuppressWarnings("unchecked")
    public CooldownManager(JavaPlugin instance) {
        plugin = instance;
 
        delayedPlayers = new ArrayList<DelayedPlayer>();
 
        if (plugin.getConfig().contains("delayed-players")) {
            try {
                delayedPlayers = (ArrayList<DelayedPlayer>) plugin.getConfig().get("delayed-players");
            } catch (Exception ex) {
                ex.printStackTrace();
            }
        }
    }
 
    public List<DelayedPlayer> getDelayedPlayers() {
        return delayedPlayers;
    }
 
    public DelayedPlayer getDelayedPlayer(Player player) {
        for (DelayedPlayer delayedPlayer : getDelayedPlayers()) {
            if (delayedPlayer.getUniqueId().equals(player.getUniqueId())) {
                return delayedPlayer;
            }
        }
 
        DelayedPlayer delayedPlayer = new DelayedPlayer(player);
        getDelayedPlayers().add(delayedPlayer);
 
        return delayedPlayer;
    }
 
}
 

To use the CooldownManager, you simply need to declare one in your Main class and instantiate it in your onEnable method, like so. You should also register all classes that implement ConfigurationSerializable with ConfigurationSerialization:

Code:java

private CooldownManager cooldownManager;
 
public void onEnable() {
    registerConfigurationSerializables();
 
    cooldownManager = new CooldownManager(this);
}
 
private void registerConfigurationSerializables() {
    ConfigurationSerialization.registerClass(Kit.class);
    ConfigurationSerialization.registerClass(DelayedPlayer.class);
}
 
public CooldownManager getCooldownManager() {
    return cooldownManager;
}
 

It might seem like a lot of code for a simple cooldown, but it's extremely versatile and lets you manage more than one cooldown for more than one object, as long as the object implements the Delayable class. Here's how you would go about creating a Kit with a specific cooldown, and adding that cooldown to that player. The kit has a cooldown of 60000 milliseconds, or 60 seconds:

Code:java

Kit kit = new Kit("My awesome kit", 60000, new ItemStack[]{new ItemStack(Material.DIAMOND)});
player.getInventory().addItem(kit.getContents());
 
DelayedPlayer delayedPlayer = plugin.getCooldownManager().getDelayedPlayer(player);
delayedPlayer.addDelay(kit);
 
if (delayedPlayer.isPlayerDelayed(kit)) {
    player.sendMessage("You are delayed for this kit.");
}
 

Finally, as an added bonus, most of you would be wondering how to retrieve the remaining time left on a cooldown for a specific Delayable object in a more readable format, rather than in milliseconds. For this, I have created a simple Utility class that you can use, which is available here:

Time Utility class

To use it, you would do something along the lines of this:

Code:java

String remainingTime = Utils.getTime(delayedPlayer.getRemainingTime(kit), false);
 
player.sendMessage("You must wait " + remainingTime);

If I missed something out, please feel free to comment. I should apologize for this thread being extremely long.

EDIT by Moderator: merged posts, please use the edit button instead of double posting.

 

Nice tutorial! I'm glad people are trying to get others away from using DelayedTasks

 

ABDTGaming DelayedTasks are love, DelayedTasks are lyfe ^_^

But anyways, very nice!

 

Regablith no they aren't, they slow down servers.