Multiplayer Netcode skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Multiplayer Netcode"
  short_description: "Instant local feel, server-decided outcomes"
  default_prompt: "$multiplayer-netcode Our online player rubber-bands every few seconds, figure out why"

# Prediction, reconciliation and interpolation in detail

Read this when implementing client prediction for an authoritative server, or when debugging
rubber-banding. Code is engine-neutral TypeScript; the structure maps directly to C#, GDScript,
C++ or Rust.

## Data on the wire

```ts
// client -> server, unreliable, every tick
interface InputMsg {
  tick: number;              // client's simulation tick this input applies to
  inputs: PlayerInput[];     // newest last; includes the previous 2-4 for loss redundancy
}

// server -> client, unreliable, at snapshot rate
interface SnapshotMsg {
  serverTick: number;
  lastProcessedInputTick: number;   // per receiving client: newest input the server applied
  entities: EntityState[];          // quantised; delta-compressed against client's last ack
}
```

The server applies each client's inputs in tick order, ignoring duplicates (already-processed
ticks) and holding a small buffer (1-3 ticks) to absorb jitter. If an input for a tick never
arrives, repeat the last known input for that tick rather than stalling.

## Client side: predict and keep history

```ts
const HISTORY = 128;                                     // ring buffer covers ~2 s at 60 Hz
const inputHistory: (PlayerInput | undefined)[] = new Array(HISTORY);
const stateHistory: (PlayerState | undefined)[] = new Array(HISTORY);

function clientTick(tick: number, input: PlayerInput) {
  inputHistory[tick % HISTORY] = input;
  local = simulatePlayer(local, input, DT);             // SAME function the server runs
  stateHistory[tick % HISTORY] = clone(local);
  send({ tick, inputs: lastN(inputHistory, tick, 3) });
}
```

`simulatePlayer` must be a pure function of (state, input, DT): no frame time, no randomness
outside a seeded generator in state, no reads from interpolated remote entities unless you
accept corrections when they differ.

## Client side: reconcile

```ts
const EPSILON = 0.01;   // metres; below this, ignore tiny float differences

function onSnapshot(snap: SnapshotMsg) {
  const ackTick = snap.lastProcessedInputTick;
  const serverState = findSelf(snap.entities);
  const predicted = stateHistory[ackTick % HISTORY];
  if (!predicted) return;

  if (distance(predicted.position, serverState.position) < EPSILON &&
      predicted.velocity.equals(serverState.velocity)) {
    return;                                              // prediction was right
  }

  // Rewind to authoritative state and replay every input after it.
  const before = local.position.clone();
  local = clone(serverState);
  stateHistory[ackTick % HISTORY] = clone(local);
  for (let t = ackTick + 1; t <= currentTick; t++) {
    const input = inputHistory[t % HISTORY];
    if (!input) continue;
    local = simulatePlayer(local, input, DT);
    stateHistory[t % HISTORY] = clone(local);
  }

  // Visual smoothing: offset the rendered mesh and decay it over ~100 ms.
  renderOffset.add(before.sub(local.position));
}
```

Each frame, decay `renderOffset` toward zero (`renderOffset.scale(Math.exp(-dt * 20))`) and
draw the player at `local.position + renderOffset`. The simulation stays exact; only the
visual catches up smoothly.

If a physics engine moves the player, reconciliation must also restore the physics body state
and re-step it per replayed tick. Engines whose physics world cannot be stepped for one body
alone (most built-in ones) need a kinematic character controller for the predicted player.

## Remote entities: snapshot interpolation

```ts
const INTERP_DELAY_TICKS = 6;           // e.g. 100 ms at 60 Hz tick, covers 2 snapshots at 20-30 Hz
const buffer = new Map<EntityId, { tick: number; state: EntityState }[]>();

function renderRemote(id: EntityId, renderServerTick: number) {
  const snaps = buffer.get(id)!;        // sorted by tick, trimmed to ~1 s
  const target = renderServerTick - INTERP_DELAY_TICKS;
  for (let i = snaps.length - 1; i > 0; i--) {
    const a = snaps[i - 1], b = snaps[i];
    if (a.tick <= target && target <= b.tick) {
      const t = (target - a.tick) / (b.tick - a.tick);
      return lerpState(a.state, b.state, t);
    }
  }
  return snaps.at(-1)!.state;           // buffer starved: hold last (or extrapolate briefly, max ~100 ms)
}
```

`renderServerTick` is the client's estimate of the current server tick (fractional), derived
from snapshot arrivals with smoothing. Adjust the client's clock slowly (speed up or slow
down by 1-2%) to keep the buffer at its target size instead of jumping.

## Server: lag compensation for hitscan

```ts
// Server keeps per-entity hitbox history for MAX_REWIND ticks.
function processFire(shooter: Player, msg: FireMsg) {
  const viewTick = msg.clientTick - INTERP_DELAY_TICKS;     // what the shooter saw
  const rewind = Math.min(serverTick - viewTick, MAX_REWIND_TICKS);
  const hit = raycastAgainstHistory(msg.origin, msg.dir, serverTick - rewind, shooter.id);
  if (hit && validateFire(shooter, msg)) applyDamage(hit.target, weaponDamage(shooter));
}
```

Validate the fire message first: weapon owned, ammo available, rate of fire respected, origin
near the shooter's server position. Cap rewind so that high-ping players cannot shoot far into
the past.

## Rollback (peer-to-peer, deterministic)

Same shape as reconciliation, applied to the whole game state:

1. Each peer simulates every frame using local input plus predicted remote input (repeat last).
2. When real remote input for frame F arrives and differs from the prediction, load the saved
   state for F, re-simulate F..now with corrected inputs, and continue.
3. Save state every frame (fast snapshot: plain arrays, no allocations) and keep a window of
   roughly 8 frames; beyond the window, stall or add input delay.
4. Add 1-3 frames of input delay to reduce rollback frequency; let players see it in options.

Libraries: GGPO (C++), GGRS (Rust, Bevy via bevy_ggrs), Photon Fusion and Quantum (Unity,
commercial). Use one rather than writing the session protocol yourself.

## Debug overlay worth building

- Current RTT, jitter, packet loss (from sequence numbers).
- Interpolation buffer depth per remote entity (ticks).
- Prediction error per correction (metres) and correction count per second.
- Server tick vs estimated server tick drift.
- Toggle to draw server-authoritative positions as ghosts next to predicted ones.