Skip to content

3D engine that AI agents drive

59.8 KB
Raw Blame
// Multiplayer state sync as a runtime system. One side is the authority (a dedicated server or a host player) and owns the
// truth. It applies every client's inputs, then sends bounded delta snapshots of its entities. A client predicts its own
// entity from its own input, corrects it when the authoritative state arrives (reconciliation) and draws the other entities
// a little in the past, between two snapshots (interpolation). The transport is a plugin: any object with
// { id, peers(), send(peerId, message), receive(callback) }. This file ships an in-memory loopback for tests and a wrapper
// for a socket-like object. Nothing here opens a connection or a timer. See docs/netcode.md.

export const NETCODE_AUTHORITIES = Object.freeze(['server', 'host', 'peer']);
export const NETCODE_ROLES = Object.freeze(['authority', 'client']);

export const NETCODE_LIMITS = Object.freeze({
  maximumEntities: 256,
  maximumPeers: 32,
  maximumNameLength: 64,
  maximumVariablesPerEntity: 16,
  maximumInputKeys: 16,
  maximumInputsPerMessage: 8,
  maximumQueuedInputsPerPeer: 64,
  maximumPendingInputs: 128,
  maximumSnapshotHistory: 64,
  maximumSamplesPerEntity: 32,
  maximumInputRedundancy: 8,
  maximumInputsPerStep: 8,
  maximumCoordinate: 100000,
  maximumMessageBytes: 1048576,
  defaultMessageBytes: 65536,
});

const DEFAULT_PEER_TIMEOUT_MILLISECONDS = 5000;

const DEFAULTS = Object.freeze({
  snapshotEveryTicks: 2,
  inputRedundancy: 3,
  inputBufferSteps: 3,
  interpolationDelaySeconds: 0.1,
  maximumExtrapolationSeconds: 0.25,
  clockCorrectionRate: 0.1,
  positionStep: 0.01,
  rotationStep: 0.001,
  velocityStep: 0.01,
  variableStep: 0.01,
  movementSpeed: 5,
});

const VECTOR_FIELDS = Object.freeze([
  Object.freeze({ wire: 'p', name: 'position', length: 3, stepOption: 'positionStep' }),
  Object.freeze({ wire: 'r', name: 'rotation', length: 4, stepOption: 'rotationStep' }),
  Object.freeze({ wire: 'v', name: 'velocity', length: 3, stepOption: 'velocityStep' }),
]);

const MAXIMUM_WIRE_INTEGER = 1e12;

function describe(value) {
  return value === null ? 'null' : typeof value;
}

function isPlainObject(value) {
  return value !== null && typeof value === 'object' && !Array.isArray(value);
}

function requireName(value, label) {
  if (typeof value !== 'string' || value === '' || value.length > NETCODE_LIMITS.maximumNameLength) {
    throw new TypeError(`${label} must be a string of 1 to ${NETCODE_LIMITS.maximumNameLength} characters, got ${typeof value === 'string' ? `${value.length} characters` : describe(value)}.`);
  }
  return value;
}

function boundedNumber(value, label, minimum, maximum) {
  if (!Number.isFinite(value) || value < minimum || value > maximum) {
    throw new RangeError(`${label} must be a number from ${minimum} to ${maximum}, got ${String(value)}.`);
  }
  return value;
}

function boundedInteger(value, label, minimum, maximum) {
  if (!Number.isInteger(value) || value < minimum || value > maximum) {
    throw new RangeError(`${label} must be an integer from ${minimum} to ${maximum}, got ${String(value)}.`);
  }
  return value;
}

function createSeededRandom(seed) {
  let state = seed >>> 0;
  return () => {
    state = (state + 0x6d2b79f5) >>> 0;
    let mixed = Math.imul(state ^ (state >>> 15), state | 1);
    mixed ^= mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61);
    return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
  };
}

function validateTransport(transport, label) {
  if (!isPlainObject(transport)) {
    throw new TypeError(`${label} needs a transport: an object like { id, peers(), send(peerId, message), receive(callback) }, got ${describe(transport)}.`);
  }
  requireName(transport.id, `${label} transport.id`);
  for (const method of ['peers', 'send', 'receive']) {
    if (typeof transport[method] !== 'function') {
      throw new TypeError(`${label} transport.${method} must be a function. A transport is { id, peers(), send(peerId, message), receive(callback) }.`);
    }
  }
}

// ----- State: one entity is a position, a rotation, a velocity and a few named numbers -----

function readVector(value, length, label) {
  if (!Array.isArray(value) || value.length !== length) {
    throw new TypeError(`${label} must be an array of ${length} numbers, got ${Array.isArray(value) ? `${value.length} entries` : describe(value)}.`);
  }
  return value.map((component, index) => boundedNumber(component, `${label}[${index}]`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate));
}

function readVariables(value, label) {
  if (!isPlainObject(value)) throw new TypeError(`${label} must be an object of named numbers like { score: 3 }, got ${describe(value)}.`);
  const names = Object.keys(value);
  if (names.length > NETCODE_LIMITS.maximumVariablesPerEntity) {
    throw new RangeError(`${label} holds ${names.length} variables; at most ${NETCODE_LIMITS.maximumVariablesPerEntity} are synced per entity.`);
  }
  const variables = {};
  for (const name of names) {
    requireName(name, `${label} variable name`);
    variables[name] = boundedNumber(value[name], `${label}.${name}`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate);
  }
  return variables;
}

// Fills the parts a caller left out. `base` supplies them when it is given, so a partial update keeps the rest.
function readState(candidate, label, base = null) {
  if (!isPlainObject(candidate)) throw new TypeError(`${label} must be an object like { position, rotation, velocity, variables }, got ${describe(candidate)}.`);
  const state = {
    position: candidate.position === undefined ? [...(base?.position ?? [0, 0, 0])] : readVector(candidate.position, 3, `${label}.position`),
    rotation: candidate.rotation === undefined ? [...(base?.rotation ?? [0, 0, 0, 1])] : readVector(candidate.rotation, 4, `${label}.rotation`),
    velocity: candidate.velocity === undefined ? [...(base?.velocity ?? [0, 0, 0])] : readVector(candidate.velocity, 3, `${label}.velocity`),
    variables: candidate.variables === undefined ? { ...(base?.variables ?? {}) } : readVariables(candidate.variables, `${label}.variables`),
  };
  return state;
}

function cloneState(state) {
  return {
    position: [...state.position],
    rotation: [...state.rotation],
    velocity: [...state.velocity],
    variables: { ...state.variables },
  };
}

function distanceBetween(first, second) {
  return Math.hypot(first[0] - second[0], first[1] - second[1], first[2] - second[2]);
}

// ----- Inputs: a small object of numbers and booleans, checked on both ends -----

function readInput(candidate, label) {
  if (!isPlainObject(candidate)) throw new TypeError(`${label} must be an object of numbers and booleans like { moveX: 1, jump: true }, got ${describe(candidate)}.`);
  const names = Object.keys(candidate);
  if (names.length > NETCODE_LIMITS.maximumInputKeys) {
    throw new RangeError(`${label} has ${names.length} keys; at most ${NETCODE_LIMITS.maximumInputKeys} are sent per input.`);
  }
  const input = {};
  for (const name of names) {
    requireName(name, `${label} key`);
    const value = candidate[name];
    if (typeof value === 'boolean') {
      input[name] = value;
    } else {
      input[name] = boundedNumber(value, `${label}.${name}`, -NETCODE_LIMITS.maximumCoordinate, NETCODE_LIMITS.maximumCoordinate);
    }
  }
  return input;
}

// The default movement rule: input { moveX, moveZ } from -1 to 1 sets a flat velocity. Pass your own `simulate` for more.
export function createPlanarMovement(options = {}) {
  const speed = boundedNumber(options.speed ?? DEFAULTS.movementSpeed, 'createPlanarMovement speed', 0, 1000);
  return function planarMovement(state, input, stepSeconds) {
    const moveX = Math.max(-1, Math.min(1, Number(input.moveX) || 0));
    const moveZ = Math.max(-1, Math.min(1, Number(input.moveZ) || 0));
    const velocity = [moveX * speed, 0, moveZ * speed];
    const position = [
      state.position[0] + velocity[0] * stepSeconds,
      state.position[1],
      state.position[2] + velocity[2] * stepSeconds,
    ];
    return { ...state, position, velocity };
  };
}

// ----- Quantisation and deltas -----

function quantizeEntity(state, tag, steps) {
  const entity = {};
  if (tag !== null) entity.t = tag;
  for (const field of VECTOR_FIELDS) {
    const step = steps[field.stepOption];
    entity[field.wire] = state[field.name].map(component => Math.round(component / step));
  }
  entity.x = {};
  for (const [name, value] of Object.entries(state.variables)) entity.x[name] = Math.round(value / steps.variableStep);
  return entity;
}

function dequantizeEntity(entity, steps) {
  const state = {};
  for (const field of VECTOR_FIELDS) {
    const step = steps[field.stepOption];
    state[field.name] = entity[field.wire].map(integer => integer * step);
  }
  state.variables = {};
  for (const [name, integer] of Object.entries(entity.x)) state.variables[name] = integer * steps.variableStep;
  return state;
}

function sameNumbers(first, second) {
  return first.length === second.length && first.every((value, index) => value === second[index]);
}

// Only the parts of an entity that differ from `base`. Null when nothing differs; the whole entity when there is no base.
function diffEntity(base, current) {
  if (!base) return current;
  const delta = {};
  for (const field of VECTOR_FIELDS) {
    if (!sameNumbers(base[field.wire], current[field.wire])) delta[field.wire] = current[field.wire];
  }
  const changedVariables = {};
  for (const [name, value] of Object.entries(current.x)) {
    if (base.x[name] !== value) changedVariables[name] = value;
  }
  for (const name of Object.keys(base.x)) {
    if (!(name in current.x)) changedVariables[name] = null;
  }
  if (Object.keys(changedVariables).length > 0) delta.x = changedVariables;
  return Object.keys(delta).length > 0 ? delta : null;
}

function applyEntityDelta(base, delta) {
  const entity = { ...(base ?? {}) };
  if (delta.t !== undefined) entity.t = delta.t;
  for (const field of VECTOR_FIELDS) {
    if (delta[field.wire] !== undefined) entity[field.wire] = delta[field.wire];
  }
  const variables = { ...(base?.x ?? {}) };
  for (const [name, value] of Object.entries(delta.x ?? {})) {
    if (value === null) delete variables[name];
    else variables[name] = value;
  }
  entity.x = variables;
  return entity;
}

function readWireIntegers(value, length) {
  if (!Array.isArray(value) || value.length !== length) return null;
  for (const integer of value) {
    if (!Number.isSafeInteger(integer) || Math.abs(integer) > MAXIMUM_WIRE_INTEGER) return null;
  }
  return value;
}

// Network data is untrusted: returns the cleaned delta, or null when anything about it is wrong.
function readWireEntityDelta(raw, isNewEntity) {
  if (!isPlainObject(raw)) return null;
  const delta = {};
  if (raw.t !== undefined) {
    if (typeof raw.t !== 'string' || raw.t.length > NETCODE_LIMITS.maximumNameLength) return null;
    delta.t = raw.t;
  }
  for (const field of VECTOR_FIELDS) {
    if (raw[field.wire] === undefined) {
      if (isNewEntity) return null;
      continue;
    }
    const integers = readWireIntegers(raw[field.wire], field.length);
    if (!integers) return null;
    delta[field.wire] = integers;
  }
  if (raw.x !== undefined) {
    if (!isPlainObject(raw.x) || Object.keys(raw.x).length > NETCODE_LIMITS.maximumVariablesPerEntity) return null;
    delta.x = {};
    for (const [name, value] of Object.entries(raw.x)) {
      if (name.length > NETCODE_LIMITS.maximumNameLength) return null;
      if (value !== null && !(Number.isSafeInteger(value) && Math.abs(value) <= MAXIMUM_WIRE_INTEGER)) return null;
      delta.x[name] = value;
    }
  }
  return delta;
}

// ----- Interpolation -----

function blendVectors(first, second, fraction) {
  return first.map((component, index) => component + (second[index] - component) * fraction);
}

function normalizeQuaternion(quaternion) {
  const length = Math.hypot(...quaternion) || 1;
  return quaternion.map(component => component / length);
}

function blendRotations(first, second, fraction) {
  const sign = first[0] * second[0] + first[1] * second[1] + first[2] * second[2] + first[3] * second[3] < 0 ? -1 : 1;
  const flipped = second.map(component => component * sign);
  return normalizeQuaternion(blendVectors(first, flipped, fraction));
}

// The drawn state at `time`: between the two samples around it, or past the newest one moved on by its velocity for a short while.
function sampleAt(samples, time, maximumExtrapolationSeconds) {
  const first = samples[0];
  if (time <= first.time) return cloneState(first.state);
  const last = samples[samples.length - 1];
  if (time >= last.time) {
    const state = cloneState(last.state);
    const seconds = Math.min(time - last.time, maximumExtrapolationSeconds);
    state.position = state.position.map((component, index) => component + last.state.velocity[index] * seconds);
    return state;
  }
  let upperIndex = samples.length - 1;
  while (samples[upperIndex - 1].time > time) upperIndex -= 1;
  const before = samples[upperIndex - 1];
  const after = samples[upperIndex];
  const fraction = (time - before.time) / (after.time - before.time);
  return {
    position: blendVectors(before.state.position, after.state.position, fraction),
    rotation: blendRotations(before.state.rotation, after.state.rotation, fraction),
    velocity: blendVectors(before.state.velocity, after.state.velocity, fraction),
    variables: { ...before.state.variables },
  };
}

// ----- Options -----

function validateNetcodeOptions(options) {
  if (!isPlainObject(options)) throw new TypeError('createNetcode needs an options object like { role: "client", transport, serverId: "server" }.');
  validateTransport(options.transport, 'createNetcode');
  const authority = options.authority ?? 'server';
  if (!NETCODE_AUTHORITIES.includes(authority)) {
    throw new RangeError(`createNetcode authority must be one of ${NETCODE_AUTHORITIES.join(', ')}, got ${String(authority)}.`);
  }
  if (authority === 'peer' && options.role !== undefined && options.role !== 'peer') {
    throw new RangeError(`createNetcode authority "peer" has no authority or client role: every peer owns its own entities. Leave role out, got ${String(options.role)}.`);
  }
  const role = authority === 'peer' ? 'peer' : (options.role ?? 'client');
  if (role !== 'peer' && !NETCODE_ROLES.includes(role)) {
    throw new RangeError(`createNetcode role must be one of ${NETCODE_ROLES.join(', ')}, got ${String(role)}.`);
  }
  if (role === 'client') requireName(options.serverId, 'createNetcode serverId');
  for (const name of ['simulate', 'readInput']) {
    if (options[name] !== undefined && typeof options[name] !== 'function') {
      throw new TypeError(`createNetcode ${name} must be a function or left out, got ${describe(options[name])}.`);
    }
  }
  if (role !== 'authority' && options.localEntityId !== undefined) requireName(options.localEntityId, 'createNetcode localEntityId');
  return {
    role,
    authority,
    transport: options.transport,
    serverId: options.serverId,
    localEntityId: options.localEntityId,
    simulate: options.simulate ?? createPlanarMovement(),
    readInput: options.readInput,
    maximumMessageBytes: boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createNetcode maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes),
    snapshotEveryTicks: boundedInteger(options.snapshotEveryTicks ?? DEFAULTS.snapshotEveryTicks, 'createNetcode snapshotEveryTicks', 1, 60),
    inputRedundancy: boundedInteger(options.inputRedundancy ?? DEFAULTS.inputRedundancy, 'createNetcode inputRedundancy', 1, NETCODE_LIMITS.maximumInputRedundancy),
    inputBufferSteps: boundedInteger(options.inputBufferSteps ?? DEFAULTS.inputBufferSteps, 'createNetcode inputBufferSteps', 0, 16),
    interpolationDelaySeconds: boundedNumber(options.interpolationDelaySeconds ?? DEFAULTS.interpolationDelaySeconds, 'createNetcode interpolationDelaySeconds', 0, 2),
    maximumExtrapolationSeconds: boundedNumber(options.maximumExtrapolationSeconds ?? DEFAULTS.maximumExtrapolationSeconds, 'createNetcode maximumExtrapolationSeconds', 0, 2),
    steps: {
      positionStep: boundedNumber(options.positionStep ?? DEFAULTS.positionStep, 'createNetcode positionStep', 1e-6, 1),
      rotationStep: boundedNumber(options.rotationStep ?? DEFAULTS.rotationStep, 'createNetcode rotationStep', 1e-6, 1),
      velocityStep: boundedNumber(options.velocityStep ?? DEFAULTS.velocityStep, 'createNetcode velocityStep', 1e-6, 1),
      variableStep: boundedNumber(options.variableStep ?? DEFAULTS.variableStep, 'createNetcode variableStep', 1e-6, 1),
    },
  };
}

// ----- The authority side -----

const SESSION_ID_LENGTH_LIMIT = 64;
// Snapshots in a row of a run that sorts before the tracked one, with none of the tracked run between them.
const OLDER_RUN_ADOPTION_THRESHOLD = 30;

function isValidSession(session) {
  return typeof session === 'string' && session.length <= SESSION_ID_LENGTH_LIMIT;
}

// An id for one run of a client or authority. A restart on the same peer id gets a new one, so the other side can tell
// a new run from a late message of the old one. The start time comes first and has a fixed width, so a plain string
// comparison orders the runs: a message of an older run is stale even when no message of the newer run came before it.
let lastSessionTimestamp = 0;

function createSessionId() {
  // Two runs started in the same millisecond still get ordered times.
  lastSessionTimestamp = Math.max(Date.now(), lastSessionTimestamp + 1);
  // Fixed width, so the byte count of a run does not depend on the draw.
  const randomWords = new Uint32Array(1);
  globalThis.crypto.getRandomValues(randomWords);
  const randomPart = randomWords[0].toString(36).padStart(7, '0');
  return `${lastSessionTimestamp.toString(36).padStart(9, '0')}-${randomPart}`;
}

function highestInputSequence(inputs) {
  let highest = 0;
  for (const entry of inputs) {
    if (Number.isSafeInteger(entry?.sequence) && entry.sequence > highest) highest = entry.sequence;
  }
  return highest;
}

function createAuthority(settings, stats) {
  const { transport, steps } = settings;
  const entities = new Map(); // id -> { owner, tag, state }
  const peers = new Map(); // peer id -> { queue, lastQueuedSequence, lastProcessedSequence, acknowledgedTick }
  const history = new Map(); // tick -> Map(id -> quantised entity)
  const sessionId = createSessionId();
  let tick = 0;

  function peerRecord(peerId) {
    let record = peers.get(peerId);
    if (record) return record;
    if (peers.size >= NETCODE_LIMITS.maximumPeers) return null;
    record = { queue: [], lastQueuedSequence: 0, lastProcessedSequence: 0, acknowledgedTick: null, session: null };
    peers.set(peerId, record);
    return record;
  }

  // A client that restarted on the same peer id starts over at sequence 1 with no snapshots.
  function resetPeerRecord(record) {
    record.queue.length = 0;
    record.lastQueuedSequence = 0;
    record.lastProcessedSequence = 0;
    record.acknowledgedTick = null;
  }

  function receiveMessage(peerId, message) {
    const record = peerRecord(peerId);
    const inputs = isPlainObject(message) && message.type === 'input' && Array.isArray(message.inputs) ? message.inputs : null;
    if (!record || !inputs || inputs.length > NETCODE_LIMITS.maximumInputsPerMessage) {
      stats.rejectedMessages += 1;
      return;
    }
    if (message.session !== undefined) {
      if (!isValidSession(message.session)) {
        stats.rejectedMessages += 1;
        return;
      }
      if (record.session !== null && record.session !== message.session) resetPeerRecord(record);
      record.session = message.session;
    }
    // The newest message carries the client's current state; an older one reordered behind it must not undo that.
    const newestSequence = highestInputSequence(inputs);
    const isNewestMessage = newestSequence > record.lastQueuedSequence;
    if (message.acknowledgedTick === null && isNewestMessage) {
      // The client holds no snapshot (it reset on a restart), so the base we remember is gone.
      record.acknowledgedTick = null;
    }
    // An ack from an earlier run of the authority cannot name a base this run has: by the run id the client says it is
    // tracking, or, for a client that does not send one, by a tick beyond this run's tick.
    const trackedRun = message.authoritySession;
    if (trackedRun !== undefined && trackedRun !== null && !isValidSession(trackedRun)) {
      stats.rejectedMessages += 1;
      return;
    }
    const ackBelongsToThisRun = trackedRun === undefined ? message.acknowledgedTick <= tick : trackedRun === sessionId;
    if (Number.isInteger(message.acknowledgedTick) && ackBelongsToThisRun && message.acknowledgedTick >= (record.acknowledgedTick ?? -1)) {
      record.acknowledgedTick = message.acknowledgedTick;
    }
    for (const entry of inputs) {
      try {
        const sequence = boundedInteger(entry?.sequence, 'input sequence', 1, Number.MAX_SAFE_INTEGER);
        if (sequence <= record.lastQueuedSequence) continue;
        record.queue.push({ sequence, input: readInput(entry.input, 'input') });
        record.lastQueuedSequence = sequence;
      } catch {
        stats.rejectedMessages += 1;
      }
    }
    while (record.queue.length > NETCODE_LIMITS.maximumQueuedInputsPerPeer) record.queue.shift();
  }

  function entityOwnedBy(peerId) {
    for (const entity of entities.values()) {
      if (entity.owner === peerId) return entity;
    }
    return null;
  }

  function applyInput(entity, input, stepSeconds) {
    entity.state = readState(settings.simulate(cloneState(entity.state), input, stepSeconds), 'simulate result', entity.state);
    stats.inputsProcessed += 1;
  }

  function processInputs(stepSeconds) {
    for (const [peerId, record] of peers) {
      if (record.queue.length === 0) continue;
      const backlog = record.queue.length - settings.inputBufferSteps;
      const count = Math.min(Math.max(1, backlog), NETCODE_LIMITS.maximumInputsPerStep, record.queue.length);
      const entity = entityOwnedBy(peerId);
      for (let index = 0; index < count; index += 1) {
        const { sequence, input } = record.queue.shift();
        if (entity) applyInput(entity, input, stepSeconds);
        record.lastProcessedSequence = sequence;
      }
    }
    if (settings.readInput) {
      const hostEntity = entityOwnedBy(transport.id);
      if (hostEntity) applyInput(hostEntity, readInput(settings.readInput(), 'readInput result'), stepSeconds);
    }
  }

  function dropDisconnectedPeers(currentPeers) {
    for (const peerId of peers.keys()) {
      if (!currentPeers.includes(peerId)) peers.delete(peerId);
    }
  }

  function buildSnapshot() {
    const snapshot = new Map();
    for (const [id, entity] of entities) snapshot.set(id, quantizeEntity(entity.state, entity.tag, steps));
    history.set(tick, snapshot);
    while (history.size > NETCODE_LIMITS.maximumSnapshotHistory) history.delete(history.keys().next().value);
    return snapshot;
  }

  function buildMessage(snapshot, record) {
    const base = record.acknowledgedTick !== null && history.has(record.acknowledgedTick) ? record.acknowledgedTick : null;
    const baseEntities = base === null ? null : history.get(base);
    const changed = {};
    for (const [id, entity] of snapshot) {
      const delta = diffEntity(baseEntities?.get(id) ?? null, entity);
      if (delta) changed[id] = delta;
    }
    const removed = baseEntities ? [...baseEntities.keys()].filter(id => !snapshot.has(id)) : [];
    return {
      type: 'snapshot',
      session: sessionId,
      tick,
      base,
      lastProcessedInput: record.lastProcessedSequence,
      entities: changed,
      removed,
    };
  }

  function sendSnapshots() {
    const currentPeers = transport.peers();
    dropDisconnectedPeers(currentPeers);
    const snapshot = buildSnapshot();
    for (const peerId of currentPeers.slice(0, NETCODE_LIMITS.maximumPeers)) {
      const record = peerRecord(peerId);
      if (!record) continue;
      const message = buildMessage(snapshot, record);
      const bytes = JSON.stringify(message).length;
      if (bytes > settings.maximumMessageBytes) {
        throw new RangeError(`A netcode snapshot is ${bytes} bytes, over maximumMessageBytes ${settings.maximumMessageBytes}. Sync fewer entities or variables, or raise maximumMessageBytes (up to ${NETCODE_LIMITS.maximumMessageBytes}).`);
      }
      transport.send(peerId, message);
      stats.snapshotsSent += 1;
      stats.bytesSent += bytes;
      if (message.base === null) stats.fullSnapshotsSent += 1;
    }
  }

  return {
    receiveMessage,
    fixedUpdate(stepSeconds) {
      processInputs(stepSeconds);
      tick += 1;
      if (tick % settings.snapshotEveryTicks === 0) sendSnapshots();
    },
    addEntity(id, definition = {}) {
      requireName(id, 'addEntity id');
      if (entities.has(id)) throw new RangeError(`addEntity: an entity named "${id}" already exists. Use setEntityState to change it.`);
      if (entities.size >= NETCODE_LIMITS.maximumEntities) {
        throw new RangeError(`A netcode world syncs at most ${NETCODE_LIMITS.maximumEntities} entities. Remove some, or sync only what players see.`);
      }
      const owner = definition.owner === undefined ? null : requireName(definition.owner, 'addEntity owner');
      const tag = definition.tag === undefined ? null : requireName(definition.tag, 'addEntity tag');
      if (owner !== null && entityOwnedBy(owner)) {
        throw new RangeError(`addEntity: "${owner}" already owns an entity. A peer drives one entity.`);
      }
      entities.set(id, { owner, tag, state: readState(definition.state ?? {}, `addEntity "${id}" state`) });
    },
    removeEntity(id) {
      if (!entities.delete(id)) throw new RangeError(`removeEntity: no entity named "${String(id)}". Present: ${[...entities.keys()].join(', ') || 'none'}.`);
    },
    setEntityState(id, partialState) {
      const entity = entities.get(id);
      if (!entity) throw new RangeError(`setEntityState: no entity named "${String(id)}". Present: ${[...entities.keys()].join(', ') || 'none'}. Use addEntity first.`);
      entity.state = readState(partialState, `setEntityState "${id}" state`, entity.state);
    },
    getEntityState(id) {
      const entity = entities.get(id);
      return entity ? cloneState(entity.state) : null;
    },
    entityIds: () => [...entities.keys()],
    get tick() { return tick; },
  };
}

// ----- The client side -----

function createClient(settings, stats) {
  const { transport, steps } = settings;
  const localEntityId = settings.localEntityId ?? null;
  const receivedStates = new Map(); // tick -> Map(id -> quantised entity)
  const samples = new Map(); // id -> [{ time, state }]
  const pendingInputs = []; // { sequence, input }, not yet confirmed by a snapshot
  let stepSeconds = null;
  const sessionId = createSessionId();
  let authoritySession = null;
  let consecutiveSnapshotsOfOlderRun = 0;
  let latestTick = -1;
  let inputSequence = 0;
  let predicted = null;
  let renderTime = null;

  function reconcile(authoritativeState, lastProcessedInput) {
    while (pendingInputs.length > 0 && pendingInputs[0].sequence <= lastProcessedInput) pendingInputs.shift();
    const before = predicted;
    let corrected = authoritativeState;
    for (const { input } of pendingInputs) {
      corrected = readState(settings.simulate(cloneState(corrected), input, stepSeconds), 'simulate result', corrected);
    }
    predicted = corrected;
    stats.reconciliations += 1;
    if (before) {
      stats.lastCorrection = distanceBetween(before.position, predicted.position);
      stats.maximumCorrection = Math.max(stats.maximumCorrection, stats.lastCorrection);
    }
  }

  // The authority restarted on the same peer id: its ticks start over, so everything held from the old run is dropped
  // and the next snapshot is asked for in full.
  function resetForNewAuthority() {
    latestTick = -1;
    receivedStates.clear();
    samples.clear();
    pendingInputs.length = 0;
    predicted = null;
    renderTime = null;
    consecutiveSnapshotsOfOlderRun = 0;
    stats.authorityRestarts += 1;
  }

  function readSnapshot(message) {
    if (!isPlainObject(message) || message.type !== 'snapshot' || !Number.isSafeInteger(message.tick) || message.tick < 0) return null;
    if (message.base !== null && !Number.isSafeInteger(message.base)) return null;
    if (!isPlainObject(message.entities) || Object.keys(message.entities).length > NETCODE_LIMITS.maximumEntities) return null;
    if (!Array.isArray(message.removed) || message.removed.length > NETCODE_LIMITS.maximumEntities) return null;
    if (!Number.isSafeInteger(message.lastProcessedInput) || message.lastProcessedInput < 0) return null;
    return message;
  }

  function receiveMessage(peerId, rawMessage) {
    if (peerId !== settings.serverId) return;
    const message = readSnapshot(rawMessage);
    if (!message) {
      stats.rejectedMessages += 1;
      return;
    }
    if (message.session !== undefined) {
      if (!isValidSession(message.session)) {
        stats.rejectedMessages += 1;
        return;
      }
      // A snapshot of an earlier run that was still in flight must not reset the new run's state, even when it arrives
      // before any snapshot of the run it came from, so it is told apart by the run order and not by a list.
      if (authoritySession !== null && message.session < authoritySession) {
        stats.staleSnapshots += 1;
        consecutiveSnapshotsOfOlderRun += 1;
        // An authority restarted with a clock behind the first run's gets an id that sorts before it. When only the
        // lower id keeps arriving, the run being tracked is gone, so the other run is adopted.
        if (consecutiveSnapshotsOfOlderRun < OLDER_RUN_ADOPTION_THRESHOLD) return;
        resetForNewAuthority();
      } else if (authoritySession !== null && message.session > authoritySession) {
        resetForNewAuthority();
      } else {
        consecutiveSnapshotsOfOlderRun = 0;
      }
      authoritySession = message.session;
    }
    if (message.tick <= latestTick) {
      stats.staleSnapshots += 1;
      return;
    }
    const baseEntities = message.base === null ? new Map() : receivedStates.get(message.base);
    if (!baseEntities) {
      stats.missingBaseSnapshots += 1;
      return;
    }
    const full = new Map(baseEntities);
    for (const id of message.removed) full.delete(id);
    for (const [id, rawDelta] of Object.entries(message.entities)) {
      const delta = readWireEntityDelta(rawDelta, !full.has(id));
      if (!delta) {
        stats.rejectedMessages += 1;
        return;
      }
      full.set(id, applyEntityDelta(full.get(id) ?? null, delta));
    }
    if (full.size > NETCODE_LIMITS.maximumEntities) {
      stats.rejectedMessages += 1;
      return;
    }
    acceptSnapshot(message, full);
  }

  function acceptSnapshot(message, full) {
    latestTick = message.tick;
    stats.snapshotsReceived += 1;
    receivedStates.set(message.tick, full);
    while (receivedStates.size > NETCODE_LIMITS.maximumSnapshotHistory) receivedStates.delete(receivedStates.keys().next().value);
    const time = message.tick * stepSeconds;
    for (const id of samples.keys()) {
      if (!full.has(id)) samples.delete(id);
    }
    for (const [id, entity] of full) {
      const list = samples.get(id) ?? [];
      list.push({ time, state: dequantizeEntity(entity, steps) });
      while (list.length > NETCODE_LIMITS.maximumSamplesPerEntity) list.shift();
      samples.set(id, list);
    }
    if (renderTime === null) renderTime = time - settings.interpolationDelaySeconds;
    if (localEntityId !== null && full.has(localEntityId)) {
      reconcile(dequantizeEntity(full.get(localEntityId), steps), message.lastProcessedInput);
    }
  }

  function sendInput(context) {
    inputSequence += 1;
    const input = settings.readInput ? readInput(settings.readInput(context), 'readInput result') : {};
    if (settings.readInput) {
      pendingInputs.push({ sequence: inputSequence, input });
      while (pendingInputs.length > NETCODE_LIMITS.maximumPendingInputs) pendingInputs.shift();
      if (predicted) predicted = readState(settings.simulate(cloneState(predicted), input, stepSeconds), 'simulate result', predicted);
    }
    transport.send(settings.serverId, {
      type: 'input',
      session: sessionId,
      authoritySession,
      acknowledgedTick: latestTick >= 0 ? latestTick : null,
      inputs: pendingInputs.slice(-settings.inputRedundancy).map(({ sequence, input: pending }) => ({ sequence, input: pending })),
    });
  }

  // Moves the drawing clock on with real time, nudged by at most a tenth toward "newest snapshot minus the delay".
  function advanceRenderTime(deltaSeconds) {
    if (renderTime === null) return;
    const target = latestTick * stepSeconds - settings.interpolationDelaySeconds;
    const error = target - renderTime;
    if (Math.abs(error) > 1) {
      renderTime = target;
      return;
    }
    const limit = deltaSeconds * DEFAULTS.clockCorrectionRate;
    renderTime += deltaSeconds + Math.max(-limit, Math.min(limit, error));
  }

  return {
    receiveMessage,
    setStep(seconds) { stepSeconds = seconds; },
    fixedUpdate(step, context) {
      stepSeconds = step;
      sendInput(context);
    },
    update(deltaSeconds) {
      advanceRenderTime(deltaSeconds);
    },
    getEntityState(id) {
      if (id === localEntityId && predicted) return cloneState(predicted);
      const list = samples.get(id);
      if (!list || renderTime === null) return null;
      return sampleAt(list, renderTime, settings.maximumExtrapolationSeconds);
    },
    entityIds: () => [...samples.keys()],
    get latestTick() { return latestTick; },
    get pendingInputCount() { return pendingInputs.length; },
  };
}

// ----- The peer to peer side -----

// Every peer owns the entities it adds and sends their full state to all peers. When two peers claim one entity, the
// higher term wins, and on equal terms the lower peer id, so every peer settles on the same owner whatever the arrival order.
function claimBeats(candidateTerm, candidateOwner, currentTerm, currentOwner) {
  if (candidateTerm !== currentTerm) return candidateTerm > currentTerm;
  return candidateOwner < currentOwner;
}

function createPeerSide(settings, stats) {
  const { transport, steps } = settings;
  const selfId = transport.id;
  const entities = new Map(); // id -> { owner, term, tag, state, samples }
  const senders = new Map(); // peer id -> { session, lastTick }
  const sessionId = createSessionId();
  let tick = 0;
  let clock = 0;

  function isLocal(entity) {
    return entity.owner === selfId;
  }

  function listPresent() {
    return [...entities.keys()].join(', ') || 'none';
  }

  function requireLocalEntity(id, action) {
    const entity = entities.get(id);
    if (!entity) throw new RangeError(`${action}: no entity named "${String(id)}". Present: ${listPresent()}. Use addEntity first.`);
    if (!isLocal(entity)) throw new RangeError(`${action}: "${id}" is owned by peer "${entity.owner}". Call claimEntity("${id}") to take it over first.`);
    return entity;
  }

  // The record of a sender, null when there is no room for another, undefined when the message is of an older run.
  function senderRecord(peerId, session) {
    let record = senders.get(peerId);
    if (!record) {
      if (senders.size >= NETCODE_LIMITS.maximumPeers) return null;
      record = { session, lastTick: -1 };
      senders.set(peerId, record);
    }
    if (record.session !== session) {
      if (session < record.session) return undefined;
      record.session = session;
      record.lastTick = -1;
    }
    return record;
  }

  function acceptRemoteEntity(peerId, id, raw) {
    const delta = isPlainObject(raw) ? readWireEntityDelta(raw, true) : null;
    if (!delta || !Number.isSafeInteger(raw.m) || raw.m < 0) {
      stats.rejectedMessages += 1;
      return;
    }
    const known = entities.get(id);
    if (known && known.owner !== peerId) {
      if (!claimBeats(raw.m, peerId, known.term, known.owner)) return;
      stats.ownershipChanges += 1;
      known.samples = [];
    } else if (!known) {
      if (entities.size >= NETCODE_LIMITS.maximumEntities) return;
      stats.ownershipChanges += 1;
    } else if (raw.m < known.term) {
      return;
    }
    const entity = known ?? { samples: [] };
    entity.owner = peerId;
    entity.term = raw.m;
    entity.tag = delta.t ?? null;
    entity.state = dequantizeEntity(delta, steps);
    entity.samples.push({ time: clock, state: cloneState(entity.state) });
    if (entity.samples.length > NETCODE_LIMITS.maximumSamplesPerEntity) entity.samples.shift();
    entities.set(id, entity);
  }

  function receiveMessage(peerId, message) {
    const valid = isPlainObject(message) && message.type === 'peer-state' && isValidSession(message.session)
      && Number.isSafeInteger(message.tick) && message.tick >= 0 && isPlainObject(message.entities)
      && Object.keys(message.entities).length <= NETCODE_LIMITS.maximumEntities;
    const record = valid ? senderRecord(peerId, message.session) : null;
    if (!valid || record === null) {
      stats.rejectedMessages += 1;
      return;
    }
    if (record === undefined || message.tick <= record.lastTick) {
      stats.staleSnapshots += 1;
      return;
    }
    record.lastTick = message.tick;
    stats.snapshotsReceived += 1;
    for (const [id, raw] of Object.entries(message.entities)) {
      if (id.length > NETCODE_LIMITS.maximumNameLength) {
        stats.rejectedMessages += 1;
        continue;
      }
      acceptRemoteEntity(peerId, id, raw);
    }
  }

  function dropEntitiesOfGonePeers() {
    const present = new Set(transport.peers());
    for (const [id, entity] of entities) {
      if (!isLocal(entity) && !present.has(entity.owner)) entities.delete(id);
    }
  }

  function sendOwnedEntities() {
    const owned = {};
    for (const [id, entity] of entities) {
      if (isLocal(entity)) owned[id] = { ...quantizeEntity(entity.state, entity.tag, steps), m: entity.term };
    }
    const message = { type: 'peer-state', session: sessionId, tick, entities: owned };
    const bytes = JSON.stringify(message).length;
    if (bytes > settings.maximumMessageBytes) {
      throw new RangeError(`A netcode peer message is ${bytes} bytes, over maximumMessageBytes ${settings.maximumMessageBytes}. Own fewer entities or variables, or raise maximumMessageBytes (up to ${NETCODE_LIMITS.maximumMessageBytes}).`);
    }
    for (const peerId of transport.peers()) {
      if (peerId === selfId) continue;
      transport.send(peerId, message);
      stats.snapshotsSent += 1;
      stats.bytesSent += bytes;
    }
  }

  function drawnState(entity) {
    if (isLocal(entity) || entity.samples.length === 0) return cloneState(entity.state);
    return sampleAt(entity.samples, clock - settings.interpolationDelaySeconds, settings.maximumExtrapolationSeconds);
  }

  function moveLocalPlayer(step) {
    const player = settings.localEntityId ? entities.get(settings.localEntityId) : null;
    if (!settings.readInput || !player || !isLocal(player)) return;
    const input = readInput(settings.readInput(), 'readInput result');
    player.state = readState(settings.simulate(player.state, input, step), 'simulate result');
    stats.inputsProcessed += 1;
  }

  return {
    receiveMessage,
    fixedUpdate(step) {
      clock += step;
      dropEntitiesOfGonePeers();
      moveLocalPlayer(step);
      tick += 1;
      if (tick % settings.snapshotEveryTicks === 0) sendOwnedEntities();
    },
    addEntity(id, definition = {}) {
      requireName(id, 'addEntity id');
      if (entities.has(id)) throw new RangeError(`addEntity: an entity named "${id}" already exists. Use setEntityState to change it, or claimEntity to take over a remote one.`);
      if (entities.size >= NETCODE_LIMITS.maximumEntities) {
        throw new RangeError(`A netcode world syncs at most ${NETCODE_LIMITS.maximumEntities} entities. Remove some, or sync only what players see.`);
      }
      if (definition.owner !== undefined && definition.owner !== selfId) {
        throw new RangeError(`addEntity: in peer to peer a peer adds only entities it owns. Leave owner out or pass "${selfId}", got ${String(definition.owner)}.`);
      }
      const tag = definition.tag === undefined ? null : requireName(definition.tag, 'addEntity tag');
      entities.set(id, { owner: selfId, term: 0, tag, state: readState(definition.state ?? {}, `addEntity "${id}" state`), samples: [] });
    },
    removeEntity(id) {
      requireLocalEntity(id, 'removeEntity');
      entities.delete(id);
    },
    setEntityState(id, partialState) {
      const entity = requireLocalEntity(id, 'setEntityState');
      entity.state = readState(partialState, `setEntityState "${id}" state`, entity.state);
    },
    // Take over an entity another peer owns, starting from the state this peer sees. The raised term beats the old owner on every peer.
    claimEntity(id) {
      const entity = entities.get(id);
      if (!entity) throw new RangeError(`claimEntity: no entity named "${String(id)}". Present: ${listPresent()}.`);
      if (isLocal(entity)) return;
      entity.state = drawnState(entity);
      entity.owner = selfId;
      entity.term += 1;
      entity.samples = [];
      stats.ownershipChanges += 1;
    },
    getEntityState(id) {
      const entity = entities.get(id);
      return entity ? drawnState(entity) : null;
    },
    getEntityOwner: id => entities.get(id)?.owner ?? null,
    entityIds: () => [...entities.keys()],
    get tick() { return tick; },
  };
}

// ----- createNetcode: the runtime system -----

function createSide(settings, stats) {
  if (settings.role === 'peer') return createPeerSide(settings, stats);
  return settings.role === 'authority' ? createAuthority(settings, stats) : createClient(settings, stats);
}

export function createNetcode(options) {
  const settings = validateNetcodeOptions(options);
  const stats = {
    snapshotsSent: 0,
    fullSnapshotsSent: 0,
    bytesSent: 0,
    inputsProcessed: 0,
    snapshotsReceived: 0,
    staleSnapshots: 0,
    missingBaseSnapshots: 0,
    authorityRestarts: 0,
    reconciliations: 0,
    lastCorrection: 0,
    maximumCorrection: 0,
    rejectedMessages: 0,
    ownershipChanges: 0,
  };
  const side = createSide(settings, stats);
  let unsubscribe = null;

  function requireAuthority(action) {
    if (settings.role === 'client') throw new TypeError(`${action} is only for the authority. This netcode is a client; the authority owns the entities.`);
  }

  const netcode = {
    name: 'netcode',
    get role() { return settings.role; },
    get authority() { return settings.authority; },
    get stats() { return { ...stats }; },
    get tick() { return settings.role === 'client' ? side.latestTick : side.tick; },
    get pendingInputCount() { return side.pendingInputCount ?? 0; },

    init(context) {
      side.setStep?.(context.fixedStepSeconds);
      // A second init must not leave the first subscription behind, or every message is handled twice.
      netcode.dispose();
      unsubscribe = settings.transport.receive((peerId, message) => side.receiveMessage(peerId, message));
    },
    fixedUpdate(step, context) {
      side.fixedUpdate(step, context);
    },
    update(deltaSeconds) {
      side.update?.(deltaSeconds);
    },
    dispose() {
      if (typeof unsubscribe === 'function') unsubscribe();
      unsubscribe = null;
    },

    // Authority: add an entity peers can see. `owner` is the peer id whose inputs drive it; `tag` names its kind.
    addEntity(id, definition) {
      requireAuthority('addEntity');
      side.addEntity(id, definition);
      return netcode;
    },
    removeEntity(id) {
      requireAuthority('removeEntity');
      side.removeEntity(id);
      return netcode;
    },
    // Authority: write a state the game computed itself (a physics prop, a teleport). Parts left out keep their value.
    setEntityState(id, partialState) {
      requireAuthority('setEntityState');
      side.setEntityState(id, partialState);
      return netcode;
    },
    // The state to draw: the truth on the authority, the prediction for the local entity, the interpolation for the rest.
    getEntityState(id) {
      return side.getEntityState(id);
    },
    // Peer to peer: take over an entity another peer owns. The raised term beats the old owner on every peer.
    claimEntity(id) {
      if (settings.role !== 'peer') throw new TypeError('claimEntity is only for peer to peer netcode (authority: "peer"). A server or host owns every entity already.');
      side.claimEntity(id);
      return netcode;
    },
    getEntityOwner(id) {
      return side.getEntityOwner?.(id) ?? null;
    },
    get entityIds() { return side.entityIds(); },
  };
  return netcode;
}

// ----- Transports -----

// An in-memory network for tests and local play. Time moves only when advance() is called, and latency, jitter and loss
// come from a seeded generator, so the same seed gives the same run. Messages are copied through JSON like a real wire.
export function createLoopbackNetwork(options = {}) {
  const seed = boundedInteger(options.seed ?? 1, 'createLoopbackNetwork seed', 0, 4294967295);
  const latencyMilliseconds = boundedNumber(options.latencyMilliseconds ?? 0, 'createLoopbackNetwork latencyMilliseconds', 0, 60000);
  const jitterMilliseconds = boundedNumber(options.jitterMilliseconds ?? 0, 'createLoopbackNetwork jitterMilliseconds', 0, 60000);
  const lossRate = boundedNumber(options.lossRate ?? 0, 'createLoopbackNetwork lossRate', 0, 1);
  const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.maximumMessageBytes, 'createLoopbackNetwork maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
  const maximumInFlight = boundedInteger(options.maximumInFlight ?? 4096, 'createLoopbackNetwork maximumInFlight', 1, 65536);
  const random = createSeededRandom(seed);
  const endpoints = new Map(); // id -> { listeners }
  const inFlight = [];
  const stats = { sent: 0, delivered: 0, dropped: 0 };
  let nowMilliseconds = 0;
  let sequence = 0;

  function send(fromId, toId, message) {
    if (!endpoints.has(toId)) throw new RangeError(`Loopback send: no transport named "${String(toId)}". Connected: ${[...endpoints.keys()].join(', ')}.`);
    const text = JSON.stringify(message);
    if (text === undefined || text.length > maximumMessageBytes) {
      throw new RangeError(`Loopback send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
    }
    stats.sent += 1;
    const lossDraw = random();
    const jitterDraw = random();
    if (lossDraw < lossRate || inFlight.length >= maximumInFlight) {
      stats.dropped += 1;
      return;
    }
    const delay = Math.max(0, latencyMilliseconds + (jitterDraw * 2 - 1) * jitterMilliseconds);
    sequence += 1;
    inFlight.push({ deliverAt: nowMilliseconds + delay, sequence, fromId, toId, text });
  }

  function deliverDue() {
    inFlight.sort((first, second) => first.deliverAt - second.deliverAt || first.sequence - second.sequence);
    while (inFlight.length > 0 && inFlight[0].deliverAt <= nowMilliseconds) {
      const packet = inFlight.shift();
      const endpoint = endpoints.get(packet.toId);
      if (!endpoint) continue;
      stats.delivered += 1;
      for (const listener of [...endpoint.listeners]) listener(packet.fromId, JSON.parse(packet.text));
    }
  }

  return {
    createTransport(id) {
      requireName(id, 'createTransport id');
      if (endpoints.has(id)) throw new RangeError(`createTransport: a transport named "${id}" is already connected.`);
      const endpoint = { listeners: new Set() };
      endpoints.set(id, endpoint);
      return {
        id,
        peers: () => [...endpoints.keys()].filter(other => other !== id),
        send: (peerId, message) => send(id, peerId, message),
        receive(callback) {
          if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
          endpoint.listeners.add(callback);
          return () => endpoint.listeners.delete(callback);
        },
        close() {
          endpoints.delete(id);
        },
      };
    },
    // Moves network time forward and delivers every message that is due.
    advance(milliseconds) {
      boundedNumber(milliseconds, 'advance milliseconds', 0, 60000);
      nowMilliseconds += milliseconds;
      deliverDue();
    },
    get stats() { return { ...stats, inFlight: inFlight.length }; },
    get nowMilliseconds() { return nowMilliseconds; },
  };
}

// Wraps a BroadcastChannel-like object ({ postMessage, addEventListener, close }) so tabs, windows and workers of one
// browser can play together with no server. Every peer hears the channel; a message names its sender and, when sent to one
// peer, its target. Peers find each other by a hello that the other side answers once, and leave with a goodbye on close().
export function createBroadcastChannelTransport(channel, options = {}) {
  if (channel === null || typeof channel !== 'object' || typeof channel.postMessage !== 'function' || typeof channel.addEventListener !== 'function') {
    throw new TypeError('createBroadcastChannelTransport needs a BroadcastChannel-like object with postMessage(value) and addEventListener(type, listener), such as new BroadcastChannel("my-game").');
  }
  const id = requireName(options.id, 'createBroadcastChannelTransport id');
  const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createBroadcastChannelTransport maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
  const peerTimeoutMilliseconds = boundedNumber(options.peerTimeoutMilliseconds ?? DEFAULT_PEER_TIMEOUT_MILLISECONDS, 'createBroadcastChannelTransport peerTimeoutMilliseconds', 50, 3600000);
  const now = options.now ?? Date.now;
  if (typeof now !== 'function') throw new TypeError('createBroadcastChannelTransport now must be a function that returns milliseconds, such as performance.now.');
  const listeners = new Set();
  const knownPeers = new Map();
  const stats = { sent: 0, received: 0, rejected: 0 };

  // A peer that closed its page without saying goodbye is forgotten once it has been silent for the timeout.
  // Netcode peers speak every tick, so a live one is heard again at once and re-learned if it was dropped.
  function forgetSilentPeers() {
    const oldestAllowed = now() - peerTimeoutMilliseconds;
    for (const [peerId, lastHeardAt] of knownPeers) {
      if (lastHeardAt < oldestAllowed) knownPeers.delete(peerId);
    }
  }

  function learnPeer(peerId) {
    if (!knownPeers.has(peerId)) {
      forgetSilentPeers();
      if (knownPeers.size >= NETCODE_LIMITS.maximumPeers) return false;
    }
    knownPeers.set(peerId, now());
    return true;
  }

  function onMessage(event) {
    const packet = event?.data;
    if (!isPlainObject(packet) || typeof packet.from !== 'string' || packet.from === '' || packet.from.length > NETCODE_LIMITS.maximumNameLength) {
      stats.rejected += 1;
      return;
    }
    const peerId = packet.from;
    const isForMe = packet.to === undefined || packet.to === id;
    if (peerId === id || !isForMe) return;
    if (packet.left === true) {
      knownPeers.delete(peerId);
      return;
    }
    const isNew = !knownPeers.has(peerId);
    if (!learnPeer(peerId)) {
      stats.rejected += 1;
      return;
    }
    if (packet.hello === true) {
      if (isNew && packet.to === undefined) channel.postMessage({ from: id, to: peerId, hello: true });
      return;
    }
    stats.received += 1;
    for (const listener of [...listeners]) listener(peerId, packet.data);
  }

  channel.addEventListener('message', onMessage);
  channel.postMessage({ from: id, hello: true });

  return {
    id,
    peers() {
      forgetSilentPeers();
      return [...knownPeers.keys()];
    },
    send(peerId, message) {
      const text = JSON.stringify(message);
      if (text === undefined || text.length > maximumMessageBytes) {
        throw new RangeError(`BroadcastChannel transport send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
      }
      channel.postMessage({ from: id, to: peerId, data: JSON.parse(text) });
      stats.sent += 1;
    },
    receive(callback) {
      if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
      listeners.add(callback);
      return () => listeners.delete(callback);
    },
    close() {
      channel.postMessage({ from: id, left: true });
      channel.removeEventListener?.('message', onMessage);
      listeners.clear();
      knownPeers.clear();
      channel.close?.();
    },
    get stats() { return { ...stats }; },
  };
}

// Wraps a socket-like object ({ send(text), addEventListener, readyState, close }) and opens nothing itself.
// By default the socket is a line to one peer (`remoteId`). With `multiplexed: true` it talks through a relay that
// wraps each message as { to, data } going out and { from, data } coming in, so a server or host can hear many clients.
export function createWebSocketTransport(socket, options = {}) {
  if (socket === null || typeof socket !== 'object' || typeof socket.send !== 'function' || typeof socket.addEventListener !== 'function') {
    throw new TypeError('createWebSocketTransport needs a socket-like object with send(text) and addEventListener(type, listener), such as a WebSocket you opened.');
  }
  const id = requireName(options.id ?? 'local', 'createWebSocketTransport id');
  const remoteId = requireName(options.remoteId ?? 'server', 'createWebSocketTransport remoteId');
  const multiplexed = options.multiplexed === true;
  const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createWebSocketTransport maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
  const openState = 1;
  const listeners = new Set();
  const relayPeers = new Set();
  const stats = { sent: 0, received: 0, rejected: 0 };

  function readPacket(text) {
    if (typeof text !== 'string' || text.length > maximumMessageBytes) return null;
    try {
      const parsed = JSON.parse(text);
      return isPlainObject(parsed) ? parsed : null;
    } catch {
      return null;
    }
  }

  function onMessage(event) {
    const packet = readPacket(event?.data);
    if (!packet) {
      stats.rejected += 1;
      return;
    }
    let peerId = remoteId;
    let message = packet;
    if (multiplexed) {
      if (typeof packet.from !== 'string' || packet.from === '' || packet.from.length > NETCODE_LIMITS.maximumNameLength) {
        stats.rejected += 1;
        return;
      }
      peerId = packet.from;
      if (packet.left === true) {
        relayPeers.delete(peerId);
        return;
      }
      if (relayPeers.size >= NETCODE_LIMITS.maximumPeers && !relayPeers.has(peerId)) {
        stats.rejected += 1;
        return;
      }
      relayPeers.add(peerId);
      message = packet.data;
    }
    stats.received += 1;
    for (const listener of [...listeners]) listener(peerId, message);
  }

  socket.addEventListener('message', onMessage);

  return {
    id,
    peers: () => multiplexed ? [...relayPeers] : socket.readyState === openState ? [remoteId] : [],
    send(peerId, message) {
      if (socket.readyState !== openState) return;
      const text = JSON.stringify(multiplexed ? { to: peerId, data: message } : message);
      if (text === undefined || text.length > maximumMessageBytes) {
        throw new RangeError(`WebSocket transport send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
      }
      socket.send(text);
      stats.sent += 1;
    },
    receive(callback) {
      if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
      listeners.add(callback);
      return () => listeners.delete(callback);
    },
    close() {
      socket.removeEventListener?.('message', onMessage);
      listeners.clear();
      socket.close?.();
    },
    get stats() { return { ...stats }; },
  };
}

// A transport over several WebRTC data channels (or any channel-like objects with send(text), addEventListener and
// readyState), one per peer. Your signalling code opens each RTCDataChannel and hands it over with addChannel(peerId, channel):
// a host adds one per player, a client adds one for the host. A peer is listed while its channel is open, so a player who
// disconnects leaves the peer list on its own; a channel that closes or errors is dropped and frees its peer slot. Nothing here opens a connection.
export function createDataChannelTransport(options = {}) {
  const id = requireName(options.id, 'createDataChannelTransport id');
  const maximumMessageBytes = boundedInteger(options.maximumMessageBytes ?? NETCODE_LIMITS.defaultMessageBytes, 'createDataChannelTransport maximumMessageBytes', 256, NETCODE_LIMITS.maximumMessageBytes);
  const openState = 'open';
  const listeners = new Set();
  const channels = new Map();
  const stats = { sent: 0, received: 0, rejected: 0 };

  function readMessage(text) {
    if (typeof text !== 'string' || text.length > maximumMessageBytes) return undefined;
    try {
      const parsed = JSON.parse(text);
      return isPlainObject(parsed) ? parsed : undefined;
    } catch {
      return undefined;
    }
  }

  function detach(entry) {
    entry.channel.removeEventListener?.('message', entry.onMessage);
    entry.channel.removeEventListener?.('close', entry.onClose);
    entry.channel.removeEventListener?.('error', entry.onClose);
  }

  function pruneClosedChannels() {
    for (const [peerId, entry] of channels) {
      if (entry.channel.readyState !== 'closed') continue;
      detach(entry);
      channels.delete(peerId);
    }
  }

  return {
    id,
    addChannel(peerId, channel) {
      requireName(peerId, 'addChannel peerId');
      if (channel === null || typeof channel !== 'object' || typeof channel.send !== 'function' || typeof channel.addEventListener !== 'function') {
        throw new TypeError('addChannel needs a data-channel-like object with send(text) and addEventListener(type, listener), such as an RTCDataChannel.');
      }
      if (!channels.has(peerId) && channels.size >= NETCODE_LIMITS.maximumPeers) pruneClosedChannels();
      if (!channels.has(peerId) && channels.size >= NETCODE_LIMITS.maximumPeers) {
        throw new RangeError(`addChannel: at most ${NETCODE_LIMITS.maximumPeers} peers are supported; remove one with removeChannel(peerId) first.`);
      }
      const previous = channels.get(peerId);
      if (previous) detach(previous);
      const entry = {
        channel,
        onMessage(event) {
          const message = readMessage(event?.data);
          if (message === undefined) {
            stats.rejected += 1;
            return;
          }
          stats.received += 1;
          for (const listener of [...listeners]) listener(peerId, message);
        },
        onClose() {
          if (channels.get(peerId) !== entry) return;
          detach(entry);
          channels.delete(peerId);
        },
      };
      channel.addEventListener('message', entry.onMessage);
      channel.addEventListener('close', entry.onClose);
      channel.addEventListener('error', entry.onClose);
      channels.set(peerId, entry);
    },
    removeChannel(peerId) {
      const entry = channels.get(peerId);
      if (!entry) return;
      detach(entry);
      channels.delete(peerId);
    },
    peers: () => [...channels].filter(([, entry]) => entry.channel.readyState === openState).map(([peerId]) => peerId),
    send(peerId, message) {
      const entry = channels.get(peerId);
      if (!entry || entry.channel.readyState !== openState) return;
      const text = JSON.stringify(message);
      if (text === undefined || text.length > maximumMessageBytes) {
        throw new RangeError(`Data channel transport send: a message must be JSON of at most ${maximumMessageBytes} characters, got ${text === undefined ? 'a value JSON cannot hold' : text.length}.`);
      }
      entry.channel.send(text);
      stats.sent += 1;
    },
    receive(callback) {
      if (typeof callback !== 'function') throw new TypeError('transport.receive needs a callback (peerId, message) => void.');
      listeners.add(callback);
      return () => listeners.delete(callback);
    },
    close() {
      for (const entry of channels.values()) {
        detach(entry);
        entry.channel.close?.();
      }
      channels.clear();
      listeners.clear();
    },
    get stats() { return { ...stats }; },
  };
}