🛒 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 |