boosCooldowns

Per-command cooldowns, warmups, limits, prices and disable rules – with a shared database so your whole network stays in sync.

Built for Paper 1.20+ (tested on 1.21.8 and 26.1.2). Java 21. Drop-in install, SQLite out of the box, MySQL/MariaDB for multi-server.

✨ Features

Core control

Per-command cooldowns – regular expressions or wildcards, per command group, with custom messages
Warmups – player has to stand still while the command charges up
Usage limits – N uses per time window, with scheduled resets
Prices – money (Vault), XP levels, items, PlayerPoints
Server-wide cooldowns – one player uses /event, everyone shares the cooldown window
Progressive cooldowns – multiplier that grows with each consecutive use, resets after a quiet period
Disable commands – flag a command disabled: true without unregistering it; bypass permission available

Player UX

Warmup effects – boss bar progress indicator, sounds, particles
Action bar for warmup countdown and cooldown notices
Confirmation dialogs – clickable [Yes] [No] for commands that cost something, per-player toggle
Refund on warmup cancel – opt-in return of charged money/items/XP when a warmup is aborted
Localization – drop messages_<locale>.yml and messages follow client language
Per-command messages – override cooldown/warmup/disabled text per command

Admin tooling

/bcd status [player] – every active cooldown, remaining uses, warmup state
/bcd rule get/set/tempset – inspect or mutate command rules live (temp overrides auto-restore)
/bcd grant cooldown/uses – manually seed state on a player
/bcd clear cooldowns/uses/warmups/all <player> – cleanup with granularity
/bcd reset now/schedule/list – global usage-counter resets, immediate or scheduled
/bcd validate – config linter (unknown keys, bad durations, typos in materials/sounds)
/bcd audit – decision log (opt-in)
/bcd diff – compare config hash across nodes sharing the same DB
Legacy aliases – every pre-4.0 command name still works (clearcooldowns, set, info, …)
Autogenerated /bcd help – permission-filtered, grouped by category
Smart tab completion – suggests options, player names, configured commands

Advanced

Per-world restrictions – rule only applies in specific worlds
WorldGuard regions – rule only applies inside specific regions (optional)
Group inheritance – vip group inherits every rule from default, overrides just what it needs
Event-based resets – wipe a cooldown when the player kills an entity or earns an advancement; optional chat message, sound cue and server-wide broadcast
Namespace-aware – commands typed as /plugin:command are rewritten to their bare form so cooldowns and limits still apply (no need to keep the old hard syntax blocker on)
Command aliases – /ja hello → /me hello with argument substitution ($1, $*, $player, $world)
Sign shortcuts – [boosCooldowns] signs that run commands as player or console
Multi-server drift detection – each node hashes its config.yml, plugin warns on divergence, /bcd diff inspects

Persistence

SQLite (default, zero-config) or MySQL / MariaDB (for networks)
JDBC drivers auto-downloaded via libraries: in plugin.yml – no manual install
HikariCP connection pool, cache-through for hot-path reads
Schema-versioned migrations (V1…V4), applied on startup
Legacy users.yml is auto-migrated on first run; old file renamed for safety

Developer

Public API – BoosCooldownAPI.getInstance() with isOnCooldown, setCooldown, getRemainingUses, …
Custom Bukkit events – CooldownEvent, WarmupEvent, CommandEvent (all cancellable)
PlaceholderAPI expansion – %boos_remaining_<cmd>%, %boos_uses_<cmd>%, %boos_on_cooldown_<cmd>%
bStats metrics – 13 custom charts covering storage backend (with driver version), feature toggles, detected integrations, multi-node setups, locale distribution and config scale

📦 Requirements

	Version
Java	21+
Paper / Spigot / Bukkit	1.20+ (API)
Storage	SQLite bundled, or MySQL 5.7+ / MariaDB 10+

Optional integrations (soft-depend)

Every integration is detected at runtime – missing one just disables that feature, never breaks startup.

Plugin	Unlocks
Vault + any Vault-compatible economy (EssentialsX Economy, CMIEconomy, …)	Money prices (`price: 100.0`)
PlayerPoints	Point prices (`playerpoints: 10`)
PlaceholderAPI	`%boos_*%` placeholders; expansion of third-party placeholders inside plugin messages
WorldGuard	`regions:` per-command restriction
LuckPerms (or any permissions plugin)	Group-based rule targeting via `booscooldowns.<group-name>`

🚀 Installation

Download boosCooldowns.jar from the Hangar page.
Drop it into plugins/.
Start the server once – default config.yml is generated in plugins/boosCooldowns/.
Edit config.yml and run /bcd reload in-game or from console.

Upgrading from a pre-4.0 version? users.yml is migrated automatically on first start and renamed to users.yml.migrated-<timestamp>.

⚙️ Configuration essentials

Database

database:
  type: sqlite                  # sqlite (default) or mysql / mariadb
  # host: localhost
  # port: 3306
  # database: boosCooldowns
  # username: user
  # password: secret
  pool-size: 4
  cache-ttl-seconds: 30

For shared cooldowns across multiple servers (BungeeCord/Velocity network), point every server at the same MySQL/MariaDB instance and give each one a unique options.options.node_id.

A command rule – everything available

commands:
  groups:
    default:
      /kit:
        cooldown: "1 hour"
        warmup: 5                         # seconds
        limit: 3
        limit_reset_delay: "6 hours"      # fixed window
        price: 100.0                      # Vault money
        xpcost: 5
        playerpoints: 10
        itemcost:
          item: DIAMOND
          count: 1
          name: "Kit Token"
        server_cooldown: "30 minutes"

        # Progressive cooldown – ×2 each time, streak resets after idle
        cooldown_multiplier: 2.0
        cooldown_reset_after: "6 hours"

        # Restrictions
        worlds: [survival, nether]
        regions: [spawn, arena]           # requires WorldGuard

        # Effects
        warmup_sound: BLOCK_BEACON_AMBIENT
        complete_sound: ENTITY_EXPERIENCE_ORB_PICKUP
        warmup_particle: ENCHANT

        # Access + messages
        disabled: false
        disabled_message: "&cKit is offline."
        cooldown_message: "&7Kit cooling down: &e&seconds&&7."
        warmup_message: "&7Preparing kit... &e&seconds&&7."
        permission: "myplugin.kit"        # optional extra gate
        denied_message: "&cNot allowed."
        shared_cooldown: [/kit_daily]
        shared_limit: [/kit_daily]

    vip:
      _inherits: default                  # all /kit rules above
      /kit:
        cooldown: "10 minutes"            # …except this one gets shorter

Aliases

commands:
  aliases:
    /ja: /me                              # exact match
    /tell *: /msg $1 $*                   # wildcard with argument substitution

Placeholders: $1, $2, …, $*, $player, $world.

Event-based cooldown resets

event_triggers:
  - when: KILL
    entity: ENDER_DRAGON
    reset_cooldown: /boss_reward
    message: "&6You slew the dragon! &e/boss_reward&6 is ready."
    sound: ENTITY_PLAYER_LEVELUP
    broadcast: true                       # default: false

  - when: ADVANCEMENT
    advancement: story/mine_diamond
    reset_cooldown: /miner_reward
    message: "&a/miner_reward has been reset."

Message placeholders: &command&, &player&, &entity& (KILL only), &advancement& (ADVANCEMENT only).

Handling `/plugin:command` syntax

Minecraft lets anyone bypass a cooldown by typing /minecraft:tp instead of /tp. You have two ways to stop that:

Hard blocker (syntax_blocker_enabled: true, the default) – rejects any namespace-prefixed command with an invalid_command_syntax message. Strict but annoying when ops type /paper:version.
Transparent rewrite (syntax_blocker_enabled: false + apply_rules_to_prefixed_syntax: true) – the plugin silently rewrites /plugin:cmd to /cmd before running its rule lookup. Players keep the shortcut, admins keep the cooldown. Recommended.

Global options

options:
  options:
    disabled_for_ops: true                # plugin has no effect on ops
    warmups_enabled: true
    cooldowns_enabled: true
    limits_enabled: true
    prices_enabled: true
    cancel_warmup_on_move: false
    cancel_warmup_on_damage: false
    cancel_warmup_on_sneak: false
    cancel_warmup_on_sprint: false
    cancel_warmup_on_gamemode_change: false
    block_interact_during_warmup: false
    clear_cooldowns_on_death: false
    clear_uses_on_death: false
    start_cooldowns_on_death: false
    command_logging: false
    command_signs: false
    syntax_blocker_enabled: true          # reject /pluginname:command outright
    # when the blocker is off, rewrite /plugin:cmd → /cmd so rules still apply
    apply_rules_to_prefixed_syntax: true
    command_confirmation: true            # ask Yes/No for priced commands
    refund_on_warmup_cancel: false
    audit_enabled: false                  # persist every decision to DB
    audit_retention_days: 30
    default_locale: en
    node_id: ""                           # "" = auto hostname:port
    config_sync_interval_seconds: 60
  action_bar:
    warmup: false
    cooldown_on_attempt: false
    update_interval_ticks: 10
  boss_bar:
    warmup: false
    color: BLUE                           # BLUE, GREEN, PINK, PURPLE, RED, WHITE, YELLOW
    style: PROGRESS                       # PROGRESS, NOTCHED_6/10/12/20

💬 Commands

Root command: /booscooldowns (alias /bcd). Tab completion is wired up throughout.

Player commands

Command	Default	Purpose
`/bcd status [player]`	`true`	Your cooldowns, limits, active warmup. `[player]` requires `booscooldowns.status.others`
`/bcd check <command>`	`true`	Is this command on cooldown for me?
`/bcd confirmations`	`true`	Toggle the confirmation dialog on/off

Administration

Command	Default	Purpose
`/bcd reload`	op	Reload `config.yml`
`/bcd clear cooldowns <player> [command]`	op	Clear active cooldowns
`/bcd clear uses <player> [command]`	op	Reset usage counters
`/bcd clear warmups <player>`	op	Cancel active warmups
`/bcd clear all <player>`	op	Wipe cooldowns + uses + warmups
`/bcd rule set <option> <command> <value> [group]`	op	Persist a rule override
`/bcd rule tempset <option> <command> <value> <duration>`	op	Temporary override (auto-restores)
`/bcd rule get <command> [group]`	op	Print effective rules (after inheritance)
`/bcd grant cooldown <player> <command> <duration>`	op	Seed a cooldown manually
`/bcd grant uses <player> <command> <count>`	op	Overwrite remaining uses
`/bcd reset now <command>`	op	Wipe the global usage counter immediately
`/bcd reset schedule <command> <time>`	op	Schedule a global reset (`+2h`, `yyyy-MM-dd HH:mm:ss`)
`/bcd reset list`	op	List pending scheduled resets

Diagnostics

Command	Default	Purpose
`/bcd validate`	op	Lint `config.yml` for typos, bad durations, unknown materials/sounds
`/bcd audit [command] [limit]`	op	Read the `command_audit` log
`/bcd diff`	op	Compare this node's config hash with peers
`/bcd help [section]`	`true`	Autogenerated help; `<section>` drills into a group

Legacy aliases (still work for backwards compatibility)

Legacy	New
`/bcd clearcooldowns`, `clearuses`, `clearwarmups`	`/bcd clear cooldowns` / `uses` / `warmups`
`/bcd set`, `tempset`	`/bcd rule set` / `tempset`
`/bcd scheduleglobalreset`, `listresets`, `startglobalreset`	`/bcd reset schedule` / `list` / `now`
`/bcd info`, `limits`, `checkcooldown`	`/bcd status [player]` / `/bcd check`

🔑 Permissions

Player-level (default `true`)

Permission	Effect
`booscooldowns.status`	Use `/bcd status` on yourself
`booscooldowns.check.cooldown`	Use `/bcd check`
`booscooldowns.list.limits`	Legacy – now covered by `booscooldowns.status`

Bypass permissions

Permission	Effect
`booscooldowns.exception`	Bypass the plugin entirely
`booscooldowns.norestriction`	Bypass warmups/cooldowns/prices/limits (aliases still apply)
`booscooldowns.nocooldown[./command]`	Bypass cooldowns, optionally per command
`booscooldowns.nowarmup[./command]`	Bypass warmups
`booscooldowns.nolimit[./command]`	Bypass limits
`booscooldowns.noprice[./command]`	Bypass Vault money cost
`booscooldowns.noxpcost[./command]`	Bypass XP cost
`booscooldowns.noitemcost[./command]`	Bypass item cost
`booscooldowns.noplayerpoints[./command]`	Bypass PlayerPoints cost
`booscooldowns.nodisable[./command]`	Use commands flagged `disabled: true`
`booscooldowns.noactionbar`	Suppress action-bar notifications
`booscooldowns.nobossbar`	Suppress boss-bar warmup indicator
`booscooldowns.nocancel.{move,damage,sneak,sprint,gamemodechange}`	Don't cancel warmup on that event
`booscooldowns.dontblock.interact`	Interact with blocks/containers during warmup

Admin permissions (default `op`)

Permission	Grants
`booscooldowns.reload`	`/bcd reload`
`booscooldowns.status.others`	`/bcd status <other player>`
`booscooldowns.clearcooldowns`	`/bcd clear cooldowns`, legacy aliases
`booscooldowns.clearuses`	`/bcd clear uses`
`booscooldowns.clearwarmups`	`/bcd clear warmups`
`booscooldowns.clear.all`	`/bcd clear all`
`booscooldowns.set`	`/bcd rule set`, `tempset`, legacy `set`/`tempset`
`booscooldowns.rule.get`	`/bcd rule get`
`booscooldowns.grant`	`/bcd grant cooldown`, `grant uses`
`booscooldowns.scheduleglobalreset`	`/bcd reset now`, `schedule`, `list`
`booscooldowns.validate`	`/bcd validate`
`booscooldowns.audit`	`/bcd audit`
`booscooldowns.diff`	`/bcd diff`
`booscooldowns.signs.{player,server}.{use,place}`	Use / place `[boosCooldowns]` signs

Group targeting

booscooldowns.<group-name> places the player in a non-default command group. Use with your permissions plugin (LuckPerms, PermissionsEx, etc.):

/lp user Alice permission set booscooldowns.vip true

🔌 PlaceholderAPI

Install PlaceholderAPI and the boos expansion registers automatically.

Placeholder	Value
`%boos_remaining_<cmd>%`	Formatted remaining cooldown (`"2h 15m"`)
`%boos_remaining_seconds_<cmd>%`	Raw integer seconds
`%boos_on_cooldown_<cmd>%`	`true` / `false`
`%boos_server_cooldown_<cmd>%`	Server-wide cooldown remaining
`%boos_uses_<cmd>%`	`"remaining/limit"` (or `∞` if no limit)
`%boos_uses_remaining_<cmd>%`	Raw integer remaining uses

Use underscores instead of spaces in command names – %boos_remaining_daily_claim% for /daily claim. Leading slash is optional.

You can also embed foreign placeholders inside plugin messages:

cooldown_message: "Wait &e%remaining%&r (balance: &a%vault_eco_balance%&r)"

🌐 Multi-server setup

All player state (cooldowns, limits, user preferences, audit log, scheduled resets) is shared automatically through the database. Point every server at the same MySQL/MariaDB and:

Cooldowns follow the player across the network
Server-wide cooldowns block every player everywhere
Scheduled resets fire consistently on the node that happens to trigger first

Command rules (the commands: section of config.yml) still live per-server – keep them in sync via git, rsync, symlink or deploy pipeline.

The plugin ships drift detection: each node hashes its config.yml on enable and on /bcd reload, writes it to config_version, and a periodic task warns you when peers disagree. /bcd diff shows the mismatch at a glance.

📡 For developers

API

BoosCooldownAPI api = BoosCooldownAPI.getInstance();
CommandData data = api.buildCommandData(player, "/kit");
if (data != null && !api.isOnCooldown(player, data)) {
    api.setCooldown(player, data);    // CompletableFuture<Void>
}

Consumers referencing BoosCooldownAPI at class-load time should declare loadbefore: [boosCooldowns] in their plugin.yml.

Events

CooldownEvent – player hit an active cooldown (cancellable)
WarmupEvent – warmup is starting or completing (cancellable)
CommandEvent – plugin is about to process a command (cancellable, set deny message)

💬 Support & community

Need help? Found a bug? Want to suggest a feature?

Discord: https://discord.gg/GFy7x62Jpd – quickest way to get help and chat with other admins
GitHub: https://github.com/LordBoos/boosCooldowns – source code, issue tracker, pull requests

For bug reports, please include:

Paper version (/version)
Full latest.log (or the relevant section with timestamps)
Your config.yml
/bcd validate output
/bcd diff output (multi-server only)

📊 Metrics

This plugin uses bStats to collect anonymous usage data. In addition to the default server metrics (player count, Java version, online mode, …) the plugin contributes these custom charts so the community can see how the plugin is actually used:

Storage backend (SQLite / MySQL) with drill-down to the driver version
Multi-node setups – how many admins share a DB across servers
Locale distribution (default_locale)
Feature toggles – confirmations, signs, action bar, boss bar, audit, refund-on-cancel
Detected integrations – Vault, PlayerPoints, PlaceholderAPI, WorldGuard, LuckPerms
Which plugin features admins actually enable (cooldowns, warmups, limits, prices, …)
Which warmup-cancel sources are wired up (move, damage, sneak, sprint, gamemode change)
Config scale buckets – how many command groups, how many configured commands, how many event triggers

You can opt out globally in plugins/bStats/config.yml.

📝 License & credits

Originally by LordBoos (in-game boosik).

boosCooldowns

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details

boosCooldowns

✨ Features

Core control

Player UX

Admin tooling

Advanced

Persistence

Developer

📦 Requirements

Optional integrations (soft-depend)

🚀 Installation

⚙️ Configuration essentials

Database

A command rule – everything available

Aliases

Event-based cooldown resets

Handling /plugin:command syntax

Global options

💬 Commands

Player commands

Administration

Diagnostics

Legacy aliases (still work for backwards compatibility)

🔑 Permissions

Player-level (default true)

Bypass permissions

Admin permissions (default op)

Group targeting

🔌 PlaceholderAPI

🌐 Multi-server setup

📡 For developers

API

Events

💬 Support & community

📊 Metrics

📝 License & credits

Handling `/plugin:command` syntax

Player-level (default `true`)

Admin permissions (default `op`)