LuckPermsTimeTracks

A Paper plugin that tracks player playtime and promotes players along a LuckPerms track based on how long they've played.

Status: early alpha (0.0.1-ALPHA). Playtime tracking, admin commands, and automatic rank promotion/demotion all work — see the Roadmap below for what's left.

Features

• Tracks each player's playtime, stored as LuckPerms user meta (playtime) — no separate database required.
• /playtime command to check your own playtime, with admin subcommands to set or add playtime for other players.
• Duration input accepts either plain seconds or compact duration strings (1h30m, 90m, 45s, ...).
• Automatically promotes/demotes players along a LuckPerms track based on playtime; promotion requirements are configured entirely through LuckPerms meta, no separate config format to learn.

Requirements

• Paper (or a Paper-based fork) 1.26.2 (api-version: '26.2')
• Java 25
• LuckPerms 5.5+ (required, joined on the classpath)

Installation

1. Download the built jar (or build it yourself, see below).
2. Drop it into your server's plugins/ folder alongside LuckPerms.
3. Restart the server.

Building from source

git clone <this-repository-url>
cd LuckPermsTimeTracks
./gradlew build

The shaded jar is produced by the build task under build/libs/.

Commands

Command	Description	Permission
/playtime	Shows your own playtime.	(none — any player)
/playtime set <player> <duration>	Sets a player's playtime to an exact value.	luckpermstimetracks.playtime.set
/playtime add <player> <duration>	Adds to a player's current playtime.	luckpermstimetracks.playtime.add

<duration> accepts either a plain number of seconds (3600) or a compact duration string combining days/hours/minutes/seconds (1d2h30m, 90m, 45s).

set/add currently only resolve online players.

Configuration

There is no config.yml yet — internal defaults (e.g. AFK cooldown) are currently hardcoded. Persisted configuration is on the roadmap below.

Roadmap

Core feature — playtime-based promotion

• Implement RankEvaluator / RankService to actually check a player's playtime against PlayTimeTrackGroup requirements and promote/demote them on the LuckPerms track.
• Schedule a recurring task (RankEvaluator) and hook player join (PlayerActivityListener) so rank evaluation runs automatically.
• Add a command to view a player's current track progress / requirements for the next rank.

Live playtime tracking

• Add PlayerJoinEvent / PlayerQuitEvent listeners to start/stop tracking and load/save playtime (PlayerActivityListener).
• Accrue playtime for online players automatically (ActivityTickTask runs every second and drives BuildInActivityPlayer).
• Periodically flush in-session playtime to LuckPerms meta instead of only on quit (PlaytimeFlushTask, scheduled every ~60s).

AFK / activity tracking

• Wire BuildInActivityProvider into join/quit events.
• Fix trackPlayers() re-checking every tracked player once per online player instead of once per tick.
• Consolidate the duplicate isPlayerAFK() stubs in ActivityService and ConfigService into one implementation.
• Fix performActivityCheck() never resetting lastActive while a player stood still, which re-added the full elapsed time every tick and compounded playtime/afktime without bound.
• Switch AFK movement detection from full Location equality to yaw/pitch-independent position checks, so idling while looking around still counts as AFK.
• Players already online when the plugin (re)loads aren't picked up — only PlayerJoinEvent starts tracking.

Configuration

• Load ActivityConfig (and future settings) from an actual config.yml instead of hardcoded defaults.

Commands & permissions

• Register luckpermstimetracks.playtime.set / .add permissions formally (with description/default) instead of relying on Bukkit's default op-only behavior for unregistered nodes.
• Add tab-completion for the <player> argument on set/add.
• Support setting/adding playtime for offline players.
• Add a read-only /playtime <player> variant to check another player's playtime.

Housekeeping

• Add automated tests (none exist yet).
• Remove the unused Group import in LuckPermsRankMetaProvider.
• Make LuckPerms group meta lookup (LuckPermsTrackGroup.getRequiredTotalPlaytimeFromMetaData) deterministic if duplicate meta nodes exist on a group.
• Remove the leftover debug player.sendMessage(...) calls in RankService.doPlayerGroupCheck() — they currently spam every online player on each rank-evaluation pass (~every 60s).

License

No license has been chosen yet.