towerdef/docs/VERSUS.md
Claude 2098d59c1f Versus mode: attack vs defend (sim, bots, server, client)
One player defends, the other plays the Internet: earns credits over time and
spends them on packets, upgrades and sabotage. Two rounds with swapped roles,
timed (the faster fall wins). Built end to end, NOT yet QA'd or balanced.

Sim (public/js/sim.js, TD.VS table): attacker economy (income, lifetime bonus,
leak payback), spawn / stage / launch convoys, 7 tech tracks, abilities (EMP,
decoy, surge, DDoS), defender tools (scan, patch, repair, quarantine), role-checked
commands, round result, role-private state. Co-op/solo unchanged (24 scripted
games replay identically).

Bots (public/js/bot.js, tools/versus.js): defender (maze + turrets) and attacker
(budgeted spender reading the tower mix); headless bot-vs-bot runner.

Server (server/versus.js, protocol doc): versus rooms with lobby / countdown /
playing / roundover / matchover, role stamping, cross-role refusal, role-private
priv messages at 4 Hz, computer seat, freeze/forfeit rules, no pause/speed.

Client (public/js/versus.js): setup dialog (role, length, vs computer or online),
countdown, defender tools row, attacker unit shop with convoy + launch, tech and
abilities, gateway choice, round/match screens, sounds, phone-first dock rows.

Status and next steps (balance: the attacker currently wins ~100% of bot rounds;
QA with two browsers; layout matrix rerun) are in docs/NEXT.md and docs/VERSUS.md.
The full planned workflow incl. balance/QA prompts is in docs/workflows/versus-full.js.

253 unit tests pass; one smoke e2e run; no other e2e per the user's request.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tb8pW2KAN4oFkh1aK1BfD8
2026-10-11 10:22:29 +00:00

107 lines
9.9 KiB
Markdown

# Versus mode: attack vs defend ("play as the Internet")
> **Status 2026-10-11:** implemented end to end (sim + bots, server + protocol, client UI) but **not QA'd and not balanced**. With the shipped numbers
> the attacker bot wins ~100% of rounds on every map; the cheap 3-credit swarm units (botnet, spam) are the dominant lever (botnet 8 and spam 6
> flips it to ~0%; botnet 6 / spam 4 / worm 8 lands near 75%). The remaining planned steps (balance pass with `tools/versus.js`, independent QA with
> two real browsers) are in `docs/workflows/versus-full.js` (the BALANCE and QA prompts at its end).
Requested 2026-10-10. One player **defends** (builds the maze and turrets, as today); the other **attacks** (earns credits over
time, spends them on spawning packets, upgrades and sabotage). Same board, same rules, one authoritative simulation per room.
Decisions made with the user: timed rounds then swap roles; attacker abilities *and* defender counter-tools; a computer
opponent for either side so it can be played alone.
## Match structure
* A match is **two rounds with the roles swapped** (host picks who starts as what; or random).
* A round ends when the **server falls** (attacker wins, the time it took is recorded) or when the **round timer** runs out
(defender wins; default 12 minutes, host can pick 8 / 12 / 16).
* Match result compares each player's attacking performance: faster fall wins; if neither felled the server, the one who
took off more integrity wins; otherwise draw. Show both rounds side by side on the result screen.
* No pause, no speed control in versus (both would be exploitable). Disconnect: the round freezes up to the 60 s grace; on
expiry the other player wins the round.
## Attacker economy ("bandwidth")
| Rule | Starting value (to be tuned with the bot) |
|---|---|
| Start credits | 150 |
| Base income | 4 credits/s, rising slowly (+0.02/s per second of the round) |
| **Lifetime bonus** | every living attacker unit earns `cost x 0.004` credits per second alive, capped at 50% of its cost in total |
| Leak bonus | a unit that reaches the server pays back its full cost (and damages integrity) |
| Unit shop | every enemy kind has a `buyCost` in the sim's `ENEMIES` table (currently ping 10, worm 6, spam 3, ghost 15, trojan 30, daemon 25, proxy 30, botnet 3, rootkit 180; about 3x the kill reward, to be tuned by the versus balance pass) |
| Caps | at most 250 units alive, 200 staged (performance) |
**Save up and launch.** Units can be bought instantly (`spawn`) or **staged** (`stage`): the price is paid now, the units wait in
a convoy and are released together by `launch` (optionally split over gateways, as a 3 s burst). The defender sees the
*size* of the staged convoy but not its composition. Presets for one tap: Rush (20 pings), Swarm (60 spam), Siege (4
trojans + a healer), Air raid (10 ghosts), Boss (rootkit).
**Tech upgrades** (permanent for the round, apply to units spawned afterwards): Armor (+1 per level, 5 levels), Speed (+8%),
Health (+15%), Regeneration (+1% hp/s), Shield (absorbs damage), Stealth (towers cannot acquire a unit for its first second
on the map, 3 levels), Encryption (resists slows). Costs double per level.
**Sabotage abilities** (credits + cooldown): *EMP* disables one turret for 6 s; *Decoy* a harmless packet every turret
prioritises for 5 s; *Surge* all units +40% speed for 6 s; *DDoS* all turrets fire 40% slower for 4 s (long cooldown).
## Defender economy and counter-tools
* Start credits 250, kill rewards (scaled by unit cost), plus a small trickle (2/s), so the defender can adapt before the first rush.
* Builds, upgrades and sells as today (walls still can never seal the route).
* **Counter-tools:** *Scan* (reveals stealth for a few seconds and clears EMP on turrets in an area), *Patch* (instantly
re-enable an EMPed turret), *Repair* (restore 3 integrity, long cooldown, costs credits), *Quarantine* (freeze every unit on
the board for 2 s, very long cooldown).
## More suggestions (not decided yet)
* Gateway choice per spawn on multi-gateway maps; attacker sees a faint heat-map of where the defender's fire is strongest.
* A short **ready/countdown** before each round so both players are present; a rematch button that swaps roles.
* **Spectators** (third connection, read-only) later.
* **Handicap sliders** in the lobby (attacker income, defender start credits) for mixed-skill pairs.
* Per-map, per-difficulty **leaderboard of attack times** once the server leaderboard exists.
* The bot defender is the maze builder from `tools/bot.js` moved into shared code; the bot attacker is a budgeted spender that
reacts to the tower mix (flyers if there is no anti-air, armoured trojans against filters, saves for a convoy).
## Implementation plan
1. **Sim** (`public/js/sim.js`, pure, with unit tests): `mode: 'versus'`, attacker state (credits, income, tech levels, staged convoy,
cooldowns), commands `spawn`, `stage`, `launch`, `tech`, `ability`, defender tools, round timer and result, role checks
(a command carries the issuer's role; the sim refuses cross-role commands). Add `buyCost` to the enemy table. No automatic waves.
2. **Bots** shared by browser and server (`public/js/bot.js`), driven only through the public sim API.
3. **Server** (`server/room.js`, protocol): room option `mode: 'coop' | 'versus'`, role assignment, ready/countdown, rounds and swap,
per-role command whitelist, attacker data in snapshots, match result message, bot seat. Update `docs/PROTOCOL.md` and tests.
4. **Client**: lobby (mode, role, limit, bot), role-aware HUD: attacker gets the unit shop (the palette becomes the shop), tech panel,
abilities, convoy and Launch, income readout, round timer; defender keeps the build palette plus counter-tools. Phone layout
first (the action bar pattern), same canvas renderer.
5. **Balance** with bot-versus-bot matches over the maps (like `tools/bot.js` does for solo): neither side should win more than
about 60% of rounds on any map.
6. **e2e**: two browsers play a round each way; one bot match.
Depends on the content wave (new enemy kinds become shop items) and on the difficulty/economy constants, so it comes after them.
## Client as built (2026-10-11)
All of it lives in `public/js/versus.js` (`NW.Versus`, created by `main.js`; with no versus game running it does nothing, so solo and co-op are untouched) plus the
`#vsSetup`, `#vsRoom` and `#vsEnd` dialogs in `index.html`, a block at the end of `style.css`, versus cues in `render.js` and the new sounds in `audio.js`.
* **Entering.** Menu -> *Versus* -> setup dialog: your role (Attack / Defend / Random), round length (8 / 12 / 16 min, from `TD.VS.LIMITS`), computer skill (Easy 0.35 /
Normal 0.7 / Hard 1). *Play the computer* starts a `LocalController` match (no server, no lobby: it starts in its 3 s countdown). *Create room* / *Join* (code) go to the
server; an invite link (`?room=`) still opens the co-op lobby dialog and works for a versus room too (the room says what it is).
* **Room (online lobby).** Seats with role badge and ready flag, your role (Attack / Defend / Random), host-only *Opponent: A friend / Computer*, host *Start match* (disabled with the
reason until the opponent is online and ready), guest *I'm ready*. Then a countdown card on the stage ("Round 1 of 2: YOU ATTACK"), round over (`#vsEnd`, both rounds side by side,
*Next round*), match over (the server's verdict from `vs.winner` / `vs.forfeit`, never recomputed; *Rematch (roles swap)*). A frozen room (opponent offline) shows a PAUSED card.
* **Defender HUD.** Today's tower palette, plus a tools row under it: Scan (tap, then tap the map; radius ring follows the pointer), Patch (re-enables the selected disabled tower, else
the one with most EMP left), Repair, Quarantine (second tap to confirm, like every action of 150+ credits). Each has a cooldown ring + seconds and greys out when it cannot be afforded.
* **Attacker HUD.** The palette becomes the unit shop (every `TD.ENEMY_ORDER` kind with `buyCost`, price shown for the chosen quantity; a tap buys; fewer is bought when credits fall short),
then a row `[x1|x5|x10] [Send|Stage] [Any gate|Gate n] [LAUNCH n + convoy composition]`, the four abilities with cooldown rings (EMP: tap it, then a tower; or select a tower and use the
button in its action bar), and the tech row (7 upgrades, level pips, price doubling per level). Credits (smoothly run forward from the 4 Hz `priv` data) and income are in the top bar,
units alive and the defender's credits in a pill on the stage. Tapping a gateway (or the gate button) chooses where packets enter; units appearing at a gateway pulse it for both sides.
Keys: 1-9 buy that unit, Space launches. Optimistic local bookkeeping (credits, cooldown start) is overwritten by the next `priv`.
* **Layout.** Stacked layouts: the dock (convoy row + abilities / tools) is pinned to the bottom of the side panel and the board gets less height (`V.minSide`); the tech row scrolls like the
shop. Short landscape: the shop and tech are scrolling grids in the 200 px column, the abilities keep four columns as icon + cost.
* **Rendering.** EMP'd towers are dimmed with hazard stripes, sparks and a draining arc; armed EMP outlines every target; decoys are dashed-ringed and half transparent (from the `decoy`
event on the wire, `m.decoy` locally); the attacker sees its own stealth (cloak shimmer for the first seconds) and shield (ring) because the wire carries neither (inferred from its tech
levels when the unit first appears, exact in a local match); Surge (orange edge), DDoS (violet scan lines), Quarantine (icy tint) and Scan zones are drawn for both sides. The defender
deliberately sees no stealth or shield cue (it does not know the attacker's tech).
* **Known limits.** A local match cannot be paused (versus has no pause; `LocalController.ctl` ignores it), so opening the menu in a computer match leaves the round running behind it.
Presets (Rush, Swarm, ...) from the design are not in the UI yet; the x1/x5/x10 selector covers most of it.