Cooldown System for Spigot/Paper

Lightweight cooldown management library for Minecraft Spigot/Paper plugins. Provides annotation-based, programmatic, and persistent cooldown systems with automatic cleanup, zero dependencies, and key flexibility.

Features

• Annotation-Based Cooldowns - Add @Cooldown to any method
• Programmatic API - Flexible cooldown management at runtime
• Multiple Key Types - Player UUID, String, or custom keys
• Automatic Cleanup - Expired cooldowns removed automatically
• Event Integration - Cancel events based on cooldown status
• Zero Dependencies - Uses only native Spigot/Paper API

Installation

<dependency>
    <groupId>com.kaloudasdev</groupId>
    <artifactId>cooldown-system</artifactId>
    <version>1.0.0</version>
</dependency>

Usage Examples

Annotation-Based

@Cooldown(duration = 30, unit = TimeUnit.SECONDS)
@Command(name = "heal")
public void onHeal(Player player) {
    player.setHealth(20);
    player.sendMessage("You have been healed");
}

Programmatic

CooldownManager cooldown = CooldownManager.getInstance();

if (cooldown.hasCooldown(key)) {
    long remaining = cooldown.getRemaining(key);
    player.sendMessage("Wait " + remaining + " seconds");
    return;
}

cooldown.setCooldown(key, 30);

API Reference

Method	Description
hasCooldown(String key)	Check if cooldown exists
getRemaining(String key)	Get remaining seconds
setCooldown(String key, long seconds)	Apply cooldown
removeCooldown(String key)	Remove cooldown
clearAll()	Clear all cooldowns

License

MIT © KaloudasDev