PlayTimePulse

⏱️ PlayTimePulse

A lightweight, accurate Minecraft plugin that tracks player playtime, integrates seamlessly with PlaceholderAPI, and provides a built-in rewards system with a claimable GUI.

---

🌟 Main Features

- ⏳ Flexible Configuration - Accurately tracks how long each player has been on your server - 🎁 Flexible Configuration - Milestone-based rewards that players can claim as they play more - 📖 Flexible Configuration - Easy-to-navigate interface with multiple pages for all rewards - 🧾 Flexible Configuration - Intuitive `/playtime` command for players and admin tools - 🔌 Flexible Configuration - Integrates with popular plugins through placeholders - 🛡️ Flexible Configuration - Prevents players from cheating by being AFK - 💾 Flexible Configuration - Lightweight flat-file storage with automatic saving - ⚡ Flexible Configuration - Optimized code that won't slow down your server - 🛡️ Flexible Configuration - Prevents reward spamming even when commands fail - ⚙️ Flexible Configuration - Easily customize all rewards, GUI, and settings

📦 All Features

- ⏳ Real-time playtime tracking (saved + current session) - 🧾 `/playtime` command: - Shows formatted playtime in `Xd Yh Zm` - Opens a GUI to claim playtime-based rewards - 🎁 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 - 📖 Pageable Rewards GUI: - Pagination support for large numbers of rewards - Customizable slots per page - Navigation buttons for moving between pages - 🧭 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 - 🔌 Full PlaceholderAPI support - 📊 bStats integration for anonymous usage statistics - 📁 Flat-file storage with autosave - ⚙️ Performance optimized and easy to configure

---

🔧 Commands

| Command | Description | Permission | |------------------------------------------------|---------------------------------------------|----------------| | `/playtime` | Shows playtime and rewards GUI | playtime.use | | `/playtime add <player> <hours>h [<minutes>m]` | Add playtime to player | playtime.admin | | `/playtime reset <player>` | Reset player's playtime and claimed rewards | playtime.admin |

---

🧩 PlaceholderAPI Support

| Placeholder | Description | |--------------------------------|----------------------------------------------------------| | `%playtime_overall_formatted%` | Total time (saved + current), formatted like `2d 4h 30m` | | `%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) |

---

🧪 Future Plans

- 🎨 Gradient color support for formatted text - 🌟 Particle effects for reward claiming - 🐛 Debug mode for easier troubleshooting - ➕ More features coming soon

---

📁 Configuration

- `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 `claimSound` parameter - 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 `headId` with Base64 texture values - Specify which page a reward should appear on using the `page` parameter (starting from 0) - Navigation buttons can use custom player heads with `headId` parameter - GUI slots and slots per page are configurable - AFK protection settings: - `interaction-threshold`: Minimum number of interactions required in the time window - `time-window-minutes`: Time window in minutes to check for interactions

---

📥 Installation

1. Download the latest release 2. Drop the `.jar` file into your `/plugins` folder 3. Restart the server 4. Configure `config.yml` to define rewards / requirements. 5. (Optional) Install PlaceholderAPI for placeholders

---

✅ Requirements

- Minecraft: `1.21 up to 1.21.8` - Java: `21+` - Server: Paper / Pufferfish / Purpur (others need testing) - (Optional) PlaceholderAPI

---

📊 Statistics

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.

---

💬 Support

- 📬 Open an issue - 💻 Discord