PlayerLevels

PlayerLevels Plugin - Enhanced Edition

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](https://github.com/PlaceholderAPI/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: "&aAchievement 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-Specific 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 (Perfect for Holograms!)

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.others | Allows checking other players' levels | op | | playerlevels.leaderboard | Allows viewing the leaderboard | true | | playerlevels.admin | Allows reloading config, setting levels, and giving boosts | op |

New Features Explained

Awards System

Awards are achievements that players unlock by meeting specific requirements. Unlike rewards (which are given every time a level is reached), awards are only granted once per player. Features: - Persistent storage - Awards are saved in the database - One-time unlock - Each award can only be earned once - Custom requirements - Set level or rank requirements - Display names - Customizable award names - View command - Players can see their earned awards Example Use Cases: - Milestone achievements (Level 10, 25, 50, 100) - Rank achievements (Top 1, Top 3, Top 10) - Special accomplishments

Progress Bar

The progress bar shows visual XP progress toward the next level: - Green filled bars (█) show completed progress - Gray empty bars (▒) show remaining progress - Percentage display shows exact progress - Works in chat and as a placeholder Placeholder: %playerlevels_progress%

Level-Up Anno