A lightweight, accurate Minecraft plugin that tracks player playtime, integrates seamlessly with PlaceholderAPI, and provides a built-in rewards system with a claimable GUI.
- ⏳ Real-time Playtime Tracking - Accurately tracks how long each player has been on your server (updates every second!)
- 🎁 24+ Playtime Rewards - Milestone-based rewards that players can claim as they play more
- 📖 Pageable Rewards GUI - Easy-to-navigate interface with multiple pages for all rewards
- 🧾 Simple Commands - Intuitive
/playtimecommand for players and admin tools - 🔌 PlaceholderAPI Support - Integrates with popular plugins through placeholders
- 🛡️ AFK Protection - Prevents players from cheating by being AFK
- 💾 Efficient Data Storage - Lightweight flat-file storage with automatic saving
- ⚡ High Performance - Optimized code that won't slow down your server
- 🛡️ Reward Error Handling - Prevents reward spamming even when commands fail
- ⚙️ Flexible Configuration - Easily customize all rewards, GUI, and settings
- 🌍 Multi-Language Support - Supports 8 languages including English, Chinese, Russian, German, French, and more
- 🔧 Admin Tools - Reload configuration and debug mode for easier management
- 🏆 Leaderboard Support - Track and display top players with leaderboard placeholders
- ⏳ Real-time playtime tracking (saved + current session)
- 🧾
/playtimecommand:- Shows formatted playtime in
Xd Yh Zm As - Opens a GUI to claim playtime-based rewards
- Shows formatted playtime in
- 🎁 Reward System:
- Milestone-based claimable rewards (24 rewards included in current config, with more to be added over time)
- Supports commands (since most of the things are given by commands)
- Blocks duplicate claiming with tracked saves
- Player head support for GUI icons (e.g., custom heads, player skulls)
- Custom sound effects when claiming rewards
- Error handling for failed commands to prevent reward spamming
- Customizable Reward Information Display - Control what information is automatically shown on reward items with
disable-default-reward-informationconfig option
- 📖 Pageable Rewards GUI:
- Pagination support for large numbers of rewards
- Customizable slots per page
- Navigation buttons for moving between pages
- "More Rewards Coming Soon" item displayed on last page
- Fixed Navigation Bug - Resolved issue where navigation between pages was not working correctly in some cases
- 🧭 Navigation System:
- Previous/Next page buttons
- Close button to exit the GUI
- Customizable navigation button materials and names
- Optional custom head textures for navigation buttons
- 🛡️ AFK Protection:
- Prevents AFK farming of playtime
- Configurable interaction threshold and time window
- Tracks meaningful player interactions to validate activity
⚠️ Configuration Validation:- Detailed error logging for misconfigured rewards
- Detection and warning of nested reward configurations (indentation errors)
- Slot conflict detection for rewards on the same page
- 🔌 Full PlaceholderAPI support
- 📊 bStats integration for anonymous usage statistics
- 📁 Flat-file storage with autosave
- ⚙️ Performance optimized and easy to configure
- 🌍 Multi-language support:
- 8 languages supported (English, Chinese, Brazilian Portuguese, Russian, Filipino, German, French, Finnish)
- Easily extensible with custom language files
- Language setting in config.yml
- 🔧 Admin tools:
/playtime reloadcommand to reload configuration without restarting- Debug mode for troubleshooting with detailed logging
/playtime debugcommand to toggle debug mode
| Command | Description | Permission |
|---|---|---|
/playtime |
Shows playtime and rewards GUI | playtime.use |
/playtime add <player> <hours>h [<minutes>m] [<seconds>s] |
Add playtime to player | playtime.admin |
/playtime reset <player> |
Reset player's playtime and claimed rewards | playtime.admin |
/playtime reload |
Reload plugin configuration | playtime.admin |
/playtime debug [true/false] |
Toggle debug mode (shows additional logs) | playtime.admin |
PlayTimePulse provides comprehensive PlaceholderAPI integration with various categories of placeholders:
| Placeholder | Description |
|---|---|
%playtime_overall_formatted% |
Total time (saved + current), formatted like 2d 4h 30m 15s |
%playtime_formatted% |
Current session only, formatted |
%playtime_overall% |
Total time in seconds (saved + current) |
%playtime_saved% |
Saved playtime only (in seconds) |
%playtime_current% |
Current online session (in seconds) |
%playtime_seconds% |
Seconds part of total playtime |
%playtime_minutes% |
Minutes part of total playtime |
%playtime_hours% |
Hours part of total playtime |
%playtime_days% |
Days part of total playtime |
| Placeholder | Description |
|---|---|
%playtime_required% |
Time required for next logical unclaimed reward (either the next reward in progression or highest qualified unclaimed reward) |
%playtime_required_{rewardId}% |
Status of specific reward (Claimed/Ready/Qualified/Not Qualified) |
%playtime_time_left% |
Time left for next reward |
%playtime_time_left_{rewardId}% |
Time left for specific reward |
%playtime_claimable_rewards% |
Number of rewards that can be claimed right now |
%playtime_next_reward_name% |
Name of the next logical unclaimed reward |
| Placeholder | Description |
|---|---|
%playtime_top_1% |
1st place player in playtime leaderboard |
%playtime_top_2% |
2nd place player in playtime leaderboard |
%playtime_top_3% |
3rd place player in playtime leaderboard |
%playtime_top_4% |
4th place player in playtime leaderboard |
%playtime_top_5% |
5th place player in playtime leaderboard |
| ... | ... |
%playtime_top_10% |
10th place player in playtime leaderboard |
%playtime_leaderboard_position% |
Player's position in the leaderboard |
%playtime_overall_formatted%→2d 4h 30m%playtime_days%→2
%playtime_required%→5h 30m(time for next logical reward)%playtime_required_level_5%→Claimed(status of specific reward)%playtime_time_left_level_5%→2h 15m(time left for specific reward)%playtime_claimable_rewards%→3(number of claimable rewards)%playtime_next_reward_name%→Level 5(name of next reward)
%playtime_top_1%→Notch (12d 4h 30m)%playtime_top_5%→Dream (8d 2h 15m)%playtime_leaderboard_position%→5(player's position)
- In chat: "You've played for %playtime_overall_formatted%!"
- In holograms: "Next reward (%playtime_next_reward_name%) in: %playtime_time_left%"
- In scoreboards: "Leader: %playtime_top_1% | Your rank: #%playtime_leaderboard_position%"
- In reward lore: "&7Welcome &f%player_name%&7! You have played for &f%playtime_overall_formatted%&7."
-
Basic Playtime Display:
%playtime_overall_formatted%→2d 4h 30m%playtime_days%→2
-
Reward Status Tracking:
%playtime_required%→5h 30m(time for next logical reward)%playtime_required_level_5%→Claimed(status of specific reward)%playtime_time_left_level_5%→2h 15m(time left for specific reward)%playtime_claimable_rewards%→3(number of claimable rewards)%playtime_next_reward_name%→Level 5(name of next reward)
-
Leaderboard Integration:
%playtime_top_1%→Notch (12d 4h 30m)%playtime_top_5%→Dream (8d 2h 15m)%playtime_leaderboard_position%→5(player's position)
-
Integration Examples:
- In chat: "You've played for %playtime_overall_formatted%!"
- In holograms: "Next reward (%playtime_next_reward_name%) in: %playtime_time_left%"
- In scoreboards: "Leader: %playtime_top_1% | Your rank: #%playtime_leaderboard_position%"
- In reward lore: "&7Welcome &f%player_name%&7! You have played for &f%playtime_overall_formatted%&7."
-
Reward IDs:
- Use the exact ID from your config.yml
- Case-sensitive (level_5 ≠ Level_5)
- Replace spaces with underscores
-
Formatting:
- All time values are formatted as
Xd Yh Zm Ws - Empty values are omitted (e.g.,
2h 30sinstead of0d 2h 0m 30s)
- All time values are formatted as
-
Next Reward Logic:
%playtime_required%shows either:- The next reward in progression (requires more playtime than current)
- The highest reward player has qualified for but not claimed
- This provides more intuitive information than simply showing the lowest unclaimed reward
- 🎨 Gradient color support for formatted text
- 🌟 Particle effects for reward claiming
- 🐛 Debug mode for easier troubleshooting
- ➕ More features coming soon
config.yml: Define playtime milestones, rewards (commands), requirements, rewards icon/lore, and sound effects.- Each reward can have a custom sound when claimed using the
claimSoundparameter - Choose from over 400 Minecraft sounds (e.g.,
entity.player.levelup,block.note_block.pling) - All sounds play at standard volume (1.0) and pitch (1.0)
- Custom heads can be added using
headIdwith Base64 texture values - Specify which page a reward should appear on using the
pageparameter (starting from 0) - Navigation buttons can use custom player heads with
headIdparameter - GUI slots and slots per page are configurable
- AFK protection settings:
interaction-threshold: Minimum number of interactions required in the time windowtime-window-minutes: Time window in minutes to check for interactions
- Language settings:
language: Set the plugin language (en, zh, pt_BR, ru, fil, de, fr, fi)- Language files automatically copied to plugin directory for customization
- Debug mode:
debug: Enable/disable debug mode for additional logging
- Configuration validation:
- Automatic detection of nested reward configurations (indentation errors)
- Helpful warning messages for fixing configuration issues
- Slot conflict detection to prevent rewards from overlapping
- Each reward can have a custom sound when claimed using the
- Download the latest release
- Drop the
.jarfile into your/pluginsfolder - Restart the server
- Configure
config.ymlto define rewards / requirements. - (Optional) Install PlaceholderAPI for placeholders
- Minecraft:
1.21 up to 1.21.8 - Java:
21+ - Server: Paper / Pufferfish / Purpur (others need testing)
- (Optional) PlaceholderAPI
PlayTimePulse collects anonymous usage statistics through bStats. This helps us understand how the plugin is used and guides future development.
You can view plugin statistics at bStats.
To opt out of statistics collection, set enabled: false in the /plugins/bStats/config.yml file.
- 📬 Open an issue
- 💻 Discord
