Playtime Rewards

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:

1 hour

Default display item:

minecraft:leather_boots

Default rewards:

• 16 Bread
• Iron Pickaxe
• Iron Axe
• Shield
• 16 Torches

Default LuckPerms group:

nomad

---

Noble

Required playtime:

6 hours

Default display item:

minecraft:golden_helmet

Default rewards:

• 4 Diamonds
• Golden Apple
• 16 Experience Bottles
• Name Tag
• Saddle

Default LuckPerms group:

noble

---

Veteran

Required playtime:

24 hours

Default display item:

minecraft:diamond_sword

Default rewards:

• Totem of Undying
• Enchanted Golden Apple
• 32 Experience Bottles
• Netherite Upgrade Smithing Template
• 8 Diamonds

Default LuckPerms group:

veteran

---

Legend

Required playtime:

25 days

Default display item:

minecraft:nether_star

Default rewards:

• Withered Claim Anchor
• Elytra
• Nether Star
• Shulker Box
• 64 Experience Bottles

Default LuckPerms group:

legend

The default Withered Claim Anchor reward uses:

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:

/playtime

or:

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

/playtime text

---

Ranks and Rewards GUI

Running:

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

{
  "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:

"displayItem": "minecraft:dragon_egg"

or:

"displayItem": "goml:withered_claim_anchor"

A global fallback is also available:

"rankDefaultDisplayItem": "minecraft:book"

Invalid item IDs fall back safely and generate a console warning.

---

Leaderboard GUI

Running:

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

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

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

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

&6 Gold
&7 Gray
&a Green
&b Aqua
&c Red
&d Light Purple
&e Yellow
&f White

Formatting codes:

&l Bold
&o Italic
&n Underline
&m Strikethrough
&r Reset

Hex colors are supported:

&#fbbf24Playtime

Per-character hex colors can be used to create gradients:

&#fbbf24P&#fabc22l&#fab81fa&#f9b51dy

Example configured title:

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

"rewards": [
  {
    "item": "minecraft:diamond",
    "count": 8
  },
  {
    "item": "minecraft:experience_bottle",
    "count": 32
  }
]

The mod supports any item registered on the server.

Vanilla example:

minecraft:elytra

Modded example:

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:

/playtime claim

Operators can check another online player with:

/playtime claim <player>

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

/playtime

Opens the personal profile.

/playtime me

Opens the personal profile.

/playtime text

Displays the classic text summary.

/playtime ranks

Opens the rank and reward browser.

/playtime top

Opens the leaderboard GUI.

/playtime top text

Displays the classic text leaderboard.

/playtime refresh

Refreshes playtime, rank, LuckPerms synchronization, and saved progression.

/playtime claim

Claims earned but unclaimed rewards.

---

Administrative Commands

/playtime admin set <player> <time>

Sets a player’s tracked playtime.

/playtime admin add <player> <time>

Adds tracked playtime.

/playtime admin remove <player> <time>

Removes tracked playtime.

/playtime admin reset <player>

Resets progression and claimed reward history.

/playtime admin reload

Reloads the configuration.

Supported time formats include:

3600
6h
30m
2d12h
1d6h30m

---

Configuration

The configuration is stored inside the active world folder:

<world>/config/playtime-rewards/config.json

Player data is stored in:

<world>/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:

Minecraft 26.2
Fabric Loader 0.19.3 or newer
Fabric API 0.156.0+26.2 or newer
Java 25

Optional:

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.