# 🛒 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 ```yaml 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 |