BidVault

AuctionHouse

A complete server-side Auction House system for Minecraft 1.21.4 with built-in economy, advanced filtering, live search, pagination, and an intuitive chest-based GUI.

---

── Overview

AuctionHouse provides a fully featured player-to-player marketplace accessible through a single command. Players can list items for sale, browse listings with filters and sorting, search by name, and purchase items -- all through a clean inventory-based interface.

The plugin ships with its own lightweight economy system. No external dependency is required.

---

── Features

Marketplace - Browse all active listings in a paginated 28-slot GUI - View detailed item information before purchasing - Purchase confirmation screen to prevent misclicks - Real-time seller notifications on sale - Automatic listing expiration with configurable duration - Collection box for expired and sold items - Personal listings management with cancellation

Filtering & Sorting - 9 item categories -- All, Weapons, Armor, Tools, Blocks, Food, Potions, Enchanted, Miscellaneous - 6 sorting modes -- Newest, Oldest, Price ascending, Price descending, Name A-Z, Name Z-A - Live search through chat input with instant results - Combined filters -- search within a specific category with a chosen sort order - Search auto-clears on GUI close for a fresh experience every time

Economy - Built-in balance system with configurable starting amount - `/balance` to check funds - `/pay` to transfer money between players - `/eco` admin commands to set, give, or take money - Configurable sales tax deducted automatically - Balance displayed directly in the Auction House GUI

Interface - Clean inventory GUI with glass pane borders - Color-coded item lore with price, seller, time remaining, and per-unit cost - Animated category cycling with representative icons - Page indicators showing current position and total pages - Collection box indicator showing pending items at a glance - Sound effects for every interaction -- open, click, buy, sell, error, page turn - All sounds configurable in `config.yml`

---

── Commands

| Command | Description | Permission | |---------|-------------|------------| | `/ah` | Open the Auction House | `auctionhouse.use` | | `/ahsell <price>` | List the held item for sale | `auctionhouse.sell` | | `/ahsearch <query>` | Search listings by name | `auctionhouse.use` | | `/ahcollect` | Open collection box | `auctionhouse.use` | | `/ahreload` | Reload configuration | `auctionhouse.admin` | | `/balance [player]` | Check balance | ── | | `/pay <player> <amount>` | Send money | ── | | `/eco <set|give|take> <player> <amount>` | Manage economy | `auctionhouse.admin` |

Aliases: `/ah` `/hdv` `/auction` | `/bal` `/money` | `/sell` `/ahlist`

---

── Permissions

| Permission | Description | Default | |------------|-------------|---------| | `auctionhouse.use` | Access the auction house | Everyone | | `auctionhouse.sell` | List items for sale | Everyone | | `auctionhouse.admin` | Admin commands and economy management | OP |

---

── Configuration

All settings are managed through a single `config.yml` file generated on first launch.

```yaml currency-symbol: "$" starting-balance: 5000.0 max-listings-per-player: 10 min-price: 1.0 max-price: 1000000000.0 default-duration-hours: 48 sales-tax: 5.0 clear-search-on-close: true ```

Configurable elements: - Currency symbol and starting balance - Listing limits, price bounds, and duration - Sales tax percentage - Expiration check interval - ActionBar and sound settings - Search behavior on GUI close

---

── How It Works

``` Player holds item | /ahsell 1000 | Item listed on AH | Other players browse /ah | Click item --> View details --> Confirm purchase | Money transferred (minus tax) Item given to buyer Seller notified + earnings deposited Sale appears in seller's collection box ```

Expired items are automatically moved to the seller's collection box and can be retrieved at any time through the GUI.

---

── Data Storage

All data is stored locally in JSON files inside the plugin folder:

- `auctions.json` -- Active listings and collection boxes - `economy.json` -- Player balances

Items are serialized using Minecraft's native format, preserving all NBT data including enchantments, custom names, lore, and durability.

Auto-save runs every 5 minutes. Data is also saved on server shutdown.

---

── Supported Platforms

AuctionHouse runs on all Paper-based server software:

- Paper - Purpur - Pufferfish - Folia *(region-aware scheduling)* - Leaves - Gale - Any Paper fork

Folia compatibility is handled automatically at runtime through a scheduler abstraction layer.

---

── Requirements

- Java 21+ or any compatible fork - Java 21+

No external plugins required. Economy is fully self-contained.

---

*AuctionHouse -- Simple, powerful, self-contained marketplace.*