Package tk.airshipcraft.commonlib.utils.cooldowns

package tk.airshipcraft.commonlib.utils.cooldowns

Cooldown Management Tools

Provides a comprehensive set of tools for managing cooldowns within a Minecraft plugin environment. This package includes interfaces and classes that enable the creation and management of cooldowns based on ticks and milliseconds, as well as a key-value cooldown handler for more complex data structures.

The package contains the following key components:

  • ICoolDownHandler: An interface defining the basic operations for a cooldown handler, such as putting an object on cooldown, checking if it is on cooldown, and getting the remaining cooldown time.
  • IKVCoolDownHandler: An extension of the ICoolDownHandler interface that includes additional functionality to work with key-value pairs, allowing for more detailed cooldown management.
  • KVTickCoolDownHandler: A concrete implementation of IKVCooldownHandler that tracks cooldowns based on the game's tick rate. This class is suitable for actions that should be synchronized with the game's internal timing.
  • MilliSecCoolDownHandler: A cooldown handler that tracks cooldowns in milliseconds, providing precision for actions that require real-time tracking, independent of the game's tick rate.
  • TickCoolDownHandler: Similar to KVTickCoolDownHandler but for single objects. It manages cooldowns in ticks, ideal for game-related actions that require synchronization with the server tick rate.

Usage Example:

To use a cooldown handler, first instantiate it with the desired cooldown period. Then, when an action occurs (such as a player casting a spell), use putOnCoolDown() to start the cooldown. Check if an action is available using onCoolDown() before allowing it to occur.

Implementing a Custom CoolDownHandler:

Create a class that implements ICoolDownHandler. Define the cooldown storage mechanism and implement all interface methods. Optionally, use Bukkit's scheduler to increment a counter for tick-based handlers.

Example:


 public class MyCustomCoolDownHandler<T> implements ICoolDownHandler<T> {
     private Map<T, Long> coolDowns = new HashMap<>();

     // Implement methods here
 }

Use this handler by creating an instance and then managing cooldowns for various objects like so:


 MyCustomCoolDownHandler<Player> playerCooldowns = new MyCustomCoolDownHandler<>();
 playerCooldowns.putOnCoolDown(player);
 if (playerCooldowns.onCoolDown(player)) {
     // Notify player that the action is on cooldown
 }

For a more detailed and synchronized cooldown, use KVTickCoolDownHandler and schedule a repeating task to increment the tick counter, tying it to the server's tick rate.

Example:


 KVTickCoolDownHandler<String, MyAction> actionCooldowns = new KVTickCoolDownHandler<>(myPlugin, 20L * 60); // 1 minute cooldown
 actionCooldowns.putOnCoolDown("Fireball", new MyAction(...));

Remember to handle the cleanup of cooldowns when they're no longer needed to prevent memory leaks.