Auction
A clean, GUI-first Auction House plugin for Paper 1.21+ using Vault for economy.
Designed to be lightweight, permission-minimal, and easy for both players and developers.
Requirements
- Paper: 1.21+
- Vault (plugin)
- A Vault-compatible economy plugin (e.g., EssentialsX)
Vault does not store balances. You must install an economy provider.
Commands
/ah
Opens the global Auction House GUI.
/ah sell <price>
Lists the item currently in the player’s hand for sale.
- Item must not be
AIR
- Item must not be blocked by config
- Price must be within configured limits
- Listing limit enforced (normal vs premium)
/ah storage
Opens Auction Storage, showing:
- Active listings (click to cancel)
- Cancelled / expired returns (click to claim)
- Delivery overflow items (when inventory was full on purchase)
/ah resell
Relists eligible stored items (premium feature + cooldown).
/ah <playerName>
Opens a view showing only listings by that exact seller name.
- Case-sensitive matching
- Does not validate whether the name belongs to a real player
- If no listings exist, GUI opens empty
/ah search <keyword> [maxPrice]
Searches auction listings by keyword.
- No
minecraft: namespace required
- Matches:
- Material key/name (e.g.,
iron_ingot)
- Display name (custom items like “Bulldozer” / “Drill”)
Examples:
/ah search iron/ah search net/ah search note block 500 (premium price filter)
Premium Features
Permission:
Premium unlocks:
- Increased listing limit (default: 20 vs 10)
/ah resell and “Relist All” button- Advanced search price filter (max price argument)
- Cooldown on relist (default: 60s)
Relist spam protection:
- “Wait X seconds” message is throttled to max once per second per player.
GUI Overview
Auction House GUI
- Paginated
- Edge glass border
- Buttons:
- Refresh (nether star)
- Storage (chest)
- Prev/Next page arrows (hidden when not usable)
Listing lore formatting:
- Seller name: Yellow
- Price: Green
- Expires in: Red
- Lore is non-italic
Confirm Purchase GUI
- Click listing → confirm screen:
- Green: Buy
- Red: Cancel (returns to
/ah)
Purchase logic:
- Checks balance before opening confirmation
- On successful buy:
- Money is withdrawn
- Item delivered to inventory
- If inventory full → moved to storage as delivery overflow
Auction Storage GUI
- Title: Auction Storage
- Shows:
- Active listings (cancelable)
- Cancelled returns
- Expired returns
- Overflow deliveries
- Back arrow returns to main
/ah
Status display:
- Cancelled: red
- Expired: red
- Delivery: yellow
Sounds
- Successful listing: “ding” sound
- Listing denied (limit reached / not allowed): villager “no”
- Successful purchase: villager “yes”
- Seller receives notification + sound on successful sale
Configuration
Key config options include:
- Listing limits for normal/premium
- Maximum sell price
- Premium relist cooldown
- Blocked item list
- GUI sound toggles (if present in your build)
(Exact keys depend on your current shipped config.yml.)
Installation
- Drop into
plugins/:
- Vault
- Economy plugin (e.g., EssentialsX)
- Xiaoklunar Auction
- Start server
- Configure
config.yml
- Assign premium permission (optional)
Troubleshooting
Vault installed but economy not working
Vault needs an economy provider (EssentialsX, etc.). Check console for economy registration logs.
“Invalid plugin.yml”
YAML must use spaces (no tabs) and usage strings should be quoted.
Have fun
