ZTimer v1.4.1

ZTimer is a precision-tuned, storage-backed timer system built for competitive Minecraft gameplay — parkour, dungeons, questlines, race events, and anywhere you need millisecond-accurate timing with full admin control. Tracks active runs, best times, and per-timer leaderboards with PlaceholderAPI integration for live HUD/scoreboard display.


Features:

• Per-player active timers with start, stop, cancel, and reset operations
• Millisecond-accurate timing with configurable display format
• Per-timer leaderboards with caching for fast scoreboard/HUD reads
• Three storage backends out of the box: YAML (default), SQLite, and MySQL/MariaDB
• Full PlaceholderAPI expansion under the ztimer identifier with active, current, best, and leaderboard placeholders
• Server-global active check — %ztimer_active_global_<timerId>% works without a player context
• Smart start behavior — automatically replaces another active timer if a different one is started, with messaging that names the replaced timer
• Strict admin timer validation — rejects any timer ID not declared under timers in config.yml
• Async storage updates for timer saves, resets, and player name refreshes
• Configurable per-timer exit teleport locations with a global fallback
• logout-commands that fire when a player logs out mid-run
• relog-commands that fire when a player rejoins after logging out mid-run
• Confirmation prompts on global resets to prevent accidental wipes
• Separate messages.yml for all player and admin-facing text — fully customizable
• Automatic config and message migration on upgrade with timestamped backups
• Tab-completion for subcommands, timer IDs, selectors, and online player names
• Optional debug logging for start/stop events and database errors

Use Cases:

• Parkour courses with leaderboards displayed via scoreboard or HUD
• Dungeon clear-time tracking with per-player best times
• Race events with millisecond precision and live time display
• Questline speed-run tracking with persistent storage
• Competitive event servers needing global "is anyone running this map" indicators
• Network-wide leaderboard sharing using the MySQL backend

Commands:

• /ztimer start <timerId> <playerSelector> — Start a timer for target player(s)
• /ztimer stop <timerId> <playerSelector> — Stop a timer for target player(s)
• /ztimer reset <timerId> — Show the global reset confirmation prompt
• /ztimer reset <timerId> confirm — Reset all stored times for that timer
• /ztimer reset <timerId> <playerSelector> — Reset stored best times for target player(s)
• /ztimer cancel <timerId> — Cancel your own active timer
• /ztimer cancel <timerId> <playerSelector> — Cancel active timers for target player(s)
• /ztimer reload — Reload config.yml and messages.yml

Permissions:

• ztimer.admin — Full administrative access to all /ztimer commands
• ztimer.cancel.self — Allows a player to cancel their own active timer (default: true)

PlaceholderAPI Examples:

• %ztimer_active_<timerId>% — Returns true/false for the player's active state
• %ztimer_active_global_<timerId>% — Returns true if any player has the timer active (no player context needed)
• %ztimer_current_<timerId>% — Player's current elapsed time, formatted
• %ztimer_best_<timerId>% — Player's best time, formatted
• %ztimer_top_<position>_<timerId>_name% — Leaderboard player name at that position
• %ztimer_top_<position>_<timerId>_time% — Leaderboard formatted time at that position

Requirements:

• Paper 1.21.10+
• Java 17+
• PlaceholderAPI
• One storage backend: YAML (default), SQLite, or MySQL/MariaDB

Note: Changing storage.type requires a full server restart — runtime storage switching is not supported. ZTimer does not require Floodgate or Geyser; placeholders and timing are independent of proxy auth.