🛒 DonutOrders

A player-driven buy order marketplace. No chest shops. No admin setup. Just a clean GUI and automatic economy.

Paper · Purpur · Folia · Spigot — 1.20.x / 1.21.x · Java 17+ · Requires Vault

---

How it works

1. A buyer opens /orders → New Order → picks a material → types quantity and price-per-unit in chat.
2. Funds are escrowed immediately — buyers can't spend money they don't have.
3. Sellers browse the marketplace, pick an order, drop items into the 45-slot delivery GUI → paid on the spot.
4. Partially-filled orders keep delivered items in a virtual stash until the buyer collects them.
5. Orders expire automatically after a configurable number of days; any unspent funds are refunded.

---

Features

Buyer side

• Post buy orders for any material on the server's allowed list
• Escrow system — funds are withdrawn on order creation, preventing double-spending
• Status tracking — Active, Completed, Expired, or Cancelled
• Virtual stash — delivered items are stored server-side even when your inventory is full
• Overflow protection — items that don't fit on collection are dropped at your feet
• Cancel & refund — cancel any active order and receive the unspent balance back

Seller side

• Browse all active orders in a paginated marketplace GUI
• 45-slot delivery grid — only the correct material is accepted
• Wrong-item rejection — the GUI refuses incompatible items immediately with a clear message
• Partial fills — deliver as many or as few items as you want; payment is per-item
• Anti-duplication lock — concurrent delivery attempts on the same order are serialised server-side
• Excess item return — items beyond what the order needs are automatically returned to your inventory

Economy

• Vault-powered — works with EssentialsX, CMI, and any Vault-compatible economy plugin
• Optional seller tax as an economy sink (disabled by default)
• Refunds are always exact — no rounding errors

Technical

• Full Folia support — all scheduling uses regionalised entity/global schedulers; also works on standard Paper/Spigot
• SQLite + HikariCP — orders persisted to a local WAL-mode database; no external DB required
• Fully async I/O — database reads and writes never block the main thread
• Shaded & relocated dependencies — no classpath conflicts with other plugins

---

GUI screens

Screen	Purpose
Main menu	Your orders / Browse market / Collect stash
Your orders	View active orders, cancel, collect stash
New order	Pick material, set amount and price via chat
Browse market	Paginated list of all active orders
Deliver items	45-slot grid accepting only the correct material
Order detail	Progress, price, expiry, stash status, cancel button

---

Commands

Command	Description	Permission
/orders	Open the orders menu (alias: /order, /market)	donutorders.use
/orders admin reload	Reload config and messages	donutorders.admin

Permissions

Permission	Description	Default
donutorders.use	All /orders commands and GUI features	Everyone
donutorders.admin	Access admin sub-commands	OP

---

Configuration

orders:
  max-per-player: 10        # Max simultaneous active orders per player
  default-expiry-days: 7    # Days before an unfilled order expires
  tax-percent: 0.0          # % of seller payout taken as economy sink (0 = off)

database:
  filename: donutorders.db

allowed-materials:
  - DIAMOND
  - EMERALD
  - GOLD_INGOT
  # ... any Bukkit Material name

All player-facing strings are in messages.yml — supports & colour codes and #RRGGBB hex colours.

---

Installation

1. Drop DonutOrders.jar into your plugins/ folder.
2. Make sure Vault and an economy plugin (e.g. EssentialsX) are installed.
3. Start the server — config.yml and messages.yml are generated automatically.
4. Edit allowed-materials and other options to your liking.
5. Run /orders admin reload to apply changes without a restart.

Requirements

Requirement	Version
Paper / Purpur / Folia / Spigot	1.20.x or 1.21.x
Java	17+
Vault	Any compatible release
Economy plugin	EssentialsX, CMI, or any Vault economy