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.

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

• Paper 1.21.4+ or any compatible fork
• Java 21+

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

---

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