====== Auction Law ======
 Otherwise known as the player auction handbook. Where players learn how **listing**, **bidding**, **timers**, **fees**, and **delivery** work at Nilgiri shopkeepers — the auction-style market behind [[player:shoplaw|Shop Law]].

A Banking Guild account is required for commerce (''help auction''). Shop-room commands that browse or buy stock without listing or bidding stay on [[player:shoplaw|Shop Law]]; this page is the auction and offer path.

Related: [[player:shoplaw|Shop Law]] · [[player:gamelaw:bankingguild|Banking Guild]] · [[player:gamelaw:postalguild|Postal Guild]] · [[immortal:creationlaw:shops|Creation Law — Shops]] · [[player:gamelaw|Game Law]] (Economy)

===== How to auction (list an item) =====
 At a keeper with ''Acts.SHOPKEEPER'', hand goods with ''auction''. From ''help auction'' and ''MobileScript.shopkeeperActAuction'':

  * ''auction <item> <start-price>''
  * or ''auction <item> for <n> gold''
  * with return postage: ''auction <item> <start-price> minimum <min-price>''

The start price must be greater than zero. A minimum, if set, must be ≥ 0 and ≤ the start price (''S.noAuctMinCost''). The item leaves your inventory into shop storage and appears on ''list''.

In-game help for ''auction'' (base listing covered by taxes; ''Constant.COST_AUCTION_LISTING'' = 0):

<code mud>
> auction headress for 10 gold
You hand a pontiff's headress to the armorer.
Account #0000-10A9 debited 0gc for auction service #00F31DC3 'a pontiff's headress' by Quenyarhun
Okay.
The armorer whispers to you, "Taxes cover the cost of your listing."
>
</code>

With a minimum (in-game help demo; fee follows weight × mail multiplier):

<code mud>
> auction the plate for 500 gold coins at a minimum of 200 with note
You hand the golden eagle breast plate to the armorer.
Account #0000-1000 debitted 106gc for auction service #01A3EEB9 by Quenarhun
Okay.

The armorer whispers to you, "That'll be 106 coins, please."
>
</code>

From ''help auction'': if you list **without** a minimum and the item never sells, the shopkeeper may **dump** it free of charge. If you need the item back, set a minimum and pay the postage deposit. Ask ''value'' on the item first (see [[player:shoplaw|Shop Law]] — Value) for the live listing / shipping quote.

Grammar notes: in-game help spells ''headress''; some help demos print ''debitted'' / ''Quenarhun'' while ''Bank.java'' ledger text uses ''debited'' and ''help auction'' uses ''Quenyarhun''. An older no-minimum sell demo still shows a non-zero listing debit from an older fee table — live ''COST_AUCTION_LISTING'' = 0 and the tax-cover whisper above. Trust the bank line and whisper you see.

===== Offer (bid) =====
 While an item is still in its **auction** window (owner-listed, time remaining), bid with ''offer'', not ''buy''. Bids below the next allowed price are refused; a successful bid debits your account. Example:

<code mud>
> list
The armorer informs you of its auctions and sales:
1) #01A51392 500gc : 'the golden eagle breast plate' (6 days offers:0)
2) #01A513CB 123gc : 'a great golden eagle shield' (6 days offers:0)
3) #01A513D2 61gc : 'a pair of armored golden eagle leggings'
> offer 125 gold for #01a513cb with note
Account #0000-1001 debitted 125gc for auction #01A513CB by Silk
Okay.
The armorer whispers to you, "Thanks for your offer! Your account will be
deducted. Should you be outbid, your offer will be refunded."
> offer 1 gold coin for item #01a51392 with note
The armorer whispers to you, "Your offer is too low. Try 500 gold coins."
> list
The armorer informs you of its auctions and sales:
1) #01A51392 500gc : 'the golden eagle breast plate' (6 days offers:0)
2) #01A513CB 125gc : 'a great golden eagle shield' (6 days offers:1)
3) #01A513D2 61gc : 'a pair of armored golden eagle leggings'
>
</code>

By list number:

<code mud>
> offer 125 gold for #1 with note
Account #0000-1001 debitted 125gc for auction #01A513CB by Silk
Okay.
The armorer whispers to you, "Thanks for your offer! Your account will be
deducted. Should you be outbid, your offer will be refunded."
>
</code>

The next bid must be at least **110%** of the current high bid (or one coin higher when that percentage would not raise the price) — ''Auction.PRICE_INCREASE_PERCENT''. Raising your **own** high bid whispers ''S.raiseOffer'': "Your account is updated and your offer has been raised."

Address items by list number (''#1'') or hex id (''#01A513CB''). Mid-auction items refuse ''buy'' with ''S.auctItemNoSale'': "That item is for auction, not for sale."

===== Auction lifecycle =====
 From ''Auction.poll'', ''AuctionEvent'', ''help auction'', ''Mailer'', and ''Bank'':

  - **List** — ''auction'' stores the item under the keeper; auction clock starts (''Auction.TIME_TO_AUCTION'' = **2 real weeks**).
  - **Bid** — ''offer'' while time remains. List lines show remaining time and ''offers: N''.
  - **Sale window** — if the auction clock ends with **no** offers, the listing enters a **sale** period (''Auction.TIME_TO_SELL'' = **1 real month**). List lines show remaining sale time as ''… sale)''. Asking price drops each real day to **70%** of the prior price (''PRICE_DECREASE_PERCENT'' / ''PRICE_DECREASE_PERIOD''), never below your minimum. Players may ''buy'' at the current sale price (see [[player:shoplaw|Shop Law]] — Buy).
  - **Cancel** — no player cancel command was found in in-game help or the shopkeeper command set; omitted.

Auction resolution is polled about every **30 real minutes** per keeper (''AuctionEvent.PULSE'' = nextPrime(30 × ''Time.MILLIS_PER_MINUTE'')).

==== When someone wins (bids present) ====
 When the auction clock expires **with** at least one offer (''Auction.poll'': ''timeLeft <= 0'' and ''_offers > 0''):

  - The high bidder is mailed the item: ''Mailer.send(bidder, shopkeeper.proper(), item)''. The **from** name is the shopkeeper's proper name.
  - If the bidder is **online** (linked), ''MaildeliverEvent'' runs with the player's mail daemon (default ''S.immMailDaemon'' = "a snowy white owl"): swoop in carrying the item, deliver it, tell ''Mailer.message()'', give the item, then fly away. ''Mailer.message()'' is built as: "You have a package here sent <time phrase> from <shopkeeper>."
  - If the bidder is **offline**, the parcel stays in the mailer queue; collect it at a Postal Guild postmaster with ''mail'' — same ''Mailer.message()'' whisper and hand-over (see [[player:gamelaw:postalguild|Postal Guild]]; sender is the shopkeeper).
  - The seller's bank account is credited the final bid via ''Bank.creditAuction'' — a ledger ''TextEntry'' of the form: ''Account #<id> credited <n>gc for auction item #<hex> '<name>'''. If the account holder is online, ''TextEntry.add'' also ''echo''es that line to them immediately; otherwise it appears later on bank ''balance''. The owner also gets an internal ''Player.log'' auction-sold line (not player-echoed).

No in-game help sample transcript was found for the win mail or seller credit line. In-game help / ''S.java'' have no "you won the auction" string. Verified player-visible win signals are only the mailed package (from the shopkeeper) and the seller's bank credit entry above — so no fabricated win mud demo is shown here.

==== When someone loses ====
 **Outbid (during the auction window).** On a new successful ''offer'', ''Auction.offer'' calls ''Bank.outbid'' for the previous high bidder: the prior bid is credited back with a ''TextEntry'' of the form ''Account #<id> credited <n>gc for auction #<hex> by <new bidder>''. If that player is online, ''TextEntry.add'' ''echo''es the credit line immediately (same string). In-game help / ''S.newOffer'' only promises the refund at bid time ("Should you be outbid, your offer will be refunded."); there is no separate outbid-keeper whisper in help or ''S.java''.

 **Auction ends without your win.** If you were outbid earlier, you already have the credit back; losing bidders are not mailed anything when the high bidder wins.

 **Expire with no bids — return (minimum set).** After the sale period also runs out (''timeLeft <= -TIME_TO_SELL'') and ''_minimum != 0'', ''Auction.poll'' mails the item back to the **owner** with ''Mailer.send(owner, shopkeeper.proper(), item)'' — same package path and ''Mailer.message()'' as a win, from the shopkeeper. In-game help states the postage deposit exists so unsold goods can be returned.

 **Expire with no bids — dump (no minimum / price reaches 0).** From ''help auction'': without a minimum, unsold goods may be dumped free of charge. Code also purges a listing when the discounted sale price reaches **0** (''item.purge()''); that path writes a ''Player.log'' "worthless … dumped" line for the owner but does **not** mail the item back.

Player-visible lose outcomes that in-game help does not sample (outbid ledger line, return package, dump) are described from Java only — not invented as mud transcripts.

===== Fees and timers =====
 From ''help auction'', ''Constant'', and ''Auction'':

  * **Auction window** — ''TIME_TO_AUCTION'' = **2 real weeks**.
  * **Sale window** — ''TIME_TO_SELL'' = **1 real month** after auction ends with no bids.
  * **Daily markdown** — each real day in sale: price × **0.7** (''PRICE_DECREASE_PERCENT'' = 70), floored at your minimum.
  * **Next bid** — ≥ **110%** of current high bid (''PRICE_INCREASE_PERCENT'').
  * **Poll** — about every **30 real minutes** per keeper (''AuctionEvent.PULSE'').
  * **Base listing** — free / covered by taxes when the listing debit is 0 (''COST_AUCTION_LISTING'' = 0; whisper ''Taxes cover the cost of your listing.'' / ''S.taxPaidListing''). Older ''value'' / sell demos may still show a non-zero listing line — trust live ''value''.
  * **Minimum / return postage** — when ''minimum'' > 0, debit adds ''COST_MAIL_MULTIPLIER'' (**2**) × item weight. ''value'' quotes ''shopMailCost'' = 1 + that product as the refundable shipping figure.
  * **Bids** — full offer debited; outbid amounts credited back (''Bank.outbid'').
  * **Identify** — ''COST_IDENTIFY'' = **2** gold (shop path; see [[player:shoplaw|Shop Law]]).

===== Related =====
  * [[player:shoplaw|Shop Law]] — list, value, buy, identify, balance at keepers
  * [[player:gamelaw:bankingguild|Banking Guild]] — accounts, notes, ledger credits
  * [[player:gamelaw:postalguild|Postal Guild]] — receive auction wins and returns
  * [[immortal:creationlaw:shops|Creation Law — Shops]] — immortal shop build
  * [[player:gamelaw|Game Law]] — economy hub