Building a Multiplayer Game

// Compares the binary snapshot with an equivalent JSON snapshot for several player counts.
import { deflateRawSync } from "node:zlib";
import { ARENA_H, ARENA_W, TICK_HZ, decodeSnapshot, encodeSnapshot } from "../shared/protocol.ts";
import type { Snapshot } from "../shared/protocol.ts";

function sample(n: number, tick: number): Snapshot {
  const players = Array.from({ length: n }, (_, i) => ({
    id: i + 1, x: 16 + Math.random() * (ARENA_W - 32), y: 16 + Math.random() * (ARENA_H - 32), hp: 25 * (1 + (i % 4)),
    alive: true, aim: Math.floor(Math.random() * 256) << 8, lastProcessedInput: 100000 + tick * 3 + i,
  }));
  return { tick, time: 3600000 + tick * 50, players, shots: tick % 7 === 0 ? [{ shooter: 1, target: 2, x: 400.25, y: 300.5 }] : [] };
}

console.log("players | binary B | JSON B | JSON deflate B | binary kbit/s per client | JSON kbit/s per client | ratio");
for (const n of [2, 4, 8, 16]) {
  let bin = 0, json = 0, defl = 0; const N = 400;
  for (let t = 1; t <= N; t++) {
    const s = sample(n, t);
    const b = encodeSnapshot(s);
    const d = decodeSnapshot(b)!;                                    // the round trip must be lossless to 1/16 px
    if (Math.abs(d.players[0].x - s.players[0].x) > 1 / 32 || d.tick !== s.tick) throw new Error("round trip failed");
    const round = (v: number) => Math.round(v * 100) / 100;     // fair to JSON: two decimals, not 17 digits
    const j = JSON.stringify({ type: "snapshot", tick: s.tick, time: s.time, players: s.players.map((p) => ({ ...p, x: round(p.x), y: round(p.y) })), shots: s.shots });
    bin += b.byteLength; json += Buffer.byteLength(j); defl += deflateRawSync(j).byteLength;
  }
  const kbps = (bytes: number) => ((bytes / N) * TICK_HZ * 8) / 1000;
  console.log(`${String(n).padStart(7)} | ${(bin / N).toFixed(0).padStart(8)} | ${(json / N).toFixed(0).padStart(6)} | ${(defl / N).toFixed(0).padStart(14)} | ${kbps(bin).toFixed(1).padStart(24)} | ${kbps(json).toFixed(1).padStart(22)} | ${(json / bin).toFixed(1)}x`);
}

players | binary B | JSON B | JSON deflate B | binary kbit/s per client | JSON kbit/s per client | ratio
      2 |       36 |    257 |            165 |                      5.7 |                   41.2 | 7.2x
      4 |       60 |    441 |            213 |                      9.6 |                   70.6 | 7.4x
      8 |      108 |    809 |            289 |                     17.3 |                  129.4 | 7.5x
     16 |      204 |   1551 |            440 |                     32.6 |                  248.1 | 7.6x

// An authoritative match: fixed 20 Hz tick, input queues, hitscan with optional lag compensation.
import {
  ARENA_H, ARENA_W, FRAGS_TO_WIN, HISTORY_MS, MAX_HP, MAX_REWIND_MS, PLAYER_RADIUS, RAY_LENGTH, RESPAWN_MS,
  SHOT_COOLDOWN_INPUTS, SHOT_DAMAGE, TICK_MS, BTN_FIRE, encodeSnapshot,
} from "../shared/protocol.ts";
import type { Input, PlayerState, Shot } from "../shared/protocol.ts";
import { applyInput, aimToRad, rayCircle } from "../shared/sim.ts";

const FRAGS = Number(process.env.FRAGS_TO_WIN ?? FRAGS_TO_WIN);   // tests override these three
const DAMAGE = Number(process.env.SHOT_DAMAGE ?? SHOT_DAMAGE);
const MAX_REWIND = Number(process.env.MAX_REWIND_MS ?? MAX_REWIND_MS);

export const serverTime = (): number => Math.floor(performance.now()) >>> 0;

type QueuedInput = Input & { view: number };

export interface Peer {                 // what the room needs from a connection
  sendJson(msg: object): void;
  sendBinary(buf: Uint8Array): boolean; // false when the snapshot was dropped (slow consumer)
}

export class Player {
  id = 0; name: string; peer: Peer; ready = false; frags = 0;
  x = 0; y = 0; hp = MAX_HP; alive = true; aim = 0; respawnAt = 0;
  lastProcessedInput = 0; lastQueuedSeq = 0; queue: QueuedInput[] = [];
  budget = 12; cooldown = 0; dropped = 0;
  constructor(name: string, peer: Peer) { this.name = name; this.peer = peer; }
}

interface HistoryEntry { time: number; pos: Map<number, { x: number; y: number; alive: boolean }> }

export class Room {
  readonly players = new Map<number, Player>();
  state: "lobby" | "playing" | "ended" = "lobby";
  tick = 0; shotsThisTick: Shot[] = [];
  history: HistoryEntry[] = [];
  private timer: NodeJS.Timeout | undefined;
  private nextAt = 0;
  tickTimes: number[] = [];

  readonly id: string; name: string; readonly max: number; readonly lagComp: boolean;
  readonly minPlayers: number; readonly onChange: () => void;

  constructor(id: string, name: string, max: number, lagComp: boolean, minPlayers: number, onChange: () => void) {
    this.id = id; this.name = name; this.max = max; this.lagComp = lagComp; this.minPlayers = minPlayers; this.onChange = onChange;
  }

  join(p: Player): boolean {
    if (this.players.size >= this.max || this.state !== "lobby") return false;
    for (let id = 1; id <= 255; id++) if (!this.players.has(id)) { p.id = id; break; }
    this.players.set(p.id, p);
    this.broadcastRoster();
    this.onChange();
    return true;
  }

  leave(p: Player): void {
    this.players.delete(p.id);
    if (this.players.size === 0) this.stop();
    else this.broadcastRoster();
    this.onChange();
    this.maybeStart();
  }

  setReady(p: Player, ready: boolean): void { p.ready = ready; this.broadcastRoster(); this.maybeStart(); }

  roster() {
    return { t: "roster", state: this.state, players: [...this.players.values()].map((p) => ({ id: p.id, name: p.name, ready: p.ready, frags: p.frags })) };
  }
  broadcastRoster(): void { this.broadcastJson(this.roster()); }
  broadcastJson(msg: object): void { for (const p of this.players.values()) p.peer.sendJson(msg); }

  private maybeStart(): void {
    if (this.state !== "lobby" || this.players.size < this.minPlayers) return;
    if (![...this.players.values()].every((p) => p.ready)) return;
    const startsAt = serverTime() + 3000;
    this.broadcastJson({ t: "countdown", startsAt });
    setTimeout(() => { if (this.state === "lobby" && this.players.size >= this.minPlayers) this.start(); }, 3000);
  }

  private spawn(p: Player): void {
    p.x = PLAYER_RADIUS + Math.random() * (ARENA_W - 2 * PLAYER_RADIUS);
    p.y = PLAYER_RADIUS + Math.random() * (ARENA_H - 2 * PLAYER_RADIUS);
    p.hp = MAX_HP; p.alive = true;
  }

  start(): void {
    this.state = "playing"; this.history = []; this.tick = 0;
    for (const p of this.players.values()) { this.spawn(p); p.frags = 0; p.queue = []; p.lastProcessedInput = 0; p.lastQueuedSeq = 0; p.cooldown = 0; }
    this.broadcastJson({ t: "start", lagComp: this.lagComp });
    this.broadcastRoster();
    this.onChange();
    this.nextAt = performance.now() + TICK_MS;
    this.schedule();
  }

  stop(): void { clearTimeout(this.timer); this.timer = undefined; }

  private schedule(): void {
    // Self-correcting timer: aim at absolute tick times so setTimeout jitter does not accumulate.
    this.timer = setTimeout(() => {
      const began = performance.now();
      this.step(serverTime());
      this.tickTimes.push(performance.now() - began);
      if (this.tickTimes.length > 200) this.tickTimes.shift();
      this.nextAt += TICK_MS;
      if (this.nextAt < performance.now() - 5 * TICK_MS) this.nextAt = performance.now() + TICK_MS; // fell far behind
      this.schedule();
    }, Math.max(0, this.nextAt - performance.now()));
  }

  queueInputs(p: Player, view: number, inputs: Input[]): void {
    for (const inp of inputs) {
      if (inp.seq <= p.lastQueuedSeq) continue;          // duplicate or old (redundant batch)
      p.lastQueuedSeq = inp.seq;
      if (p.queue.length < 30) p.queue.push({ ...inp, view });
    }
  }

  step(now: number): void {
    this.tick++;
    this.shotsThisTick = [];
    for (const p of this.players.values()) {
      p.budget = Math.min(p.budget + 4, 12);                    // at most ~4 commands per tick (3 are nominal)
      let n = 0;
      while (p.queue.length > 0 && n < p.budget) {
        const inp = p.queue.shift()!;
        n++;
        this.processInput(p, inp, now);
      }
      p.budget -= n;
      if (!p.alive && now >= p.respawnAt) this.spawn(p);
    }
    this.history.push({ time: now, pos: new Map([...this.players.values()].map((p) => [p.id, { x: p.x, y: p.y, alive: p.alive }])) });
    while (this.history.length > 0 && this.history[0].time < now - HISTORY_MS) this.history.shift();

    const states: PlayerState[] = [...this.players.values()].map((p) => ({
      id: p.id, x: p.x, y: p.y, hp: p.hp, alive: p.alive, aim: p.aim, lastProcessedInput: p.lastProcessedInput,
    }));
    const buf = encodeSnapshot({ tick: this.tick, time: now, players: states, shots: this.shotsThisTick });
    for (const p of this.players.values()) if (!p.peer.sendBinary(buf)) p.dropped++;
  }

  private processInput(p: Player, inp: QueuedInput, now: number): void {
    p.lastProcessedInput = inp.seq;
    p.aim = inp.aim;
    if (p.cooldown > 0) p.cooldown--;
    if (!p.alive || this.state !== "playing") return;
    applyInput(p, inp);
    if (inp.buttons & BTN_FIRE && p.cooldown === 0) { p.cooldown = SHOT_COOLDOWN_INPUTS; this.fire(p, inp, now); }
  }

  // Position of a player as it was at time t (clamped to the history we keep).
  private positionAt(id: number, t: number, now: number): { x: number; y: number; alive: boolean } | null {
    const live = this.players.get(id);
    if (!live) return null;
    const entries = [...this.history, { time: now, pos: new Map([[id, { x: live.x, y: live.y, alive: live.alive }]]) }];
    for (let i = entries.length - 1; i > 0; i--) {
      const a = entries[i - 1], b = entries[i];
      if (t >= a.time && t <= b.time) {
        const pa = a.pos.get(id), pb = b.pos.get(id);
        if (!pa || !pb) return pb ?? null;
        const k = b.time === a.time ? 1 : (t - a.time) / (b.time - a.time);
        return { x: pa.x + (pb.x - pa.x) * k, y: pa.y + (pb.y - pa.y) * k, alive: k < 0.5 ? pa.alive : pb.alive };
      }
    }
    return { x: live.x, y: live.y, alive: live.alive };
  }

  private fire(shooter: Player, inp: QueuedInput, now: number): void {
    // Lag compensation: evaluate the targets where the shooter saw them (viewTime), but never further back than MAX_REWIND_MS.
    const t = this.lagComp ? Math.min(now, Math.max(now - MAX_REWIND, inp.view)) : now;
    const angle = aimToRad(inp.aim);
    let best: { dist: number; target: Player } | null = null;
    for (const target of this.players.values()) {
      if (target === shooter) continue;
      const pos = this.lagComp ? this.positionAt(target.id, t, now) : { x: target.x, y: target.y, alive: target.alive };
      if (!pos || !pos.alive) continue;
      const d = rayCircle(shooter.x, shooter.y, angle, pos.x, pos.y, PLAYER_RADIUS, RAY_LENGTH);
      if (d >= 0 && (!best || d < best.dist)) best = { dist: d, target };
    }
    const len = best ? best.dist : RAY_LENGTH;
    this.shotsThisTick.push({ shooter: shooter.id, target: best ? best.target.id : 0, x: shooter.x + Math.cos(angle) * len, y: shooter.y + Math.sin(angle) * len });
    if (!best || !best.target.alive) return;
    const target = best.target;
    target.hp = Math.max(0, target.hp - DAMAGE);
    if (target.hp === 0) {
      target.alive = false; target.respawnAt = now + RESPAWN_MS; shooter.frags++;
      this.broadcastJson({ t: "frag", killer: shooter.id, victim: target.id, frags: shooter.frags });
      if (shooter.frags >= FRAGS) this.end(shooter);
    }
  }

  private end(winner: Player): void {
    this.state = "ended";
    this.broadcastJson({ t: "end", winner: winner.id, scores: [...this.players.values()].map((p) => ({ id: p.id, name: p.name, frags: p.frags })) });
    setTimeout(() => {
      this.stop(); this.state = "lobby";
      for (const p of this.players.values()) p.ready = false;
      this.broadcastRoster(); this.onChange();
    }, 3000);
  }

  summary() {
    return { id: this.id, name: this.name, players: this.players.size, max: this.max, state: this.state, lagComp: this.lagComp };
  }
}

// Optional unreliable data-channel transport: the browser offers, the server answers, signalling rides the lobby WebSocket.
import { RTCPeerConnection } from "node-datachannel/polyfill";

export interface RtcLink {
  channelOpen: () => boolean;
  send: (buf: Uint8Array) => boolean;
  addCandidate: (candidate: string, mid: string) => Promise<void>;
  close: () => void;
}

export async function answerOffer(
  sdp: string,
  signal: (msg: object) => void,
  onBinary: (data: Uint8Array) => void,
  onClose: () => void,
): Promise<RtcLink> {
  const iceServers = (process.env.STUN_URLS ?? "").split(",").filter(Boolean).map((urls) => ({ urls }));
  const pc = new RTCPeerConnection({ iceServers });
  let channel: any = null;

  pc.onicecandidate = (e: any) => {
    if (e.candidate) signal({ t: "rtc-candidate", candidate: e.candidate.candidate, mid: e.candidate.sdpMid ?? "0" });
  };
  pc.ondatachannel = (e: any) => {
    if (e.channel.label !== "arena") { e.channel.close(); return; }  // accept only the label we expect
    channel = e.channel;
    channel.binaryType = "arraybuffer";
    channel.onmessage = (m: { data: ArrayBuffer | string }) => { if (typeof m.data !== "string") onBinary(new Uint8Array(m.data)); };
    channel.onclose = onClose;
  };
  pc.onconnectionstatechange = () => { if (["failed", "closed", "disconnected"].includes(pc.connectionState)) onClose(); };

  await pc.setRemoteDescription({ type: "offer", sdp });
  await (pc as any).setLocalDescription();
  signal({ t: "rtc-answer", sdp: pc.localDescription!.sdp });

  return {
    channelOpen: () => channel !== null && channel.readyState === "open",
    send: (buf) => {
      if (!channel || channel.readyState !== "open") return false;
      if (channel.bufferedAmount > 8 * 1024) return false;   // unreliable data: drop instead of queueing
      channel.send(buf);
      return true;
    },
    addCandidate: async (candidate, mid) => { await pc.addIceCandidate({ candidate, sdpMid: mid }); },
    close: () => { try { pc.close(); } catch { /* already closed */ } },
  };
}

// Pixel Arena server: uWebSockets.js for HTTP + WebSocket, one authoritative Room per match.
import { createRequire } from "node:module";
import { readFileSync } from "node:fs";
import { randomBytes } from "node:crypto";
import { ARENA_H, ARENA_W, C_INPUT, C_PING, INPUT_HZ, INTERP_DELAY_MS, MAX_REWIND_MS, SPEED, TICK_HZ, decodeInputs, encodePong } from "../shared/protocol.ts";
import type { ClientMsg } from "../shared/protocol.ts";
import { Player, Room, serverTime } from "./room.ts";
import type { Peer } from "./room.ts";
import { answerOffer } from "./rtc.ts";
import type { RtcLink } from "./rtc.ts";

const uWS = createRequire(import.meta.url)("uWebSockets.js");   // the ESM wrapper of v20.71.0 is broken
const PORT = Number(process.env.PORT ?? 8080);
const MIN_PLAYERS = Number(process.env.MIN_PLAYERS ?? 2);
const PUBLIC_DIR = new URL("../../public/", import.meta.url);
const ALLOWED_ORIGINS = new Set((process.env.ALLOWED_ORIGINS ?? `http://localhost:${PORT},http://127.0.0.1:${PORT}`).split(","));

interface Conn {
  id: string; name: string; ws: any; player: Player | null; room: Room | null; rtc: RtcLink | null; closed: boolean;
  pendingCandidates: Array<{ candidate: string; mid: string }>;
}
const rooms = new Map<string, Room>();
const conns = new Set<Conn>();

const roomList = () => ({ t: "rooms", rooms: [...rooms.values()].map((r) => r.summary()) });
const publishRooms = () => app.publish("lobby", JSON.stringify(roomList()), false);

function peerFor(c: Conn): Peer {
  return {
    sendJson: (msg) => { if (!c.closed) c.ws.send(JSON.stringify(msg), false); },
    sendBinary: (buf) => {
      if (c.closed) return false;
      if (c.rtc?.channelOpen()) return c.rtc.send(buf);                 // data channel when it is up
      if (c.ws.getBufferedAmount() > 8 * 1024) return false;            // slow consumer: skip this snapshot
      return c.ws.send(buf, true) !== 0;
    },
  };
}

function leaveRoom(c: Conn): void {
  if (c.room && c.player) {
    const room = c.room;
    room.leave(c.player);
    if (room.players.size === 0) rooms.delete(room.id);
  }
  c.room = null; c.player = null;
  c.rtc?.close(); c.rtc = null;
  publishRooms();
}

async function onJson(c: Conn, msg: ClientMsg): Promise<void> {
  const reply = (m: object) => c.ws.send(JSON.stringify(m), false);
  switch (msg.t) {
    case "hello": c.name = String(msg.name ?? "player").slice(0, 16) || "player"; break;
    case "list": reply(roomList()); break;
    case "create": {
      if (c.room) return reply({ t: "error", code: "conflict", message: "already in a room" });
      const id = randomBytes(3).toString("hex");
      const room = new Room(id, String(msg.name ?? `room-${id}`).slice(0, 24), Math.min(16, Math.max(1, Number(msg.max) || 8)), msg.lagComp !== false, MIN_PLAYERS, publishRooms);
      rooms.set(id, room);
      return onJson(c, { t: "join", room: id });
    }
    case "join": {
      const room = rooms.get(String(msg.room));
      if (!room) return reply({ t: "error", code: "not_found", message: "no such room" });
      if (c.room) return reply({ t: "error", code: "conflict", message: "already in a room" });
      const player = new Player(c.name, peerFor(c));
      if (!room.join(player)) return reply({ t: "error", code: "room_full", message: "room full or already playing" });
      c.room = room; c.player = player;
      reply({ t: "joined", room: room.id, you: player.id, lagComp: room.lagComp });
      break;
    }
    case "leave": leaveRoom(c); reply({ t: "left" }); break;
    case "ready": if (c.room && c.player) c.room.setReady(c.player, !!msg.ready); break;
    case "rtc-offer": {
      if (!c.player) return reply({ t: "error", code: "forbidden", message: "join a room first" });
      c.rtc?.close();
      c.rtc = await answerOffer(String(msg.sdp), (m) => { if (!c.closed) reply(m); },
        (data) => handleBinary(c, data), () => { c.rtc = null; });
      for (const k of c.pendingCandidates.splice(0)) await c.rtc.addCandidate(k.candidate, k.mid);
      break;
    }
    case "rtc-candidate":
      if (c.rtc) await c.rtc.addCandidate(String(msg.candidate), String(msg.mid));
      else c.pendingCandidates.push({ candidate: String(msg.candidate), mid: String(msg.mid) });
      break;
    default: reply({ t: "error", code: "bad_request", message: "unknown type" });
  }
}

// The binary data plane is the same whether it arrives over the WebSocket or the data channel.
function handleBinary(c: Conn, data: Uint8Array): void {
  const reply = (buf: Uint8Array) => { if (c.rtc?.channelOpen()) c.rtc.send(buf); else if (!c.closed) c.ws.send(buf, true); };
  if (data[0] === C_PING && data.byteLength === 5) {
    const v = new DataView(data.buffer, data.byteOffset, data.byteLength);
    reply(encodePong(v.getUint32(1, true), serverTime()));
  } else if (data[0] === C_INPUT && c.room && c.player) {
    const batch = decodeInputs(data);
    if (batch) c.room.queueInputs(c.player, batch.viewTime, batch.inputs);
  }
}

const files: Record<string, { body: Buffer; type: string }> = {};
for (const [path, name, type] of [["/", "index.html", "text/html; charset=utf-8"], ["/main.js", "main.js", "text/javascript; charset=utf-8"]] as const) {
  try { files[path] = { body: readFileSync(new URL(name, PUBLIC_DIR)), type }; } catch { /* built later */ }
}

const app = uWS.App()
  .get("/healthz", (res: any) => { res.end("ok"); })
  .get("/stats", (res: any) => {
    const ticks = [...rooms.values()].flatMap((r) => r.tickTimes);
    res.writeHeader("content-type", "application/json").end(JSON.stringify({
      rooms: rooms.size, connections: conns.size,
      tickMsAvg: ticks.length ? ticks.reduce((a, b) => a + b, 0) / ticks.length : 0, tickMsMax: ticks.length ? Math.max(...ticks) : 0,
    }));
  })
  .get("/*", (res: any, req: any) => {
    const f = files[req.getUrl()];
    if (!f) { res.writeStatus("404 Not Found").end("not found"); return; }
    res.writeHeader("content-type", f.type).writeHeader("cache-control", "no-cache").end(f.body);
  })
  .ws("/ws", {
    maxPayloadLength: 8192,
    idleTimeout: 30,
    maxBackpressure: 64 * 1024,
    closeOnBackpressureLimit: true,
    upgrade: (res: any, req: any, context: any) => {
      const origin = req.getHeader("origin");
      const key = req.getHeader("sec-websocket-key"), proto = req.getHeader("sec-websocket-protocol"), ext = req.getHeader("sec-websocket-extensions");
      if (origin && !ALLOWED_ORIGINS.has(origin)) { res.writeStatus("403 Forbidden").end("origin not allowed"); return; }
      const conn: Conn = { id: randomBytes(4).toString("hex"), name: "player", ws: null, player: null, room: null, rtc: null, closed: false, pendingCandidates: [] };
      res.upgrade({ conn }, key, proto.split(",")[0].trim() === "pixel-arena.v1" ? "pixel-arena.v1" : "", ext, context);
    },
    open: (ws: any) => {
      const c: Conn = ws.getUserData().conn;
      c.ws = ws; conns.add(c);
      ws.subscribe("lobby");
      ws.send(JSON.stringify({
        t: "welcome", id: c.id, serverTime: serverTime(),
        config: { arenaW: ARENA_W, arenaH: ARENA_H, speed: SPEED, tickHz: TICK_HZ, inputHz: INPUT_HZ, interpDelayMs: INTERP_DELAY_MS, maxRewindMs: MAX_REWIND_MS },
      }), false);
      ws.send(JSON.stringify(roomList()), false);
    },
    message: (ws: any, data: ArrayBuffer, isBinary: boolean) => {
      const c: Conn = ws.getUserData().conn;
      if (isBinary) { handleBinary(c, new Uint8Array(data)); return; }
      let msg: ClientMsg;
      try { msg = JSON.parse(Buffer.from(data).toString("utf8")); } catch { ws.end(1007, "invalid json"); return; }
      onJson(c, msg).catch((e) => { console.error("handler error", e); ws.send(JSON.stringify({ t: "error", code: "internal", message: "internal error" }), false); });
    },
    close: (ws: any) => {
      const c: Conn = ws.getUserData().conn;
      c.closed = true; conns.delete(c); leaveRoom(c);
    },
  })
  .listen("0.0.0.0", PORT, (token: unknown) => {
    if (!token) { console.error(`cannot listen on ${PORT}`); process.exit(1); }
    console.log(`pixel-arena listening on :${PORT} (min players ${MIN_PLAYERS})`);
  });

for (const sig of ["SIGINT", "SIGTERM"] as const) process.on(sig, () => { process.exit(0); });

// Transport: lobby WebSocket + binary data plane (WebSocket or unreliable data channel), clock sync, optional delay simulation.
import { MAX_BATCH, S_PONG, S_SNAPSHOT, decodeSnapshot, encodeInputs, encodePing } from "../shared/protocol.ts";
import type { Input, Snapshot } from "../shared/protocol.ts";

export interface NetSim { delayMs: number; jitterMs: number }   // one-way, applied in both directions, order preserved

export type Json = { t: string; [k: string]: any };

export class ServerClock {
  offset = 0; rtt = 0; private samples: Array<{ rtt: number; offset: number }> = [];
  update(clientSent: number, serverTime: number, clientNow: number): void {
    const rtt = clientNow - clientSent;
    this.samples.push({ rtt, offset: serverTime + rtt / 2 - clientNow });
    if (this.samples.length > 8) this.samples.shift();
    const best = this.samples.reduce((a, b) => (b.rtt < a.rtt ? b : a));   // lowest-RTT sample is the least queued
    this.offset = best.offset; this.rtt = rtt;
  }
  serverNow(clientNow: number): number { return clientNow + this.offset; }
}

export class Connection {
  readonly clock = new ServerClock();
  ws!: WebSocket;
  dc: RTCDataChannel | null = null;
  pc: RTCPeerConnection | null = null;
  onJson: (m: Json) => void = () => {};
  onSnapshot: (s: Snapshot, receivedAt: number) => void = () => {};
  sim: NetSim = { delayMs: 0, jitterMs: 0 };
  bytesIn = 0; msgsIn = 0; bytesOut = 0;
  private lastIn = 0; private lastOut = 0;
  private pingTimer: ReturnType<typeof setInterval> | undefined;
  private readonly url: string;
  private readonly rtc: { RTCPeerConnection: typeof RTCPeerConnection };
  constructor(url: string, rtc: { RTCPeerConnection: typeof RTCPeerConnection } = globalThis as any) { this.url = url; this.rtc = rtc; }

  connect(name: string): Promise<Json> {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(this.url, "pixel-arena.v1");
      this.ws.binaryType = "arraybuffer";
      this.ws.onerror = () => reject(new Error("websocket error"));
      this.ws.onopen = () => this.sendJson({ t: "hello", name });
      this.ws.onmessage = (e) => {
        if (typeof e.data === "string") {
          const m = JSON.parse(e.data) as Json;
          if (m.t === "welcome") { resolve(m); this.startPing(); }
          if (m.t === "rtc-answer") void this.pc?.setRemoteDescription({ type: "answer", sdp: m.sdp });
          else if (m.t === "rtc-candidate") void this.pc?.addIceCandidate({ candidate: m.candidate, sdpMid: m.mid });
          else this.onJson(m);
        } else this.receive(new Uint8Array(e.data as ArrayBuffer));
      };
    });
  }

  private startPing(): void {
    const ping = () => this.sendBinary(encodePing(Math.floor(performance.now())));
    ping();
    this.pingTimer = setInterval(ping, 1000);
  }

  sendJson(m: object): void { this.ws.send(JSON.stringify(m)); }

  // Both directions pass through the optional delay simulator; delivery order is preserved.
  private delayed(dir: "in" | "out", fn: () => void): void {
    const { delayMs, jitterMs } = this.sim;
    if (delayMs === 0 && jitterMs === 0) return fn();
    const at = Math.max(performance.now() + delayMs + Math.random() * jitterMs, dir === "in" ? this.lastIn : this.lastOut);
    if (dir === "in") this.lastIn = at; else this.lastOut = at;
    setTimeout(fn, Math.max(0, at - performance.now()));
  }

  sendBinary(buf: Uint8Array): void {
    this.delayed("out", () => {
      this.bytesOut += buf.byteLength;
      if (this.dc && this.dc.readyState === "open") { if (this.dc.bufferedAmount < 16 * 1024) this.dc.send(buf as unknown as ArrayBufferView<ArrayBuffer>); }
      else if (this.ws.readyState === WebSocket.OPEN) this.ws.send(buf as unknown as ArrayBufferView<ArrayBuffer>);
    });
  }

  // Over the WebSocket send only new inputs; over the lossy channel repeat every unacknowledged input (redundancy).
  sendInputs(newInputs: Input[], unacked: Input[], viewTime: number): void {
    const redundant = this.dc?.readyState === "open";
    const list = (redundant ? unacked : newInputs).slice(-MAX_BATCH);
    if (list.length > 0) this.sendBinary(encodeInputs(list, viewTime));
  }

  private receive(buf: Uint8Array): void {
    this.delayed("in", () => {
      const now = performance.now();
      this.bytesIn += buf.byteLength; this.msgsIn++;
      if (buf[0] === S_SNAPSHOT) { const s = decodeSnapshot(buf); if (s) this.onSnapshot(s, now); }
      else if (buf[0] === S_PONG) {
        const v = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
        this.clock.update(v.getUint32(1, true), v.getUint32(5, true), now);
      }
    });
  }

  // Unreliable channel: ordered:false and maxRetransmits:0, signalling over the lobby WebSocket.
  async startRtc(): Promise<void> {
    const pc = new this.rtc.RTCPeerConnection({ iceServers: [] });
    this.pc = pc;
    const dc = pc.createDataChannel("arena", { ordered: false, maxRetransmits: 0 });
    dc.binaryType = "arraybuffer";
    dc.onmessage = (e) => { if (typeof e.data !== "string") this.receive(new Uint8Array(e.data as ArrayBuffer)); };
    const opened = new Promise<void>((res, rej) => { dc.onopen = () => res(); setTimeout(() => rej(new Error("data channel timeout")), 10000); });
    pc.onicecandidate = (e) => { if (e.candidate) this.sendJson({ t: "rtc-candidate", candidate: e.candidate.candidate, mid: e.candidate.sdpMid ?? "0" }); };
    await pc.setLocalDescription();
    this.sendJson({ t: "rtc-offer", sdp: pc.localDescription!.sdp });
    await opened;
    this.dc = dc;
  }

  close(): void { clearInterval(this.pingTimer); this.dc?.close(); this.pc?.close(); this.ws.close(1000); }
}

// Client-side world model: prediction, reconciliation and interpolation (no DOM, usable from tests and bots).
import { INTERP_DELAY_MS } from "../shared/protocol.ts";
import type { Input, PlayerState, Shot, Snapshot } from "../shared/protocol.ts";
import { applyInput } from "../shared/sim.ts";

export interface Toggles { prediction: boolean; reconciliation: boolean; interpolation: boolean }
export interface Drawn { id: number; x: number; y: number; hp: number; alive: boolean; aim: number }

export class ClientWorld {
  toggles: Toggles = { prediction: true, reconciliation: true, interpolation: true };
  myId = 0;
  predicted = { x: 0, y: 0 };
  pending: Input[] = [];
  nextSeq = 1;
  snapshots: Snapshot[] = [];
  lastShots: Shot[] = [];
  stats = { snapshots: 0, corrections: 0, maxError: 0, lastError: 0, outOfOrder: 0 };
  private lastTick = 0;
  private spawned = false;
  private arrivalOffsets: number[] = [];   // arrival time minus snapshot time, in ms
  private offset = 0;

  // Called once per 1/60 s step: build the command, apply it locally, keep it until the server acknowledges it.
  makeInput(buttons: number, aim: number): Input {
    const input: Input = { seq: this.nextSeq++, buttons, aim };
    this.pending.push(input);
    if (this.toggles.prediction) applyInput(this.predicted, input);
    return input;
  }

  onSnapshot(s: Snapshot, arrivedAt: number): void {
    if (s.tick <= this.lastTick) { this.stats.outOfOrder++; return; }   // unordered channel: never go back in time
    this.lastTick = s.tick;
    this.snapshots.push(s);
    // The render clock follows the snapshot stream. The smallest arrival offset of the last 20 snapshots is the least delayed one,
    // so it equals the network latency without queueing and keeps the clock independent of jitter.
    this.arrivalOffsets.push(arrivedAt - s.time);
    if (this.arrivalOffsets.length > 20) this.arrivalOffsets.shift();
    this.offset = Math.min(...this.arrivalOffsets);
    if (this.snapshots.length > 40) this.snapshots.shift();
    this.lastShots = s.shots;
    this.stats.snapshots++;
    const me = s.players.find((p) => p.id === this.myId);
    if (!me) return;
    if (!this.spawned) { this.spawned = true; this.predicted.x = me.x; this.predicted.y = me.y; }   // adopt the spawn point
    this.pending = this.pending.filter((i) => i.seq > me.lastProcessedInput);   // acknowledged inputs are history
    if (!this.toggles.prediction) { this.predicted.x = me.x; this.predicted.y = me.y; return; }
    if (!this.toggles.reconciliation) return;                                   // prediction without correction drifts
    const replay = { x: me.x, y: me.y };
    for (const i of this.pending) applyInput(replay, i);                        // re-apply the unacknowledged inputs
    const err = Math.hypot(replay.x - this.predicted.x, replay.y - this.predicted.y);
    this.stats.lastError = err; this.stats.maxError = Math.max(this.stats.maxError, err);
    if (err > 0.01) this.stats.corrections++;
    this.predicted.x = replay.x; this.predicted.y = replay.y;
  }

  // The server time currently on screen; also what the shooter reports to the server for lag compensation.
  viewTime(clientNow: number): number {
    const latest = this.snapshots[this.snapshots.length - 1];
    if (!latest) return 0;
    return this.toggles.interpolation ? Math.floor(clientNow - this.offset - INTERP_DELAY_MS) : latest.time;
  }

  drawn(clientNow: number): Drawn[] {
    const latest = this.snapshots[this.snapshots.length - 1];
    if (!latest) return [];
    const out: Drawn[] = [];
    const rt = this.viewTime(clientNow);
    for (const p of latest.players) {
      if (p.id === this.myId && this.toggles.prediction) {
        out.push({ id: p.id, x: this.predicted.x, y: this.predicted.y, hp: p.hp, alive: p.alive, aim: p.aim });
      } else out.push(this.toggles.interpolation ? this.interpolate(p.id, rt) ?? p : p);
    }
    return out;
  }

  // Interpolate between the two snapshots around renderTime; hold the newest one instead of extrapolating.
  interpolate(id: number, renderTime: number): Drawn | null {
    const s = this.snapshots;
    for (let i = s.length - 1; i > 0; i--) {
      const a = s[i - 1], b = s[i];
      if (renderTime >= a.time && renderTime <= b.time) {
        const pa = a.players.find((p) => p.id === id), pb = b.players.find((p) => p.id === id);
        if (!pb) return null;
        if (!pa) return pb;
        const k = (renderTime - a.time) / (b.time - a.time || 1);
        return { id, x: pa.x + (pb.x - pa.x) * k, y: pa.y + (pb.y - pa.y) * k, hp: pb.hp, alive: pb.alive, aim: pb.aim };
      }
    }
    const last = s[s.length - 1]?.players.find((p) => p.id === id);
    return renderTime > (s[s.length - 1]?.time ?? 0) ? last ?? null : s[0]?.players.find((p) => p.id === id) ?? null;
  }
}
export type { PlayerState };

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Pixel Arena</title>
  <style>
    body { margin: 0; background: #14161c; color: #e8eaf0; font: 14px system-ui, sans-serif; }
    #lobby { max-width: 520px; margin: 40px auto; padding: 0 16px; }
    #lobby button, #lobby input { font: inherit; padding: 6px 10px; margin: 2px; }
    #rooms li { margin: 6px 0; }
    #game { display: none; width: 100vw; max-height: 100vh; aspect-ratio: 16 / 9; background: #1d2230; touch-action: none; }
    #hud { position: fixed; left: 8px; top: 8px; font: 12px ui-monospace, monospace; white-space: pre; pointer-events: none; }
  </style>
</head>
<body>
  <div id="lobby">
    <h1>Pixel Arena</h1>
    <p><label>Name <input id="name" value="player" maxlength="16"></label>
       <label><input id="rtc" type="checkbox"> data channel</label></p>
    <p><button id="create">Create room</button> <button id="ready" disabled>Ready</button> <button id="leave" disabled>Leave</button></p>
    <ul id="rooms"></ul>
    <pre id="roster"></pre>
  </div>
  <canvas id="game" width="1280" height="720"></canvas>
  <div id="hud"></div>
  <script type="module" src="/main.js"></script>
</body>
</html>

// Browser entry: lobby UI, fixed 60 Hz input loop, canvas rendering.
import { ARENA_H, ARENA_W, BTN_DOWN, BTN_FIRE, BTN_LEFT, BTN_RIGHT, BTN_UP, INPUT_HZ, PLAYER_RADIUS } from "../shared/protocol.ts";
import type { Input } from "../shared/protocol.ts";
import { radToAim } from "../shared/sim.ts";
import { Connection } from "./net.ts";
import type { Json } from "./net.ts";
import { ClientWorld } from "./world.ts";

const $ = <T extends HTMLElement>(id: string) => document.getElementById(id) as T;
const q = new URLSearchParams(location.search);
const conn = new Connection(`${location.protocol === "https:" ? "wss" : "ws"}://${location.host}/ws`);
conn.sim = { delayMs: Number(q.get("lag") ?? 0), jitterMs: Number(q.get("jitter") ?? 0) };   // ?lag=60&jitter=10 adds 60-70 ms each way
const world = new ClientWorld();
const canvas = $<HTMLCanvasElement>("game"); const ctx = canvas.getContext("2d")!;
const keys = new Set<string>(); let mouse = { x: ARENA_W / 2, y: ARENA_H / 2, down: false };
const forced: { buttons: number | null; aim: number | null } = { buttons: null, aim: null };   // test hook
let inRoom = false, playing = false, myReady = false, lagComp = true;

conn.onJson = (m: Json) => {
  switch (m.t) {
    case "rooms":
      $("rooms").innerHTML = "";
      for (const r of m.rooms) {
        const li = document.createElement("li");
        li.textContent = `${r.name} ${r.players}/${r.max} ${r.state}${r.lagComp ? "" : " (no lag comp)"} `;
        const b = document.createElement("button"); b.textContent = "Join"; b.onclick = () => conn.sendJson({ t: "join", room: r.id });
        li.append(b); $("rooms").append(li);
      }
      break;
    case "joined": inRoom = true; world.myId = m.you; lagComp = m.lagComp; ($("ready") as HTMLButtonElement).disabled = false; ($("leave") as HTMLButtonElement).disabled = false; break;
    case "left": inRoom = false; playing = false; ($("ready") as HTMLButtonElement).disabled = true; ($("leave") as HTMLButtonElement).disabled = true; $("roster").textContent = ""; break;
    case "roster": $("roster").textContent = m.players.map((p: any) => `${p.id === world.myId ? ">" : " "} ${p.name} ${p.ready ? "ready" : "-"} frags ${p.frags}`).join("\n"); break;
    case "start": playing = true; $("lobby").style.display = "none"; canvas.style.display = "block"; break;
    case "end": playing = false; $("lobby").style.display = ""; canvas.style.display = "none"; myReady = false; break;
    case "error": console.warn("server error", m); break;
  }
};

$("create").onclick = () => conn.sendJson({ t: "create", name: `${($("name") as HTMLInputElement).value}'s arena`, max: 8, lagComp: true });
$("ready").onclick = async () => {
  myReady = !myReady;
  if (myReady && ($("rtc") as HTMLInputElement).checked && !conn.dc) await conn.startRtc().catch((e) => console.warn("data channel failed, staying on WebSocket", e));
  conn.sendJson({ t: "ready", ready: myReady });
};
$("leave").onclick = () => conn.sendJson({ t: "leave" });
addEventListener("keydown", (e) => { keys.add(e.code); if (e.code === "KeyP") world.toggles.prediction = !world.toggles.prediction; if (e.code === "KeyR") world.toggles.reconciliation = !world.toggles.reconciliation; if (e.code === "KeyI") world.toggles.interpolation = !world.toggles.interpolation; });
addEventListener("keyup", (e) => keys.delete(e.code));
canvas.addEventListener("pointermove", (e) => { const r = canvas.getBoundingClientRect(); mouse.x = ((e.clientX - r.left) / r.width) * ARENA_W; mouse.y = ((e.clientY - r.top) / r.height) * ARENA_H; });
canvas.addEventListener("pointerdown", () => (mouse.down = true));
addEventListener("pointerup", () => (mouse.down = false));

conn.onSnapshot = (s, at) => world.onSnapshot(s, at);

function sampleButtons(): number {
  if (forced.buttons !== null) return forced.buttons;
  let b = 0;
  if (keys.has("KeyA") || keys.has("ArrowLeft")) b |= BTN_LEFT;
  if (keys.has("KeyD") || keys.has("ArrowRight")) b |= BTN_RIGHT;
  if (keys.has("KeyW") || keys.has("ArrowUp")) b |= BTN_UP;
  if (keys.has("KeyS") || keys.has("ArrowDown")) b |= BTN_DOWN;
  if (mouse.down) b |= BTN_FIRE;
  return b;
}

// Fixed-step loop: 60 commands per second regardless of the display refresh rate.
const STEP_MS = 1000 / INPUT_HZ;
let acc = 0, last = performance.now();
function frame(now: number): void {
  acc += Math.min(now - last, 250); last = now;           // cap catch-up after a background tab
  const fresh: Input[] = [];
  while (acc >= STEP_MS) {
    acc -= STEP_MS;
    if (!playing) continue;
    const me = world.predicted;
    const aim = forced.aim ?? radToAim(Math.atan2(mouse.y - me.y, mouse.x - me.x));
    fresh.push(world.makeInput(sampleButtons(), aim));
  }
  if (playing && fresh.length > 0) conn.sendInputs(fresh, world.pending, world.viewTime(now));
  draw(now);
  requestAnimationFrame(frame);
}

function draw(now: number): void {
  ctx.clearRect(0, 0, ARENA_W, ARENA_H);
  if (!playing) return;
  for (const p of world.drawn(now)) {
    ctx.globalAlpha = p.alive ? 1 : 0.25;
    ctx.fillStyle = p.id === world.myId ? "#4cc2ff" : "#ff8a4c";
    ctx.beginPath(); ctx.arc(p.x, p.y, PLAYER_RADIUS, 0, Math.PI * 2); ctx.fill();
    const a = (p.aim / 65536) * Math.PI * 2;
    ctx.strokeStyle = "#fff"; ctx.beginPath(); ctx.moveTo(p.x, p.y); ctx.lineTo(p.x + Math.cos(a) * 24, p.y + Math.sin(a) * 24); ctx.stroke();
    ctx.fillStyle = "#3a3"; ctx.fillRect(p.x - 16, p.y - 28, (32 * p.hp) / 100, 4);
  }
  ctx.globalAlpha = 1; ctx.strokeStyle = "#ffe36b";
  for (const s of world.lastShots) {
    const shooter = world.snapshots.at(-1)?.players.find((p) => p.id === s.shooter);
    if (shooter) { ctx.beginPath(); ctx.moveTo(shooter.x, shooter.y); ctx.lineTo(s.x, s.y); ctx.stroke(); }
  }
  $("hud").textContent = `rtt ${conn.clock.rtt.toFixed(0)} ms  snapshots ${world.stats.snapshots}  corrections ${world.stats.corrections}  maxErr ${world.stats.maxError.toFixed(1)} px\n` +
    `[P]rediction ${world.toggles.prediction}  [R]econciliation ${world.toggles.reconciliation}  [I]nterpolation ${world.toggles.interpolation}  lagComp ${lagComp}  channel ${conn.dc ? "rtc" : "ws"}`;
}

await conn.connect(($("name") as HTMLInputElement).value);
requestAnimationFrame(frame);
if (q.has("debug")) (window as any).__arena = { world, conn, forced, state: () => ({ inRoom, playing }) };

npm install
npm run build:client      # esbuild -> public/main.js
npm run check             # tsc --noEmit
MIN_PLAYERS=1 node src/server/server.ts
# open http://localhost:8080 in two browser windows, create a room in one, join from the other, press Ready in both

// Drives two headless Chrome pages through lobby -> match and prints what the client saw.
import puppeteer from "puppeteer-core";

const BASE = process.env.BASE ?? "http://localhost:8080";
const CHROME = process.env.CHROME ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
const browser = await puppeteer.launch({ executablePath: CHROME, headless: "new", args: ["--no-sandbox", "--no-first-run", "--disable-renderer-backgrounding", "--disable-background-timer-throttling", "--disable-backgrounding-occluded-windows"] });
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const query = process.env.QUERY ?? "debug=1";

const a = await (await browser.createBrowserContext()).newPage(); a.on("pageerror", (e) => console.log("A err:", e.message)); await a.goto(`${BASE}/?${query}`);
const b = await (await browser.createBrowserContext()).newPage(); await b.goto(`${BASE}/?${query}`);
await sleep(500);
await a.evaluate(() => document.querySelector("#create").click()); await sleep(300);
await b.waitForSelector("#rooms button"); await b.evaluate(() => document.querySelector("#rooms button").click()); await sleep(300);
if (process.env.RTC) { await a.evaluate(() => document.querySelector("#rtc").click()); await b.evaluate(() => document.querySelector("#rtc").click()); }
await a.evaluate(() => document.querySelector("#ready").click()); await b.evaluate(() => document.querySelector("#ready").click());
await a.waitForFunction(() => window.__arena?.state().playing, { timeout: 15000 });
await sleep(500);

await a.evaluate(() => { window.__arena.forced.buttons = 2; });   // hold right for one second
await sleep(1000);
await a.evaluate(() => { window.__arena.forced.buttons = 0; });
await sleep(500);
const report = await a.evaluate(() => {
  const { world, conn } = window.__arena;
  const last = world.snapshots.at(-1);
  const me = last.players.find((p) => p.id === world.myId);
  return { predicted: world.predicted, server: { x: me.x, y: me.y }, pending: world.pending.length, stats: world.stats, rtt: conn.clock.rtt, channel: conn.dc ? "rtc" : "ws", bytesIn: conn.bytesIn, msgsIn: conn.msgsIn };
});
console.log(JSON.stringify(report, null, 1));
await browser.close();

{
 "predicted": {
  "x": 355.8125,
  "y": 152.1875
 },
 "server": {
  "x": 355.8125,
  "y": 152.1875
 },
 "pending": 1,
 "stats": {
  "snapshots": 40,
  "corrections": 0,
  "maxError": 0,
  "lastError": 0,
  "outOfOrder": 0
 },
 "rtt": 1,
 "channel": "ws",
 "bytesIn": 1463,
 "msgsIn": 47
}

{
 "predicted": {
  "x": 846.1875,
  "y": 435.4375
 },
 "server": {
  "x": 846.1875,
  "y": 435.4375
 },
 "pending": 13,
 "stats": {
  "snapshots": 38,
  "corrections": 0,
  "maxError": 0,
  "lastError": 0,
  "outOfOrder": 0
 },
 "rtt": 235.2000000178814,
 "channel": "ws",
 "bytesIn": 1384,
 "msgsIn": 44
}

// Applies Chrome DevTools network throttling (CDP Network.emulateNetworkConditions) and reads the game's own RTT.
import puppeteer from "puppeteer-core";

const BASE = process.env.BASE ?? "http://localhost:8080";
const CHROME = process.env.CHROME ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const browser = await puppeteer.launch({ executablePath: CHROME, headless: "new", args: ["--no-first-run"] });
const page = await (await browser.createBrowserContext()).newPage();
const cdp = await page.createCDPSession();
await cdp.send("Network.enable");
await page.goto(`${BASE}/?debug=1`);
await sleep(1500);
const emulate = (latency) => cdp.send("Network.emulateNetworkConditions", { offline: false, latency, downloadThroughput: (1.6 * 1024 * 1024) / 8, uploadThroughput: (750 * 1024) / 8 });
const rtt = () => page.evaluate(() => Math.round(window.__arena.conn.clock.rtt));
console.log("no throttling       rtt ms:", await rtt());
await emulate(300);                                   // throttle, then open a NEW WebSocket by reloading
await page.reload(); await sleep(4000);
console.log("throttled before the socket opened, rtt ms:", await rtt(), "(latency 300 ms requested)");
const t0 = Date.now(); await page.evaluate(() => fetch("/healthz").then((r) => r.text())); console.log("HTTP fetch took ms:", Date.now() - t0);
await browser.close();

no throttling       rtt ms: 1
throttled before the socket opened, rtt ms: 24 (latency 300 ms requested)
HTTP fetch took ms: 317

// Does DevTools throttling reach the data channel? Compare the game's RTT on the channel before and after emulateNetworkConditions.
import puppeteer from "puppeteer-core";

const BASE = process.env.BASE ?? "http://localhost:8080";
const CHROME = process.env.CHROME ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const browser = await puppeteer.launch({ executablePath: CHROME, headless: "new", args: ["--no-first-run"] });
const page = await (await browser.createBrowserContext()).newPage();
const cdp = await page.createCDPSession();
await page.goto(`${BASE}/?debug=1`); await sleep(800);
await page.evaluate(() => document.querySelector("#create").click()); await sleep(400);
await page.evaluate(() => document.querySelector("#rtc").click());
await page.evaluate(() => document.querySelector("#ready").click());
await page.waitForFunction(() => window.__arena.conn.dc?.readyState === "open", { polling: 100 });
const rtt = () => page.evaluate(() => Math.round(window.__arena.conn.clock.rtt));
await sleep(2500);
console.log("channel open, rtt ms:", await rtt());
await cdp.send("Network.emulateNetworkConditions", { offline: false, latency: 200, downloadThroughput: -1, uploadThroughput: -1, packetLoss: 5 });
await sleep(3500);
console.log("after emulateNetworkConditions(latency 200, packetLoss 5), rtt ms:", await rtt());
await browser.close();

channel open, rtt ms: 2
after emulateNetworkConditions(latency 200, packetLoss 5), rtt ms: 1

// Measures what prediction and interpolation change on screen, in a real browser with 100 ms of simulated delay each way.
import puppeteer from "puppeteer-core";

const BASE = process.env.BASE ?? "http://localhost:8080";
const CHROME = process.env.CHROME ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const browser = await puppeteer.launch({ executablePath: CHROME, headless: "new", args: ["--no-first-run", "--disable-renderer-backgrounding", "--disable-background-timer-throttling"] });
const open = async () => { const p = await (await browser.createBrowserContext()).newPage(); await p.goto(`${BASE}/?debug=1&lag=100`); return p; };
const a = await open(), b = await open();
await sleep(800);
await a.evaluate(() => document.querySelector("#create").click()); await sleep(500);
await b.evaluate(() => document.querySelector("#rooms button").click()); await sleep(500);
await a.evaluate(() => document.querySelector("#ready").click()); await b.evaluate(() => document.querySelector("#ready").click());
await a.waitForFunction(() => window.__arena.state().playing, { polling: 100 });
await sleep(1500);

// 1. Input latency: time from "key down" to the first change of the player's own drawn position.
async function inputLatency(page, prediction) {
  return page.evaluate(async (prediction) => {
    const { world, conn, forced } = window.__arena;
    world.toggles.prediction = prediction;
    forced.buttons = 0; await new Promise((r) => setTimeout(r, 1000));
    const mine = () => world.drawn(performance.now()).find((p) => p.id === world.myId);
    const x0 = mine().x, t0 = performance.now();
    forced.buttons = world.predicted.x < 600 ? 2 : 1;
    return await new Promise((resolve) => { const tick = () => { if (Math.abs(mine().x - x0) > 0.5) resolve(Math.round(performance.now() - t0)); else requestAnimationFrame(tick); }; tick(); });
  }, prediction);
}
const withPrediction = [], without = [];
for (let i = 0; i < 5; i++) { withPrediction.push(await inputLatency(a, true)); without.push(await inputLatency(a, false)); }
await a.evaluate(() => { window.__arena.forced.buttons = 0; window.__arena.world.toggles.prediction = true; });
console.log("input-to-pixel latency, prediction on  (ms):", withPrediction.join(" "));
console.log("input-to-pixel latency, prediction off (ms):", without.join(" "));

// 2. Smoothness of a remote player: fraction of rendered frames in which player A's drawn position changed on B's screen.
await a.evaluate(() => { window.__arena.forced.buttons = 2; setInterval(() => { const w = window.__arena.world; window.__arena.forced.buttons = w.predicted.x > 1100 ? 1 : w.predicted.x < 180 ? 2 : window.__arena.forced.buttons; }, 50); });
async function smoothness(interpolation) {
  return b.evaluate(async (interpolation) => {
    const { world } = window.__arena; world.toggles.interpolation = interpolation;
    const idA = [...new Set(world.snapshots.at(-1).players.map((p) => p.id))].find((id) => id !== world.myId);
    let frames = 0, changed = 0, last = null, maxStep = 0;
    await new Promise((resolve) => { const t0 = performance.now(); const tick = (now) => {
      const p = world.drawn(now).find((q) => q.id === idA);
      if (last !== null) { frames++; const d = Math.abs(p.x - last); if (d > 0.01) changed++; maxStep = Math.max(maxStep, d); }
      last = p.x; if (now - t0 < 3000) requestAnimationFrame(tick); else resolve(); }; requestAnimationFrame(tick); });
    return { frames, changedPct: Math.round((100 * changed) / frames), maxStepPx: +maxStep.toFixed(1) };
  }, interpolation);
}
console.log("remote player, interpolation on :", JSON.stringify(await smoothness(true)));
console.log("remote player, interpolation off:", JSON.stringify(await smoothness(false)));
await browser.close();

input-to-pixel latency, prediction on  (ms): 3 16 16 16 17
input-to-pixel latency, prediction off (ms): 300 282 282 281 283
remote player, interpolation on : {"frames":180,"changedPct":100,"maxStepPx":4.2}
remote player, interpolation off: {"frames":180,"changedPct":33,"maxStepPx":12}

// Headless bots: a runner paces left and right, a shooter aims at where it SEES the runner and fires.
// Prints one JSON line with RTT, snapshot cadence, prediction error and hit rate. Run it against any server.
import { BTN_DOWN, BTN_FIRE, BTN_LEFT, BTN_RIGHT, BTN_UP, INPUT_HZ } from "../shared/protocol.ts";
import type { Input } from "../shared/protocol.ts";
import { radToAim } from "../shared/sim.ts";
import { Connection } from "../client/net.ts";
import type { Json } from "../client/net.ts";
import { ClientWorld } from "../client/world.ts";

const URL_ = process.env.URL ?? "ws://127.0.0.1:8080/ws";
const TRANSPORT = process.env.TRANSPORT ?? "ws";             // ws | rtc
const SECONDS = Number(process.env.SECONDS ?? 20);
const LAG = Number(process.env.LAG ?? 0), JITTER = Number(process.env.JITTER ?? 0);   // in-process delay simulation
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function makeBot(name: string, role: "runner" | "shooter", createRoom: boolean, roomId?: string) {
  const conn = new Connection(URL_, TRANSPORT === "rtc" ? await rtcGlobals() : undefined);
  conn.sim = { delayMs: LAG, jitterMs: JITTER };
  const world = new ClientWorld();
  const bot = { conn, world, name, roomId: roomId ?? "", playing: false, settled: false, fired: 0, hits: 0, gaps: [] as number[], lastSnapAt: 0, ownShotTicks: new Set<number>() };
  conn.onJson = (m: Json) => {
    if (m.t === "joined") world.myId = m.you;
    if (m.t === "rooms" && createRoom && !bot.roomId) bot.roomId = m.rooms.find((r: any) => r.name === "bench")?.id ?? "";
    if (m.t === "start") bot.playing = true;
  };
  conn.onSnapshot = (s, at) => {
    if (bot.lastSnapAt) bot.gaps.push(at - bot.lastSnapAt);
    bot.lastSnapAt = at;
    world.onSnapshot(s, at);
    for (const sh of s.shots) if (sh.shooter === world.myId && !bot.ownShotTicks.has(s.tick)) { bot.ownShotTicks.add(s.tick); if (sh.target !== 0) bot.hits++; }
  };
  await conn.connect(name);
  if (createRoom) conn.sendJson({ t: "create", name: "bench", max: 4, lagComp: process.env.LAGCOMP !== "off" });
  return bot;
}

async function rtcGlobals() {
  const mod = await import("node-datachannel/polyfill");
  return { RTCPeerConnection: mod.RTCPeerConnection as unknown as typeof RTCPeerConnection };
}

function drive(bot: Awaited<ReturnType<typeof makeBot>>, role: "runner" | "shooter", other: () => number): () => void {
  const STEP = 1000 / INPUT_HZ; let acc = 0, last = performance.now(), dir = BTN_RIGHT, nextFire = performance.now() + 1500;
  const timer = setInterval(() => {
    const now = performance.now(); acc += Math.min(now - last, 250); last = now;
    if (!bot.playing) { acc = 0; return; }
    const fresh: Input[] = [];
    while (acc >= STEP) {
      acc -= STEP;
      let buttons = 0, aim = 0;
      const me = bot.world.predicted;
      // Phase 1: walk to a fixed station so every run has the same geometry (runner on y=600, shooter at 640,100).
      const station = role === "runner" ? { x: me.x, y: 600 } : { x: 640, y: 100 };
      const arrived = Math.abs(me.x - station.x) < 4 && Math.abs(me.y - station.y) < 4;
      if (!arrived && !bot.settled) {
        if (me.x < station.x - 3) buttons |= BTN_RIGHT; else if (me.x > station.x + 3) buttons |= BTN_LEFT;
        if (me.y < station.y - 3) buttons |= BTN_DOWN; else if (me.y > station.y + 3) buttons |= BTN_UP;
      } else if (role === "runner") {
        bot.settled = true;                                    // Phase 2: pace left and right at 240 px/s
        if (me.x > 1100) dir = BTN_LEFT; if (me.x < 180) dir = BTN_RIGHT;
        buttons = dir;
      } else {
        bot.settled = true;
        const target = bot.world.drawn(now).find((p) => p.id === other());
        if (target) aim = radToAim(Math.atan2(target.y - me.y, target.x - me.x));
        if (target && now >= nextFire && bot.settled) { buttons = BTN_FIRE; nextFire = now + 400; bot.fired++; }
      }
      fresh.push(bot.world.makeInput(buttons, aim));
    }
    if (fresh.length > 0) bot.conn.sendInputs(fresh, bot.world.pending, bot.world.viewTime(now));
  }, 4);
  return () => clearInterval(timer);
}

const pct = (a: number[], q: number) => { const s = [...a].sort((x, y) => x - y); return s.length ? +s[Math.min(s.length - 1, Math.floor(q * s.length))].toFixed(1) : 0; };

const shooter = await makeBot("shooter", "shooter", true);
await sleep(300);
const runner = await makeBot("runner", "runner", false, shooter.roomId);
await sleep(300);
runner.conn.sendJson({ t: "join", room: shooter.roomId });
await sleep(300);
if (TRANSPORT === "rtc") { await shooter.conn.startRtc(); await runner.conn.startRtc(); }
shooter.conn.sendJson({ t: "ready", ready: true }); runner.conn.sendJson({ t: "ready", ready: true });
while (!shooter.playing) await sleep(50);
await sleep(1000);
const stop1 = drive(shooter, "shooter", () => runner.world.myId);
const stop2 = drive(runner, "runner", () => shooter.world.myId);
while (!(shooter.settled && runner.settled)) await sleep(100);
await sleep(1500);
shooter.fired = 0; shooter.hits = 0;
shooter.gaps.length = 0; runner.gaps.length = 0; shooter.world.stats.corrections = 0; runner.world.stats.corrections = 0; runner.world.stats.maxError = 0;
const bytes0 = runner.conn.bytesIn;
await sleep(SECONDS * 1000);
stop1(); stop2();
const out = {
  transport: shooter.conn.dc ? "rtc" : "ws", lagComp: process.env.LAGCOMP !== "off", seconds: SECONDS, simDelayMs: LAG,
  rttMs: +runner.conn.clock.rtt.toFixed(1),
  snapshotsPerSec: +(runner.gaps.length / SECONDS).toFixed(1),
  gapMs: { p50: pct(runner.gaps, 0.5), p95: pct(runner.gaps, 0.95), p99: pct(runner.gaps, 0.99), max: pct(runner.gaps, 1) },
  runnerCorrections: runner.world.stats.corrections, runnerMaxErrorPx: +runner.world.stats.maxError.toFixed(1),
  outOfOrder: runner.world.stats.outOfOrder, kbpsDown: +(((runner.conn.bytesIn - bytes0) * 8) / 1000 / SECONDS).toFixed(1),
  shotsFired: shooter.fired, hits: shooter.hits, hitRatePct: shooter.fired ? +((100 * shooter.hits) / shooter.fired).toFixed(0) : 0,
};
console.log(JSON.stringify(out));
process.exit(0);

#!/bin/sh
# Usage: scripts/netem-matrix.sh   (needs Docker; applies the same impairment in both directions)
set -e
export COMPOSE_PROJECT_NAME="${COMPOSE_PROJECT_NAME:-pixel-arena-netem}"
export SHOT_DAMAGE=0 MIN_PLAYERS=2          # the runner must stay alive so hit rates are comparable
run() {  # $1 label  $2 netem rule  $3 transport  $4 lag compensation (on|off)
  export NETEM_SERVER="$2" NETEM_CLIENT="$2" TRANSPORT="$3" LAGCOMP="$4"
  docker compose up -d --force-recreate --wait arena >/dev/null 2>&1
  printf '%s | %s | %s | ' "$1" "$3" "$4"
  docker compose run --rm --no-deps -T bench 2>/dev/null | tail -n 1
}
run "baseline"                  ""                          ws  on
run "delay 50ms 10ms"           "delay 50ms 10ms"           ws  on
run "delay 50ms 10ms"           "delay 50ms 10ms"           ws  off
run "delay 100ms 30ms"          "delay 100ms 30ms"          ws  on
run "delay 100ms 30ms"          "delay 100ms 30ms"          ws  off
run "delay 50ms 10ms loss 5%"   "delay 50ms 10ms loss 5%"   ws  on
run "delay 50ms 10ms loss 5%"   "delay 50ms 10ms loss 5%"   rtc on
docker compose down -v >/dev/null 2>&1