Initial Release

🚢 The game

A viewer takes command of a fleet and duels a CPU opponent, the Admiral. Both fleets are placed
at random and never revealed to the other side. Every !fire is a full exchange — the player shoots,
then the Admiral shoots back — which halves the number of chat commands a battle costs.

Commands

Command	Description
!battleship	Put a fleet to sea and start a battle.
!fire B7	Fire at a square. Accepts b7, B 7, b-7.
!fleet	Redeploy your ships at random. Only before your first shot.
!board	Repost shots, accuracy, ships remaining and your running total.

Board presets — Blitz (6×6, 3 ships), Quick (8×8, 3 ships, the default), Classic (10×10, 5 ships),
or a custom fleet on any grid from 5×5 to 12×12. An optional no-touching rule keeps a one-square gap
around every ship.

Firing at a square twice is rejected without consuming the turn or the clock — a misclick should not
cost a shot.

There is no command to leave a battle. Walking away is what the turn clock is for: it runs out,
whatever has already sunk is settled, and damaged-but-floating ships are charged pro-rata if that
setting is on.

---

🎯 The Admiral

Three skill levels, plus a blunder slider that handicaps any of them by making the AI throw away its
plan and fire blind some percentage of the time.

Level	Behaviour
Ensign	Fires uniformly at random, never repeating a square.
Captain (default)	Hunts: after a hit it works the neighbouring squares, and once two hits line up it follows that axis to both ends.
Admiral	Adds lattice hunting spaced to the shortest ship still afloat, and skips gaps too small for anything still floating.

Measured over 10,000 games per difficulty on the Quick preset: roughly 59, 36 and 30 shots to clear
the board. On Classic: roughly 96, 62 and 52.

The AI never sees the board it is firing at. It is given only the squares it has fired at, what
each turned out to be, and the lengths of the ships still afloat — which sinking announcements make
public anyway. This is enforced by the type it is handed, not by convention.

---

💰 Economy — live, symmetric, per ship

There is no entry fee and no stake. Each ship class carries a configurable value, and every
sinking is a points event applied immediately:

• Sink one of the Admiral's ships → credited on the spot.
• Lose one of your own → debited on the spot.
• Win the battle → an optional flat bonus on top.

Settling live is what closes the rage-quit hole: by the time a battle is going badly the player has
already paid for everything they lost, so walking away saves nothing.

Charge for damaged ships on abandon (default on) closes the remaining ship-granularity gap, where
a player could walk away one hit before a Carrier sank. Timing out charges pro-rata for
hit-but-floating ships — a Carrier at 4 of 5 hits costs 4/5 of its value. It never applies during
normal play.

Guard rails: a minimum balance to play, defaulting to the value of the player's own fleet so
nobody plays a game they cannot lose; balances that clamp at zero; an optional daily winnings cap
that rolls over on its own; per-user and global cooldowns; and Max Battles/Hour.

---

⏱️ Automatic timers

Two clocks, both running on their own so an abandoned battle closes itself.

• Deploy — 60s. Started a battle but never fired. Nothing has sunk, so nothing is charged and it
  is not recorded as a battle.
• Turn — 90s. Chat warnings at 30s and 15s remaining, with the overlay countdown ring
  turning amber and then pulsing red at the same moments. Running out ends the battle and settles
  whatever has already sunk.

Both durations and both thresholds are configurable. A warning threshold that would not fit inside
the turn clock is skipped rather than fired instantly, and the settings page renders the resulting
sequence as a sentence so a misconfigured clock is visible at a glance.

---

📺 OBS Overlay

A self-contained browser source, installed automatically into the overlay folder — no manual file
copying. The background is transparent.

• Two grids side by side: your fleet drawn in full, enemy waters fogged until something is
  hit. Revealing your own ships gives nothing away, since the AI reads neither chat nor the overlay.
• Miss pegs, impact bursts, revealed silhouettes for sunk ships, and a marker on the square that was
  just hit.
• Fleet roster under each board with per-ship damage pips and struck-through sinkings.
• Countdown ring matching the chat warnings, running smoothly between updates rather than ticking
  only when a shot lands.
• Running points total and live accuracy, then a result badge that holds and fades —
  ENEMY FLEET SUNK, FLEET LOST, ABANDONED or STOOD DOWN, each one saying whose fleet
  it was.
• Scale, font scale, every colour, and per-element toggles, all configurable.
• Numbers use the separator configured in the settings window rather than the browser's locale, so
  the overlay and chat always agree.
• Version-stamped and self-upgrading, preserving your previous file as a .bak.

It holds together at every board size. The middle column keeps a fixed share of the width and
refuses to be squeezed by the grids; the cell size gives way instead. The badge measures itself and
steps its size down until it fits, so no wording can overflow whatever the board size and scale —
whole words, always inside the box. Checked across every grid size from 5 to 12, at 100%, 125% and
160% scale, against all four badges: 48 combinations, none clipped, none overlapping, no page
overflow.

OBS Auto-Setup — one button creates the scene and the browser source for you, pointed at the
overlay file, over Streamer.bot's own OBS connection. Configurable connection number, scene name and
source name. If the overlay file is not on disk yet, the setup runs the game action once to install
it, so a first-time setup works without anyone having played a round. It refuses to touch a source
that already exists rather than duplicating it.

---

🔎 Whispered fleets

Optionally whispers each player the positions of their own ships when a battle starts, and again
after a !fleet reroll.

Twitch only — Streamer.bot has no whisper API for YouTube or Kick, and Twitch itself drops whispers
from accounts without a verified phone number. Best-effort by design: a failure is logged and play
continues, because the overlay already shows the player their own fleet.

---

🏆 Leaderboard & Statistics

Every tracked value is written to a persisted Streamer.bot user variable named bsg_*, so any
other action can read a player's record — bsg_shipsSunk, bsg_netProfit — without involving this
game at all.

Tracked: battles played, won, lost and abandoned, shots fired, hits, misses, ships sunk and lost,
flawless victories, fewest-shots win, points won and lost, net, and current and best streak.

!ballstats ranks on net by default — the honest measure now that losing ships costs points —
and can also rank by points won, ships sunk, or accuracy. Accuracy requires at least 25 shots to
qualify, so one lucky shot is not a record.

🥇🥈🥉 medals for the top three, 1–10 places, and optional hiding of the broadcaster and bot account
matched by user id so a name change cannot put them back on the board.

!bstats reports a player's own record, and accepts a name to look someone else up.

Resets — on demand from the settings window with a confirmation spelling out exactly what will be
cleared, or automatically weekly or monthly for running seasons. Two scopes: running totals only, or
every statistic. Enabling automatic resets never wipes anything immediately; the current period is
recorded first and the reset happens at the next boundary.

---

📜 Action log

Every battle is written to a daily file as a structured line, and the settings window reads those
files back as one searchable table.

• Every daily file is read as one list — no picking a day from a dropdown.
• Sortable columns: time, result, user, platform, trigger, board, shots, hits, accuracy, change and
  currency. Click a heading to sort by it.
• Filter by result, by platform, by age (today, last 7 days, last 30 days) and by free-text search
  across every column, with a count of what is showing.
• Selecting a row shows the raw line underneath.
• A Write log file tick box on the General page turns the whole thing off.

---

🎨 Settings window

Searchable page navigation and an unsaved-changes counter with a prompt on close.

SETUP        ⚙️ General · 📺 OBS Overlay · ⏱️ Timers & Cooldowns
BATTLESHIP   🚢 Board & Fleet · 🎯 The Admiral · 💰 Ship Values & Economy
MESSAGES     🎬 Play · 🏆 Result · ⚠️ Errors · 🔔 System
TRACKING     🏅 Leaderboard · 📜 Action Log
HELP         📖 How To Play · ℹ️ About & Links

• Board & Fleet leads with the three preset buttons and shows a live summary —
  "8×8 · 3 ships · 10 of 64 squares occupied · ~36 shots per battle" — plus warnings if a ship no
  longer fits the board or every ship is disabled.
• Timers & Cooldowns renders the warning sequence as a sentence and flags thresholds it will
  ignore.
• Ship Values & Economy keeps the earn and lose sides together, since they are the same number.
• Every message field lists the placeholders it understands, both in the tooltip and below the box.
• Clickable placeholder chips — the `{u...