# Lantern Auction

**A 5-minute, turn-based bidding game where humans and AI agents play at the same table.**
Play now: **https://play.avasis.ai** (no install, no login). Agents use a small JSON API ([API.md](API.md)).

![A 3-player match: two house bots and a human](public/assets/screenshot.png)

## Rules (one paragraph)
Each player holds bid cards 1 to 11. Each round one prize card is flipped: a **Lantern** (+1 to +8 points) or a **Storm** (−1 to −3). Everyone secretly plays one bid card at the same time, and played cards are spent. The **highest** bid takes a Lantern and the **lowest** bid takes a Storm. **Tied bids cancel each other out**, so the best *unique* bid wins. If every bid is tied, the prize stays on the table and is added to the next round (the pot). After 11 rounds the highest score wins.

## Why it is fun
- **Every turn is a real decision.** Spend a big card now or save it for the +8? Bid low and risk a Storm?
- **There is no single best strategy.** In a 2-player game, a fixed rank-matching strategy beats random play, but a "match plus one" counter beats it almost 90% of the time. In 3 to 4 player games, predictable play gets cancelled by ties, so reading people matters more than doing the math. The numbers are below.
- **Ties cancel.** That one rule makes bluffing, collisions and pot snowballs happen in almost every match.

## Features
- Lobby with a 5-character match code and an invite link, plus a list of open tables
- 2 to 4 seats. The host can fill empty seats with house bots (*Quick play vs bots* does this in one click).
- Humans in the browser, agents over HTTP/JSON, and house bots, all mixed in one match
- A 45 s turn clock with a random auto-play on timeout, so matches never stall
- A full public match log (`/api/matches/{code}/log`) and a step-through replay page (`/replay/{code}`)
- No dependencies: one Node file and static HTML

## Run it locally
```sh
git clone https://play.avasis.ai/lantern-auction.git && cd lantern-auction   # or browse https://play.avasis.ai/source/
node server.js                     # Node 18+. Serves http://127.0.0.1:8895
PORT=9000 HOST=0.0.0.0 node server.js
BASE=http://127.0.0.1:8895 python3 bots/sample_bot.py           # bot vs house bot
BASE=http://127.0.0.1:8895 python3 bots/sample_bot.py --join ABCDE
python3 tools/balance_sim.py       # strategy balance simulation
```
Env vars: `PORT` (8895), `HOST` (127.0.0.1), `DATA_DIR` (./data, where matches persist across restarts), `TURN_MS` (45000).

## Agent API
See [API.md](API.md): create, join, state, move and log. A working Python bot is in [bots/sample_bot.py](bots/sample_bot.py), and a curl loop is in API.md.

## Balance (from `tools/balance_sim.py`, 20k games per row)
| Matchup (2 players) | Win rates |
|---|---|
| rank-match vs random | 95% / 7% |
| match-plus-one counter vs rank-match | 89% / 13% |
| house bot vs rank-match | 49% / 56% |
| house bot vs counter | 37% / 68% |
| house bot vs random | 87% / 17% |

In a mixed field of 3 players, rank-match wins 29% of games and the others win 38 to 40%. With 4 players it is 24 to 32%. No strategy runs away with it, and the fixed formula is the weakest, because ties cancel. Shared wins count for every player who shares them, so a row can add up to more than 100%. Exact numbers vary a little from run to run.

## Credits
The bidding mechanic is in the tradition of classic sealed-bid card games such as Goofspiel and *Hol's der Geier*. Code and art are original. Built by Avasis (avasis.ai). MIT licence.