Xiaoklunar Auction House

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:

• auctionhouse.premium

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

1. Drop into plugins/:
   • Vault
   • Economy plugin (e.g., EssentialsX)
   • Xiaoklunar Auction
2. Start server
3. Configure config.yml
4. Assign premium permission (optional)
   • Example (LuckPerms):

     /lp group premium permission set auctionhouse.premium true
     

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