Auctions

Auction System

The Auction System is a fully-featured player-to-player marketplace built into CustomNPC+. Players can list items for sale, bid on auctions, use instant buyout, and claim their winnings — all through an in-game GUI or via NPC Auctioneers. The system includes snipe protection, sales tax, item blacklisting, admin controls, and full scripting support.

---

Overview

The Auction System provides three core components:

• Listings:   Players can list items for sale with a starting price and optional buyout price. Listings appear in a browsable marketplace grid with search and sorting.

• Bidding & Buyout:   Other players can place bids or instantly buy items at the buyout price. Outbid players are automatically refunded. Snipe protection extends auctions when bids are placed near the end.

• Claims:   After an auction ends, winners collect their items and sellers collect their currency through a claims system. Unclaimed items expire after a configurable number of days.

---

Accessing the Auction House

There are two ways to open the Auction interface:

1. NPC Auctioneer:   Assign the Auctioneer role to any NPC. When a player interacts with the NPC, the Auction GUI opens automatically.

2. Command:   Use /auction open to open the Auction GUI directly without needing an NPC.

---

Auction Interface

The Auction GUI has three tabs accessible from the top of the interface:

Listings Tab

Browse all active auctions in a 9x5 grid (45 items per page) with pagination.

• Search: Click the search button to open a filter dialog. Search by item name or seller name.
• Sort Options:
  • Newest — Most recently created listings first
  • Ending Soon — Auctions closest to expiring first
  • Price: Low to High — Cheapest current price first
  • Price: High to Low — Most expensive current price first
  • Most Bids — Listings with the most bids first

Click any listing to open the Bidding Details screen.

---

Sell Tab

Create a new auction listing from this tab.

1. Click an item from your inventory into the auction sell slot.
2. Set a starting price (must be at or above the minimum listing price).
3. (Optional) Set a buyout price — toggle the buyout option and enter a price higher than the starting price.
4. Confirm — The listing fee is deducted from your balance and the auction goes live.

Important Notes:

• A listing fee is charged when creating an auction (default: 10 currency).
• The item is removed from your inventory while listed.
• You are limited by your trade slot count (see Trade Slots below).

---

Trades Tab (My Trades)

View and manage your auction activity.

Items in the Trades tab are color-coded by status:

Color	Meaning
Blue	Active listing you're selling, or an active bid you've placed
Green	Won item ready to claim, or sale proceeds ready to collect
Yellow	Outbid refund ready to claim
Red	Expired or cancelled listing — item returned

• Claim items by clicking on green/yellow/red entries and confirming.
• Cancel active listings by clicking on blue entries (a cancellation penalty applies if the listing has bids).

---

Bidding on an Auction

Click any listing in the Listings tab to open the Bidding Details screen.

From here you can:

• Place a Bid:   Enter a bid amount. The minimum bid is the starting price (if no bids yet) or the current bid plus the minimum increment (default: 5% of current bid).

• Buy Now (Buyout):   If the seller set a buyout price, click the Buy Now button to purchase instantly. A confirmation dialog appears before completing the purchase.

Bidding Rules:

• You cannot bid on your own auctions.
• The full bid amount is deducted from your balance immediately.
• If you are outbid, your currency is automatically returned as a refund claim with a notification.
• If the current high bidder uses buyout, they only pay the difference between their existing bid and the buyout price.

---

Snipe Protection

When a bid is placed within the last few minutes of an auction (default: 2 minutes), the auction timer is automatically extended by the snipe protection duration. This prevents last-second sniping and gives other bidders a fair chance to respond.

---

Auction Lifecycle

Here's how an auction progresses from start to finish:

1. Seller creates listing
   └─ Listing fee deducted
   └─ Item removed from inventory
   └─ Auction status: ACTIVE

2. Players browse and bid
   └─ Bids deducted immediately
   └─ Outbid players refunded automatically
   └─ Snipe protection extends time if bid near end

3. Auction ends (timer expires)
   ├─ If bids were placed:
   │   ├─ Winner receives ITEM claim
   │   ├─ Seller receives CURRENCY claim (minus sales tax)
   │   └─ Status: ENDED
   └─ If no bids:
       ├─ Seller receives ITEM RETURN claim
       └─ Status: EXPIRED

4. Players collect claims from Trades tab
   └─ Claims expire after configurable days (default: 20)
   └─ Unclaimed items/currency are permanently lost

---

Cancelling an Auction

Sellers can cancel their own active listings from the Trades tab.

• No bids: Item is returned to the seller with no penalty.
• Has bids: A cancellation penalty is applied (default: 10% of the current bid). The highest bidder is refunded in full, and the seller's item is returned.

---

Sales Tax

A configurable sales tax is applied to all successful sales (default: 5%). The tax is deducted from the seller's proceeds before the currency claim is created. This currency is destroyed as a currency sink — it is not given to any player or admin.

Example:   An item sells for 1000 currency with a 5% tax.   Seller receives: 1000 - (1000 × 0.05) = 950 currency

---

Trade Slots

Each player has a limited number of trade slots that determine how many active auctions, bids, and unclaimed items they can have simultaneously.

• Default: 8 slots
• Maximum: 45 slots
• Expansion: Grant the permission customnpcs.auction.trades.X where X is the desired slot count.

Example:   customnpcs.auction.trades.20 gives the player 20 trade slots.

Trade slots are shared across all auction activity — active listings, active bids, and pending claims all count toward the limit.

---

Item Blacklist

Server administrators can prevent specific items from being listed on the auction house.

Blacklist Types

Type	Description	Example
Item	Block a specific item by registry name	minecraft:bedrock
Mod	Block all items from an entire mod	customnpcs
NBT	Block items containing a specific NBT tag	ench

Default Blacklisted Items

The following items are blacklisted by default:

• minecraft:bedrock
• minecraft:command_block
• customnpcs:npcWand
• customnpcs:npcMobCloner
• customnpcs:npcScripter
• customnpcs:npcMovingPath
• customnpcs:npcMounter
• customnpcs:npcTeleporter
• customnpcs:npcTool
• customnpcs:npcSoulstoneFilled

Blacklist Commands

Command	Description
/auction blacklist add <item|mod|nbt> <value>	Add an entry to the blacklist
/auction blacklist remove <item|mod|nbt> <value>	Remove an entry from the blacklist
/auction blacklist list [item|mod|nbt]	Display current blacklist contents
/auction blacklist reload	Reload blacklist from config file
/auction blacklist check	Check if your held item is blacklisted

Bypass Permission: customnpcs.auction.blacklist.bypass — Allows a player to list blacklisted items.

---

Commands

All auction commands are managed via the /auction command.

List Auctions

/auction list [page]

• Description: Lists all active auctions in chat with pagination (10 per page).

View Player Activity

/auction view <player>

• Description: View a specific player's auction activity, including their listings, bids, and claims.

Open Auction GUI

/auction open

• Description: Opens the Auction GUI directly without needing to interact with an NPC Auctioneer.

Blacklist Management

/auction blacklist <add|remove|list|reload|check> [args]

• Description: Manage the item blacklist. See Item Blacklist for details.

---

Configuration

All auction settings are located in the config file at: config/CustomNpcPlus/market.cfg

Currency Settings

Setting	Default	Description
UseVault	false	Use Vault API for currency instead of built-in system
CurrencyName	"Coins"	Display name for the currency
StartingBalance	—	Initial balance for new players
MaxBalance	—	Maximum balance cap

Auction Settings

Setting	Default	Description
AuctionEnabled	true	Enable or disable the entire auction system
AuctionDurationHours	24	How long auctions last (in hours)
ListingFee	10	Fee charged when creating a listing
MinimumListingPrice	1	Minimum starting price for listings
SalesTaxPercent	0.05 (5%)	Tax deducted from sales (currency sink)
DefaultMaxTrades	8	Default trade slots per player
SnipeProtectionMinutes	2	Time extension when bid placed near auction end
ClaimExpirationDays	20	Days before unclaimed items/currency are deleted
MinBidIncrementPercent	0.05 (5%)	Minimum bid increase over current bid
CancellationPenaltyPercent	0.10 (10%)	Penalty when cancelling an auction with active bids

Blacklist Settings

Setting	Default	Description
BlacklistEnabled	true	Enable item blacklist checking
BlacklistedItems	(see above)	Specific items blocked from auction
BlacklistedMods	[]	Entire mods blocked from auction
BlacklistedNBTTags	[]	Items with specific NBT tags blocked

Logging Settings

Setting	Default	Description
AuctionLoggingEnabled	false	Master toggle for auction logging
LogAuctionCreated	false	Log when auctions are created
LogAuctionBid	false	Log when bids are placed
LogAuctionBuyout	false	Log when buyouts occur
LogAuctionSold	false	Log when auctions are sold
LogAuctionExpired	false	Log when auctions expire
LogAuctionCancelled	false	Log when auctions are cancelled
LogAuctionClaimed	false	Log when claims are collected

---

NPC Auctioneer Role

Any NPC can be assigned the Auctioneer role to serve as an auction access point.

1. Open the NPC editor.
2. Navigate to the Advanced tab.
3. Set the Role to Auctioneer.
4. Players who interact with this NPC will have the Auction GUI open automatically.

Permission Required: customnpcs.npc.advanced.role to assign the Auctioneer role.

---

Admin Features

Global Listings

Administrators can create global listings — auctions that are not owned by any player. These are useful for server shops or admin-run sales.

• Access the admin auction GUI via the Global NPC Manager (Auction section).
• Create Tab: Set the item, custom seller name (e.g., "Server Shop"), starting price, buyout price, and duration.
• Proceeds from global listings go to global claims (not any player's balance).

Manage Auctions

From the admin GUI, administrators can:

• Browse all active auctions with search and pagination.
• Stop/Cancel any auction — refunding bidders and returning items.
• View and claim global claims (items/currency from global listings).

---

Notifications

The auction system sends automatic notifications to players for important events:

Event	Notification
Auction Won	You won an auction — claim your item
Outbid	Someone outbid you — refund available
Auction Sold	Your item sold — claim your currency
Auction Expired	Your auction expired with no bids — item returned
Claim Ready	A claim is ready for collection

---

Permission Nodes

Permission	Description
customnpcs.global.auction	Access to admin auction management
customnpcs.auction.blacklist.bypass	Bypass item blacklist restrictions
customnpcs.auction.trades.X	Set max trade slots to X (e.g., trades.20 = 20 slots)
customnpcs.npc.advanced.role	Permission to assign NPC roles (including Auctioneer)

---

Scripting API

The Auction System is fully integrated with the CustomNPC+ scripting engine, allowing server developers to hook into auction events.

Accessing the Auction Handler

var auctions = API.getAuctions();

Handler Methods

Method	Description
isEnabled()	Check if the auction system is enabled
getActiveListings()	Get all active listings
getListing(id)	Get a specific listing by ID
getListingsBySeller(uuid)	Get all listings by a seller
getListingsByBidder(uuid)	Get listings where player is high bidder
getActiveListingCount()	Count of active listings
createListing(player, item, startPrice, buyoutPrice)	Programmatically create a listing
placeBid(listingId, player, amount)	Place a bid via script
buyout(listingId, player)	Execute a buyout via script
cancelListing(listingId, player, isAdmin)	Cancel a listing via script
searchListings(searchText)	Search active listings
getListingFee()	Get current listing fee
getSalesTaxPercent()	Get current sales tax rate
getMinBidIncrementPercent()	Get minimum bid increment
getAuctionDurationHours()	Get auction duration setting
getSnipeProtectionMinutes()	Get snipe protection duration
getCurrencyName()	Get currency display name
getMinimumListingPrice()	Get minimum listing price
save()	Force save auction data

Scripting Events

All auction events are cancelable — returning false or calling event.setCanceled(true) prevents the action.

auctionCreate

Fired before a new listing is created.

function auctionCreate(event) {
    var item = event.getItem();
    var price = event.getStartingPrice();
    var buyout = event.getBuyoutPrice();
    // Cancel to prevent listing
    event.setCanceled(true);
}

auctionBid

Fired before a bid is placed.

function auctionBid(event) {
    var listing = event.getListing();
    var amount = event.getBidAmount();
    // Cancel to prevent bid
}

auctionBuyout

Fired before an instant buyout.

function auctionBuyout(event) {
    var listing = event.getListing();
    // Cancel to prevent buyout
}

auctionCancel

Fired before an auction is cancelled.

function auctionCancel(event) {
    var listing = event.getListing();
    var isAdmin = event.isAdmin();
    // Cancel to prevent cancellation
}

auctionClaim

Fired before a claim is collected.

function auctionClaim(event) {
    var claim = event.getClaim();
    // Cancel to prevent claim collection
}

---

NBT Structure

Auction data is stored in customnpcs/auction.dat. Each listing's NBT is structured as follows:

AuctionListing
 ├─ id              (String)   Unique listing UUID
 ├─ sellerUUID      (String)   Seller's player UUID
 ├─ sellerName      (String)   Seller's display name
 ├─ item            (Compound) Full ItemStack NBT data
 ├─ startingPrice   (Long)     Starting bid price
 ├─ buyoutPrice     (Long)     Buyout price (0 = no buyout)
 ├─ currentBid      (Long)     Current highest bid
 ├─ highBidderUUID  (String)   Highest bidder's UUID
 ├─ highBidderName  (String)   Highest bidder's name
 ├─ bidCount        (Int)      Total number of bids placed
 ├─ createdTime     (Long)     Creation timestamp (ms)
 ├─ endTime         (Long)     Expiration timestamp (ms)
 ├─ status          (Byte)     ACTIVE / ENDED / CANCELLED / CLAIMED
 └─ isGlobalListing (Boolean)  Admin-created listing flag

Claims are stored per-player in PlayerData:

AuctionClaim
 ├─ id              (String)   Unique claim UUID
 ├─ playerUUID      (String)   Claimant's UUID
 ├─ playerName      (String)   Claimant's name
 ├─ listingId       (String)   Related auction listing ID
 ├─ type            (Byte)     ITEM / CURRENCY / REFUND
 ├─ item            (Compound) ItemStack (for ITEM claims)
 ├─ itemName        (String)   Item display name (for reference)
 ├─ otherPlayerName (String)   Buyer name (CURRENCY) or outbidder (REFUND)
 ├─ currency        (Long)     Amount (for CURRENCY/REFUND claims)
 ├─ createdTime     (Long)     Creation timestamp (ms)
 ├─ claimed         (Boolean)  Whether claimed
 └─ isReturned      (Boolean)  Item returned (expired) vs won

---

Tips & Best Practices

• Set a buyout price on your listings to attract buyers who want instant purchases.
• Check your Trades tab regularly — unclaimed items expire after the configured number of days and are permanently lost.
• Use snipe protection to your advantage — bidding near the end of an auction extends the timer, giving you more time.
• Watch your trade slots — active listings, bids, and unclaimed items all count toward your limit.
• Server admins: Enable auction logging in production to maintain an audit trail of all transactions.
• Server admins: Use global listings to create a rotating server shop without needing a dedicated plugin.