# Multiplayer Architecture — analysis & the land/WorldManager refactor

*2026.06.09 — written alongside the `land` (3D meadow) build. Companion to
`plans/arena-multiplayer.md` (the original Q3-style design doc).*

## The stack today

```
piece (land.mjs / arena.mjs, in the disk worker)
  │  usercmds @60Hz (cmd backup ×3, seq-numbered)        snaps @30Hz (delta vs ack)
  ▼                                                       ▲
net.udp  ── geckos.io WebRTC datachannel (unordered/unreliable)
net.socket ─ WebSocket (reliable; hello/bye/join/leave/ping + cmd/snap fallback)
  │
  ▼
session-server (ONE monolith node process for everything:
  chat ×3 instances, duel, worlds, notepat MIDI, DAW, status streams, machines)
  └─ WorldManager per world {arena, land}: 60Hz tick, 30Hz per-client
     delta snapshots, pmove integration on cmd arrival (Q3-style)
```

Client prediction: cam-doll integrates the same pmove model locally;
`reconcileLocal()` replays unacked cmds from the server's authoritative state
and soft-corrects (dead zone 0.5u, soft-K 0.18, hard snap > 4u). Remote
players render ~100ms in the past from an interpolation buffer, with ≤250ms
velocity extrapolation when the buffer starves.

## Why it felt skippy

Ranked by observed impact:

1. **Silent UDP death (found & fixed today).** A WebRTC datachannel can die
   while `webrtcConnection.state` stays `"open"` and `channel.emit()` keeps
   returning success. The server's "prefer UDP, fall back to WS" check never
   falls back, so the client *receives nothing* — remotes freeze, then the
   piece coasts on extrapolation, then teleports. Reproduced 100% in
   headless Chromium (UDP resolves, then rx dies ~8s in); the same failure
   shape exists on flaky NATs/mobile in prod, where it reads as "skippy".
   **Fix (shipped):**
   - server: stall watchdog in `broadcastSnapshots` — a player on UDP whose
     snap-ack hasn't advanced for ~2s of sends is demoted to WS snapshots,
     with a 30s re-promotion block so a dead-but-open channel can't flap;
   - session.mjs re-resolves the UDP channel on *every* UDP cmd (freshest
     liveness signal), gated by that block;
   - client (arena + land): if snaps go quiet >1.5s while UDP claims
     connected, cmds are mirrored over WS so the server keeps seeing acks.
2. **The lobby leak (fixed today).** `broadcastWS` was `everyone()` — every
   arena join/leave hit every client on the monolith, including chat tabs;
   anything not explicitly routed in session.mjs also relays to everyone.
   World events are now member-scoped inside WorldManager (it already knows
   every member wsId), and *all* `<world>:*` verbs are consumed by the world
   router instead of falling through to the relay.
3. **Server integrates only on cmd arrival.** Faithful to Q3, but cmds ride
   an unreliable channel in bursts; a late batch means the victim's snapshot
   position stalls then jumps, which the remote interp buffer reproduces
   faithfully. The cmd-backup window (×3) plus extrapolation mostly covers
   it; if it still shows, the next lever is server-side per-tick coasting
   (integrate held inputs on empty ticks), which trades a little authority
   drift for smoothness.
4. **Event-loop contention on the monolith.** The 60Hz world tick shares one
   node event loop with chat history loads, Mongo round-trips, status
   streams, etc. Timer jitter directly becomes snap jitter (clients
   max-filter + slew the clock to absorb it, but the floor is set by the
   server). Worth measuring before splitting; the clean split is one
   process (or worker thread) per world, same protocol.
5. **JSON wire format.** Fine at ≤8 players (delta snaps are small);
   bit-packing was deliberately deferred — still the right call.

## The lobby model after the refactor

- `session-server/world-manager.mjs` — `WorldManager` class, one instance
  per world; prefix parameterizes the protocol (`arena:*`, `land:*`).
  Everything else (tick, snapshots, takeover/spectate, stale sweep, delta
  compression, lag-comp history) is shared.
- Adding a world = one cfg module in `lib/<name>-world.mjs` + one line in
  session.mjs's `worldManagers` map + a client piece. Routing (hello / bye /
  cmd / ping, WS close, UDP identity/cmd) is generic over the map.
- `land` proves the pattern: its *entire* world cfg lives in
  `lib/land-world.mjs`, imported by both client and server — no duplicated
  MUST-MATCH block (arena still has one; migrate it the same way when
  convenient).

Current scope is **one room per world** (matches the single global chat).
Next steps when a meadow gets crowded: shard key `world:instance`, spawn a
WorldManager per instance, and have hello return the assigned instance —
the protocol already carries everything needed.

## Test harness (all local, no prod risk)

- `npm test` in `session-server/` — vitest; `tests/world.test.mjs` covers
  prefixed events, member-scoped broadcasts, pmove integration, takeover,
  reload races, multi-world isolation.
- `npm run land:probe:local` / `arena:probe:local` — terminal probe
  (`--world` flag) for live snap-rate/RTT/roster against any server.
- `node artery/test-land-multiplayer.mjs` — two headless Chromium players
  on `/land` + a wire-level walker bot; asserts snaps flow to both browsers
  and that the bot appears in both rosters (this is the test that caught
  the silent-UDP-death bug). `--keep` runs headful for manual driving.