Box Plugin

The Skyblock/box plugin powering BurgerSMP, a multi-server SMP network: every player gets a personal "Box" — an isolated Overworld and Nether world pair — that can be visited, shared with friends, and upgraded. Boxes are distributed across a network of backend servers behind BungeeCord/Velocity, coordinated through Redis and persisted in MySQL, so the network can scale by adding more backend servers without any single one holding all the world data.

How it works

• One world per player, on demand. Each box's Overworld (<ownerUuid>) and Nether (nether-<ownerUuid>) are separate Slime Worlds, loaded lazily when a player needs them and unloaded again after a period of inactivity to keep memory usage bounded.
• Cross-server coordination via Redis. Which server currently hosts a given box, pending invitations, world-count-based load balancing, and reservations to avoid double-redirects are all tracked in Redis (via Redisson). A pub/sub topic (box-events) lets servers ask each other to create/load a box and get notified when it's ready, so a player can be redirected (via a BungeeCord plugin message) to wherever their box actually lives.
• MySQL as the source of truth. Box ownership, members, levels, and friend relationships are persisted relationally; Redis only holds transient/coordination state.
• Fake chunks via packet injection. A Netty handler intercepts outgoing chunk packets so a template world's terrain can be shown to players inside their box world without that terrain actually existing in the Slime World data — keeping each player's world file small.

Project structure

service/       business logic (box lifecycle, teleport/redirects, friends, upgrades, levels)
repository/    persistence — MySQL (box, user) and Redis (server assignments, invitations,
               reservations, world counts, cross-box-uuid lookups)
manager/       in-memory state: box cache, single-flight creation lock, player join routing
event/         cross-server Redis pub/sub message router
listener/      Bukkit event handlers (chat, portals, minions, permissions, player lifecycle)
packet/        Netty packet injection for fake chunk data
inventory/     GUI menus
command/       player-facing commands (ACF)
model/         domain types (Box, BoxType, BoxLevel, ...)

Testing

./gradlew test

Unit tests (JUnit 5 + Mockito) focus on the parts where correctness actually matters under concurrency and failure: the box-creation single-flight lock (verified under real multi-threaded contention), cross-server assignment matching, the least-loaded-server selection algorithm, member/index bookkeeping, and permission checks around box/minion access.

Features

• Personal Overworld + Nether box pair per player, created on first use
• Friend system: invite, accept, remove, leave, and visit friends' boxes
• Leveling/upgrade system tied to an economy plugin, with per-level world border size
• Cross-server load balancing (least-loaded server selection) and automatic redirects
• Minion integration (ownership-aware placement/removal, tied to box membership)
• LuckPerms-based permission checks (e.g. extra friend slots)
• PlaceholderAPI expansion

Running it

Requirements: Java 21, Paper 1.21.x, a running MySQL server and Redis instance, plus the companion plugins this depends on (database-api, redis-plugin, economy-plugin, LuckPerms; soft: PlaceholderAPI, TurboMinions).

./gradlew build

Produces a shaded jar (via Shadow) with third-party libraries relocated to avoid classpath collisions with other plugins.

config.yml:

server-id: "box1"       # this server's unique id in the network

servers:                 # every backend server box worlds can be created on
  - box1

database:
  host: "localhost"
  port: 3306
  database: "smp"
  username: "root"
  password: ""
  file: ""

currency: "money"        # currency key used by economy-plugin for box upgrades

lang.yml, levels.yml, and inventory.yml control player-facing messages, the box level/price table, and GUI layout respectively.

Commands

Command	Description
/box	Opens the box main menu
/box go	Teleport to your own box
/box rename <name>	Rename your box
/box friends add <target>	Invite a player to your box
/box friends remove <target>	Remove a friend from your box
/box friends leave <owner>	Leave a box you're a member of
/box friends accept	Accept a pending invite
/box visit <target>	Visit a friend's box
/upgrade	Open the box upgrade menu