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
30 KiB
Netwall multiplayer protocol (v1)
Two people play the same map together: one shared base, one shared credit pool, one shared set of lives.
The Node server runs the game (the same public/js/sim.js the browser uses for solo play) and is the
single source of truth. Clients send commands; the server steps the simulation and broadcasts snapshots.
Clients never simulate in multiplayer; they render (with interpolation) what the server says.
A room is either co-op (this document up to "Tick loop") or versus (attack vs defend, see "Versus" at the end: same transport, same
snapshots, plus lobby / role-private messages); join.mode picks.
Transport: one WebSocket per player at ws(s)://<host>/ws, JSON text frames, one object per frame, field t
= message type. Client -> server frames are capped at 2048 bytes (maxPayload).
Server
server/index.js exports createServer(opts) and, when run directly (node server/index.js), starts it.
createServer({ port = 8080, host = '::', publicDir = <repo>/public,
graceMs = 60000, snapshotHz = 20, maxRooms = 50,
trustProxy = 'auto', trustedProxies = null, allowedOrigins = [], maxConnPerIp = 40, pingMs = 25000,
log = console.log })
-> Promise<{ port, addresses: string[], close(): Promise<void>, rooms: Map }>
Env when run directly: PORT (8080), HOST (::), TRUST_PROXY (auto|1|0), TRUSTED_PROXIES (comma separated
IPs / CIDRs added to the private ranges that auto trusts; a bad entry stops the start-up), ALLOWED_ORIGINS
(comma separated, e.g. https://game.example.com; include :port when it is not 80/443), MAX_CONN_PER_IP, GRACE_MS.
Prints http://localhost:PORT/ and every non-internal LAN URL from os.networkInterfaces() (IPv4 as
http://a.b.c.d:PORT/, IPv6 as http://[addr]:PORT/, skip link-local fe80::).
Handles SIGINT/SIGTERM by closing sockets and exiting 0.
Dual stack
Default host is :: and the listen call must pass ipv6Only: false so that one socket serves IPv4 and
IPv6 (IPv4 arrives as ::ffff:a.b.c.d; normalise it for logs). If binding :: fails with EAFNOSUPPORT,
EADDRNOTAVAIL or similar (IPv6 disabled in the container), fall back to 0.0.0.0 and log that. Any explicit
host (e.g. 127.0.0.1 in tests, or HOST=0.0.0.0) is honoured as given. addresses lists what is bound.
Behind a reverse proxy (nginx Proxy Manager, nginx, Caddy, Traefik)
The server is meant to sit behind TLS-terminating proxies with "Websockets Support" enabled and must work both at a domain root and under a path prefix the proxy strips.
- Keep-alive. Every
pingMsthe server sends a WebSocket protocol ping to each socket and terminates sockets that did not pong since the previous round (so a dead mobile client is noticed within ~2 rounds and goes into the grace period). The pings are for dead-peer detection: a joined socket gets ~20 snapshots/s anyway, which is what keeps a proxy's idle timer (nginxproxy_read_timeout; 60 s by default, 90 s in nginx Proxy Manager) quiet. - Real client IP is used only for logging and the per-IP socket cap
maxConnPerIp.trustProxy:'auto'means: if the TCP peer is loopback / RFC1918 /fc00::/7/ link-local (or listed intrustedProxies), take the client IP fromX-Forwarded-For(elseX-Real-IP): the rightmost entry that is not a private address (proxies append, so entries further left are the client's own forgeable claim); otherwise use the TCP peer and ignore those headers.true/falseforce it.maxConnPerIp: 0disables the cap. Reject extra sockets with HTTP429on upgrade. - Origin check (see below) accepts: Origin host ==
Hostheader; or ==X-Forwarded-Hostwhen the proxy is trusted; or, when the proxy is trusted andHosthas no port, the same host name on any port (nginx'sHost $host, which nginx Proxy Manager uses, drops the port ofhttps://game.example.com:8443); or the Origin is listed inallowedOrigins. Compare scheme-lesshost[:port], treat default ports (80/443) as equal to "no port", case-insensitive. - No absolute URLs, no hard-coded port anywhere in served content; the client builds the socket URL relative
to the page (
new URL('ws', location.href)withhttp->ws,https->wss), sohttps://x.example/netwall/proxied to/works. The server therefore accepts the upgrade on path/wsonly (the proxy strips any prefix). HEAD/GET /healthzreturns200 okfor proxy health checks.- Do not trust
X-Forwarded-Protofor anything security relevant. - Disable
wsper-message-deflate (default for the server) - snapshots are small and CPU is better spent elsewhere.
HTTP
GET|HEADof files underpublic/only./->index.html. Correct MIME (html, js, css, json, svg, png, jpg, ico, woff2, mp3, ogg, wav, txt).Cache-Control: no-cache.- Path traversal (
..,%2e%2e,%2f, backslash, NUL, absolute paths, dotfiles) -> 400/404, never a file outsidepublic/. Other methods -> 405. GET /healthz->200 ok.- Headers on every response:
X-Content-Type-Options: nosniff,Referrer-Policy: no-referrer,Content-Security-Policy: default-src 'self'; connect-src 'self' ws: wss:; img-src 'self' data:; style-src 'self' 'unsafe-inline'; media-src 'self' data:; base-uri 'none'; frame-ancestors 'none'.
WebSocket upgrade
- Only on path
/ws. If the request has anOriginheader, its host must equal theHostheader (or one of the trusted-proxy /allowedOriginscases above), else403(stops random web pages from driving a LAN server). NoOrigin(non-browser clients/tests) is fine. - A socket that has not sent a valid
joinwithin 10 s is closed (4408). - Per-socket rate limit: token bucket 60 msg/s, burst 120; beyond that close with 4429.
- More than 20 malformed/unknown messages on a socket -> close 4400.
Handshake
Client's first message:
{ t:'join', pid, name, room?, map?, difficulty?, mode?, limit?, rounds? }
pid^[A-Za-z0-9_-]{8,40}$- random, generated by the client, kept insessionStorage(stable across reloads).nameany string; server trims, strips control chars, caps at 16 chars, default"Player".roomabsent -> create a room.mapmust be a key ofTD.MAPS(default'open').difficultymust be a key ofTD.DIFFICULTIES('easy','normal','hard'; default'normal',nullcounts as absent), see "Difficulty" below. Server generates a 4 character code fromABCDEFGHJKLMNPQRSTUVWXYZ23456789, unique among rooms.mode,limit,rounds(creating join only):modeis'coop'(the default;nullcounts as absent) or'versus'(see "Versus" below). For'versus',limitis the round length in seconds, one ofTD.VS.LIMITS(480, 720, 960; default 720) androundsmust be 2. They are checked aftermapanddifficulty. A co-op creating join ignoreslimitandrounds.roompresent (^[A-Za-z0-9]{4}$, case-insensitive -> upper-cased) -> join.map,difficulty,mode,limitandroundsare ignored on a join (not even validated): the joiner gets the room's, instate.map/state.difficulty(andstate.mode/state.limitin versus) of thejoinedmessage. A reconnect (samepid) is a join.
Failure: { t:'error', code, msg } then the server closes the socket (code 4000+).
Codes: bad_request, no_room, full (two other pids already hold the slots, or a computer holds the second seat of a running versus match),
too_many_rooms, bad_map, bad_difficulty
(a creating join whose difficulty is not one of the table's keys: wrong type, 'toString', '__proto__', ... all refused, no room is
created, the socket closes with 4400; a bad map is checked first), bad_mode (mode is neither 'coop' nor 'versus'), bad_limit (versus limit not in
TD.VS.LIMITS, or not a number), bad_rounds (versus rounds is not 2). The three new codes also close with 4400 and create no room.
Success: reply to the joiner
{ t:'joined', room, resumed, you:{ pid, slot, host },
players:[ { pid, slot, name, host, online } ], // everyone incl. you
state: <sim.fullState()>, snap: <sim.snapshot()>, speed, paused }
then broadcast { t:'players', players:[...] } to all other players.
pid is the reconnect secret (whoever presents it takes the slot), so in every players list it is the viewer's own
pid for the viewer's own entry and an opaque, stable per-room alias for the other player's entry. Compare entries by
pid within the lists you receive and find yourself with you.pid; never expect to see the other player's real pid.
- A player owns a slot (0 or 1), the lowest free one, kept until they leave for good.
- Host = creator; if the host leaves for good the other player becomes host.
- Reconnect: a
joinwhosepidalready holds a slot in that room re-binds to it (resumed:true); the old socket, if still open, is closed with 4001. Nofullerror for the pid that owns the slot. - Grace: when a socket closes the player stays in the room with
online:falseforgraceMs, then is removed (andplayersre-broadcast). A player who sent{t:'leave'}is removed immediately. - The simulation only ticks while at least one player is online. A room with no one left is deleted.
Client -> server (after joining)
| message | meaning |
|---|---|
{t:'cmd', c:'place', type, x, y} |
build. Server calls sim.cmd({...msg, by: slot}) (never trust a by from the client) |
{t:'cmd', c:'sell', id} / 'upgrade' id, lv? / 'target' id,mode / 'wave' n? / 'auto' v / 'continue' |
other sim commands, same path. lv and n make upgrade and wave idempotent, see below |
{t:'ctl', c:'pause', v:bool} / {t:'ctl', c:'speed', v:1|2|3} |
room-level; reflected in snap.pa / snap.sp |
{t:'cursor', x, y} |
hover position in cell units (floats) or x:null to hide; clamp to board, round to 2 dp |
{t:'mark', x, y} |
map ping; at most 1 per 400 ms per player; server broadcasts mark (below) |
{t:'rtt', ts} |
latency probe; reply immediately with the same ts |
{t:'sync'} |
ask for a full state resend |
{t:'newgame', map?, difficulty?} |
host only: replace the sim with a fresh new Sim({map, difficulty}); resets pause/speed. An absent (or null) map / difficulty keeps the room's current one, so a plain {t:'newgame'} is "play again" |
{t:'leave'} |
leave now |
{t:'vs', c, v?} |
versus rooms only (malformed in a co-op room): role, ready, bot, start, next, rematch; see "Versus" |
Idempotent upgrade and wave. Two players who press Upgrade (or Next wave) at the same moment both send the command; without
a guard the tower would be upgraded twice and the second player charged for a level they never asked for, or two waves would start.
Both commands therefore carry what the sender saw: lv (upgrade) is the tower level on the sender's screen, n (wave) is the wave
number the sender expects the command to start (the wave counter they saw, plus one). The sim applies the command only if that still
holds; otherwise nothing changes and the sender gets { t:'reject', c, reason:'stale', id? }. Clients treat stale as "your partner
was a moment faster" and show nothing. Both fields are optional (no field, no check: older clients, the balance bot and the server's
own auto-wave timer send none); when present they must be integers, anything else is a malformed message. stale is checked after
over / no_tower and before max / gold, so a sender who is behind is told it is stale rather than that the tower is maxed out.
Command validation is the server's job: t:'cmd' must carry a string c in the whitelist above; unknown
c, non-object, etc. count as malformed. A command the sim refuses ({ok:false, reason}) gets
{ t:'reject', c, reason, x?, y?, id? } sent to the sender only (echo x,y/id when present).
Successful commands send nothing extra; the effect arrives via snap.
newgame from a non-host -> reject with reason:'not_host'; newgame with a bad map -> reject bad_map; with a bad difficulty
-> reject bad_difficulty (checked in the order not_host, bad_map, bad_difficulty; a rejected newgame changes nothing and sends no state).
Client behaviour that the protocol relies on
- Dead connections. A joined socket gets ~20
snaps per second even when the game is paused, so the client treats 5 s without any frame as a dead socket (a half-open connection after a Wi-Fi / cell switch or a NAT / proxy drop never delivers a close for a minute or more). It shows its "reconnecting" state at once, detaches the old socket and opens a new one with the samejoin(samepid); the server hands the seat to the new connection and closes the old one with 4001, which the abandoned socket ignores. A socket that has not reachedjoined10 s after it was opened is abandoned the same way. Retries back off up to 5 s, 14 in all. - Tower lists.
twis sent once perrevchange and must never be lost, whatever the render rate: a client that is stalled (hidden tab, long frame) and gets a burst of snapshots keeps the newest undisplayedtwwhen it trims its interpolation buffer, and asks forsyncifsnap.revand the rev of the last applied list ever disagree. - "No such room" after a reconnect (
error/no_roomin answer to ajoinfor the room the client was in) means the server restarted (rooms live in memory only) or the room expired. The client says so ("The server restarted, your game was lost.") and forgets the saved room; after a plain connection failure it keeps the saved room, because the seat is held forgraceMs.
Server -> client
{ t:'snap', seq, ...sim.snapshot(), ev:[ ...sim.drainEvents() ],
cur:[ [slot, x, y], ... ], // other players' cursors (only those currently set), all players included
pa:0|1, sp:1|2|3,
tw?: sim.towerList() } // ONLY when sim.rev changed since the previous snap was sent to the room
{ t:'state', state:<fullState>, snap:<snapshot>, speed, paused, newgame?:true } // reply to sync / newgame
{ t:'players', players:[...] }
{ t:'mark', slot, x, y } // to everyone in the room, including the sender
{ t:'rtt', ts }
{ t:'reject', c, reason, ... }
{ t:'error', code, msg }
state.difficulty(also in thejoinedmessage) is the room's difficulty id. It is a field offullState(), added next tomap,rev,towers,winWaveandmaxLives; an older server sends none and a client then assumes'normal'. The per-ticksnapdoes not repeat it: it cannot change without astatemessage (only the host'snewgamechanges it, and that sends one).seqincrements by 1 per snapshot per room.- Snapshots are sent every
1000/snapshotHzms whether or not the sim advanced (paused rooms still send, so cursors keep moving) but only to online players, and only if at least one player is online. evevents are drained from the sim once per snapshot, so every client sees every event exactly once.- Tower rows (
tw,state.towers) are[id, type, x, y, level, mode, spent, owner, pm];pmis the price multiplier the tower was bought at (1 for almost every tower; the Orbital Uplink gets dearer for every one owned, and its upgrades cost the same multiple). Clients that ignore the ninth field still work; the UI uses it to show the same upgrade price the sim will charge. - Monster entries in
snap.moare[id, kindIndex, x, y, hp, maxhp, slow].kindIndexindexesTD.ENEMY_ORDER(append-only, so old and new clients agree). Two encodings keep the format fixed: a shielded enemy (the Proxy) sendshp = hp + shieldandmaxhp = maxhp + maxShield(the client derives the shield part from the kind's base hp : shield ratio); and theslowflag is1while the enemy is slowed or stunned (a stunned enemy simply stops moving, the client infers the stun from that). - New events:
stun {x, y, r, n}(a Sandbox pulse: centre, radius, number of enemies hit) andheal {x, y, r}(a Daemon pulse), besides the Orbital Uplink'sbeam {x, y, tx, ty, w, bx, by, br}. - Because WebSocket is reliable and ordered,
twdeltas cannot be lost;snap.revlets a client detect a bug/desync (revdiffers from therevit last applied and notwcame along) and ask forsync.
Difficulty
TD.DIFFICULTIES (sim.js) has one row per difficulty, { id, name, gold, lives, hp, reward }, every number a multiplier on the normal
game; TD.DIFFICULTY_ORDER is ['easy', 'normal', 'hard'] (append-only: the ids are on the wire). new Sim({ map, difficulty }):
gold,lives: the starting credits and integrity areSTART_GOLD/START_LIVEStimes it (rounded, integrity at least 1;state.maxLivesfollows). An explicitgold/livesoption of the Sim (tests, the balance bot) is used as given.hp: the hit points of every enemy and its shield, so the snapshot'shp + shield/maxhp + maxShieldencoding (the client splits the two by the kind's base ratio) stays right.reward: what a kill pays (at least 1). The wave clear bonus and the tower prices do not change.- An unknown value in
new Simis'normal'; the server refuses it (bad_difficulty) instead.
Normal is all 1: it plays the base tables of sim.js as they are (those tables were retuned in the wave 4 balance pass, see docs/BALANCE.md). The room's difficulty is fixed for a game: the host picks
it when creating the room (join.difficulty) or when starting a new game (newgame.difficulty).
Tick loop
(Co-op. A versus room has its own phases and only ticks while playing with every human online, at speed 1: see "Versus".)
Fixed step TD.STEP (1/60 s) with an accumulator driven by process.hrtime.bigint(); real time elapsed is
multiplied by speed (1-3) and ignored while paused; clamp elapsed per iteration to 250 ms so a stalled event
loop does not fast-forward the game. Drive it with a setInterval of ~8 ms (or setTimeout chain) per room, or one
global loop for all rooms. Must keep working with several rooms at once.
Events (ev), produced by the sim
place, sell, up, shot, arc, boom, kill, leak, wave, clear, win, lose (see sim.js).
Treat them as opaque JSON.
Versus (attack vs defend)
Design: docs/VERSUS.md. A versus room is created with join.mode = 'versus'. One player defends (builds the maze and turrets with the credits of
snap.g), the other attacks (buys packets with credits only they can see); a match is two rounds with the roles swapped. The server is the
only simulation (new TD.Sim({ map, mode: 'versus', limit }), a fresh one per round) and the only referee. Everything below is additive: a co-op room
never sends or accepts any of it (a vs message or a versus command sent to a co-op room is malformed, exactly as before), the joined / state
messages of a co-op room are byte-identical to what they were.
Seats and roles
- Two seats (the same slots 0 and 1). A seat is held by a human (as in co-op: grace period, reconnect by
pid, host migration) or, in the lobby, by a computer (below).rolesmaps each seat to'attacker'or'defender'and is always one of each. - Round 1 roles: whatever the lobby says when the host starts (a coin flip until somebody chooses). Round 2 swaps them.
- The server decides the role of every command from the seat, for the current round; a
roleorbyfield in a client message is ignored. A command for the other role is answered{ t:'reject', c, reason:'role' }and changes nothing.
Phases
lobby --start--> countdown --> playing --> roundover --next--> countdown --> playing --> matchover --rematch--> countdown ...
| phase | what happens |
|---|---|
lobby |
roles, ready flags and the computer seat are agreed. The room's sim exists (so a joiner has a board) but never ticks; game commands are refused with reason:'phase'. Snapshots keep flowing (the client's watchdog needs them). |
countdown |
a fresh sim for the round was built and sent as { t:'state', newgame:true, ... }; countdown seconds left are in the vs message; nothing ticks, no command is accepted ('phase'). |
playing |
the sim ticks (speed 1 only) while every human seat is online; commands are accepted. |
roundover |
the round's result is shown; the next round starts when every human sent next, or after vsNextMs (30 s by default) whichever is first. |
matchover |
after round 2 (or a forfeit): scores and winner. rematch starts a new match. |
Commands in roundover / matchover get reason:'over'; while a human seat is offline reason:'frozen'.
Messages, client -> server
Lobby and match control, all { t:'vs', c, ... }. A malformed one (wrong type, unknown c) counts towards the 20-malformed limit; a well-formed one that is
not allowed right now gets { t:'reject', c:<the vs command>, reason }.
| message | who / when | meaning | reasons |
|---|---|---|---|
{ t:'vs', c:'role', v:'attacker'|'defender'|'random' } |
any human, lobby | choose your role; the other seat gets the opposite. 'random' flips a coin (random:true in the vs message). The last choice wins. Clears every ready flag. |
phase |
{ t:'vs', c:'ready', v:boolean } |
any human, lobby | ready flag (the host does not need one; a computer is always ready) | phase |
{ t:'vs', c:'bot', v:'attacker'|'defender'|null, skill?:0..1 } |
host, lobby | put a computer with that role in the empty seat (the human gets the opposite role); null removes it. skill defaults to 1. A human who joins in the lobby takes the seat over (the computer goes away). |
not_host, phase, full (both seats already hold humans) |
{ t:'vs', c:'start' } |
host, lobby | begin the match: every human except the host must be ready and online, two seats must be filled | not_host, phase, no_opponent, offline, not_ready |
{ t:'vs', c:'next' } |
any human, roundover | go on to the next round; it starts when every human has sent it (a computer needs no vote) | phase |
{ t:'vs', c:'rematch' } |
any human, matchover | vote for a new match with the first round's roles swapped, straight into the countdown; needs every human (and an opponent) | phase, no_opponent |
Game commands are { t:'cmd', c, ... } as in co-op, with a per-mode whitelist (the sim checks the values and answers { ok:false, reason }, which becomes
a reject to the sender):
| role | c |
fields |
|---|---|---|
| defender | place sell upgrade target |
as in co-op (type,x,y / id / id,lv? / id,mode) |
| defender | tool |
id:'scan'|'patch'|'repair'|'quarantine', x,y (scan), tid (patch) |
| attacker | spawn stage |
kind (an enemy kind), n? (1..250, default 1), gate? (spawn index) |
| attacker | launch |
gate? |
| attacker | tech |
id (armor, speed, health, regen, shield, stealth, crypt) |
| attacker | ability |
id:'emp'|'decoy'|'surge'|'ddos', tid? (emp, decoy), gate? (decoy) |
| nobody | wave auto continue |
valid messages, always refused with reason:'versus' |
Types are checked before the sim sees anything: kind a string (at most 24 chars), n / lv / gate / tid integers (or null), id a string for
tool / ability / tech and a number for sell / upgrade / target; anything else is malformed. Reasons: role, credits (gold for place),
cooldown, cap, max, bad_target, bad_kind, bad_cmd, empty (nothing staged), over, phase, frozen, versus, plus the co-op ones.
A reject echoes x, y, id (now also a string id) and tid. ctl pause / speed are refused in versus with { t:'reject', c:'pause'|'speed', reason:'versus' }
(a malformed ctl is still malformed), and newgame with reason:'versus' (replay with rematch).
Messages, server -> client
{ t:'vs', phase, round, rounds, roles:{ '0':role, '1':role }, random, bot:{ slot, role, skill, name }|null, limit, ready:{ '0':bool, '1':bool }, frozen,
countdown?, // countdown: whole seconds left
next?:{ '0':bool, '1':bool }, nextIn?, // roundover: who has pressed next, seconds until the next round starts anyway
result?, // roundover, matchover: the round that just ended
history?, // as soon as a round has finished (also in round 2's countdown / playing, and after a reconnect)
scores?, winner?, forfeit?, rematch? } // matchover
{ t:'priv', role, ...sim.privateState(role) } // role-private data, see below
vsis sent to everybody on every change (a role, a ready flag, the computer, a phase, each countdown second, a vote, a player joining, leaving, dropping or returning) and is part ofjoinedasjoined.vs.frozenis true while the round (or countdown, or result timer) waits for an offline human.randomis true while the roles are still the coin flip.bot.nameis'Computer'; its seat showsready: true.result={ winner:'attacker'|'defender', t, integrityLost, attacker:slot, defender:slot, forfeit? }: the sim's ownvs.resultplus who sat where.historylists every finished round of the match as{ round, roles, result }(absent until the first round has finished, and in a new match), so the end screen can show both rounds side by side and a client that reconnects in round 2 can still show round 1. After round 2 the phase goes straight tomatchover(it carries that round'sresult).scores=[{ slot, name, fellAt|null, integrityLost }]per attacking performance:fellAtis the sim time the server fell in the round that seat attacked (null if it did not, or if the round was a forfeit);integrityLostis the integrity taken off in total (repairs do not give it back).winneris a slot, ornullfor a draw. Rule: the earlier fall wins; if only one seat felled the server it wins; if neither did, the one who took off more integrity; equal is a draw.forfeit(matchover) is the seat that left (or whose grace period ran out); the other seat wins the match and, if a round was being played, that round.- Private data
priv:{ t:'priv', role, credits, income, tech, staged, cd, active }for the attacker,{ t:'priv', role, cd }for the defender, to each human only for its own current role, at 4 Hz duringcountdownandplaying, once when a round ends, onsync, and when a player (re)joins. The attacker's purse, tech, convoy composition and cooldowns are never sent to the defender, the defender's cooldowns never to the attacker (the test suite scans every frame both sockets receive). After a role swap the firstprivof the new round replaces the old; clients should comparepriv.rolewith their current role. - No cursors, no map pings.
cursorandmarkare valid messages in a versus room but are ignored:snap.curis always[]and nomarkis ever broadcast (an opponent must not see what you are about to build or target). - Snapshots are the co-op ones plus the shared block
vs: { t, lim, st }(round clock, round limit, size of the staged convoy) and a 4th field[id, tgt, kills, emp]on thettrows (seconds of EMP left).state/joined.statecarrymode:'versus'andlimit.snap.sis'playing'until the round ends, then'over'(snap.pais always 0 andsnap.spalways 1). The sim'sroundevent arrives inevas{ e:'round', winner, t }; the other new events areemp,decoy,surge,ddos,quarantine,scan,repair. Every round starts with a{ t:'state', newgame:true }(new sim, new tower list). - Size: the worst case is the alive cap (250 units) plus a built-up defence, about 38 bytes per unit row, roughly 10 KB per snapshot, 200 KB/s per client at 20 Hz
(a test pins it below 16 KB). The
vsandprivmessages are under 500 bytes each.
The computer seat
{ t:'vs', c:'bot', v:<role> } (host, lobby) puts NWBot (public/js/bot.js) in the empty seat, with that role and skill 0..1. It runs on the server, inside the room loop,
and plays through exactly the same door as a human: its commands are stamped with the seat's role and by, refused outside playing and while frozen, and it only sees the
sim through the public API (privateState of its own role). Limits so that a computer seat cannot be used to burn CPU: it is asked to think at most 4 times per second of game
time, only while playing; all the computers of the server together may start thinking only while less than 15 ms were spent on them in this 8 ms loop iteration, and a decision that
took d buys a quiet period of 3d for its room (so a heavy decision costs at most about a quarter of the loop); a bot that throws is switched off for the round. The computer seat is not
a connection: a room with only a computer left is deleted, and in a running match a stranger who joins gets full. A solo player can also play a computer without the server:
NW.LocalController with mode:'versus' (same vs / priv shapes, see controllers.js).
Disconnects, forfeits and hosts
- Freeze. While any human seat is offline the countdown, the round and the result timer stand still (co-op ticks while anyone is online; versus must not let one side keep
building or spawning against an absent opponent) and commands get
reason:'frozen'. The player can come back with the samepidwithingraceMs(60 s):joinedcarries the currentvs, aprivfollows,frozenbecomes false for everybody. - Forfeit. When the grace period runs out, or a player sends
leave, the one who stays wins: inplayingthe current round is awarded to them (the sim ends it with theroundevent,result.forfeit:true), between rounds the match is over with the finished rounds inhistory; either way the phase becomesmatchoverwithforfeit:<leaver's seat>andwinner:<the other seat>. A forfeit never counts as "the server fell". After that the remaining player is host (migration as in co-op) and the room stays inmatchover: a new human can take the empty seat (rematchthen needs both votes); the computer seat can only be set in the lobby, so a player who wants a computer instead creates a new room. - A leave or a timed-out grace period in the lobby just changes the seats (ready flags are cleared); in the countdown of round 1 it sends the room back to the lobby (no match had started); in the countdown of round 2 it is a forfeit.
- The host migrates exactly as in co-op; the host's powers are
botandstart. A guest can pick roles and ready up. - Server options for tests:
vsCountdownMs(3000) andvsNextMs(30000) increateServer.