# Playtime Rewards **Playtime Rewards** is a configurable, server-side Fabric mod that turns player activity into automatic progression. It tracks every player’s online time, imports existing vanilla playtime, awards ranks, synchronizes LuckPerms groups, delivers item rewards, and provides a complete set of progression GUIs. The mod is designed for long-term SMPs, survival communities, whitelisted servers, and progression-focused Fabric servers. No client-side mod is required. --- # Features * Tracks every second a player is online * Imports existing vanilla playtime * Saves progress by UUID * Supports unlimited configurable ranks * Automatically detects rank milestones * Broadcasts rank-ups * Integrates with LuckPerms * Creates configured LuckPerms groups * Assigns and removes managed playtime groups * Preserves unrelated staff and donor groups * Supports configurable prefixes and priorities * Gives physical item rewards * Supports vanilla and modded item IDs * Prevents duplicate rewards * Retries missing or failed rewards * Drops inventory overflow safely * Includes manual reward recovery * Includes a personal profile GUI * Includes a rank and reward browser * Includes individual reward-detail screens * Includes a paginated leaderboard GUI * Includes multiple leaderboard sorting modes * Includes configurable rank icons * Includes configurable GUI icons and text * Supports classic colors and hex gradients * Includes administrative playtime commands * Remains completely server-side --- # Playtime Tracking Playtime Rewards records every second a player remains online. When a player joins for the first time after installation, the mod checks their vanilla Minecraft playtime statistic and imports it automatically. Players do not lose previous progress when the mod is installed on an established server. Player records are saved by UUID, so username changes do not reset: * Total playtime * Current rank * LuckPerms synchronization * Claimed rewards * Leaderboard position --- # Rank Progression Ranks are configured using required playtime in seconds. When a player reaches a milestone, the mod can automatically: 1. Update their current rank 2. Create the configured LuckPerms group 3. Remove older managed playtime groups 4. Assign the new group 5. Preserve unrelated groups 6. Apply the configured prefix 7. Deliver item rewards 8. Broadcast the rank-up 9. Save the player’s progress There is no hard limit on the number of ranks. --- # Default Ranks ## Nomad Required playtime: ```text 1 hour ``` Default display item: ```text minecraft:leather_boots ``` Default rewards: * 16 Bread * Iron Pickaxe * Iron Axe * Shield * 16 Torches Default LuckPerms group: ```text nomad ``` --- ## Noble Required playtime: ```text 6 hours ``` Default display item: ```text minecraft:golden_helmet ``` Default rewards: * 4 Diamonds * Golden Apple * 16 Experience Bottles * Name Tag * Saddle Default LuckPerms group: ```text noble ``` --- ## Veteran Required playtime: ```text 24 hours ``` Default display item: ```text minecraft:diamond_sword ``` Default rewards: * Totem of Undying * Enchanted Golden Apple * 32 Experience Bottles * Netherite Upgrade Smithing Template * 8 Diamonds Default LuckPerms group: ```text veteran ``` --- ## Legend Required playtime: ```text 25 days ``` Default display item: ```text minecraft:nether_star ``` Default rewards: * Withered Claim Anchor * Elytra * Nether Star * Shulker Box * 64 Experience Bottles Default LuckPerms group: ```text legend ``` The default Withered Claim Anchor reward uses: ```text goml:withered_claim_anchor ``` This item requires Get Off My Lawn to be installed. It can be replaced with any registered vanilla or modded item. --- # Personal Profile GUI Running: ```text /playtime ``` or: ```text /playtime me ``` opens a personal progression profile. The profile can display: * Player name * Total playtime * Current rank * Current rank icon * Next rank * Progress percentage * Time remaining * Leaderboard position * Rank and reward browser button * Claim rewards button * Leaderboard button The original text-based output remains available through: ```text /playtime text ``` --- # Ranks and Rewards GUI Running: ```text /playtime ranks ``` opens the rank browser. Each configured rank appears as its own clickable item. The rank list displays: * Rank name * Required playtime * Locked or unlocked status * Configurable rank icon * A prompt to open the reward page Clicking a rank opens its dedicated reward-detail screen. --- # Reward Detail Screens Every rank has its own reward page. The screen displays: * The rank’s configurable display item * Every configured reward * The real reward item icon * Configured item quantity * Claimed or unclaimed status * A button to return to the rank list Both vanilla and modded rewards are supported. If a rank has no item rewards, a configurable empty-state item and message are displayed. --- # Configurable Rank Icons Each rank can define its own visual item: ```json { "name": "Veteran", "seconds": 86400, "displayItem": "minecraft:diamond_sword", "luckPermsGroup": "veteran", "luckPermsPrefix": "&4[Veteran]&r ", "luckPermsPrefixPriority": 300, "rewards": [] } ``` The display item is used in: * The rank browser * The personal profile * The reward-detail header It is visual only and is not given as a reward. Any registered item can be used: ```json "displayItem": "minecraft:dragon_egg" ``` or: ```json "displayItem": "goml:withered_claim_anchor" ``` A global fallback is also available: ```json "rankDefaultDisplayItem": "minecraft:book" ``` Invalid item IDs fall back safely and generate a console warning. --- # Leaderboard GUI Running: ```text /playtime top ``` opens the graphical leaderboard. The leaderboard displays: * Overall position * Player name * Total playtime * Current rank * Special podium icons * The viewer’s own position * Page controls * Sorting controls * A button to return to the profile Offline players remain visible because entries are generated from saved player records. The classic text leaderboard remains available through: ```text /playtime top text ``` --- # Leaderboard Sorting The leaderboard can be sorted by: * Total playtime * Rank * Online players first * Alphabetical order Clicking the sorting control cycles between available sorting modes. The leaderboard supports multiple pages with up to 45 player entries per page. --- # Safe Read-Only GUIs All Playtime Rewards interfaces use protected display slots. Players cannot: * Remove GUI display items * Place inventory items into GUI slots * Shift-click items into a menu * Drag items across display slots * Use item-transfer actions on GUI items * Lose cursor items by clicking menu slots All profile, rank, reward, and leaderboard interfaces remain server-side. --- # Configurable GUI Text The GUI title, descriptions, buttons, icons, and status messages can be customized in `config.json`. Examples: ```json "leaderboardGuiTitle": "&6&lPlaytime Leaderboard", "leaderboardEntryText": "&6#{position} &f{player} &7| &e{playtime} &7| &b{rank}", "leaderboardYourPositionText": "&eYour position: &6#{position} &7| &e{playtime}", "rewardDetailGuiTitle": "&b&l{rank} Rewards", "rewardDetailClaimedText": "&aClaimed", "rewardDetailUnclaimedText": "&eUnclaimed" ``` Available placeholders include: ```text {player} {position} {playtime} {seconds} {rank} {nextRank} {remaining} {progress} {required} {status} {rewards} {claimed} {totalRewards} {count} {item} {page} {pages} {sort} ``` --- # Color Formatting Classic Minecraft color codes are supported: ```text &6 Gold &7 Gray &a Green &b Aqua &c Red &d Light Purple &e Yellow &f White ``` Formatting codes: ```text &l Bold &o Italic &n Underline &m Strikethrough &r Reset ``` Hex colors are supported: ```text &#fbbf24Playtime ``` Per-character hex colors can be used to create gradients: ```text &#fbbf24P&#fabc22l&#fab81fa&#f9b51dy ``` Example configured title: ```json "leaderboardGuiTitle": "&#fbbf24&nP&#fabc22&nl&#fab81f&na&#f9b51d&ny&#f9b21a&nt&#f8af18&ni&#f7ab15&nm&#f7a813&ne&r" ``` Adding `&r` resets active formatting. --- # LuckPerms Integration LuckPerms integration is optional. When installed, Playtime Rewards can: * Create configured playtime groups * Assign the correct group * Remove older managed playtime groups * Preserve unrelated groups * Apply configured prefixes * Apply configurable prefix priorities * Resynchronize players on join * Resynchronize players on rank-up * Resynchronize through refresh commands The mod only manages groups that appear in its own rank configuration. Staff, donor, builder, booster, and unrelated groups remain untouched. LuckPerms prefixes require a compatible chat, tab-list, or nametag formatter to appear visually. --- # Item Rewards Each rank can define an unlimited number of item rewards. Example: ```json "rewards": [ { "item": "minecraft:diamond", "count": 8 }, { "item": "minecraft:experience_bottle", "count": 32 } ] ``` The mod supports any item registered on the server. Vanilla example: ```text minecraft:elytra ``` Modded example: ```text goml:withered_claim_anchor ``` When a reward is granted, the mod: 1. Looks up the item registry ID 2. Creates the item stack 3. Inserts it into the player’s inventory 4. Drops overflow at the player’s position 5. Marks the individual reward as claimed 6. Saves player data A reward is only marked as claimed after successful delivery. --- # Duplicate Protection Each reward is tracked independently. If one item succeeds and another fails: * The successful reward remains claimed * The successful reward cannot duplicate * The failed reward remains unclaimed * The failed reward can be retried later Restarting, reconnecting, refreshing, or repeatedly claiming does not duplicate successfully delivered items. --- # Reward Recovery Players can check for missing rewards with: ```text /playtime claim ``` Operators can check another online player with: ```text /playtime claim ``` This is useful when: * Rewards were added after a player passed a rank * A modded item was temporarily unavailable * A previous delivery failed * A server restart interrupted delivery * A player believes they missed a reward --- # Player Commands ```text /playtime ``` Opens the personal profile. ```text /playtime me ``` Opens the personal profile. ```text /playtime text ``` Displays the classic text summary. ```text /playtime ranks ``` Opens the rank and reward browser. ```text /playtime top ``` Opens the leaderboard GUI. ```text /playtime top text ``` Displays the classic text leaderboard. ```text /playtime refresh ``` Refreshes playtime, rank, LuckPerms synchronization, and saved progression. ```text /playtime claim ``` Claims earned but unclaimed rewards. --- # Administrative Commands ```text /playtime admin set ``` Sets a player’s tracked playtime. ```text /playtime admin add ``` Adds tracked playtime. ```text /playtime admin remove ``` Removes tracked playtime. ```text /playtime admin reset ``` Resets progression and claimed reward history. ```text /playtime admin reload ``` Reloads the configuration. Supported time formats include: ```text 3600 6h 30m 2d12h 1d6h30m ``` --- # Configuration The configuration is stored inside the active world folder: ```text /config/playtime-rewards/config.json ``` Player data is stored in: ```text /config/playtime-rewards/players.tsv ``` After changing the configuration, fully restart the server unless using the administrative reload command for supported settings. Always back up configuration and player data before major updates. --- # Saving and Persistence Player data is saved: * On a configurable interval * When a player disconnects * When a player ranks up * When a reward is delivered * When a refresh is performed * When a claim succeeds * When the server shuts down Stored information includes: * UUID * Last known username * Total playtime * Current rank * Rank history * Claimed rewards --- # Requirements Required: ```text Minecraft 26.2 Fabric Loader 0.19.3 or newer Fabric API 0.156.0+26.2 or newer Java 25 ``` Optional: ```text LuckPerms Get Off My Lawn A compatible chat, tab-list, or nametag formatter ``` Only the server needs Playtime Rewards. Players do not need to install the mod. --- # Installation 1. Install Fabric Loader for Minecraft 26.2. 2. Install Fabric API. 3. Place Playtime Rewards in the server’s `mods` folder. 4. Optionally install LuckPerms. 5. Optionally install Get Off My Lawn. 6. Start the server. 7. Review the generated configuration. 8. Restart after editing configuration values. --- # Built for Long-Term Servers Playtime Rewards gives active players meaningful progression without introducing paid advantages. It is well suited for: * Survival multiplayer servers * Community SMPs * Whitelisted servers * Semi-vanilla servers * Long-term worlds * Modded Fabric servers * Progression-focused communities Reward loyalty. Recognize dedicated players. Give every hour a purpose.

Playtime Rewards

Compatibility

Minecraft: Java Edition

Platforms

Supported environments

Links

Tags

Creators

Details