Guide

uxmAuction is an auction house: players list items at a fixed price or for bids, place buy orders that the house fills from new listings, and collect what they are owed from a mailbox. It prices in several currencies at once and never converts between them.

Install

1. Put the jar in plugins/.
2. Start the server once. The plugin writes its files into plugins/uxmAuction/.
3. Check currencies.conf: coins (Vault) and experience ship on. Turn on the ones your server runs.
4. Run /uxmauction reload after any change.

PlaceholderAPI, Vault and the other economy plugins are optional. A currency whose plugin is missing stays listed and says it is not ready; listings in it are refused until the plugin is installed.

Files

Selling and buying

• /auction sell <price> [amount] [-t <time>] [-c <currency>] [-r] lists the item in hand at a fixed price. Without a price it opens the sell window. -r (retail) lets buyers take part of the stack; otherwise a buyer takes all of it.
• /auction auction <price> [-t <time>] [-c <currency>] lists the item in hand for bids, starting at the price. A bidding listing is never sold in parts.
• /auction buy <listing> [amount] buys from a fixed price listing.
• /auction bid <amount> <listing> bids on an auction. The bid must be at least the leading bid plus the step of that currency.
• /auction reprice <listing> <price> lowers the price of your own listing.
• /auction cancel <id> takes your listing or order back, when house.allow-cancelling is on.

Times are written like 30s, 5m, 2d. Without -t a listing stands for house.listing.default-duration; a longer time than maximum-duration is refused. Without -c the price is in the currency with the lowest order.

When a listing sells, the seller is paid straight into their balance if the currency can pay a player who is offline, and otherwise into their mailbox. An unsold item, an outbid refund and anything else the house owes goes to the mailbox: /auction mailbox, or /auction claim <row>.

Buy orders

/auction order <price> <amount> [-t <time>] [-c <currency>] [-m <material|enchanted|exact>] [-x] asks the house to buy the item in hand for you and holds the money until it does. Without a price it opens the order window.

-m sets how closely a listing must match: material (any item of that type), enchanted (the same enchantments) or exact (the same item in every detail). A new listing at or below the order's price is offered to the best paying orders first and sells into them at once, unless the order was made with -x (manual). A seller can also sell the item in hand into an order with /auction fill <order> [amount].

House rules

house {
  max-listings-per-seller = 10
  price {
    minimum { coins = "1" }
    maximum { coins = "1000000000" }
  }
  bidding {
    step { coins = "10" }
    anti-snipe { window = "30s", extension = "1m" }
  }
}

Fees

fees has four charges: listing (paid by the seller when the listing is written, not refunded on expiry), reprice, sale-tax (kept out of what the seller earns) and purchase-tax (paid by the buyer on top of the price). Each takes:

A player who is offline holds no group node, so a seller paid while away pays the house rate. A sale tax never takes more than the sale brought. Everything ships at zero.

fees {
  sale-tax {
    type = "percent"
    value = "5"
    cap = "1000"
    groups { "uxmauction.fee.vip" { value = "2" } }
  }
}

Currencies

Each block in currencies.conf is one currency, keyed by its id. Every price, bid, fee and refund of a listing stays in the currency it was listed in.

An item currency counts whole numbers only, so a fractional price is refused. A shown price is rounded up, never down. The file documents the placeholder and bridge types for economy plugins without a supported API.

Categories

Each block in categories.conf is a tab: order (lowest first, and the winner when two tabs accept an item), icon, and matches, a list of item ids where * stands for any run of characters. An item no tab accepts goes to the fallback category.

Notices

• effects holds a list of actions for listed, listed-and-sold, bought, bid-leading, bid-outbid, bid-beaten, auction-sold, auction-won and mailbox-took, in the same [verb] payload form as the other UXM plugins; @line is the plugin's own sentence for that moment.
• webhook posts new listings, sales and operator moves to a Discord webhook. Set enabled and url; least.listing.<currency> and least.sale.<currency> skip small events. Keep the address out of version control.
• events.enabled publishes Bukkit events for other plugins.
• history keeps one row per finished sale for keep-for (default 30d); /auction history shows what the item in hand has sold for.

Network

For several servers on one database, set storage to a shared mysql, mariadb or postgresql database and network.transport to sql (polls the database every poll-every) or redis (instant, needs a Redis server and the redis block). server-name may stay empty. keep-for is how long a network message is kept and must be longer than poll-every.

Commands

The names and aliases come from commands.conf. The reference lists the default aliases and every permission.

Placeholders

The identifier is placeholders.identifier, uxmauction by default. Values are cached for fresh-for; waiting is shown before the first read and none for an item nobody sells.

Troubleshooting

• A listing is refused because the currency is not ready. Its plugin is not installed or not loaded; /uxmauction doctor says which.
• A price with a fraction is refused. The currency counts whole numbers (item, or a plugin that is whole).
• Bids go up by one coin. Set house.bidding.step.<currency>.
• Nothing moves at all. The house is locked; /uxmauction lock off.