playtime reward

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

🌟 Features

Core Features

• Time-Based Rewards - Automatically reward players based on their playtime
• Fully Configurable - Customize everything: items, amounts, intervals, messages
• Smart Storage System - Stores rewards when inventory is full for later collection
• Player Tracking - Tracks total playtime, session time, and reward history
• Rich Visual Feedback - Custom messages, sounds, particles, and actionbar countdowns
• Admin Tools - Comprehensive commands to manage and monitor player rewards
• Performance Optimized - Efficient tracking with auto-save system
• Permission-Based - Control who receives rewards and who has admin access

Advanced Features

• Inventory Full Protection - Never lose rewards! They're stored automatically
• Custom Item Support - Any Minecraft item with custom names and lore
• Actionbar Countdown - Players see countdown in their actionbar
• Welcome Messages - Greet players with playtime information on join
• AFK Prevention - Minimum online time requirement before earning rewards
• Maximum Storage Limit - Configurable limit to prevent abuse
• Data Persistence - 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. Download the latest PlaytimeReward-1.0.0.jar file
2. Stop your Minecraft server
3. Place the JAR file in your server's plugins folder
4. Start your server
5. The plugin will create a PlaytimeReward folder with default configuration
6. Configure 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

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):

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

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

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

reward:
  interval: 600
  item: EMERALD
  amount: 3

Example 2: Give 1 Netherite Ingot every hour

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)

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

Admin Commands

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 Examples

Give admin permission to a moderator:

# Using LuckPerms
/lp user Moderator permission set PlaytimeReward.admin true

Remove receive permission from a player:

# Using LuckPerms
/lp user Player permission set PlaytimeReward.receive false

Group permissions (in your permissions plugin):

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

• Check data: /ptr check <player>
• Reset player: /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 Material List
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

• Memory: Minimal (<5MB for typical server)
• CPU: Very light (single async task every second)
• Disk: 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