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 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 Announcements

When a player levels up, the server can broadcast a message to all players:

• Configurable message format
• Can be enabled/disabled
• Variables: %player% and %level%

XP Boost System

Admins can give players temporary XP boosts:

• Multiplies all XP gained during the boost period
• Configurable multiplier (default 2.0x)
• Duration in minutes
• Active boost indicator in /level command

Command: /level boost <player> <minutes>

Rank Display

Players can see their server-wide rank:

• Shows in /level command
• Available as placeholder: %playerlevels_rank%
• Updates automatically
• Shows in leaderboard if not in top list

Data Migration

Good News! The enhanced version is 100% backward compatible. If you're upgrading from an older version:

✅ All existing player data is preserved ✅ No manual migration needed ✅ New awards table is created automatically ✅ Existing levels and XP remain unchanged

Simply replace the old JAR with the new one and restart your server!

Performance Optimization

The plugin is designed for efficiency:

• Async Operations: All database queries run asynchronously
• Caching: Player data is cached in memory
• Batch Updates: Data is saved in batches to reduce database load
• Optimized Queries: Efficient SQL queries with proper indexing

Troubleshooting

PlaceholderAPI not working

1. Ensure PlaceholderAPI is installed: /papi version
2. Install Statistic expansion: /papi ecloud download Statistic
3. Reload PAPI: /papi reload
4. Check placeholder format: %playerlevels_level% (not %player_level%)

Awards not being granted

1. Check award requirements in config
2. Verify database connection
3. Check console for errors
4. Test with /level awards command

XP not updating

1. Verify statistics are configured correctly
2. Check if plugin is enabled: enable-plugin: true
3. Reload config: /level reload
4. Check for conflicting plugins

Database connection issues

SQLite:

• Ensure plugins folder has write permissions
• Check if playerlevels.db exists in plugin folder

MySQL:

• Verify host, port, username, and password
• Ensure MySQL server is running
• Check if database exists
• Grant proper permissions to MySQL user

API for Developers

Other plugins can interact with PlayerLevels:

// Get the plugin instance
PlayerLevels plugin = (PlayerLevels) Bukkit.getPluginManager().getPlugin("PlayerLevels");

// Get player data
PlayerLevels.PlayerData data = plugin.getPlayerData(player.getUniqueId());
int level = data.getLevel();
double xp = data.getXp();

// Get player rank
int rank = plugin.getPlayerRank(player.getUniqueId());

// Set player level
plugin.setPlayerLevel(player.getUniqueId(), player.getName(), 50);

// Give XP boost (duration in minutes)
plugin.giveXpBoost(player.getUniqueId(), 60);

// Check if player has active boost
boolean hasBoos = plugin.hasActiveXpBoost(player.getUniqueId());

// Get player awards
List<String> awards = plugin.getPlayerAwards(player.getUniqueId());

Planned Features

• GUI for leaderboard and player stats
• Custom XP events (quests, minigames)
• Level-based permissions
• Multi-language support
• Statistics tracking and graphs
• Daily/weekly challenges
• Party/Guild level bonuses

Support

• Issues: Report bugs on GitHub
• Discord: Join our community server
• Wiki: Full documentation available

Credits

• Author: flow258
• Contributors: Community members
• Dependencies: PlaceholderAPI

---

Changelog

Version 2.0.0 (Enhanced Edition)

• Added Awards System with persistent storage
• Added visual progress bar
• Added level-up broadcast announcements
• Added XP boost system for players
• Added server rank display
• Added player_awards database table
• Improved /level command with rank and awards display
• Enhanced leaderboard with better formatting
• Added new placeholders: progress, rank, awards
• Bug fixes and performance improvements

Version 3.0.0 (Initial Release)

• Dynamic player leveling based on statistics
• Configurable XP values for statistics
• Level milestone rewards
• Leaderboard with pagination
• PlaceholderAPI integration
• SQLite and MySQL support
• Fully configurable system

---

Enjoy the enhanced PlayerLevels experience!