Skip to content
BattleStudio

Information

OptimalAuctions features, how listings work, commands, permissions, placeholders, tokens and formatting in one reference.

BattleStudio plugin

OptimalAuctions

A player auction house with a price per item, so buyers take as many as they want, in any currency you configure. Categories, search, bumping and offline payouts built in.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryVault
Buy on BuiltByBitInstallation guideGet support

OptimalAuctions is a player auction house. A seller lists the stack in their hand at a price per item, in any currency you configure. Buyers open the listing and take as many items as they want out of it: one, a stack, everything that is left, or a typed amount. The listing stays on the market until it is sold out, cancelled or expires, and expired items wait in the seller’s expired menu until they collect them.

There is no bidding. Every listing is a fixed price per item.

OptimalAuctions runs on top of OptimalLibrary, a free shared plugin that has to be installed next to it. See Installation.

How it works

Section titled “How it works”
  • Prices are per item. /ah hand 10 while holding 10 cobblestone lists all ten at 10 each, so the whole listing is worth 100. Min-Price and Max-Price apply to the per item price.
  • Buyers take part of a listing. Clicking a listing opens the purchase menu with preset amounts (+1, +64, everything) and a custom amount button. Each purchase lowers the listing’s stock. A preset is capped to what is left, so “x64” on a listing with 3 left buys 3.
  • Purchases are safe under load. Two buyers can never get the same items: each one receives only what was really left, and anything they paid for but did not get is refunded.
  • Sellers are paid per purchase, minus the currency’s Tax. Online sellers get the money right away. Offline sellers are paid directly when the currency supports it (Vault, PlayerPoints); otherwise the payout is queued and paid three seconds after they next join.
  • Listings expire after Listing-Duration (24 hours by default). The seller is told if they are online, and the leftovers move to their expired menu. Expired items are kept forever unless you set Expired-Deletion-Time.
  • Your own listings stay on the board. In the main menu your listings show a different lore: left-click cancels and returns the remaining stock, right-click bumps the listing back to the front of the “Recent” order. You can never buy your own listing.

Features

Section titled “Features”
  • Fixed-price listings, priced per item, bought in any quantity
  • Sell the held stack (/ah hand) or every copy of the held item in your inventory (/ah all)
  • Multiple currencies in one auction house: Vault, PlayerPoints, RivalCredits, OptimalGens and OptimalMobcoins currencies, each with its own colors, format and sales tax
  • Categories with wildcard material, name and custom model data rules
  • Item name search, through chat or an anvil
  • Four sort orders: Recent, Lowest Price, Highest Price, Oldest
  • Bumping with a per-listing cooldown and optional cost
  • Listing limits per permission, listing fee, minimum and maximum price, material and name blacklist
  • Expired menu with single and “collect all” collection
  • Offline seller payouts, queued safely in the database
  • Admin removal menu, force expiry and a sale history menu
  • Optional broadcast of new listings
  • Live menus: expiry timers tick while a menu is open
  • PlaceholderAPI placeholders
  • SQLite or MySQL storage
  • Folia-ready

Commands

Section titled “Commands”

Player - /auctionhouse (aliases /ah, /auction, /auctions, /optimalauctions) · all optimalauctions.use:

  • /ah - open the auction house.
  • /ah hand [price] [currency] - auction the whole stack in your main hand.
  • /ah all [price] [currency] - auction every copy of the held item in your inventory as one listing.
  • /ah expired - open your expired listings.
  • /ah collect - collect every expired listing at once.
  • /ah help - show the help panel.

[price] is the price per item. It accepts k, m, b, t and q suffixes (2.5k, 1m) and ignores commas. Leave it out and you are asked to type it (in chat or an anvil, see Search-Mode). Leave out [currency] and the listing uses the default currency, which is the first enabled file in currencies/ by file name. Any unknown subcommand opens the main menu.

Admin - /auctionhouseadmin (aliases /ahadmin, /auctionadmin, /optimalauctionsadmin) · all optimalauctions.admin:

  • /ahadmin - show the admin help.
  • /ahadmin open [player] - without a player, open the main menu. With a player, open the removal menu for their active listings.
  • /ahadmin remove <player> - open the removal menu for a player’s active listings.
  • /ahadmin history [player] - open the sale history, for everyone or for one player (as buyer or seller).
  • /ahadmin expire <player> - expire every active listing of a player. Works from console.
  • /ahadmin reload - reload every config, currency, category and menu file. Works from console.

Target players must be online. open, remove and history open a menu, so they have to be run by a player.

Permissions

Section titled “Permissions”
  • optimalauctions.use - /ah, its subcommands and the menus (default: everyone)
  • optimalauctions.admin - every /ahadmin command (default: op)
  • optimalauctions.limit.<n> - raise the player’s active listing cap to <n> (not set by default)
  • optimalauctions.limit.unlimited - no listing cap (not set by default)

Without a limit permission a player can have Settings.Default-Listing-Limit (default 5) active listings. When a player has several limit permissions, the highest one wins. A limit permission lower than the default never lowers it.

/ahadmin and its aliases are hidden from tab completion for players without optimalauctions.admin.

Placeholders

Section titled “Placeholders”

Requires PlaceholderAPI. Identifier optimalauctions.

Placeholder Value
%optimalauctions_listings% Active listings on the whole auction house.
%optimalauctions_my_listings% The player’s active listings.
%optimalauctions_my_expired% The player’s expired listings waiting to be collected.
%optimalauctions_limit% The player’s active listing cap. Online players only.
%optimalauctions_balance_<currency>% The player’s balance in that currency, formatted. <currency> is the currency file name, e.g. %optimalauctions_balance_money%.

balance_<currency> returns an empty string when the currency does not exist, is unavailable, or can only be read for online players (OptimalGens and OptimalMobcoins currencies) and the player is offline.

With PlaceholderAPI installed, %...% placeholders from other plugins also resolve inside messages, menu titles, menu items and menu action arguments.

Tokens

Section titled “Tokens”

These are the plugin’s own {...} tokens. Where each one works is listed on the config pages; this is the summary.

Token Value Where
{item} The item’s display name. Listing lore, purchase menu, listing messages.
{material} The material, prettified (Diamond Sword). Listing lore, purchase menu, listing messages.
{stock}, {amount} Items left in the listing. In purchase, sale and collect messages it is the amount that changed hands. Listing lore, purchase menu, listing messages.
{listed-stock} How many items the listing started with. Listing lore, purchase menu.
{unit-price} The price per item, in the currency’s primary color. Listing lore, purchase menu, listing messages.
{price} The value of the remaining stock (or of the purchase), in the currency’s primary color. Listing lore, purchase menu, listing messages.
{unit-price-raw}, {price-raw} The same numbers, unformatted. Listing lore, purchase menu.
{currency} The currency’s display name in its secondary color. Listing lore, purchase menu, listing messages.
{seller}, {buyer} Player names. {buyer} is only filled in sale history and sale messages. Listing lore, listing messages.
{expires} Time until the listing expires (23h, 59m, 57s). Listing lore, purchase menu.
{listed}, {sold} Date listed and date sold (dd/MM/yyyy HH:mm). Listing lore.
{id} The listing’s unique id. Listing lore.
{my-listings}, {my-expired}, {limit}, {listings} Listing counters for the viewer and the whole board. Menus.
{category}, {search}, {sort}, {sorts} The current browse state. Main and category menus.
{page}, {pages}, {results} Paging and the number of entries shown. Paged menus.
{subject} The player (or “Everyone”) an admin menu is about. History and removal menus.
{player} The viewer’s name. As Base64: "{player}" it shows the viewer’s own head. Menus.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:HEX,HEX>, <rainbow>, <bold>, <#RRGGBB>, …) and, with PlaceholderAPI installed, %...%. Messages also support [center] to center a line in chat.

Text players control (renamed item names, search text) is inserted safely, so a renamed item cannot inject MiniMessage tags into your menus and messages.

Reference

Section titled “Reference”