PlayerLevels

A feature-rich Minecraft plugin that introduces player levels based on statistics tracking for Paper 1.21.3.

Features

Core Features

• Dynamic Leveling: Players gain levels as they play based on their in-game statistics
• Balanced Scaling: Higher levels require exponentially more XP
• Configurable Stats: Server owners choose which stats affect leveling
• Level Rewards: Automatically reward players when they reach certain levels
• PlaceholderAPI Integration: Use player level information in other plugins
• Leaderboard: View top players by level with pagination

Enhanced Features (v2.0)

• Awards System: Achievement-based rewards for milestones and ranks
• Progress Bar: Visual XP progress indicator with percentage
• Level-Up Announcements: Broadcast messages when players level up
• XP Boost System: Give players temporary XP multipliers
• Rank Display: See your server rank in /level command
• Database Support: SQLite or MySQL storage options

Requirements

• Paper 1.21.3 or newer
• PlaceholderAPI with Statistic Expansion
• Java 17+

Installation

1. Download the plugin JAR from the releases page
2. Place the JAR in your server's plugins folder
3. Restart your server
4. Make sure PlaceholderAPI is installed
5. Install the Statistic expansion: /papi ecloud download Statistic and /papi reload
6. Configure the plugin to your liking in plugins/PlayerLevels/config.yml

Configuration

The plugin is highly configurable. Here's a breakdown of the main configuration sections:

Basic Settings

settings:
  enable-plugin: true
  
  # Level-up announcements
  level-up-broadcast: true
  level-up-message: "&6%player% &ehas reached &aLevel %level%&e!"
  
  levels:
    base-xp: 100       # Base XP required for level 1
    xp-multiplier: 1.5 # XP increase per level (exponential scaling)

XP Boost System

xp-boost:
  multiplier: 2.0    # XP multiplier when boost is active

Statistics Configuration

You can configure which statistics count towards player levels and how much XP they provide:

statistics:
  1:
    statistic: "MINE_BLOCK"
    material: "STONE"
    xp-value: 5      # Gain 5 XP per stone mined
  2:
    statistic: "KILL_ENTITY"
    entity: "ZOMBIE"
    xp-value: 20     # Gain 20 XP per zombie killed

The statistic field should be a valid Minecraft statistic name. For statistics related to blocks, include the material field. For statistics related to entities, include the entity field.

Negative XP values can be used to penalize certain actions (like deaths).

Level Rewards

Configure rewards for reaching specific levels:

rewards:
  5:
    commands:
      - "give %player% diamond 1"
    message: "&aYou reached Level 5! Enjoy a diamond!"
  10:
    commands:
      - "give %player% diamond 5"
      - "eco give %player% 1000"
    message: "&eLevel 10! You got 5 diamonds and $1,000!"

Awards System (New!)

Create achievement awards that players can earn:

awards:
  level_10_pioneer:
    display-name: "&6Level 10 Pioneer"
    requirement: "level=10"
    message: "&a✨ Achievement Unlocked: &6Level 10 Pioneer&a!"
    commands:
      - "give %player% golden_apple 3"
  top_player:
    display-name: "&e&l⭐ #1 Player"
    requirement: "rank=1"
    message: "&6&l✨ You're #1! You earned the Top Player award!"
    commands:
      - "give %player% diamond_block 10"

Requirements can be:

• level=X - Player must reach level X
• rank=X - Player must reach rank X or better

Commands

Command	Description	Permission
/level	View your current level, rank, and progress	playerlevels.use
/level <player>	View another player's level	playerlevels.others
/level awards [player]	View your awards (or another player's)	playerlevels.use
/level reload	Reload the plugin configuration	playerlevels.admin
/level set <player> <level>	Set a player's level	playerlevels.admin
/level boost <player> <minutes>	Give a player temporary XP boost	playerlevels.admin
/leveltop [limit] [page]	Show the leaderboard of highest levels	playerlevels.leaderboard

Examples:

• /level - View your stats
• /level awards - View your awards
• /level Steve - View Steve's stats
• /level boost Steve 60 - Give Steve 1 hour of 2x XP
• /leveltop - Show top 10 players (page 1)
• /leveltop 20 - Show top 20 players (page 1)
• /leveltop 10 2 - Show top 10 players on page 2

Placeholders

The plugin provides the following PlaceholderAPI placeholders:

Player Placeholders

• %playerlevels_level%: Player's current level
• %playerlevels_xp%: Player's total XP points
• %playerlevels_xp_needed%: XP needed for next level
• %playerlevels_progress%: Visual progress bar with percentage
• %playerlevels_rank%: Player's server rank
• %playerlevels_awards%: Number of awards earned

Leaderboard Placeholders

These placeholders work without player context, making them ideal for holographic displays:

• %playerlevels_top_<position>_name%: Player name at position (e.g., %playerlevels_top_1_name%)
• %playerlevels_top_<position>_level%: Player level at position (e.g., %playerlevels_top_1_level%)
• %playerlevels_top_<position>_xp%: Player XP at position (e.g., %playerlevels_top_1_xp%)
• %playerlevels_top_<position>_rank%: Position number (e.g., %playerlevels_top_1_rank%)
• %playerlevels_total_players%: Total number of players in database

Hologram Example

Using DecentHolograms or similar plugins:

lines:
  - '&6&l⚔ Top Players ⚔'
  - '&e#1 &f%playerlevels_top_1_name% &7- &aLevel %playerlevels_top_1_level%'
  - '&e#2 &f%playerlevels_top_2_name% &7- &aLevel %playerlevels_top_2_level%'
  - '&e#3 &f%playerlevels_top_3_name% &7- &aLevel %playerlevels_top_3_level%'
  - ''
  - '&7Total Players: &f%playerlevels_total_players%'

Scoreboard Example

# In your scoreboard plugin config
lines:
  - '&6&lYour Stats'
  - '&eLevel: &f%playerlevels_level%'
  - '&eRank: &f#%playerlevels_rank%'
  - '%playerlevels_progress%'
  - '&eAwards: &f%playerlevels_awards%'

Storage

By default, the plugin uses SQLite for data storage. You can switch to MySQL by changing the configuration:

storage:
  type: "mysql"
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: ""

Permissions

Permission	Description	Default
playerlevels.use	Allows checking own level	true
`playerlevels.