NPC shop plugin for Paper 1.21+
Create shops, attach them to NPC vendors, and let players buy, sell, or barter — all through a clean in-game GUI with no YAML editing required.
| Feature | Description |
|---|---|
| Custom NPC vendors | Spawn vendors with custom skins, holograms, and equipment. No Citizens dependency, but it's supported. |
| Three trade modes | Buy, sell, and item-for-item barter — all configurable per listing. |
| Multi-economy | Works with Vault, GemsEconomy, CoinsEngine, and PlayerPoints out of the box. |
| In-game editor | Create and manage catalogs, listings, and vendors entirely in-game. |
| Quotas | Limit how many times a player can buy an item, with optional auto-reset timers. |
| Sales & discounts | Apply discounts to individual items or entire catalogs, with time-window scheduling. |
| Directives | Run console or player commands when a player completes a purchase (ranks, kits, crate keys, etc.). |
| Barter mode | Accept items instead of currency — define exactly what to take and what to give. |
| Bulk buy/sell | Shift-click for a quantity selector with smart presets. |
| Transaction log | Every buy, sell, and barter is written to a plain-text log for auditing. |
| Folia support | Thread-safe and Folia-compatible out of the box. |
| Citizens integration | Link vendors to Citizens NPCs if you prefer. |
| dtlTraders migration | One-click import from dtlTraders and dtlTradersPlus. |
- Paper 1.21+ or Folia 1.21+
- Java 21
- PacketEvents — required for vendor NPCs
- One of: Vault + EssentialsX, GemsEconomy, CoinsEngine, or PlayerPoints
- Drop the JAR into your
plugins/folder - Install PacketEvents if you haven't already
- Start the server — a default config will generate
- Run
/tradersin-game to get started
See docs/installation.md for a full setup walkthrough.
# Clone the repo
git clone https://github.com/JimSpecter/SovereignTraders.git
cd SovereignTraders
# Build (obfuscated with ProGuard)
./gradlew buildFree
# Development build (unobfuscated)
./gradlew shadowFreeJar
# Spin up a local test server
./gradlew runServerFreeThe test server task downloads Paper automatically and pre-installs VaultUnlocked, EssentialsX, and PacketEvents. Drop any additional plugin JARs (Citizens.jar, GemsEconomy.jar, etc.) in the project root and they'll be picked up automatically.
| Topic | |
|---|---|
| Installation | Getting the plugin running |
| Commands & Permissions | Full command and permission reference |
| Configuration | config.yml walkthrough |
| Catalogs & Listings | How shops and items work |
| GUI Customization | Customizing every GUI |
| Vendors | Setting up NPC vendors |
| Economy Providers | Supported economy plugins |
| Quotas | Purchase limits and resets |
| Sales | Discounts and time-window scheduling |
| Directives | Command execution on purchase |
| Barter Mode | Item-for-item trading |
| Citizens Integration | Using Citizens NPCs as vendors |
| Migration | Importing from dtlTraders |
| FAQ | Common questions |
See CONTRIBUTING.md. TL;DR: fork, make a focused change, ensure ./gradlew check passes, then open a PR.
Source-available under the PolyForm Noncommercial License 1.0.0. You can read, learn from, and modify the code for noncommercial purposes. The author retains all commercial distribution rights.