Market, auctions and orders

Three modules let players trade with each other without meeting. The market sells at a price the seller sets, the auction house sells to whoever bids highest, and orders turn it round: a buyer pays first and sellers fill the order.

Each one has its own switch under modules in config.yml (market, auctions, orders), and all three are on by default. Each needs an economy. Without one the module still loads, logs a warning, and refuses every sale, bid and order.

What the three share

Any currency. A price can be in any currency registered on the server, with the default one listed first. When a player leaves the currency out of a command and there is more than one, a picker opens (menus/currency_select.yml). With a single currency nobody is asked. Currencies themselves are covered on Economy.

The item leaves the hand. Listing or auctioning takes the whole stack in the main hand at once. If the database write fails, the stack and the fee come back.

Delivery never drops anything. Items handed out by these modules (a purchase, an auction won, an expired listing, a delivered order) go through the plugin's reward store. Anything that does not fit in the inventory, and anything owed to a player who is offline, is kept and handed over on their next join.

Limits come from permissions. The configured per-player limit applies unless the player holds a numbered permission, in which case the highest number they hold wins. A configured limit of 0 or less means no limit, and the menus then show ∞.

Fees and taxes are percentages. They are rounded to two decimals and then to the currency's own precision. Prices in the settings (min-price, max-price, broadcast-above) are plain numbers, compared against the price in whichever currency it was set in.

Announcements are in the default currency only. A market sale or an auction won at or above broadcast-above is announced to the server only when it was priced in the default currency, since 100 gems and 100 coins are not the same amount. Each player can turn market and auction announcements off in /settings. See Quality of life.

Market

exyliasurvivalcore.market opens the market, exyliasurvivalcore.market.sell is needed to list, and exyliasurvivalcore.market.admin covers /marketadmin. The admin commands run from a player only, not the console.

Listing

Hold the item and use /market sell, or press Sell what you hold on the board or on your listings. The button asks for the currency, then for the price in chat.

A listing is refused when the material is in blocked-materials, when the item is damaged and allow-damaged-items is off, when the price is outside min-price and max-price, or when the player is at their limit. The listing fee is then charged: a percentage of the asking price. It is not refunded when the listing expires or is cancelled, which is what stops the market being used as free storage.

Buying

Clicking a listing opens a confirmation showing the total, the price per item, the currency, and the buyer's balance before and after. Confirming takes the money first and then claims the listing. If somebody else got there first, the money goes straight back.

The seller is paid the price minus sales-tax-percent, online or not, and the stack is delivered to the buyer. allow-self-purchase is off by default: cancelling is how you take your own listing back.

Expiry and cancelling

A listing lasts listing-hours. 0 or less means it never expires. Expired listings disappear from the board and can no longer be bought. A check every minute sends them back to the seller, who is told if they are online. Listings that ran out while the server was down go back the same way once it starts.

Clicking a listing in My listings takes it back.

Looking inside

A shulker box or bundle with something in it is drawn with its own template. Shift-click it on the board or in your listings, or use Look inside on the confirmation, to open it. A box inside the box opens the same way, and Back climbs out one level at a time. The screen shows a copy, so nothing in it can be taken, and looking buys nothing. preview.container-hint is the lore added to a container drawn inside the preview, with %items%.

Every listing's lore also describes the stack: its size, how many items are inside it, its enchantments (including those stored in an enchanted book) and, when the shop module buys that item, what the shop pays for one.

The board

Search filters by material, seller name or item name, up to 32 characters. Right-click clears it. Order steps through newest first, cheapest first and most expensive first. Search and order are forgotten when the player leaves.

These live under settings in modules/market/config.yml. sounds sets listed, bought, sold and cancelled.

Auctions

exyliasurvivalcore.auctions opens the auction house, exyliasurvivalcore.auctions.sell is needed to sell, and exyliasurvivalcore.auctions.admin covers /auctionadmin, which runs from a player only.

Opening an auction

In the command, hours come before the buyout. Leaving the hours out uses default-hours, and a buyout of 0 means no buyout. Auction what you hold asks for the currency, then opens a form with the starting price, an optional buy-it-now price and the hours.

An auction is refused when the material is blocked, the item is damaged and allow-damaged-items is off, the start is below min-start-price, the buyout is not above the start, the hours fall outside min-hours and max-hours, or the player is at their limit. The fee is a percentage of the starting price and is not refunded, even if nobody bids.

Bidding

The first bid must be at least the starting price. After that, each bid must beat the top bid by min-bid-increment-percent of it or by min-bid-increment, whichever is more.

Clicking an auction opens the bid screen:

• Bid places exactly the next valid bid.
• Bid another amount takes a typed amount, from the next valid bid up to the buyout.
• Buy it now appears only when the auction has a buyout.

A bid is held. The money leaves the bidder when the bid is placed and stays with the auction. When somebody outbids them, it goes straight back, whether they are online or not. Raising your own top bid works the same way: the old amount comes back and the new one is held. Nobody can bid on their own auction.

A bid that reaches the buyout price counts as a buyout, and the buyer pays the buyout price.

Anti-snipe

A bid placed with less than anti-snipe-seconds left pushes the end back to that many seconds from the bid, so the last word does not go to whoever clicked last. 0 turns it off.

How an auction ends

Auctions are checked every second.

Items go to the winner through the reward store, so a winner who is offline receives them on their next join.

The board

An auction is drawn in one of three templates in modules/auctions/menus/auctions.yml: item for one you can bid on, leading for one you are winning, and mine for your own, which opens My auctions when clicked. Sort steps through ending soonest (the default), newest, cheapest and most expensive, by current price. Search works as on the market. The lore shows what is inside a shulker box or bundle, but auctions have no look-inside screen.

These live under settings in modules/auctions/config.yml. sounds sets listed, bid, outbid, won, sold and cancelled.

Orders

exyliasurvivalcore.orders opens orders, exyliasurvivalcore.orders.create is needed to place one, and exyliasurvivalcore.orders.admin covers /ordersadmin.

Placing an order

Hold one of the item you want. It becomes the order's template: sellers must deliver items that match it exactly, with the same name, enchantments and other data. The amount is how many units you want, from 1 to max-amount, and the price is for all of them. Order what you hold asks for the amount, the currency and then the price.

The full price plus creation-fee-percent is taken up front. The fee is never refunded. Blocked materials cannot be ordered, and neither can damaged items; orders have no setting to allow them. Only orders still taking items count towards the limit, so a finished order waiting to be collected does not.

Filling an order

Anybody can sell into an open order, and the buyer does not need to be online. The board lists open orders with the best price per unit first. Clicking one shows how many matching items you carry, how many will be sold and what you will earn. Confirming takes them from your inventory and hotbar (not the off-hand, armour slots or containers), up to what the order still needs, and pays you at once minus sales-tax-percent.

A seller is paid for the units they deliver, as that share of the total rounded down. The last unit settles the remainder, so the partial payments always add up to exactly the order's price. If the order filled up or closed while you were confirming, the items it no longer needs come back to you.

allow-self-fill is off by default.

Collecting, closing and expiry

Delivered items wait in the order. In My orders, left-clicking an order collects as many as fit in your inventory, and the rest stay ready for later. Right-clicking closes the order: no more items are taken, the part of the price not yet paid to sellers is refunded, and anything already delivered can still be collected.

An order lasts order-hours. 0 or less means it never expires. Every minute, expired orders are closed and refunded the same way, and the buyer is told if they are online. An order is deleted once it is closed or complete and nothing is left to collect.

These live under settings in modules/orders/config.yml.

Across servers

Orders are built for several servers sharing one database. Every change to an order holds a lock row that exactly one server can take at a time, and reads the order fresh from the database. Other servers refresh their copy when an order changes. A player who hits an order another server is changing sees "Somebody else is using that order right now" after about two seconds of retries.

Menus

In the ledger and the stat counters

Every movement of money carries a reason in the economy ledger:

They also feed the stat counters that missions and seasons measure: