@pylonsync/realtime 0.14.0

package/src/interpolation.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from "bun:test";
+
+import { replicationPayload, type TestFrame } from "../test/frames";
+import { EntityInterpolator, type InterpolationOptions } from "./interpolation";
+import { EntityTable } from "./replication";
+
+/** Feeds frames to a table and an interpolator, tick by tick. */
+function harness(options?: InterpolationOptions) {
+  const table = new EntityTable();
+  const interp = new EntityInterpolator(options);
+  return {
+    interp,
+    frame(tick: number, f: TestFrame) {
+      interp.record(table, table.apply(replicationPayload(f)), tick);
+    },
+    at(renderTick: number) {
+      interp.update(renderTick);
+      return interp.entities;
+    },
+  };
+}
+
+describe("EntityInterpolator", () => {
+  test("draws an entity between the samples around the render tick", () => {
+    const h = harness();
+    h.frame(1, { full: true, spawn: [{ id: 1, pos: [0, 0, 0] }] });
+    h.frame(2, { update: [{ id: 1, from: [0, 0, 0], pos: [10, 0, 0] }] });
+    h.frame(3, { update: [{ id: 1, from: [10, 0, 0], pos: [20, -4, 0] }] });
+    expect(h.at(1.5).get(1)?.x).toBeCloseTo(5);
+    const e = h.at(2.25).get(1)!;
+    expect(e.x).toBeCloseTo(12.5);
+    expect(e.y).toBeCloseTo(-1);
+    expect([e.from.tick, e.to.tick, e.t]).toEqual([2, 3, 0.25]);
+    // Past the newest sample it stays there.
+    expect(h.at(7).get(1)?.x).toBeCloseTo(20);
+  });
+
+  test("an entity appears at its spawn tick and leaves at its despawn tick", () => {
+    const h = harness();
+    h.frame(1, { full: true });
+    h.frame(5, { spawn: [{ id: 3, pos: [1, 1, 1] }] });
+    h.frame(8, { despawn: [3] });
+    expect(h.at(4.9).has(3)).toBe(false);
+    h.at(5);
+    expect(h.interp.entered).toEqual([3]);
+    expect(h.at(7.9).has(3)).toBe(true);
+    h.at(8);
+    expect(h.interp.left).toEqual([3]);
+    expect(h.interp.entities.size).toBe(0);
+  });
+
+  test("a reused id is a new entity: the old one leaves where it was", () => {
+    const h = harness();
+    h.frame(1, { full: true, spawn: [{ id: 7, pos: [0, 0, 0], components: { 1: [1] } }] });
+    h.frame(3, { despawn: [7], spawn: [{ id: 7, pos: [50, 0, 0] }] });
+    const old = h.at(2.5).get(7)!;
+    expect(old.x).toBeCloseTo(0);
+    expect(old.components.get(1)).toEqual(new Uint8Array([1]));
+    const fresh = h.at(3).get(7)!;
+    expect(h.interp.left).toEqual([7]);
+    expect(h.interp.entered).toEqual([7]);
+    expect(fresh).not.toBe(old);
+    expect(fresh.x).toBeCloseTo(50);
+    expect(fresh.components.size).toBe(0);
+  });
+
+  test("a quiet entity stands still until the tick before its next move", () => {
+    const h = harness();
+    h.frame(1, { full: true, spawn: [{ id: 1, pos: [0, 0, 0] }] });
+    h.frame(10, { update: [{ id: 1, from: [0, 0, 0], pos: [10, 0, 0] }] });
+    expect(h.at(5).get(1)?.x).toBeCloseTo(0);
+    expect(h.at(9.5).get(1)?.x).toBeCloseTo(5);
+
+    const spread = harness({ holdWhenQuiet: false });
+    spread.frame(1, { full: true, spawn: [{ id: 1, pos: [0, 0, 0] }] });
+    spread.frame(11, { update: [{ id: 1, from: [0, 0, 0], pos: [10, 0, 0] }] });
+    expect(spread.at(6).get(1)?.x).toBeCloseTo(5);
+  });
+
+  test("a move longer than snapDistance jumps instead of sliding", () => {
+    const h = harness({ snapDistance: 5 });
+    h.frame(1, { full: true, spawn: [{ id: 1, pos: [0, 0, 0] }] });
+    h.frame(2, { update: [{ id: 1, from: [0, 0, 0], pos: [100, 0, 0] }] });
+    h.frame(3, { update: [{ id: 1, from: [100, 0, 0], pos: [102, 0, 0] }] });
+    expect(h.at(1.9).get(1)?.x).toBeCloseTo(0);
+    expect(h.at(2).get(1)?.x).toBeCloseTo(100);
+    expect(h.at(2.5).get(1)?.x).toBeCloseTo(101);
+  });
+
+  test("components change at the tick they changed, with the positions", () => {
+    const h = harness();
+    h.frame(1, { full: true, spawn: [{ id: 1, components: { 1: [100] } }] });
+    h.frame(3, { update: [{ id: 1, components: { 1: [40], 2: [9] } }] });
+    h.frame(4, { update: [{ id: 1, components: { 2: null } }] });
+    expect(h.at(2.9).get(1)?.components.get(1)).toEqual(new Uint8Array([100]));
+    const e = h.at(3.5).get(1)!;
+    expect(e.components.get(1)).toEqual(new Uint8Array([40]));
+    expect(e.to.components.has(2)).toBe(false);
+    expect(h.at(4).get(1)?.components.has(2)).toBe(false);
+  });
+
+  test("a full frame ends entities it lacks and continues the rest", () => {
+    const h = harness();
+    h.frame(1, { full: true, spawn: [{ id: 1 }, { id: 2, pos: [0, 0, 0] }] });
+    h.at(1);
+    h.frame(5, { full: true, spawn: [{ id: 2, pos: [4, 0, 0] }] });
+    expect(h.at(4.5).has(1)).toBe(true);
+    const e = h.at(5).get(2)!;
+    expect(h.interp.left).toEqual([1]);
+    expect(h.interp.entered).toEqual([]);
+    expect(e.x).toBeCloseTo(4);
+  });
+
+  test("ticks that go back (a restarted shard) start over", () => {
+    const h = harness();
+    h.frame(100, { full: true, spawn: [{ id: 1, pos: [5, 0, 0] }] });
+    h.at(100);
+    h.frame(1, { full: true, spawn: [{ id: 9 }] });
+    const now = h.at(1);
+    expect([...now.keys()]).toEqual([9]);
+    expect(h.interp.left).toEqual([1]);
+  });
+
+  test("keeps a bounded history", () => {
+    const h = harness({ maxSamples: 4 });
+    h.frame(0, { full: true, spawn: [{ id: 1, pos: [0, 0, 0] }] });
+    for (let t = 1; t <= 50; t++) {
+      h.frame(t, { update: [{ id: 1, from: [t - 1, 0, 0], pos: [t, 0, 0] }] });
+    }
+    // Only the newest samples remain; an old render tick clamps to them.
+    expect(h.at(10).get(1)?.x).toBeCloseTo(47);
+    expect(h.at(49.5).get(1)?.x).toBeCloseTo(49.5);
+  });
+
+  test("a render tick never goes back below one already drawn", () => {
+    const h = harness();
+    h.frame(10, { full: true, spawn: [{ id: 5 }] });
+    h.frame(12, { update: [{ id: 5, from: [0, 0, 0], pos: [2, 0, 0] }] });
+    h.at(11);
+    expect(h.interp.entered).toEqual([5]);
+    h.at(9);
+    expect(h.interp.left).toEqual([]);
+    expect(h.interp.entities.get(5)?.x).toBeCloseTo(0);
+    // It stood still until tick 11, then moved 2 by tick 12.
+    h.at(11.5);
+    expect(h.interp.entered).toEqual([]);
+    expect(h.interp.entities.get(5)?.x).toBeCloseTo(1);
+  });
+
+  test("ended entities do not pile up when update does not run", () => {
+    const h = harness();
+    h.frame(0, { full: true });
+    let tick = 1;
+    for (let id = 1; id <= 20_000; id++) {
+      h.frame(tick++, { spawn: [{ id }] });
+      h.frame(tick++, { despawn: [id] });
+    }
+    const lives = (h.interp as unknown as { lives: Map<number, unknown> }).lives;
+    expect(lives.size).toBeLessThan(200);
+    // A render tick past them all draws nothing.
+    expect(h.at(tick).size).toBe(0);
+  });
+});

package/src/interpolation.ts

@@ -0,0 +1,317 @@
+/**
+ * Entity interpolation for render loops.
+ *
+ * Record every replication frame with the tick it was built on; each render
+ * frame, call `update` with a tick a little behind the server's (see
+ * `ShardClock`). Each entity is then drawn between the two samples around
+ * that tick, so motion is smooth even though frames arrive at the tick rate
+ * and with jitter. Spawns, despawns, and component changes appear at the
+ * tick they happened, in step with the positions.
+ */
+
+import type { EntityTable, ReplicatedEntity, ReplicationSummary } from "./replication";
+
+export interface InterpolationOptions {
+  /**
+   * A move longer than this (world units) between two samples is a
+   * teleport: the entity jumps instead of sliding. Default: no limit.
+   */
+  snapDistance?: number;
+  /**
+   * Treat an entity that sent no update as not moving, so its next move
+   * starts from the tick before it arrives. Default true. Set false for a
+   * shard with a byte budget (`max_bytes_per_tick`), where updates can
+   * wait for later ticks.
+   */
+  holdWhenQuiet?: boolean;
+  /** Samples kept per entity. Default 32. */
+  maxSamples?: number;
+}
+
+/** An entity's state at one tick. */
+export interface EntitySample {
+  readonly tick: number;
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  /** Component id to bytes. Shared between samples; do not change it. */
+  readonly components: ReadonlyMap<number, Uint8Array>;
+}
+
+/** One entity as drawn at the render tick. The object is reused. */
+export interface InterpolatedEntity {
+  readonly id: number;
+  x: number;
+  y: number;
+  z: number;
+  /** Components as of the sample at or before the render tick. */
+  components: ReadonlyMap<number, Uint8Array>;
+  /**
+   * The samples around the render tick and the fraction between them, to
+   * interpolate game data kept in components (a heading, a health bar).
+   * `from` and `to` are the same sample when there is no later one.
+   */
+  from: EntitySample;
+  to: EntitySample;
+  t: number;
+}
+
+/** One entity from spawn to despawn. An id can have a later life. */
+interface Life {
+  spawnTick: number;
+  /** The tick it despawned on, or null while it exists. */
+  despawnTick: number | null;
+  samples: EntitySample[];
+}
+
+const EMPTY: ReadonlyMap<number, Uint8Array> = new Map();
+/** Ticks an ended life is kept for a render tick that lags behind. */
+const ENDED_TICKS = 256;
+
+export class EntityInterpolator {
+  /** Entities that exist at the last `update`'s render tick. */
+  readonly entities = new Map<number, InterpolatedEntity>();
+  /**
+   * Ids the last `update` added to `entities`. An id in both `left` and
+   * `entered` names a new entity that reused the id: rebuild what you
+   * drew for it.
+   */
+  readonly entered: number[] = [];
+  /** Ids the last `update` removed from `entities`. */
+  readonly left: number[] = [];
+
+  private readonly lives = new Map<number, Life[]>();
+  /** The life each entry in `entities` shows. */
+  private readonly shown = new Map<number, Life>();
+  private readonly snapDistance: number;
+  private readonly holdWhenQuiet: boolean;
+  private readonly maxSamples: number;
+  private lastTick = -1;
+  /** The newest tick the last `update` drew; a render tick never goes
+   *  below it. */
+  private floor = -Infinity;
+  /** Lives that ended, oldest first, so `record` can drop them when
+   *  `update` does not run (a hidden tab keeps receiving frames). */
+  private ended: Array<{ id: number; life: Life }> = [];
+
+  constructor(options: InterpolationOptions = {}) {
+    this.snapDistance = options.snapDistance ?? Infinity;
+    this.holdWhenQuiet = options.holdWhenQuiet ?? true;
+    this.maxSamples = Math.max(2, options.maxSamples ?? 32);
+  }
+
+  /** The newest tick recorded, or -1. */
+  get latestTick(): number {
+    return this.lastTick;
+  }
+
+  /** Forget everything. The next `update` removes every entity. */
+  clear(): void {
+    this.lives.clear();
+    this.ended = [];
+    this.lastTick = -1;
+    this.floor = -Infinity;
+  }
+
+  /**
+   * Record the table after a replication frame for `tick` applied, with the
+   * summary `EntityTable.apply` returned.
+   */
+  record(table: EntityTable, summary: ReplicationSummary, tick: number): void {
+    if (tick < this.lastTick) {
+      // Ticks went back: a restarted or different shard.
+      this.clear();
+    }
+    this.lastTick = tick;
+    this.dropEnded(tick);
+
+    if (summary.full) {
+      // The table was rebuilt: what it lacks now is gone.
+      const present = new Set(summary.spawned);
+      for (const [id, lives] of this.lives) {
+        const open = lives[lives.length - 1];
+        if (open.despawnTick === null && !present.has(id)) this.end(id, open, tick);
+      }
+      for (const id of summary.spawned) {
+        const e = table.get(id);
+        if (!e) continue;
+        const open = this.openLife(id);
+        if (open) this.push(open, e, tick);
+        else this.spawn(id, e, tick);
+      }
+      return;
+    }
+
+    for (const id of summary.despawned) {
+      const open = this.openLife(id);
+      if (open) this.end(id, open, tick);
+    }
+    for (const id of summary.spawned) {
+      const e = table.get(id);
+      if (e) this.spawn(id, e, tick);
+    }
+    for (const id of summary.updated) {
+      const e = table.get(id);
+      const open = this.openLife(id);
+      if (e && open) this.push(open, e, tick);
+    }
+  }
+
+  /**
+   * Place every entity at `renderTick` (fractional). A render tick below
+   * one already drawn is raised to it, so nothing drawn goes back in time.
+   */
+  update(renderTick: number): void {
+    this.entered.length = 0;
+    this.left.length = 0;
+    renderTick = Math.max(renderTick, this.floor);
+    // What this update draws is at most the newest tick recorded.
+    this.floor = Math.min(renderTick, this.lastTick);
+    for (const [id, lives] of this.lives) {
+      // Lives that ended by the render tick are over.
+      while (lives.length > 0 && lives[0].despawnTick !== null && lives[0].despawnTick <= renderTick) {
+        lives.shift();
+      }
+      if (lives.length === 0) {
+        this.lives.delete(id);
+        this.remove(id);
+        continue;
+      }
+      const life = lives[0];
+      if (life.spawnTick > renderTick) {
+        // Not spawned yet at the render tick.
+        this.remove(id);
+        continue;
+      }
+      this.place(id, life, renderTick);
+    }
+    for (const id of this.entities.keys()) {
+      if (!this.lives.has(id)) this.remove(id);
+    }
+  }
+
+  private end(id: number, life: Life, tick: number): void {
+    life.despawnTick = tick;
+    this.ended.push({ id, life });
+  }
+
+  /**
+   * Forget lives that ended long before `tick`. `update` removes them
+   * when it runs; this bounds them when it does not.
+   */
+  private dropEnded(tick: number): void {
+    let n = 0;
+    while (n < this.ended.length && (this.ended[n].life.despawnTick as number) < tick - ENDED_TICKS) {
+      const { id, life } = this.ended[n];
+      const lives = this.lives.get(id);
+      if (lives) {
+        const i = lives.indexOf(life);
+        if (i >= 0) lives.splice(i, 1);
+        if (lives.length === 0) this.lives.delete(id);
+      }
+      n++;
+    }
+    if (n > 0) this.ended.splice(0, n);
+  }
+
+  private openLife(id: number): Life | null {
+    const lives = this.lives.get(id);
+    const last = lives?.[lives.length - 1];
+    return last && last.despawnTick === null ? last : null;
+  }
+
+  private spawn(id: number, e: ReplicatedEntity, tick: number): void {
+    let lives = this.lives.get(id);
+    if (!lives) {
+      lives = [];
+      this.lives.set(id, lives);
+    }
+    const open = lives[lives.length - 1];
+    if (open && open.despawnTick === null) this.end(id, open, tick);
+    lives.push({
+      spawnTick: tick,
+      despawnTick: null,
+      samples: [{ tick, x: e.x, y: e.y, z: e.z, components: new Map(e.components) }],
+    });
+  }
+
+  private push(life: Life, e: ReplicatedEntity, tick: number): void {
+    const samples = life.samples;
+    const last = samples[samples.length - 1];
+    const components = sameComponents(last.components, e.components)
+      ? last.components
+      : new Map(e.components);
+    const moved = last.x !== e.x || last.y !== e.y || last.z !== e.z;
+    if (!moved && components === last.components) return;
+    if (last.tick === tick) {
+      samples[samples.length - 1] = { tick, x: e.x, y: e.y, z: e.z, components };
+      return;
+    }
+    if (this.holdWhenQuiet && moved && last.tick < tick - 1) {
+      // No update since `last`: it stood still until the tick before.
+      samples.push({ ...last, tick: tick - 1 });
+    }
+    samples.push({ tick, x: e.x, y: e.y, z: e.z, components });
+    while (samples.length > this.maxSamples) samples.shift();
+  }
+
+  private place(id: number, life: Life, renderTick: number): void {
+    const samples = life.samples;
+    // The last sample at or before the render tick. Samples before the
+    // spawn tick do not exist, and the first sample is the spawn.
+    let i = samples.length - 1;
+    while (i > 0 && samples[i].tick > renderTick) i--;
+    const from = samples[i];
+    const to = samples[i + 1] ?? from;
+    let t = to === from ? 0 : (renderTick - from.tick) / (to.tick - from.tick);
+    t = Math.min(1, Math.max(0, t));
+    const dx = to.x - from.x;
+    const dy = to.y - from.y;
+    const dz = to.z - from.z;
+    const teleport = dx * dx + dy * dy + dz * dz > this.snapDistance * this.snapDistance;
+    const k = teleport ? 0 : t;
+
+    let view = this.entities.get(id);
+    if (view && this.shown.get(id) !== life) {
+      // The id names a new entity now: the old one left.
+      this.remove(id);
+      view = undefined;
+    }
+    if (!view) {
+      view = { id, x: 0, y: 0, z: 0, components: EMPTY, from, to, t };
+      this.entities.set(id, view);
+      this.shown.set(id, life);
+      this.entered.push(id);
+    }
+    view.x = from.x + dx * k;
+    view.y = from.y + dy * k;
+    view.z = from.z + dz * k;
+    view.components = from.components;
+    view.from = from;
+    view.to = to;
+    view.t = t;
+
+    // Samples two behind the one in use are no longer needed.
+    if (i > 1) samples.splice(0, i - 1);
+  }
+
+  private remove(id: number): void {
+    this.shown.delete(id);
+    if (this.entities.delete(id)) this.left.push(id);
+  }
+}
+
+/** True when `a` and `b` hold the same components with the same bytes. */
+function sameComponents(
+  a: ReadonlyMap<number, Uint8Array>,
+  b: ReadonlyMap<number, Uint8Array>,
+): boolean {
+  if (a.size !== b.size) return false;
+  for (const [k, v] of b) {
+    const w = a.get(k);
+    if (w === v) continue;
+    if (!w || w.length !== v.length) return false;
+    for (let i = 0; i < v.length; i++) if (w[i] !== v[i]) return false;
+  }
+  return true;
+}

package/src/prediction.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+
+import { Predictor } from "./prediction";
+
+type Move = { dx: number };
+const step = (x: number, m: Move) => x + m.dx;
+
+describe("Predictor", () => {
+  test("replays the inputs the shard has not processed on its state", () => {
+    const p = new Predictor(step);
+    p.push(1, { dx: 1 });
+    p.push(2, { dx: 2 });
+    p.push(3, { dx: 4 });
+    // The shard applied 1 (x = 1) as of this frame.
+    expect(p.reconcile(1, 1)).toBe(7);
+    expect(p.size).toBe(2);
+    // It clamped input 2 (x = 1.5 instead of 3): the prediction follows.
+    expect(p.reconcile(1.5, 2)).toBe(5.5);
+    expect(p.reconcile(5.5, 3)).toBe(5.5);
+    expect(p.size).toBe(0);
+  });
+
+  test("forgets refused inputs and inputs that were not sent", () => {
+    const p = new Predictor(step);
+    p.push(0, { dx: 100 });
+    p.push(4, { dx: 1 });
+    p.push(5, { dx: 2 });
+    p.reject(4);
+    p.reject(null);
+    expect(p.reconcile(0, 3)).toBe(2);
+  });
+
+  test("reset drops everything, and pending inputs are bounded", () => {
+    const p = new Predictor(step, { maxPending: 3 });
+    for (let seq = 1; seq <= 5; seq++) p.push(seq, { dx: 1 });
+    expect(p.size).toBe(3);
+    expect(p.reconcile(0, 0)).toBe(3);
+    p.reset();
+    expect(p.reconcile(10, 0)).toBe(10);
+  });
+});

package/src/prediction.ts

@@ -0,0 +1,80 @@
+/**
+ * Client-side prediction for the local player.
+ *
+ * Apply each input locally as it is sent, and keep it until the shard
+ * acknowledges it. When a frame arrives with the server's state and its
+ * `ack` (the highest input sequence number the shard has processed), start
+ * from the server's state and apply the inputs it has not processed yet.
+ * The result is where the local player is after every input, corrected by
+ * whatever the server decided.
+ *
+ * `step` must be deterministic and must match what the shard does with an
+ * input closely enough that the replayed state agrees with the server's.
+ * It must not change `state` in place; return a new one.
+ */
+
+export interface PredictorOptions {
+  /**
+   * Inputs kept while waiting for an ack. Past this the oldest are
+   * dropped (the prediction then misses them). Default 256.
+   */
+  maxPending?: number;
+}
+
+interface Pending<I> {
+  seq: number;
+  input: I;
+}
+
+export class Predictor<S, I> {
+  private pending: Array<Pending<I>> = [];
+  private readonly maxPending: number;
+
+  constructor(
+    private readonly step: (state: S, input: I) => S,
+    options: PredictorOptions = {},
+  ) {
+    this.maxPending = Math.max(1, options.maxPending ?? 256);
+  }
+
+  /** Inputs sent and not yet acknowledged. */
+  get size(): number {
+    return this.pending.length;
+  }
+
+  /** Record an input sent with sequence number `seq`. A `seq` of 0 (not
+   *  sent) is ignored. */
+  push(seq: number, input: I): void {
+    if (seq <= 0) return;
+    this.pending.push({ seq, input });
+    if (this.pending.length > this.maxPending) this.pending.shift();
+  }
+
+  /** The shard refused input `seq`: it will never apply. */
+  reject(seq: number | null): void {
+    if (seq === null) return;
+    this.pending = this.pending.filter((p) => p.seq !== seq);
+  }
+
+  /**
+   * The predicted state: `server` (the shard's state as of a frame) with
+   * every input after `ack` applied. Inputs up to `ack` are dropped.
+   */
+  reconcile(server: S, ack: number): S {
+    let drop = 0;
+    while (drop < this.pending.length && this.pending[drop].seq <= ack) drop++;
+    if (drop > 0) this.pending.splice(0, drop);
+    let state = server;
+    for (const p of this.pending) state = this.step(state, p.input);
+    return state;
+  }
+
+  /**
+   * Drop every pending input. Call it when the connection reopens: inputs
+   * sent on the old connection either applied before it closed (and are
+   * in the server's state) or never will.
+   */
+  reset(): void {
+    this.pending = [];
+  }
+}