PlayTimeRewards

A server-side Minecraft Forge mod that rewards players and/or executes commands for time spent on your server.

Players earn configurable item and command rewards at playtime milestones. One-time rewards, repeating hourly bonuses, random loot, AFK pause, and a pending-claim queue for full inventories are included.

Side: Server-only (clients can join without the mod)

Features

• Tracks online playtime per player and persists it with the world
• One-time milestone rewards and repeating rewards every N hours
• Give all listed items, or pick one random item
• Run all listed console commands, or pick one random command
• Optional NBT on reward items
• Pending rewards if the player's inventory is full (/rewards claim)
• Optional AFK detection that pauses playtime
• Configurable messages with & color codes
• Server-side only: no client install required

Installation

1. Install Minecraft Forge for 1.20.1. Forge 47.3.0 or newer is recommended.
2. Drop the PlayTimeRewards jar into the server's mods folder.
3. Start the server once. Default configs are created at config/playtimerewards/.
4. Edit the configs and run /rewards reload, or restart the server.

Players do not need this mod on their client.

Commands

Command	Permission	Description
/rewards	Everyone	Show your playtime and pending rewards
/rewards claim	Everyone	Claim pending rewards that could not fit in your inventory
/rewards check <player>	OP level 2	View another player's playtime and pending reward count
/rewards reload	OP level 2	Reload settings.json and rewards.json
/rewards reset <player>	OP level 3	Delete a player's stored playtime and reward progress

Configuration

Configs live in config/playtimerewards/ and are generated on first launch.

settings.json

Option	Default	Description
playtimeCheckIntervalTicks	20	How often playtime is counted; minimum 20 ticks
rewardCheckIntervalTicks	1200	How often reward eligibility is checked; minimum 200 ticks
broadcastRewards	true	Broadcast when a reward is granted
broadcastMessage	&a{player} received: {reward}!	Server-wide reward message
rewardMessage	&6You earned the {reward} reward for {hours}h of playtime!	Message sent to the rewarded player
pendingRewardMessage	&eInventory full! Use /rewards claim to collect.	Shown when items cannot fit
afkEnabled	false	Pause playtime when a player is idle
afkTimeoutMinutes	5	Idle time before AFK starts
afkMessage	&7Playtime paused -- you are AFK.	Sent when AFK starts
afkReturnMessage	&aWelcome back! Playtime resumed.	Sent when AFK ends
saveIntervalMinutes	5	How often player data is saved
debug	false	Extra logging

Message placeholders: {player}, {reward}, {hours}, {minutes}. AFK is reset by movement, looking around, breaking/placing blocks, interacting, or opening a container.

rewards.json

Each tier defines a reward:

• name: unique display name
• requiredHours: threshold in hours
• repeating: false for one-time milestone, true for every N hours
• items: array of { "item": "minecraft:diamond", "count": 1, "nbt": "" }
• randomItem: if true, give 1 random item from the list
• commands: array of console command strings ({player} is replaced)
• randomCommand: if true, run 1 random command from the list

Default tiers: Starter Kit (1h), Hourly Random Bonus (every 1h), Veteran Reward (10h).

{
  "tiers": [
    {
      "name": "Starter Kit",
      "requiredHours": 1.0,
      "repeating": false,
      "randomItem": false,
      "randomCommand": false,
      "items": [
        { "item": "minecraft:iron_ingot", "count": 16, "nbt": "" },
        { "item": "minecraft:bread", "count": 32, "nbt": "" }
      ],
      "commands": [
        "say {player} has played for 1 hour and received a Starter Kit!"
      ]
    }
  ]
}

Storage

Per-world data is saved to world/playerdata/playtimerewards_playerdata.json.

License

MIT License (c) 2026 Flurben.