JustLevelBorder

by BinJustDev

What this project does

JustLevelBorder is a lightweight plugin for Minecraft Java Edition (1.21.x) that controls the World Border size based on player XP levels.

The world border is centered at (0.5, 0.5) in the main world and automatically grows or shrinks as players gain or lose XP levels. The border size follows a simple formula:

Border Size = 1 + (Level × blocks-per-level)

Depending on configuration, the border can be:

Driven by the highest current level of all players (even if they are offline), or

Fully shared, meaning all online players have the exact same XP bar (level and progress are synchronized in real time).

Level loss through death, enchanting, or anvil usage is detected, stored, and reflected in the world border size accordingly.

Why you should download this plugin

JustLevelBorder is ideal if you want:

• A progression-based survival challenge

• A server where XP directly controls exploration

• A minimal plugin with no databases and no dependencies

• Persistent progression that does not reset when players go offline

• Optional shared XP gameplay

The plugin is intentionally kept simple and transparent, making it easy to configure, extend, or audit.

Please read this before using the plugin:

• The world border is server-side and affects all players in the main world.
• Player levels are stored persistently in saved_levels.yml. This file represents the current levels, not all-time highs.
• When use-shared-levels is enabled: All online players share the same XP level and XP bar. The shared level initializes from the highest stored level, even if that player is offline.
• On death, players are reset to level 0 (if enabled), and the border may shrink.
• Border changes are animated smoothly (configurable).
• The plugin never logs level or border changes to the server console.
• Chat notifications for level loss are optional and can be toggled in-game.

The plugin currently affects only the overworld (first loaded world). I'm working on supporting the nether and end soon.

How to download and install

1. Download the JustLevelBorder.jar

2. Place the jar into your server’s plugins/ folder

3. Start or restart the server

4. Edit config.yml to your liking

5. Run /justlevelborder reload to apply changes

Commands

/justlevelborder
/levelborder

Shows a short explanation of the plugin.

/justlevelborder status

Displays the current plugin state (mode, highest level, border size, animation time, notifications).

/justlevelborder reload

Reloads config.yml and saved_levels.yml and immediately applies the values.

/justlevelborder notifications on|off

Enables or disables chat notifications for level loss.

Config

center-x: 0.5
center-z: 0.5

These values define the center point of the world border in the main world. 0.5, 0.5 centers the border exactly on the middle of the (0,0) block. You can change these values if you want the border centered elsewhere.

use-shared-levels: false

Controls how player XP levels are handled. false (default): Each player keeps their own XP level. The world border is based on the highest current level of all players, even if that player is offline.

true: All online players share the same XP level and XP progress bar. When one player gains or loses XP, everyone updates instantly. The shared level initializes from the highest stored level, preventing offline players from losing progress.

lose-progress-on-death: true

Controls what happens when a player dies. true (default): The player is reset to level 0 on death. This value is saved persistently. The world border may shrink depending on the new highest level.

false: The player keeps their level on death. No border change is triggered by death alone.

blocks-per-level: 2

Defines how much the world border grows per XP level. Higher values make progression faster; lower values make the challenge more challenging.

border-transition-seconds: 1

Controls how long the world border takes to resize. 0 → instant change 1 or higher → smooth animation in seconds This affects all border updates, including growth and shrinking.

notifications:
  enabled: true

Controls whether players see chat messages when someone loses XP levels.

true (default): Red chat messages are sent to all players. Messages explain who lost levels, why, and whether the border changed.

false: No chat messages are sent. Border logic still works normally.

causes:
anvil: "anvil"
enchanter: "enchanter"
dying: "dying"
other: "other"

These strings are used in notification messages to describe why a player lost levels. Examples: Using an anvil → "anvil"

Enchanting items → "enchanter"

Player death → "dying"

Any other reason → "other"

You can customize these freely.

PLEASE NOTE:

The plugin is actively being worked on, so please be aware that things may change in the future. If you encounter any issues please join my discord or report the bug to the GitHub issue tracker.

Thanks for playing JustLevelBorder. ❤️

BinJustDev out.