DonutOrders is a standalone buy-order marketplace plugin for Paper and Folia servers running Minecraft 1.20+. Players can post orders for items they want to buy, escrow the required funds automatically, and let other players fulfill those orders for instant payment. No chest shops and no admin-created marketplace are required — everything is handled through a clean GUI with Vault-compatible economy integration.

Features

Feature	Description
Player Buy Orders	Players can create public buy orders for allowed materials with custom quantities and prices
Escrow System	Funds are withdrawn when an order is created so buyers cannot spend money already committed to an order
Marketplace Browser	Sellers can browse active orders through a clean paginated GUI
Instant Seller Payments	Sellers receive payment immediately when valid items are delivered
Partial Order Fills	Orders can be fulfilled gradually by one or multiple deliveries
Virtual Stash	Purchased items are stored safely until the buyer is ready to collect them
Vault Economy Support	Works with Vault-compatible economy plugins such as EssentialsX, CMI, and other supported providers
Configurable Tax	Optional seller payout tax can be used as an economy sink
SQLite & HikariCP	Persistent local SQLite storage with HikariCP connection management
Paper & Folia Support	Designed for modern Paper and Folia servers with region-aware scheduling
Async Database Operations	Database reads and writes are handled asynchronously to avoid blocking server threads
Customizable Experience	Configure order limits, expiry duration, allowed materials, messages, colors, and marketplace behavior

How It Works

DonutOrders creates a player-driven marketplace centered around buy orders rather than traditional chest shops or item listings.

The process is simple:

1. Buyer opens /orders, selects New Order, chooses an item, and enters the quantity and price-per-unit through chat prompts.
2. The required funds are immediately placed into escrow.
3. Sellers browse active orders, select one, and deliver matching items through the delivery GUI.
4. Sellers are paid instantly for accepted items.
5. Purchased items are stored in the buyer's personal stash until collected.
6. Unfilled orders expire automatically after the configured duration, refunding any remaining escrow balance.

Buyer Experience

Buyers can create and manage orders directly through the GUI.

Buyer Features

• Post buy orders for materials allowed by the server
• Choose the desired quantity
• Set a price per item
• Track Active, Completed, Expired, and Cancelled orders
• View order progress and remaining quantity
• Cancel active orders
• Receive exact refunds for unspent escrow funds
• Collect delivered items from a personal virtual stash
• Keep delivered items safe even when the player's inventory is full

When collecting stash items, anything that cannot fit in the player's inventory is safely dropped at their feet.

Seller Experience

Sellers can browse active demand across the server and fulfill orders without creating their own shop.

Seller Features

• Browse all active orders in a paginated marketplace
• Select an order to view its requirements
• Deliver items through a dedicated 45-slot input GUI
• Receive payment per accepted item
• Partially fulfill orders
• Deliver only as much as they want
• Automatically receive excess items back
• Receive immediate feedback when an incompatible item is inserted

The delivery interface only accepts the material requested by the selected order.

Escrow & Economy

DonutOrders integrates with Vault and a compatible economy provider.

When a buyer creates an order, the required funds are withdrawn immediately and reserved for that order.

This provides:

• Reliable seller payouts
• Protection against buyers spending committed funds
• Exact cancellation refunds
• Exact expiry refunds
• Per-item seller payments
• Optional configurable seller tax
• Support for common Vault-compatible economy providers

The optional tax is disabled by default and can be used as an economy sink when enabled.

Order Management

Orders move through several states during their lifecycle.

Order States

• Active — Available for sellers to fulfill
• Completed — Requested quantity has been fully delivered
• Expired — Order reached its configured expiry time
• Cancelled — Buyer manually cancelled the order

Buyers can view order details, progress, price, expiry information, and stash status from the GUI.

Virtual Stash

Delivered items do not require the buyer to be online or have free inventory space.

Instead, DonutOrders stores purchased items in a personal virtual stash.

The stash system provides:

• Safe server-side item storage
• Collection at the buyer's convenience
• Protection when the player's inventory is full
• Overflow handling during collection
• Persistent access to items from completed or partially fulfilled orders

Marketplace GUI

DonutOrders uses inventory-based interfaces to keep marketplace interaction simple.

Screen	Purpose
Your Orders	View personal buy orders, status, stash, and cancellation options
New Order	Choose an item and begin creating a new buy order
Browse Market	Browse active orders posted by players
Deliver Items	Place requested items into a 45-slot delivery grid
Confirm Delivery	Review items before completing a delivery
Order Detail	View progress, price, expiry, and collection options
Collect Stash	Collect delivered items stored for the buyer

Performance & Safety

DonutOrders is designed around modern server performance and safe marketplace transactions.

The plugin includes:

• Asynchronous database reads and writes
• Region-aware Folia scheduling
• Main-thread-safe Paper operation
• Server-side delivery serialization
• Anti-duplication protection
• Safe excess-item returns
• Escrow-backed transactions
• Persistent SQLite storage
• HikariCP connection management
• Shaded and relocated dependencies to reduce plugin conflicts

Concurrent delivery attempts against the same order are serialized server-side to help prevent duplication and transaction conflicts.

Configuration

DonutOrders can be customized for different server economies and marketplace styles.

Configurable options include:

• Maximum active orders per player
• Default order expiry duration
• Seller tax percentage
• SQLite database filename
• Allowed materials
• Player-facing messages
• GUI text
• Color formatting

All player-facing strings are stored in messages.yml and support traditional & color codes as well as #RRGGBB hex colors.

Example configuration:

orders:
  max-per-player: 10
  default-expiry-days: 7
  tax-percent: 0.0

database:
  filename: donutorders.db

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

Commands

Command	Description	Permission
/orders	Open the orders interface. Aliases: /order, /market	donutorders.use
/orders admin reload	Reload config.yml and messages.yml without restarting the server	donutorders.admin

Permissions

Permission	Default	Description
donutorders.use	Everyone	Access /orders and the marketplace GUI
donutorders.admin	OP	Access DonutOrders administrative commands

Installation

1. Place DonutOrders-1.0.0.jar inside your server's plugins/ directory.
2. Install Vault and a compatible economy plugin.
3. Start the server.
4. DonutOrders automatically generates config.yml and messages.yml.
5. Configure your allowed materials, limits, expiry duration, and other options.
6. Run /orders admin reload after making configuration changes.

Why Choose DonutOrders?

1. Player-Driven Economy — Players create real demand by posting exactly what they want to purchase.
2. No Chest Shops — The entire marketplace works through clean inventory interfaces.
3. Secure Escrow — Money is reserved when an order is created, providing reliable payments and refunds.
4. Flexible Fulfillment — Sellers can completely or partially fill orders and receive payment immediately.
5. Safe Item Storage — The virtual stash keeps delivered items secure until buyers collect them.
6. Modern Performance — Async storage and Folia-aware scheduling help keep marketplace activity away from critical server threads.
7. Highly Configurable — Server owners control tradeable materials, order limits, expiry, taxes, and messages.

Compatibility

• Paper 1.20+
• Folia 1.20+
• Java 17+
• Vault
• Vault-compatible economy providers
• EssentialsX Economy
• CMI Economy
• SQLite
• Standard Paper servers
• Folia regionized servers

Requirements

DonutOrders requires a supported Paper or Folia Minecraft server running version 1.20 or newer.

Required dependencies:

• Java 17+
• Vault
• A Vault-compatible economy plugin

No external database is required because SQLite is supported out of the box.

Community & Support

• Discord: https://discord.gg/TJc3CxR4jK
• GitHub: https://github.com/MeherBenSalem
• Website: https://nightbeam.dev
• Store: https://nightbeam.dev/store
• CurseForge: https://www.curseforge.com/members/nightbeamstudio/projects
• Modrinth: https://modrinth.com/organization/nightbeam

If you encounter a bug or have a feature request, please join the Discord community or report it through the appropriate project page.

License

DonutOrders is licensed under the Apache License 2.0.

You are free to use, modify, and redistribute DonutOrders in accordance with the terms of the Apache License 2.0.