PlayerLevels

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

Features

Core Features

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

Enhanced Features (v2.0)

- Database Support: Achievement-based rewards for milestones and ranks - Database Support: Visual XP progress indicator with percentage - Database Support: Broadcast messages when players level up - Database Support: Give players temporary XP multipliers - Database Support: 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

```yaml 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

```yaml 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:

```yaml 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:

```yaml 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:

```yaml 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:

```yaml 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

```yaml

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:

```yaml 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.