Multiplayer Netcode skill for Claude Code

# Prediction, reconciliation, interpolation, lag compensation, rollback

Reference loops in TypeScript-style pseudocode. They assume one shared, deterministic
`simulate(state, input, dt)` used by both client and server; that shared function is the
single most important property of working netcode.

```ts
const TICK = 1 / 60;
type Input = { seq: number; tick: number; moveX: number; moveY: number; buttons: number };
type PlayerState = { x: number; y: number; vx: number; vy: number };

function simulate(s: PlayerState, i: Input, dt: number): PlayerState {
  const speed = 6;
  const vx = i.moveX * speed, vy = i.moveY * speed;
  return { x: s.x + vx * dt, y: s.y + vy * dt, vx, vy };
}
```

## 1. Client: prediction and reconciliation

```ts
class PredictedPlayer {
  state: PlayerState = { x: 0, y: 0, vx: 0, vy: 0 };
  pending: Input[] = [];          // sent but not yet acknowledged by the server
  seq = 0;
  visualOffset = { x: 0, y: 0 };  // for smoothing corrections

  tick(raw: { moveX: number; moveY: number; buttons: number }, clientTick: number) {
    const input: Input = { seq: ++this.seq, tick: clientTick, ...raw };
    this.pending.push(input);
    send({ type: 'input', inputs: this.pending.slice(-4) });   // redundancy: last 4 inputs
    this.state = simulate(this.state, input, TICK);            // predict immediately
  }

  onServerSnapshot(authoritative: PlayerState, lastProcessedSeq: number) {
    const before = { x: this.state.x, y: this.state.y };
    // 1. drop inputs the server has processed
    this.pending = this.pending.filter((i) => i.seq > lastProcessedSeq);
    // 2. rewind to server truth, 3. replay the rest
    let s = authoritative;
    for (const i of this.pending) s = simulate(s, i, TICK);
    this.state = s;
    // 4. smooth small corrections, snap large ones
    const ex = before.x - s.x, ey = before.y - s.y;
    if (Math.hypot(ex, ey) < 2) { this.visualOffset.x += ex; this.visualOffset.y += ey; }
    else this.visualOffset = { x: 0, y: 0 };
  }

  renderPosition(dtFrame: number) {
    const decay = Math.exp(-dtFrame / 0.1);                    // ~100 ms smoothing
    this.visualOffset.x *= decay; this.visualOffset.y *= decay;
    return { x: this.state.x + this.visualOffset.x, y: this.state.y + this.visualOffset.y };
  }
}
```

Debug aid: log `(seq, predicted, authoritative)` pairs. Non-zero error in straight-line
movement means the two simulations differ; find the divergent input, not a bigger smoothing
factor.

## 2. Server: authoritative tick

```ts
class ServerPlayer {
  state: PlayerState = { x: 0, y: 0, vx: 0, vy: 0 };
  queue = new Map<number, Input>();   // seq -> input
  lastProcessedSeq = 0;
  lastInput: Input | null = null;

  receive(inputs: Input[]) {
    for (const i of inputs) {
      if (i.seq <= this.lastProcessedSeq || this.queue.has(i.seq)) continue;  // duplicate
      if (!isValid(i)) { flag(i); continue; }   // clamp axes to [-1,1], known buttons only
      this.queue.set(i.seq, i);
    }
  }

  tick() {
    const next = this.queue.get(this.lastProcessedSeq + 1);
    const input = next ?? (this.lastInput && { ...this.lastInput, seq: this.lastProcessedSeq });
    if (next) { this.queue.delete(next.seq); this.lastProcessedSeq = next.seq; this.lastInput = next; }
    if (input) this.state = simulate(this.state, input, TICK);
  }
}
// every snapshot interval: send each client its own state + lastProcessedSeq,
// and other entities' states stamped with the server tick
```

Process one input per tick per player. If a client floods inputs (speed hack by sending
more than one per tick), the queue grows; cap it (e.g. 8) and drop the excess.

## 3. Remote entity interpolation

```ts
type Snap = { serverTime: number; x: number; y: number };

class InterpolatedEntity {
  buffer: Snap[] = [];
  push(s: Snap) { this.buffer.push(s); if (this.buffer.length > 32) this.buffer.shift(); }

  sample(renderServerTime: number): { x: number; y: number } | null {
    // renderServerTime = estimatedServerNow - interpDelay (e.g. 100 ms)
    const b = this.buffer;
    for (let i = b.length - 1; i > 0; i--) {
      const a = b[i - 1], c = b[i];
      if (a.serverTime <= renderServerTime && renderServerTime <= c.serverTime) {
        const t = (renderServerTime - a.serverTime) / (c.serverTime - a.serverTime);
        return { x: a.x + (c.x - a.x) * t, y: a.y + (c.y - a.y) * t };
      }
    }
    const last = b[b.length - 1];
    return last ?? null;   // starved: hold last (or extrapolate briefly, capped)
  }
}
```

Choose `interpDelay` as about 2 snapshot intervals plus observed jitter. Track how often
the buffer starves; adapt the delay upward when it does.

## 4. Server-side lag compensation

```ts
type Hitbox = { id: number; x: number; y: number; r: number };
const history: { time: number; boxes: Hitbox[] }[] = [];   // ring buffer, ~1 s
const MAX_REWIND = 0.25;                                   // seconds

function recordHistory(now: number, boxes: Hitbox[]) {
  history.push({ time: now, boxes: boxes.map((b) => ({ ...b })) });
  while (history.length && now - history[0].time > 1) history.shift();
}

function validateShot(now: number, shooterViewTime: number, ray: Ray): number | null {
  // shooterViewTime = time the client was rendering remote entities at when it fired
  const t = Math.max(shooterViewTime, now - MAX_REWIND);
  const frame = closestFrames(history, t);            // interpolate between two records
  return raycastHitboxes(ray, frame);                  // id of the hit entity or null
}
```

The client sends with each fire command its current interpolation render time (or the tick
pair and fraction it was rendering). Never trust a client-supplied time beyond the cap.

## 5. Rollback loop (GGPO-style)

```ts
const INPUT_DELAY = 2;        // frames
const MAX_ROLLBACK = 8;       // frames
let frame = 0;
const states = new Map<number, GameState>();       // frame -> snapshot (save every frame)
const localInputs = new Map<number, PadInput>();
const remoteInputs = new Map<number, PadInput>();   // confirmed
let lastConfirmedRemote = -1;

function advance() {
  localInputs.set(frame + INPUT_DELAY, readPad());
  send({ frame: frame + INPUT_DELAY, input: localInputs.get(frame + INPUT_DELAY) });

  if (frame - lastConfirmedRemote > MAX_ROLLBACK) return;   // stall: too far ahead

  const remote = remoteInputs.get(frame) ?? predictRemote(frame);  // usually repeat last
  states.set(frame, save(current));
  current = step(current, localInputs.get(frame)!, remote);
  frame++;
}

function onRemoteInput(f: number, input: PadInput) {
  remoteInputs.set(f, input);
  lastConfirmedRemote = Math.max(lastConfirmedRemote, f);
  if (f < frame && input !== predictedFor(f)) {
    current = load(states.get(f)!);                 // roll back
    for (let g = f; g < frame; g++) {
      states.set(g, save(current));
      current = step(current, localInputs.get(g)!, remoteInputs.get(g) ?? predictRemote(g));
    }
  }
}
```

Requirements: `step` is deterministic and fast enough to run MAX_ROLLBACK + 1 times per
frame; `save`/`load` are cheap (flat arrays, no allocation); audio and particles are
triggered idempotently so a resimulated frame does not replay sounds. Exchange a state
checksum every N frames to detect desync early.

## 6. Clock and tick sync

- Ping/pong with timestamps every 1-2 s; RTT = now - sentTime; keep a median of the last
  10 samples.
- Server time estimate = serverTimestamp + RTT / 2.
- Client tick target = estimated server tick + (RTT / 2) / TICK + 1-2 ticks of safety, so
  inputs arrive just before the server needs them. Nudge by speeding or slowing the client
  tick by 1-5% rather than jumping.