| name | src-net-skill |
| description | Implement the transport-independent multiplayer protocol, lobby, authority, snapshots, and network adapters. |
claude-of-tanks / src/net
Purpose
Provide one authoritative match path for campaign, LAN, private, and ranked
play without importing Three.js rendering or DOM state.
Mental model & key files
protocol.js owns wire vocabulary and untrusted input validation.lobby.js owns teams, team size, readiness, permissions, and start policy.matchRuntime.js owns fixed ticks, input ordering, snapshots, and client time.snapshot.js owns quantization, visibility filtering, and interpolation.snapshotWireCodec.js owns compact binary snapshot rows; protocol v2 uses
explicit snapshot acknowledgements, per-peer deltas, and periodic keyframes.loopbackTransport.js, channelTransport.js, and webrtcPeer.js implement
the same bounded transport contract.localSession.js proves solo play traverses the real host/client path.rankedServiceClient.js owns service-scoped ladder identity and queue polling;
dedicatedClient.js owns authenticated WebSocket handoff and reconnect.privateRoomSession.js owns lobby WebRTC composition;
privateMatchHandoff.js deterministically fills open team slots with bots
and releases those same channels to match authority.browserBattleBridge.js is presentation-only and must stay lazy from main.
Patterns and invariants
- Player/entity identity is independent from
specId.
- Authority accepts controls only; it computes every gameplay result.
- Spotting filters data before serialization.
- Queues, extrapolation, catch-up, sequences, and payload sizes are bounded.
- WebRTC control/events stay reliable and ordered; replaceable snapshots and
live input use the unordered zero-retransmit state lane. Fire/consumable
edges repeat until acknowledged and authority deduplicates them. WebSocket
snapshots and input coalesce under backpressure so stale state cannot
consume control headroom.
- Modules remain Node-runnable with no DOM/WebGL dependency.
- Tests exercise the public host/client interface, not private internals.
Verification
Run node src/net/net.selftest.mjs,
node src/net/privateMatchHandoff.selftest.mjs, then npm test and
npm run build. Network adapters additionally require browser-pair proof.
