**Author:** RajaAditya **Website:** [rajaaditya.my.id](https://rajaaditya.my.id) **Version:** 2.0 **API:** Paper 1.21.x (including 1.21.10 & 1.21.11) --- ## Overview PlaytimeLevel is a playtime-based leveling plugin for Paper servers. Players earn levels automatically based on total time played — no grinding, no quests, just active server playtime. - Progressive level system (Level 1–100) - Fully configurable rewards per level (commands, messages, broadcast) - One-time claimable rewards — each reward can only be claimed once per player - Auto-claim on join — unclaimed rewards are given automatically when a player logs in - Auto-claim on level-up — scheduler detects level-ups and immediately gives rewards - Level color system — each level range has a configurable color via `config.yml` - GUI reward claiming with pagination support - PlaceholderAPI support with 20+ placeholders - EssentialsX integration with Bukkit Statistics fallback - Fully customizable messages via `messages.yml` - Auto-save player data with configurable interval --- ## Dependencies | Dependency | Type | Version | |------------|------|---------| | Paper / Spigot | Server | 1.21.x (including 1.21.10/11) | | Java | Runtime | 17 or higher | | EssentialsX | Required | 2.x (latest recommended) | | PlaceholderAPI | Optional | 2.11+ | --- ## Installation 1. Download `PlaytimeLevel-2.0.jar` and place it in your `plugins/` folder 2. Ensure **EssentialsX** is already installed and running 3. *(Optional)* Install **PlaceholderAPI** if you want placeholders in scoreboards, tab lists, etc. 4. Start or restart your server 5. The plugin will auto-generate `config.yml`, `messages.yml`, `gui.yml`, and `data.yml` inside `plugins/PlaytimeLevel/` 6. Edit the files as needed, then run `/level reload` to apply changes > No server restart is needed after editing configuration files — just run `/level reload`. --- ## File Structure ``` plugins/ └── PlaytimeLevel/ ├── config.yml # Main settings, rewards, placeholder format, level colors ├── messages.yml # All in-game messages ├── gui.yml # GUI layout and appearance └── data.yml # Player level & reward data (auto-managed, do not edit manually) ``` --- ## Level System ### How It Works Levels are calculated in real-time from the player's total playtime. A scheduler runs every N seconds (default: 60s) and recalculates each online player's level. If a level-up is detected, rewards are given automatically — no manual action required. > Rewards are given automatically in two situations: when the scheduler detects a level-up while the player is online, and when the player joins the server and has unclaimed rewards from previous sessions. ### Progressive Requirements Each level requires more playtime than the previous one, scaling from ~3.02 hours for Level 2 up to ~39.67 hours for Level 100, totalling ~1,440 hours to reach the maximum level. | Level Range | Hours Per Level | Cumulative Total | |-------------|-----------------|------------------| | 2 – 11 | 3.02 – 3.46 h | ~29 h | | 12 – 21 | 3.52 – 4.36 h | ~67 h | | 22 – 31 | 4.48 – 5.81 h | ~117 h | | 32 – 41 | 5.99 – 7.92 h | ~184 h | | 42 – 51 | 8.18 – 10.86 h | ~275 h | | 52 – 61 | 11.20 – 14.78 h | ~401 h | | 62 – 71 | 15.22 – 19.71 h | ~570 h | | 72 – 81 | 20.25 – 25.64 h | ~793 h | | 82 – 91 | 26.28 – 32.57 h | ~1,079 h | | 92 – 100 | 33.32 – 39.67 h | ~1,440 h | ### Milestones (at 8 hours/day) | Level | Total Hours | Estimated Time | |-------|-------------|----------------| | 10 | ~29 h | ~4 days | | 20 | ~67 h | ~8 days | | 30 | ~117 h | ~15 days | | 50 | ~275 h | ~34 days | | 70 | ~570 h | ~71 days | | 90 | ~1,079 h | ~135 days | | 100 | ~1,440 h | ~6 months | ### Max Level Default max level is **100**, configurable via `config.yml`: ```yaml level-system: max-level: 100 ``` Once a player reaches max level, their progress shows 100% and the formatted placeholder displays the `max-level-format` text instead of a number. --- ## Commands Main command: `/level` — Aliases: `/lvl`, `/playtimelevel` ### Player Commands | Command | Description | Permission | |---------|-------------|------------| | `/level` | View your own level, playtime, and progress | `playtimelevel.use` | | `/level info` | Detailed breakdown of your level progression | `playtimelevel.use` | | `/level rewards` | List all rewards — claimed, claimable, and locked | `playtimelevel.use` | | `/level claim ` | Claim the reward for a specific level | `playtimelevel.reward` | | `/level claim all` | Claim all unclaimed rewards you are eligible for | `playtimelevel.reward` | ### Admin Commands | Command | Description | Permission | |---------|-------------|------------| | `/level check ` | View another player's level and stats (must be online) | `playtimelevel.check.others` | | `/level reset ` | Reset a player's claimed reward data (works offline too) | `playtimelevel.reset` | | `/level reload` | Reload all config files without restart | `playtimelevel.reload` | ### Command Output Example ``` === Level Stats === Level: [ 25 ] | Playtime: 120.5 hours Progress: 67.3% ▊▊▊▊▊▊▊▊▊▊ To Level 26: 2.3 hours Required for Level 26: 5.15 hours ``` --- ## Permissions | Permission | Default | Description | |------------|---------|-------------| | `playtimelevel.use` | `true` | Use `/level` to view own stats | | `playtimelevel.reward` | `true` | Use `/level claim` to claim rewards | | `playtimelevel.check.others` | `op` | Use `/level check ` | | `playtimelevel.reload` | `op` | Use `/level reload` | | `playtimelevel.reset` | `op` | Use `/level reset ` | | `playtimelevel.*` | `op` | All permissions | --- ## Configuration ### config.yml ```yaml settings: # How often player data is auto-saved to data.yml (in seconds) data-save-interval: 300 # Use EssentialsX as the playtime source (recommended: true) # If false or unavailable, falls back to Bukkit Statistics use-essentials-playtime: true # How often the plugin checks online players for level-ups (in seconds) level-check-interval: 60 level-system: max-level: 100 rewards: enabled: true broadcast-enabled: true broadcast-message: "&e%player% &fhas reached &aLevel %level% &fand received special rewards!" reward-message: "§6§lREWARD! §eYou reached level %level% and received rewards!" already-claimed: "§cYou have already claimed the reward for level %level%" # Define rewards per level — add as many levels as you want levels: 1: commands: - "ac key give %player% Common 1" - "eco give %player% 1000" message: "&e&lLEVEL &a/ &fLevel 1 reward successfully claimed!" broadcast: false 10: commands: - "ac key give %player% Common 5" - "ac key give %player% Uncommon 1" - "eco give %player% 15000" message: "&e&lCONGRATULATIONS!! &fYou just reached &aLevel 10 &fand received special rewards!" broadcast: true # ... continue for each level up to 100 placeholder: level-format: "§e[ §6%level% §e] §f§l|" max-level-format: "§6§l[ §eMAX §6§l] §f§l|" level-color-format: "%color%[ %level% ] §f§l|" # Tab/tablist-specific format level-color-tab-format: "%color%[ %level% ]" max-level-tab-format: "§6§l[ §eMAX §6§l]" progress-bar: length: 10 filled: "§a▊" empty: "§7▊" time-format: hours: "§b%hours% §ehours" minutes: "§b%minutes% §eminutes" seconds: "§b%seconds% §eseconds" storage: type: "file" file: "data.yml" # Level Color Settings # Entries are checked top to bottom — first match wins. level-colors: - min: 1 max: 9 color: "§7" # Gray - min: 10 max: 19 color: "§f" # White - min: 20 max: 29 color: "§6" # Gold - min: 30 max: 39 color: "§b" # Aqua - min: 40 max: 49 color: "§a" # Green - min: 50 max: 59 color: "§3" # Dark Aqua - min: 60 max: 69 color: "§4" # Dark Red - min: 70 max: 79 color: "§d" # Pink - min: 80 max: 89 color: "§9" # Blue - min: 90 max: 99 color: "§5" # Purple - min: 100 max: 100 color: "§e" # Yellow ``` --- ### messages.yml All player-facing messages are stored here. Edit freely and run `/level reload` to apply. Standard Minecraft color codes (`§` or `&` prefix) are supported. ```yaml no-permission: "§cYou don't have permission!" player-not-found: "§cPlayer §e%player% §cnot found!" player-not-online: "§cPlayer §e%player% §cis not online!" reload-success: "§aConfiguration reloaded successfully!" max-level-reached: "§6§lMAX LEVEL! §eYou have reached the highest level!" reward-received: "§a§lREWARD! §eYou received level %level% rewards!" reward-already-claimed: "§cYou have already claimed reward for level %level%" reward-no-rewards: "§cNo rewards available for level %level%" reward-level-not-reached: "§cYou haven't reached level %level% yet! Your current level is %current_level%" reset-success: "§a✓ Successfully reset reward data for §e%player%" # Stats display — own player self-stats: | §e=== §6Level Stats §e=== §bLevel: §f%level% §bPlaytime: §f%playtime_hours% hours §bProgress: §f%progress_percent%% %progress_bar% §bTo Level §f%next_level%: §f%next_level_in% hours §bRequired for Level §f%next_level%: §f%required_for_next% hours %max_level_message% # Stats display — other player other-stats: | §e=== §6Level Stats §e%player% §e=== §bLevel: §f%level% §bPlaytime: §f%playtime_hours% hours §bProgress: §f%progress_percent%% %progress_bar% §bTo Level §f%next_level%: §f%next_level_in% hours §bRequired for Level §f%next_level%: §f%required_for_next% hours %max_level_message% ``` **Available placeholders in messages:** | Placeholder | Used In | |-------------|---------| | `%player%` | player-not-found, player-not-online, reset-success, other-stats | | `%level%` | reward-received, reward-already-claimed, reward-no-rewards, reward-level-not-reached | | `%current_level%` | reward-level-not-reached | | `%playtime_hours%`, `%progress_percent%`, `%progress_bar%`, `%next_level%`, `%next_level_in%`, `%required_for_next%`, `%max_level_message%` | self-stats, other-stats | --- ### gui.yml Controls the appearance of the reward claiming GUI. ```yaml claim-gui: title: "&6&lClaim Rewards" # Empty slot filler filler: material: GRAY_STAINED_GLASS_PANE name: " " # Unclaimed reward — player is eligible but hasn't claimed yet unclaimed-item: material: CHEST_MINECART name: "&e&lLevel &6&l%level%" lore: - "&7Click to claim this reward!" # Already claimed reward claimed-item: material: HOPPER_MINECART name: "&7Level &8%level%" lore: - "&aAlready claimed." # Locked reward — level not yet reached locked-item: material: CHEST_MINECART name: "&8Level %level%" lore: - "&cNot available yet." # Navigation row (row 6, slots 45–53) navigation: prev-page: slot: 45 material: ARROW name: "&e&l< Previous" lore: - "&7Page &e%current_page% &7of &e%total_pages%" claim-all: slot: 49 material: EMERALD name: "&a&lClaim All" lore: - "&7Claim all available rewards at once." - "&7Available: &a%claimable_count%" next-page: slot: 53 material: ARROW name: "&e&lNext >" lore: - "&7Page &e%current_page% &7of &e%total_pages%" ``` --- ## PlaceholderAPI Requires PlaceholderAPI to be installed. All placeholders use the prefix `%playtimelevel_`. | Placeholder | Returns | Example | |-------------|---------|---------| | `%playtimelevel_level%` | Current level as number | `25` | | `%playtimelevel_level_formatted%` | Level with color formatting | `[ 25 ] \|` | | `%playtimelevel_level_color%` | Minecraft color code for current level | `§6` | | `%playtimelevel_level_colored%` | Level number with its color code | `§625` | | `%playtimelevel_level_color_formatted%` | Level with auto color from config | `§6[ 25 ] §f§l\|` | | `%playtimelevel_level_color_tab_formatted%` | Level formatted for tab/tablist (no trailing pipe) | `§6[ 25 ]` | | `%playtimelevel_playtime_hours%` | Total playtime in hours | `120.5` | | `%playtimelevel_playtime_hours_formatted%` | Formatted playtime | `120.5 hours` | | `%playtimelevel_progress_percent%` | Progress to next level (%) | `67.3` | | `%playtimelevel_progress_bar%` | Visual progress bar | `▊▊▊▊▊▊▊▊▊▊` | | `%playtimelevel_next_level%` | Next level number | `26` | | `%playtimelevel_next_level_in_hours%` | Hours remaining to next level | `2.3` | | `%playtimelevel_next_level_in_hours_formatted%` | Formatted hours to next level | `2.3 hours` | | `%playtimelevel_required_for_next_level%` | Total hours required for next level | `5.15` | | `%playtimelevel_required_for_next_level_formatted%` | Formatted version | `5.2 hours` | | `%playtimelevel_total_required_current%` | Hours required to unlock current level | `4.87` | | `%playtimelevel_total_current%` | Cumulative hours needed for current level | `116.6` | | `%playtimelevel_total_current_formatted%` | Formatted version | `116.6 hours` | | `%playtimelevel_level_info%` | One-line level summary | `Level 25 (120.5/125.3h) - Need 2.3h to Level 26` | | `%playtimelevel_max_level%` | Max level configured | `100` | | `%playtimelevel_is_max_level%` | Whether player is at max level | `true / false` | | `%playtimelevel_total_max_level%` | Total hours to reach max level | `1440.0` | | `%playtimelevel_total_max_level_formatted%` | Formatted version | `1440.0 hours` | | `%playtimelevel_reward_claimed_%` | Whether reward for a level is claimed | `true / false` | **Usage examples:** Scoreboard: ``` Level: %playtimelevel_level_color_formatted% Progress: %playtimelevel_progress_bar% %playtimelevel_progress_percent%% Next in: %playtimelevel_next_level_in_hours%h ``` Tab list prefix: ``` %playtimelevel_level_color_tab_formatted% %player_name% ``` Check if a specific reward is claimed: ``` %playtimelevel_reward_claimed_10% → true (if level 10 reward was claimed) ``` --- ## Reward System ### How Rewards Work 1. Every `level-check-interval` seconds, the plugin checks if any online player has leveled up 2. When a player joins, all unclaimed rewards for their current level are given automatically 3. If a player has an unclaimed reward, it is given **automatically** without any player action 4. Players can also claim rewards manually with `/level claim ` or `/level claim all`, or via the GUI 5. Each reward can only be claimed **once per player** 6. Reward commands are executed from **console** with `%player%` replaced by the player's name ### Default Reward Tiers The default config includes rewards for all 100 levels with progressively better crate keys and money. Milestone levels (10, 20, 30, 40, 50, 60, 70, 80, 90, 100) have broadcast announcements enabled and bonus rewards. | Level Range | Crate Keys | Money | |-------------|------------|-------| | 1 – 9 | Common (1–4) | 1,000 – 9,000 | | 10 | Common 5 + Uncommon 1 | 15,000 | | 11 – 19 | Common 2 + Uncommon (1–3) | 11,000 – 19,000 | | 20 | Uncommon 5 + Rare 1 | 30,000 | | 21 – 29 | Uncommon 2 + Rare (1–3) | 21,000 – 29,000 | | 30 | Rare 5 + Epic 1 | 45,000 | | 31 – 39 | Rare 2 + Epic (1–2) | 31,000 – 39,000 | | 40 | Epic 3 + Legendary 1 | 60,000 | | 41 – 49 | Epic 2 + Legendary (0–1) | 41,000 – 49,000 | | 50 | Epic 5 + Legendary 2 | 80,000 | | 51 – 59 | Epic 2 + Legendary 1 | 76,500 – 88,500 | | 60 | Legendary 3 | 100,000 | | 61 – 69 | Legendary (1–3) | 91,500 – 103,500 | | 70 | Legendary 4 | 125,000 | | 71 – 79 | Legendary 2 | 106,500 – 118,500 | | 80 | Legendary 5 | 150,000 | | 81 – 89 | Legendary (2–3) | 162,000 – 178,000 | | 90 | Legendary 7 | 200,000 | | 91 – 99 | Legendary 3 | 182,000 – 198,000 | | 100 | Legendary 15 + Epic 10 | 500,000 | ### Adding a New Reward Level In `config.yml` under `rewards.levels`, add a new entry: ```yaml rewards: levels: 25: commands: - "eco give %player% 25000" - "give %player% diamond 10" message: "§d§lLEVEL 25 MILESTONE REWARD!" broadcast: true broadcast-message: "§e%player% §7reached §dLevel 25§7! Amazing!" ``` Then run `/level reload` — no restart needed. ### Reward Security Before giving any reward, the plugin verifies: - The reward system is enabled (`rewards.enabled: true`) - A reward is configured for that level - The player has actually reached that level - The player has not already claimed the reward --- ## Auto-Claim Behaviour | Trigger | When | Behaviour | |---------|------|-----------| | Scheduler | Every `level-check-interval` seconds | Detects level-up and immediately gives unclaimed rewards | | Player Join | 1 second after joining | Scans all eligible levels and gives any unclaimed rewards | | Manual Claim | On `/level claim` or GUI interaction | Player claims a specific reward or all rewards on demand | > The 1-second delay on join exists because EssentialsX playtime data may not be fully loaded the moment `PlayerJoinEvent` fires. The short delay ensures accurate playtime is available before level calculation runs. --- ## Data Storage Player data is stored in `plugins/PlaytimeLevel/data.yml`. **Stored per player:** | Field | Type | Description | |-------|------|-------------| | `level` | Integer | Last known level — used to detect level-ups between scheduler checks | | `lastPlaytime` | Long (seconds) | Last recorded playtime in seconds | | `claimedRewards` | List\ | List of level numbers whose rewards have been claimed | Data is saved automatically every `data-save-interval` seconds (default: 5 minutes), and also immediately on level-up, reward claim, and when the plugin is disabled. > **Warning:** Do not edit `data.yml` manually while the server is running. Changes will be overwritten by the next auto-save. --- ## Playtime Source The plugin uses a two-tier fallback system to retrieve playtime. ### Tier 1 — EssentialsX (Primary) Hooks into EssentialsX via the `IEssentials` API and calls `user.getPlaytime()`. Returns playtime in milliseconds, converted to seconds internally. Recommended because EssentialsX tracks playtime accurately across sessions. ### Tier 2 — Bukkit Statistics (Fallback) Used automatically if EssentialsX is not installed, the hook fails, or `use-essentials-playtime` is set to `false`. Reads `player.getStatistic(Statistic.PLAY_ONE_MINUTE)` which returns ticks, divided by 20 to get seconds. This value may differ slightly from EssentialsX playtime. ### Checking Which Source Is Active Check your server console on startup: ``` [PlaytimeLevel] Successfully hooked into EssentialsX! ``` or ``` [PlaytimeLevel] EssentialsX not found! Using Bukkit statistics for playtime. ``` --- ## FAQ **A player's level is not updating.** The plugin checks every `level-check-interval` seconds (default: 60). Wait up to a minute after the player's playtime increases. If it still does not update, check that EssentialsX is running and the hook succeeded in the startup logs. **Rewards are not being given automatically on level-up.** Check that `rewards.enabled: true` in `config.yml`. Verify the reward is defined for the exact level number and that the player's level actually changed during the last check cycle. Check the console for any error messages. **The player joined but unclaimed rewards were not given.** Check the console for a line like `Auto-claimed N unclaimed reward(s) for on join.` If absent, verify the player's level is correctly calculated after login. **Can I change the total hours required to reach Level 100?** Yes, but it requires editing the `LEVEL_REQUIREMENTS` array in `LevelManager.java` and recompiling. The current values total ~1,440 hours (~6 months at 8 hours/day). **Can I add more than 100 levels?** Change `level-system.max-level` in `config.yml`. Levels beyond 100 will use a fallback of 20 hours per level since the requirements array only covers up to 100. **Does `/level reload` also reload `data.yml`?** No. `/level reload` only reloads `config.yml`, `messages.yml`, and `gui.yml`. Player data in `data.yml` is managed in memory and saved automatically. **Can I reset a player who is offline?** Yes. `/level reset ` works for both online and offline players as long as they have played on the server before. **PlaceholderAPI placeholders are not working.** Make sure PlaceholderAPI is installed and enabled. Check the startup log for `[PlaytimeLevel] PlaceholderAPI expansion registered successfully!`. If it says "Failed to register", try running `/papi reload` then `/level reload`. **How do I change the level colors?** Edit the `level-colors` section in `config.yml`. Each entry defines a level range (`min`–`max`) and a color code. Run `/level reload` after saving. **How do I use the tab list placeholder without the trailing pipe?** Use `%playtimelevel_level_color_tab_formatted%` instead of `%playtimelevel_level_color_formatted%`. The tab variant omits the `§f§l|` suffix so it looks cleaner in tab lists.

RA-PlaytimeLevel