boosCooldowns

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

Optional integrations (soft-depend)

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

🚀 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

Administration

Diagnostics

Legacy aliases (still work for backwards compatibility)

🔑 Permissions

Player-level (default true)

Bypass permissions

Admin permissions (default op)

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.

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).