Donut Orders

Players post buy orders for items, other players fulfill them for instant payment. No chest shops. No admin setup. Just a clean GUI and automatic economy.

---

How It Works

1. stash opens `/orders`, clicks stash, picks an item, types the quantity and price-per-unit in chat. 2. Funds are escrowed immediately — the buyer can't spend money they don't have. 3. stash browse the public marketplace, pick an order, drop their items into the delivery GUI, and get paid on the spot. 4. If an order only partially fills, the buyer's purchased items wait in a personal stash until they collect them. 5. Orders expire automatically after a configurable number of days — any unspent funds are refunded and any collected items stay in the stash ready to pick up.

---

Features

Buyer Side

- Order detail view for any material on the server's allowed-materials list - Order detail view — funds withdrawn on order creation, never double-spent - Order detail view — Active, Completed, Expired, or Cancelled - Order detail view — delivered items are stored safely server-side until you collect them, even if your inventory is full - Order detail view — stash items that don't fit on collection are dropped at your feet - Order detail view — cancel an active order at any time and receive the unspent balance back - Order detail view — see progress, price, expiry, and stash status from a single GUI

Seller Side

- Excess item return in a paginated marketplace GUI - Excess item return — dedicated 45-slot input grid; only the correct material is accepted - Excess item return — the GUI refuses incompatible items immediately with a clear message - Excess item return — deliver as many or as few items as you want; payment is per-item - Excess item return — concurrent delivery attempts on the same order are serialized server-side - Excess item return — any items beyond what the order needs are automatically returned to your inventory

Economy

- Powered by configurable tax — works with any Vault-compatible economy plugin (EssentialsX, CMI, etc.) - Optional configurable tax applied to seller payouts as an economy sink (disabled by default) - Refunds are always exact — no rounding errors

Admin & Configuration

- `messages.yml` — hot-reload `config.yml` and `messages.yml` without a server restart - Fully configurable `messages.yml` - Configurable `messages.yml` (days) - Configurable `messages.yml` — control exactly which items can be traded - All player-facing strings in `messages.yml` — fully translatable, supports `&` color codes and `#RRGGBB` hex colors

Technical

- SQLite + HikariCP — all scheduling uses regionised entity/global schedulers; also works on standard Paper/Spigot - SQLite + HikariCP — orders are persisted to a local database with WAL mode; no external database required - Async database I/O — DB reads and writes never block the main thread or region threads - Shaded & relocated dependencies — no classpath conflicts with other plugins

---

Commands

| Command | Description | Permission | |---|---|---| | `/orders` | Open your orders (aliases: `/order`, `/market`) | `donutorders.use` | | `/orders admin reload` | Reload config and messages | `donutorders.admin` |

---

Permissions

| Permission | Default | Description | |---|---|---| | `donutorders.use` | Everyone | Use `/orders` and all GUI features | | `donutorders.admin` | OP | Access admin sub-commands |

---

GUI Overview

| Screen | Purpose | |---|---| | Collect Stash | View your own buy orders, check status and stash, cancel orders | | Collect Stash | Pick an item, set amount and price via chat prompts | | Collect Stash | Paginated list of all active orders posted by any player | | Collect Stash | 45-slot grid to drop items into for a chosen order | | Collect Stash | Review the delivery before it is processed | | Collect Stash | Full info on one of your own orders with cancel and collect options | | Collect Stash | Take all delivered items out of your virtual stash |

---

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 # SQLite file in the plugin's data folder

allowed-materials: - DIAMOND - EMERALD - GOLD_INGOT - IRON_INGOT - NETHERITE_INGOT - COAL - LAPIS_LAZULI - REDSTONE - QUARTZ - AMETHYST_SHARD - GLOWSTONE_DUST - BLAZE_ROD - ENDER_PEARL - GHAST_TEAR - NETHER_STAR - ELYTRA - TOTEM_OF_UNDYING - SHULKER_SHELL - HEART_OF_THE_SEA - TRIDENT - OAK_LOG

... and any other Bukkit Material name

```

---

Requirements

| Requirement | Version | |---|---| | Paper / Folia | 1.20+ | | Java | 17+ | | Vault | Any compatible release | | Economy plugin | EssentialsX, CMI, or any Vault economy |

---

Installation

1. Drop `DonutOrders-1.0.0.jar` into your `plugins/` folder. 2. Make sure Vault and an economy plugin are installed. 3. Start the server — `config.yml` and `messages.yml` are generated automatically. 4. Edit `allowed-materials` and other options, then run `/orders admin reload`.

---

Support & Source

Open an issue or pull request on the project repository.