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

1. Download boosCooldowns.jar from the Hangar page.
2. Drop it into plugins/.
3. Start the server once – default config.yml is generated in plugins/boosCooldowns/.
4. 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:

1. Paper version (/version)
2. Full latest.log (or the relevant section with timestamps)
3. Your config.yml
4. /bcd validate output
5. /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

Licensed under the MIT License –
copyright © 2011–2026 LordBoos (in-game boosik) and contributors.

Originally by LordBoos (in-game boosik).