DeliverySystem
A complete, fully configurable delivery system for Paper Minecraft servers (1.20.x). Players pick up packages from sender NPCs, carry them to a receiver NPC within a time limit, and get rewarded with money (via Vault), vanilla experience, and internal "courier" experience with a full leveling system.
No hard dependency required — Vault is optional (soft-dependency) and only used for money rewards. NPCs are vanilla entities (Villagers by default), no third-party plugin needed.
✨ Features
- 6 mission types: normal, urgent, fragile, valuable, night, secret — each with its own reward multiplier, time limit and permission.
- 4 difficulty tiers (easy / normal / hard / extreme) affecting max distance, reward multiplier and experience gained.
- Tamper-proof packages identified through
PersistentDataContainer— never by name or lore, which stay purely cosmetic. - Persistent delivery NPCs, created/removed in-game, no external dependencies.
- Timer with bonuses/penalties: deliver early for a reward bonus, late for a penalty, or too late and the mission fails.
- Configurable cooldown between missions (bypassable via permission).
- Courier leveling system with experience and fully customizable rank titles.
- Stats, history and leaderboard, each with a dedicated in-game GUI.
- YAML or SQLite storage, fully swappable from config, 100% asynchronous I/O (nothing ever touches the main thread). Architecture ready for a future MySQL backend.
- Public API (
DeliverySystemAPI) so other plugins can create, assign, and complete deliveries, or read courier stats. - Solid lifecycle handling: logout, death, world change, server restart — nothing gets lost or corrupted.
📋 Commands
| Command | Description |
|---|---|
/delivery |
Open the available-missions menu |
/delivery accept <id> |
Accept a mission |
/delivery cancel |
Cancel your active mission |
/delivery info |
Show your active mission |
/delivery history [page] |
Your delivery history |
/delivery stats |
Your courier stats |
/delivery leaderboard |
Server-wide courier leaderboard |
/deliveryadmin create <sender|receiver> <id> [name] |
Create an NPC at your location |
/deliveryadmin remove <id> |
Remove an NPC |
/deliveryadmin give <player> <type> [difficulty] |
Manually assign a mission |
/deliveryadmin reload |
Reload configuration |
/deliveryadmin debug |
Show diagnostic info |
🔑 Permissions
deliverysystem.use— base usage (default: everyone)deliverysystem.admin— base admin access (default: op)deliverysystem.admin.create/.remove/.give/.reload/.debugdeliverysystem.bypass.cooldowndeliverysystem.mission.urgent/.fragile/.valuable/.night/.secret
Full list in permissions.md (update link once published).
⚙️ Requirements
- Paper 1.20.x or a compatible fork — vanilla Spigot is not supported (some Paper-only APIs are used).
- Java 17+
- Vault + a compatible economy plugin (optional, only needed for money rewards).
💾 Storage
- YAML — one file per data category, plus one file per player. Good for small servers.
- SQLite (default) — single-file database, pure-Java JDBC driver bundled in the jar, no native dependency. Recommended for most servers.
- MySQL — architecture is ready (shared JDBC pool interface), implementation coming in a future release.
📜 License
Released under the MIT License.
