ZVaults v1.0

ZVaults is a lightweight Paper plugin that adds configurable per-player cooldowns to Minecraft trial vaults. Every TRIAL_KEY and OMINOUS_TRIAL_KEY interaction is gated by a delay tracked per block position + player UUID, with three pluggable storage backends and a full admin command suite. ZVaults wraps the vanilla trial vault mechanic without replacing it — vanilla still dispenses loot, and cooldowns are only recorded after vanilla confirms the dispense, so missed interactions never eat a player's cooldown.


Features:

• Per-player, per-vault cooldown tracking keyed on world:x:y:z + UUID
• Separate configurable durations for normal and ominous vaults
• Deferred cooldown write — timestamp only commits after vanilla confirms loot dispense
• Automatic rewarded-player reset when a cooldown expires — no admin action needed to re-open
• Three storage backends out of the box: YAML (default), SQLite, and MySQL (all SQL paths via HikariCP)
• Admin force-unlock via sneak + right-click with a trial key — clears the vault's rewarded-players list
• Bypass permission that skips the cooldown check but still records timestamps — revoking bypass puts the player on cooldown from their last open
• Live cooldown tuning via /zvaults setdelay — no restart required
• Per-player and global cooldown wipes
• Fully configurable chat prefix, deny sound, and deny-sound pitch
• 9 branch-specific cooldown-remaining messages (minutes × seconds matrix with zero/one/many variants)
• Async prune task that automatically trims expired entries on a configurable interval
• Optional debug logging of every confirmed cooldown write
• Paper 26.1 native — registered via the new Paper command API

Use Cases:

• Prevent farming of trial vaults on survival or SMP servers
• Throttle ominous vault openings separately from normal vaults for balanced loot pacing
• Share cooldown state across a network with the MySQL backend
• Grant trusted players bypass while still tracking their timestamps for audit/revoke control
• Admin-reset a single player's cooldowns without affecting others via /zvaults resetplayer

Commands:

• /zvaults reload — Reloads config.yml and messages.yml without a restart
• /zvaults getdelay — Shows the current normal and ominous cooldown durations
• /zvaults setdelay <seconds> [ominous] — Live-tune cooldown durations
• /zvaults resetplayer <name> — Clears all cooldowns for a specific player
• /zvaults resetglobal — Wipes all stored cooldowns

Permissions:

• zvaults.use — Allows interacting with vaults (default: true)
• zvaults.bypass — Skips the cooldown check (timestamps are still recorded)
• zvaults.forceunlock — Allows sneak + right-click force-unlock on vaults (default: op)
• zvaults.admin.* — Access to all /zvaults admin commands

Requirements:

• Paper 26.1.2+ (api-version 26.1)
• Java 25+
• (MySQL backend only) A reachable MySQL/MariaDB server with a pre-created database