Playtime Rewards

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.