playtime reward

Discord

> A flexible playtime reward plugin that automatically rewards your players for their time spent on your server!

🌟 Features

Core Features

- ⏰ Permission-Based - Automatically reward players based on their playtime - 🎁 Permission-Based - Customize everything: items, amounts, intervals, messages - 💾 Permission-Based - Stores rewards when inventory is full for later collection - 📊 Permission-Based - Tracks total playtime, session time, and reward history - 🎨 Permission-Based - Custom messages, sounds, particles, and actionbar countdowns - 🛠️ Permission-Based - Comprehensive commands to manage and monitor player rewards - 💪 Permission-Based - Efficient tracking with auto-save system - 🔒 Permission-Based - Control who receives rewards and who has admin access

Advanced Features

- Tab Completion - Never lose rewards! They're stored automatically - Tab Completion - Any Minecraft item with custom names and lore - Tab Completion - Players see countdown in their actionbar - Tab Completion - Greet players with playtime information on join - Tab Completion - Minimum online time requirement before earning rewards - Tab Completion - Configurable limit to prevent abuse - Tab Completion - All data saved automatically and persists across restarts - Tab Completion - All commands support tab completion for better UX

---

📥 Installation

Prerequisites

- Paper or Spigot server running Minecraft 1.21+ - Java 17 or higher installed on your server

Steps

1. Reload the latest `PlaytimeReward-1.0.0.jar` file 2. Reload your Minecraft server 3. Reload the JAR file in your server's `plugins` folder 4. Reload your server 5. The plugin will create a `PlaytimeReward` folder with default configuration 6. Reload the plugin by editing `plugins/PlaytimeReward/config.yml` 7. Reload the plugin with `/ptr reload` or restart the server

Verification

After installation, verify the plugin is working: ``` > plugins [10:00:00 INFO]: Plugins (1): PlaytimeReward ```

---

⚙️ Configuration

The plugin generates a `config.yml` file in `plugins/PlaytimeReward/` with extensive customization options.

Basic Configuration

Reward Settings

```yaml reward:

Time in seconds between each reward

interval: 300 # 5 minutes (300 seconds)

Item to give as reward (use Minecraft material names)

Examples: DIAMOND, EMERALD, GOLD_INGOT, IRON_INGOT, NETHERITE_INGOT

item: DIAMOND

Amount of items to give per reward

amount: 1

Custom display name for the reward item (optional)

Use & for color codes (&a = green, &b = blue, etc.)

display-name: "&b&lPlaytime Reward"

Lore for the reward item (optional)

lore: - "&7Thank you for playing!" - "&7Earned from playtime" ```

Message Customization

All messages support Minecraft color codes (`&` format): ```yaml messages:

Message when player receives reward

reward-received: "&a&l✦ &aYou received &e{amount}x {item} &afor playing!"

Message when inventory is full

inventory-full: "&c&l⚠ &cYour inventory is full! &7Reward saved. Use &e/ptr claim &7to claim it later."

Message when claiming stored rewards

rewards-claimed: "&a&l✦ &aYou claimed &e{amount} &astored reward(s)!"

Message when no rewards to claim

no-rewards: "&c&l✦ &cYou don't have any stored rewards!"

Message for next reward countdown

next-reward: "&b&l⏰ &bNext reward in: &e{time}"

Welcome message on join

welcome: "&a&l✦ &aWelcome back! You'll earn rewards every &e{interval} &aof playtime!" ```

Feature Toggles

```yaml features:

Send welcome message when player joins

welcome-message: true

Show actionbar with time until next reward

actionbar-countdown: true

Play sound when reward is received

reward-sound: true sound: ENTITY_PLAYER_LEVELUP

Enable particle effects when giving reward

reward-particles: true particle: TOTEM_OF_UNDYING ```

Advanced Settings

```yaml advanced:

Auto-save player data (in minutes)

auto-save-interval: 5

Reset playtime on server restart (not recommended)

reset-on-restart: false

Maximum stored rewards per player (prevents abuse)

max-stored-rewards: 100

Minimum online time to start earning (in seconds)

Prevents AFK farmers at spawn

minimum-online-time: 60 ```

Configuration Examples

Example 1: Give 3 Emeralds every 10 minutes ```yaml reward: interval: 600 item: EMERALD amount: 3 ```

Example 2: Give 1 Netherite Ingot every hour ```yaml reward: interval: 3600 item: NETHERITE_INGOT amount: 1 display-name: "&6&l⭐ &ePremium Hour Reward &6&l⭐" lore: - "&7You've played for 1 hour!" - "&eThank you for your dedication" ```

Example 3: Quick rewards for testing (30 seconds) ```yaml reward: interval: 30 item: DIAMOND amount: 5 ```

Available Items

You can use any valid Minecraft material name. Common examples: - `DIAMOND`, `EMERALD`, `GOLD_INGOT`, `IRON_INGOT` - `NETHERITE_INGOT`, `ANCIENT_DEBRIS` - `ENCHANTED_GOLDEN_APPLE`, `GOLDEN_APPLE` - `ELYTRA`, `TOTEM_OF_UNDYING` - `EXPERIENCE_BOTTLE`, `BEACON`

See Spigot Material List for all available materials.

---

📜 Commands

All commands use the `/ptr` prefix (alias for `/playtimereward`).

Player Commands

| Command | Description | Permission | |---------|-------------|------------| | `/ptr info` | Displays your playtime statistics | None (default) | | `/ptr claim` | Claims your stored rewards | None (default) |

Admin Commands

| Command | Description | Permission | |---------|-------------|------------| | `/ptr reload` | Reloads the configuration | `PlaytimeReward.admin` | | `/ptr check <player>` | Views a player's statistics | `PlaytimeReward.admin` | | `/ptr reset <player>` | Resets a player's playtime data | `PlaytimeReward.admin` | | `/ptr save` | Manually saves all player data | `PlaytimeReward.admin` |

Command Details

`/ptr info`

Shows your personal playtime information: - Total playtime - Current session time - Time until next reward - Number of stored rewards (if any)

Example Output: ``` === Your Playtime Info === Total Playtime: 2 hours 45 minutes 30 seconds Current Session: 15 minutes 10 seconds Next Reward: 4 minutes 30 seconds Stored Rewards: 3 (Use /ptr claim) ```

`/ptr claim`

Claims all stored rewards that were saved due to full inventory.

Example Output: ``` ✦ You claimed 5 stored reward(s)! ```

`/ptr reload`

Reloads the plugin configuration without restarting the server.

Use Case: After editing config.yml

`/ptr check <player>`

Views detailed statistics for any player.

Example Output: ``` === Steve's Playtime Data === Total Playtime: 2 hours 45 minutes 30 seconds Time Since Last Reward: 4 minutes 20 seconds Stored Rewards: 3 Current Session: 15 minutes 10 seconds ```

`/ptr reset <player>`

⚠️ WARNING: Permanently resets all playtime data for a player. Cannot be undone!

`/ptr save`

Forces an immediate save of all player data to disk.

Use Case: Before server maintenance or manual file edits

---

🔐 Permissions

| Permission | Description | Default | |------------|-------------|---------| | `PlaytimeReward.receive` | Allows receiving playtime rewards | `true` (everyone) | | `PlaytimeReward.admin` | Allows using admin commands | `op` (operators only) |

Permission Examples

Give admin permission to a moderator: ```yaml

Using LuckPerms

/lp user Moderator permission set PlaytimeReward.admin true ```

Remove receive permission from a player: ```yaml

Using LuckPerms

/lp user Player permission set PlaytimeReward.receive false ```

Group permissions (in your permissions plugin): ```yaml groups: default: permissions: - PlaytimeReward.receive moderator: permissions: - PlaytimeReward.admin ```

---

📖 Usage Guide

For Players

Joining the Server

When you join, you'll see a welcome message (if enabled): ``` ✦ Welcome back! You'll earn rewards every 5 minutes of playtime! ```

Earning Rewards

Simply play on the server! Every configured interval (default 5 minutes), you'll automatically receive a reward: ``` ✦ You received 1x diamond for playing! [Sound and particle effects play] ```

Full Inventory

If your inventory is full, the reward is automatically stored: ``` ⚠ Your inventory is full! Reward saved. Use /ptr claim to claim it later. ```

Checking Your Progress

Use `/ptr info` to see: - How long until your next reward - Your total playtime - Any stored rewards waiting

Claiming Stored Rewards

When you have inventory space, use `/ptr claim` to collect all stored rewards at once.

For Admins

Monitoring Players

Check any player's statistics: ``` /ptr check PlayerName ```

Testing the System

Give yourself a test reward: ``` /ptr check YourName # Check your current data

(Wait for automatic reward or adjust config for testing)

```

Changing Configuration

1. Edit `plugins/PlaytimeReward/config.yml` 2. Run `/ptr reload` 3. Changes apply immediately

Managing Player Data

- Force save: `/ptr check <player>` - Force save: `/ptr reset <player>` (use cautiously) - Force save: `/ptr save` (before maintenance)

---

💾 Data Storage

Files Created

``` plugins/ └── PlaytimeReward/ ├── config.yml # Plugin configuration └── playerdata.yml # Player playtime data ```

Player Data Structure

The `playerdata.yml` file stores: - UUID-based player identification - Total playtime (in seconds) - Last reward timestamp - Stored (unclaimed) rewards - Session information

Data Persistence

Player data is automatically saved: - When a player disconnects - Every 5 minutes (configurable) - When the server stops - When `/ptr save` is executed

---

🔧 Troubleshooting

Common Issues

Issue: Players not receiving rewards

Solutions: 1. Check player has `PlaytimeReward.receive` permission 2. Verify config interval setting: `/ptr reload` 3. Check player data: `/ptr check <player>` 4. Ensure `minimum-online-time` requirement is met

Issue: Invalid material error in console

Solutions: 1. Check your `reward.item` setting in config.yml 2. Use valid Minecraft 1.21+ material names 3. See Solutions: 4. Reload config: `/ptr reload`

Issue: Commands not working

Solutions: 1. Verify permissions are set correctly 2. Check console for errors 3. Ensure player is online (for check/reset commands) 4. Try using the full command: `/playtimereward` instead of `/ptr`

Issue: Data not saving

Solutions: 1. Check file permissions on server 2. Look for errors in console 3. Manually trigger save: `/ptr save` 4. Verify plugin folder exists and is writable

Issue: Rewards given too frequently/slowly

Solutions: 1. Check `reward.interval` in config.yml (value is in seconds) 2. Use `/ptr reload` after changing 3. Example: 300 = 5 minutes, 600 = 10 minutes, 3600 = 1 hour

Getting Help

If you need additional support: 1. Check console logs for error messages 2. Verify your configuration is valid YAML syntax 3. Join our Discord server: https://discord.gg/cybycQ9wGp

---

📊 Performance

Resource Usage

- Network: Minimal (<5MB for typical server) - Network: Very light (single async task every second) - Network: Small data file (YAML format) - Network: No network operations

Optimization Tips

1. Adjust `auto-save-interval` based on player count 2. Set appropriate `max-stored-rewards` limit 3. Use `minimum-online-time` to reduce unnecessary checks 4. Consider longer intervals for high-population servers

Tested Performance

- ✅ Works efficiently with 100+ concurrent players - ✅ No noticeable TPS impact - ✅ Fast data saving (<100ms) - ✅ Minimal memory footprint

---

🚀 Roadmap

Potential features for future versions: - [ ] Multiple reward tiers based on total playtime - [ ] Discord webhook integration for milestones - [ ] MySQL/PostgreSQL database support - [ ] PlaceholderAPI integration - [ ] Per-world reward configuration - [ ] Reward multipliers for events/boosters - [ ] GUI for viewing statistics - [ ] Reward history tracking

🤝 Support

Bug Reports

If you find a bug, please report it with: - Plugin version - Server software and version - Steps to reproduce - Console errors (if any)

Feature Requests

Have an idea? Share it with details about: - What you want to achieve - How it would benefit users - Example use cases

Discord Community

Join our Discord server for support, updates, and community discussion: https://discord.gg/cybycQ9wGp

---

📜 License

This plugin is free to use for your server.

Terms

- ✅ Licensed for use on any server - ❌ Modification for personal purposes is prohibited - ❌ Redistribution, even with credit, is prohibited - ❌ Commercial resale is prohibited - ❌ No warranty or guarantee is provided

---

👨‍💻 Author

Yenith

---

⭐ Thank You!

Thank you for using PlaytimeReward! If you enjoy this plugin: - Share it with other server owners - Leave feedback and suggestions - Report bugs to help improve it - Consider supporting future development - Join our Discord community: https://discord.gg/cybycQ9wGp

---

Made with ❤️ for the Minecraft community

*Last Updated: 06 October 2025*