towerdef/docs/workflows/versus-full.js
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

109 lines
19 KiB
JavaScript

export const meta = {
name: 'netwall-wave4-versus-mode',
description: 'Wave 4: attack-vs-defend multiplayer: sim rules + bots, then server/protocol, then client UI, then bot-vs-bot balance, then independent QA (strictly sequential, one owner at a time)',
phases: [
{ title: 'Sim', detail: 'versus rules, economy, abilities, bots (pure, tested)' },
{ title: 'Server', detail: 'rooms, roles, rounds, protocol, bot seat' },
{ title: 'Client', detail: 'lobby, role-aware HUD, attacker shop, tools, phone-first' },
{ title: 'Balance', detail: 'bot-vs-bot matches, time-boxed' },
{ title: 'QA', detail: 'two real browsers play a full match' },
],
}
const SP = '/tmp/claude-1000/-home-jav-git-towerdefence/417476cf-3c23-4caf-be25-6f9a83ee50b9/scratchpad'
const ROOT = '/home/jav/git/towerdefence'
const COMMON = `
PROJECT: "Netwall", an HTML5 maze-building tower defence game: solo in the browser, two-player co-op through a Node server (ws). Repo: ${ROOT} (git repo; do NOT run git commit/push or checkout/reset/stash: the lead commits).
Read ${ROOT}/README.md, ${ROOT}/docs/NEXT.md, ${ROOT}/docs/PROTOCOL.md and ESPECIALLY ${ROOT}/docs/VERSUS.md (the design the user approved: attack-vs-defend, timed rounds then swap roles, attacker abilities AND defender counter-tools, a computer opponent for either side).
Layout: public/ (index.html, css/style.css, js/sim.js shared PURE rules (browser solo + Node server), js/controllers.js Local+Remote, js/render.js, js/main.js UI/input/lobby, js/audio.js, sw.js), server/ (Node + ws), test/ (node:test; ONLY real test files), e2e/ (Playwright scenarios, "npm run e2e [-- filter]"), tools/bot.js (headless defender bot used for balancing).
ENVIRONMENT: no system Node. First: source ${SP}/pwenv.sh. playwright-core is in ${ROOT}/node_modules. Launch with chromium.launch({args:['--no-sandbox']}). Examples: ${ROOT}/e2e/scenarios/*.js. Look at screenshots with the Read tool. Real server: cd ${ROOT} && PORT=<yours> HOST=127.0.0.1 node server/index.js (serves public/ too). Use ONLY your port range; KILL every server/browser you start by port (ss -ltnp | grep :PORT), never a broad pkill. Scratch work in ${SP}/wave4/<key>/, never in the repo.
Compatibility rules: (1) sim.js stays PURE and DOM-free; (2) the existing co-op/solo behaviour and wire format must keep working unchanged (versus is an additional mode); (3) never assume 3 tower levels, a fixed tower/enemy count or exactly 2 maps; (4) no new dependencies, vanilla JS, classic scripts (no ES modules) in public/; (5) every new rule has a unit test, every new UI behaviour an e2e assertion that FAILS without it; (6) phones first: all new controls must be reachable by thumb on 320x568, 390x844 and 667x375, in the same compact/bar patterns the UI already uses (read public/css/style.css and main.js layoutBars/towerbar code first, and extend the 22-layout matrix e2e/scenarios/05-layout-matrix.js for new controls).
CURRENT STATE you build on (all of this exists and is tested): 7 maps, 9 towers (wall, filter, ids, mortar, throttle, arc, sandbox, balancer, uplink; the Uplink has 4 levels and gets dearer per owned unit via TD.priceFor/upgradePrice and a per-tower price multiplier 'pm' carried as the 9th field of tower rows), 9 enemy kinds in TD.ENEMY_ORDER (ping, worm, trojan, spam, ghost, rootkit, daemon healer, proxy shielded, botnet swarm) each with a buyCost, an Easy/Normal/Hard difficulty option for solo and co-op (versus IGNORES difficulty: units use base stats x attacker tech, no wave hp scaling), idempotent upgrade/wave commands ('stale'), a shared priceOf in the UI, 17 e2e scenarios and 156 unit tests, and phone UI patterns (layoutBars, #confirm and tower bars, compact overlays with pinned footers, role=dialog handling). Read the code before extending it; do not undo any of it.
MACHINE NOTE: the box is shared and slow under load; e2e timing checks can flake: rerun a failing scenario alone before concluding anything; the full layout matrix takes ~8 minutes.
Aim for about 75 minutes of focused work per agent; do not gold-plate; "node --test" and "npm run e2e" must be green when you finish.
BINDING CONTRACT between the agents (names are exact; extend, do not rename):
SIM
- new TD.Sim({ map, mode: 'versus', limit: 720 }). In versus: no automatic waves, startWave refused, no clear bonus, no win-wave; hp scaling by wave is off (units use base stats x attacker tech); state stays 'playing' until the round ends; then sim.state = 'over' and sim.vs.result = { winner: 'attacker'|'defender', t: <seconds>, integrityLost: n }.
- sim.cmd({ c, role, by, ...fields }) where role is 'defender' | 'attacker' (the server fills role from the seat; the sim REFUSES cross-role commands with reason 'role'). Solo/co-op commands (no role) behave exactly as before.
- defender commands: place, sell, upgrade, target (as today) and { c:'tool', id:'scan'|'patch'|'repair'|'quarantine', x?, y?, tid? }.
- attacker commands: { c:'spawn', kind, n?, gate? } buy and release now; { c:'stage', kind, n? } pay now, hold in the convoy; { c:'launch', gate? } release the convoy as a ~3 s stream; { c:'tech', id } buy the next level; { c:'ability', id:'emp'|'decoy'|'surge'|'ddos', tid?, gate? }. 'gate' is a spawn index (default: round robin).
- Every command returns { ok, reason? }. Reasons used: 'role','credits','cooldown','cap','max','bad_target','over'.
- sim.snapshot() gains a SHARED block 'vs': { t, lim, st /*staged count*/ } only. Role-private data comes from sim.privateState(role) -> attacker: { credits, income, tech:{armor,speed,health,regen,shield,stealth,crypt}, staged:[[kind,n]], cd:{emp,decoy,surge,ddos}, active:{surge,ddos} } ; defender: { cd:{scan,patch,repair,quarantine} }. fullState() carries mode, limit and map as today.
- ENEMIES entries have 'buyCost' (already added to every enemy kind by an earlier agent; verify).
- events: 'spawn' not needed; add { e:'emp', id }, { e:'surge' }, { e:'ddos' }, { e:'quarantine' }, { e:'scan', x, y }, { e:'repair' }, { e:'round', winner, t } as needed (small objects).
BOTS (public/js/bot.js, UMD like sim.js: window.NWBot / module.exports): NWBot.create(sim, role, { seed, skill }) -> { think(dt) } driven ONLY through sim.cmd/sim.preview/sim.privateState (the same API humans use). Defender bot: a productionised, lighter version of the maze+turret logic in tools/bot.js (reuse its ideas, keep it < ~400 lines, no heavy analytic model needed). Attacker bot: a budgeted spender that watches the tower mix (flyers when there is no anti-air, armoured units against filters/arcs, healers behind trojans), saves credits for convoys, buys tech, uses abilities sensibly.
PROTOCOL (see docs/PROTOCOL.md; add a "Versus" section)
- join/create takes { mode:'coop'|'versus' (default coop), limit?:480|720|960, rounds?: 2 }.
- versus lobby messages (client -> server): { t:'vs', c:'role', v:'attacker'|'defender'|'random' }, { t:'vs', c:'ready', v:boolean }, { t:'vs', c:'bot', v:'attacker'|'defender'|null } (host: put a computer in the empty seat with that role), { t:'vs', c:'start' } (host, when everyone is ready), { t:'vs', c:'next' } (continue after a round), { t:'vs', c:'rematch' }.
- server -> client: { t:'vs', phase:'lobby'|'countdown'|'playing'|'roundover'|'matchover', round:1|2, rounds, roles:{ '<slot>': 'attacker'|'defender' }, bot:{ slot?, role }|null, countdown?:seconds, limit, result?:{...}, scores?:[{slot, name, fellAt|null, integrityLost}] } on every change; role-private data { t:'priv', role, ...sim.privateState(role) } to each human at 4 Hz while playing; snapshots as today with the shared 'vs' block.
- commands arrive as { t:'cmd', c:..., ...} exactly as today; the server adds role from the seat. ctl pause/speed are rejected in versus ({t:'reject', reason:'versus'}).
- disconnect: the round freezes for the 60 s grace, then the remaining player wins the round.
MATCH RULES: two rounds, roles swapped after round 1 (host's first role choice, or random); a round ends when integrity reaches 0 (attacker wins, time recorded) or the timer hits the limit (defender wins). Match winner = the player whose attacking round ended earlier; if neither felled the server, the player who took off more integrity; else a draw.
ECONOMY (starting numbers, tuned later by the balance agent through constants in one VS table at the top of sim.js): attacker start 150, income 4/s + 0.02/s per second elapsed, lifetime bonus buyCost*0.004 per second alive capped at 50% of buyCost per unit, leak pays back the unit's buyCost; caps 250 units alive / 200 staged; defender start 250, trickle 2/s, kill reward round(buyCost*0.4); tech levels: armor +1 (5 levels), speed +8% (5), health +15% (5), regen +1% max hp/s (3), shield +40 per level (3), stealth: towers cannot target a unit for its first 1/1.5/2 s on the map (3 levels), crypt: resists slows 20/40/60% (3); costs 100*2^level. Abilities (credits, cooldown): emp (disable one tower 6 s; 80cr, 20 s), decoy (a harmless unit every tower prioritises 5 s; 60cr, 25 s), surge (all units +40% speed 6 s; 120cr, 40 s), ddos (all towers fire 40% slower 4 s; 200cr, 70 s). Defender tools: scan (clear emp + reveal stealth in radius 4 for 3 s; 40cr, 15 s), patch (instantly re-enable one tower; 30cr, 8 s), repair (+3 integrity up to max; 120cr, 30 s), quarantine (all units frozen 2 s; 150cr, 60 s).`
const RESULT = {
type: 'object',
properties: {
summary: { type: 'string' },
implemented: { type: 'array', items: { type: 'object', properties: { what: { type: 'string' }, details: { type: 'string' } }, required: ['what', 'details'] } },
contractChanges: { type: 'array', items: { type: 'string' } },
filesChanged: { type: 'array', items: { type: 'string' } },
testsAdded: { type: 'array', items: { type: 'string' } },
unitTests: { type: 'string' },
e2e: { type: 'string' },
notes: { type: 'string' },
},
required: ['summary', 'implemented', 'unitTests', 'e2e'],
}
const SIM = `${COMMON}
YOUR BRIEF (agent "vs-sim", ports 8610-8619). You OWN public/js/sim.js, public/js/bot.js (new), test/sim-versus.test.js (new), tools/ additions. Implement the SIM and BOTS part of the contract: versus mode in the Sim (economy, spawn/stage/launch, tech, abilities, defender tools, role checks, round timer and result, private state, snapshot vs block, events), the shared VS constants table at the top, and public/js/bot.js with a defender bot and an attacker bot. Also add a headless runner tools/versus.js: "node tools/versus.js --maps open,twin --limit 600 --seeds 6 [--attacker-skill 1 --defender-skill 1]" that plays bot-vs-bot rounds and prints a table (who won, time to fall, integrity lost, credits spent, units spawned) so the balance agent can tune later; keep it fast (all CPU cores via worker threads or child processes like tools/bot.js).
Unit tests (test/sim-versus.test.js) must cover: role refusal both ways, credits and caps, spawn vs stage vs launch, lifetime bonus and its cap, leak payback, every tech level effect on a spawned unit (armor, speed, health, regen, shield, stealth: towers skip a stealthed unit; crypt), each ability and tool incl. cooldowns and costs (emp disables a tower for its duration, decoy is prioritised and harmless, surge, ddos slows fire, scan reveals/clears, patch, repair never exceeds max, quarantine freezes), round end both ways and the result object, privateState shape, snapshot JSON round trip with the vs block, no regression of solo/co-op (existing tests keep passing), and bot smoke tests (a bot round runs to completion without throwing and without illegal commands on all maps).
Keep co-op/solo behaviour byte-identical when mode is not 'versus'.`
const SERVER = (prev) => `${COMMON}
YOUR BRIEF (agent "vs-server", ports 8620-8629). The sim agent finished (report: ${JSON.stringify(prev)}). You OWN server/*, test/server.test.js (and new test files for versus), docs/PROTOCOL.md, docs/DEPLOY.md only if needed, and public/js/controllers.js ONLY for the RemoteController message handling of the new messages (vs / priv) and exposing them (ctrl.vs, ctrl.priv, events 'vs' and 'priv'), plus LocalController support for a local versus game against a bot (ctrl.kind 'local', the human has a role and NWBot plays the other seat; no pause/speed). Implement the SERVER and PROTOCOL part of the contract: room mode versus, the lobby/ready/countdown/round/roundover/matchover state machine, seats and roles (random/choose/swap), the optional bot seat (server-side NWBot ticking with the room loop, think() at about 4 Hz, commands go through the same validated path as humans), role added to commands from the seat and cross-role refusal surfaced as reject, ctl pause/speed rejected, private data messages at 4 Hz, grace/forfeit rules, host migration, rematch, disconnect during countdown/roundover, snapshot size sanity, and docs/PROTOCOL.md "Versus" section. Security: a client can never see the other role's private data, never send commands for the other role, malformed vs messages count as malformed, and a bot seat cannot be used to run unbounded work (cap thinking time per tick).
INTERRUPTED EARLIER ATTEMPT: a previous run of this agent was cut off by an account spend limit in the middle of its work. The working tree already contains its UNVERIFIED partial work: server/versus.js, test/server-versus.test.js, test/controllers-versus.test.js, edits to server/room.js, server/index.js, public/js/controllers.js and docs/PROTOCOL.md; "node --test" currently shows about 4 failing tests because of it. Start by reading "git status" and "git diff", understand what is there, review it critically against the contract (do not trust it), keep what is good, fix what is wrong, finish what is missing, and make everything green. Do not duplicate files.
Tests: protocol tests with raw ws clients for the full match (two humans, and human + bot), role leaks, forged role, reconnect mid-round, forfeit, rematch, and that co-op rooms behave exactly as before.`
const CLIENT = (prev) => `${COMMON}
YOUR BRIEF (agent "vs-client", ports 8630-8639). The sim and server agents finished (reports: sim ${JSON.stringify(prev.sim)}; server ${JSON.stringify(prev.server)}). You OWN public/index.html, public/css/style.css, public/js/main.js, public/js/render.js, public/js/audio.js (new sfx) and e2e/. Implement the CLIENT part: (1) lobby: mode choice Co-op vs Versus, role choice (attacker / defender / random), round time limit, 'play against computer' (a bot in the other seat; also a SOLO versus game that needs no server using LocalController), ready/start/countdown, round-over and match-over screens (both rounds side by side, who won, rematch); the lobby/menu slots #menuOpts and #roomList exist (reserved earlier) but are not required for this; (2) ROLE-AWARE HUD: the defender keeps today's build palette plus a counter-tools bar (scan, patch, repair, quarantine with cooldown rings and costs) and the round timer; the attacker gets: the palette becomes the UNIT SHOP (all enemy kinds with buyCost, tap = buy 1, a x1/x5/x10 quantity selector, a Send-now/Stage toggle), a Convoy readout with a big LAUNCH button, a tech panel (7 upgrades with level pips and cost), an abilities bar (emp: tap then tap a tower; decoy; surge; ddos) with cooldown rings, the credits + income/s readout, units alive, round timer; the attacker cannot place towers; the attacker sees the defender's board live; (3) rendering for versus: units already render; add shield/stealth/decoy/emp visuals (a disabled tower looks disabled), surge/ddos/quarantine screen cues, spawn pulses at gates the attacker chooses (an attacker can tap a gateway to choose it); (4) phone-first layouts using the existing bar patterns (attacker shop must scale to 9+ unit kinds, convoy/launch always reachable), add the new controls to the 22-layout matrix (e2e/scenarios/05-layout-matrix.js) with the same objective reachability assertions; (5) sounds for the new actions; (6) help text for versus; (7) e2e: a scenario with TWO browsers (one attacker, one defender, real server) that plays a full short round (limit 60 s via a test option or server option), checks role-private data does not leak into the other client, the swap, the match result, plus a solo-vs-bot scenario; (8) keep co-op and solo untouched.`
const BALANCE = (prev) => `${COMMON}
YOUR BRIEF (agent "vs-balance", ports 8640-8649). All parts exist now (reports: ${JSON.stringify(prev)}). TIME-BOX HARD: at most 12 runs of tools/versus.js (each run in the background with a wait; do not babysit), then stop. You OWN only the VS constants table at the top of public/js/sim.js, the enemy buyCost values, and public/js/bot.js tuning. Goal: neither side wins more than about 60% of rounds on any of the 7 maps when two equally skilled bots play (limit 720 s); the defender must be able to survive a sensible attacker for a good while on easy maps; the attacker's lifetime bonus must matter but not snowball; abilities and tools must be used by the bots and matter. Report a before/after table and every constant you changed. Keep all tests green.`
const QA = (all) => `${COMMON}
YOUR BRIEF (independent QA, ports 8650-8659). Versus mode was built in 4 steps: ${JSON.stringify(all)}.
1. Run "cd ${ROOT} && node --test" and "cd ${ROOT} && npm run e2e" yourself (the layout matrix takes ~6 minutes); report exact results.
2. PLAY a full match with TWO real browsers (a desktop and a 390x844 phone with CDP touch) on the real server: humans in both roles, then human + bot in both roles, then solo versus bot with no server. Look at screenshots (Read tool) of every state: lobby, countdown, attacker shop (all unit kinds), staging and launch, tech, abilities, defender tools, round over, match over. Judge thumb reach, clarity, clutter, and whether a first-time attacker would understand what to do.
3. ATTACK the implementation: attacker sends defender commands and vice versa (raw ws), forged role, spamming spawn to hit caps, negative/huge n, NaN, staging 10^6 units, launching an empty convoy, using an ability on a dead tower, disconnect mid-round (both sides), reconnect, host leaves, rematch spam, three clients in a versus room, a coop client joining a versus room. Check the defender can never read attacker credits/composition from any message, the server stays responsive with a bot seat and 250 units, and snapshot size stays sane.
4. Review "git diff"/"git status" for sloppy code, protocol/doc/code mismatches, leftover debug.
Fix trivial regressions yourself (say what); report bigger issues with exact repro. No new features.`
phase('Sim')
const sim = await agent(SIM, { label: 'vs-sim', phase: 'Sim', schema: RESULT })
phase('Server')
const server = await agent(SERVER(sim), { label: 'vs-server', phase: 'Server', schema: RESULT })
phase('Client')
const client = await agent(CLIENT({ sim, server }), { label: 'vs-client', phase: 'Client', schema: RESULT })
phase('Balance')
const balance = await agent(BALANCE({ sim, server, client }), { label: 'vs-balance', phase: 'Balance', schema: RESULT })
phase('QA')
const qa = await agent(QA({ sim, server, client, balance }), {
label: 'qa', phase: 'QA',
schema: {
type: 'object',
properties: {
unitTests: { type: 'string' }, e2e: { type: 'string' },
regressions: { type: 'array', items: { type: 'string' } },
changedByQa: { type: 'array', items: { type: 'string' } },
securityFindings: { type: 'array', items: { type: 'string' } },
uxProblems: { type: 'array', items: { type: 'string' } },
verdict: { type: 'string' },
},
required: ['unitTests', 'e2e', 'verdict'],
},
})
return { sim, server, client, balance, qa }