@lagless/desync-diagnostics 0.0.48

package/src/lib/diagnostics-collector.spec.ts

@@ -0,0 +1,354 @@
+import { DiagnosticsCollector } from './diagnostics-collector.js';
+import type { DiagnosticsConfig } from './types.js';
+
+// ─── Mocks ──────────────────────────────────────────────────
+
+function createMockRunner(options?: { maxPlayers?: number }) {
+  const maxPlayers = options?.maxPlayers ?? 4;
+  let tickHandler: ((tick: number) => void) | null = null;
+  let rollbackHandler: ((tick: number) => void) | null = null;
+  let currentTick = 0;
+  let hashAtTickMap = new Map<number, number>();
+  let memHash = 0;
+  let verifiedTick = -1;
+  const rpcsByTick = new Map<number, Array<{ meta: { playerSlot: number }; inputId: number }>>();
+
+  const runner = {
+    Config: { maxPlayers },
+    Simulation: {
+      tick: 0,
+      addTickHandler: (fn: (tick: number) => void) => {
+        tickHandler = fn;
+        return () => { tickHandler = null; };
+      },
+      addRollbackHandler: (fn: (tick: number) => void) => {
+        rollbackHandler = fn;
+        return () => { rollbackHandler = null; };
+      },
+      getHashAtTick: (tick: number) => hashAtTickMap.get(tick),
+      mem: {
+        getHash: () => memHash,
+      },
+    },
+    InputProviderInstance: {
+      get verifiedTick() { return verifiedTick; },
+      rpcHistory: {
+        getRPCsAtTick: (tick: number) => rpcsByTick.get(tick) ?? [],
+        getRPCCountAtTick: (tick: number) => (rpcsByTick.get(tick) ?? []).length,
+      },
+    },
+  };
+
+  return {
+    runner: runner as unknown as Parameters<typeof DiagnosticsCollector['prototype']['dispose']> extends [] ? any : any,
+    fireTick: (tick: number) => {
+      currentTick = tick;
+      runner.Simulation.tick = tick;
+      tickHandler?.(tick);
+    },
+    fireRollback: (tick: number) => {
+      // Simulate real ECSSimulation behavior: tick is restored BEFORE handler fires
+      runner.Simulation.tick = tick;
+      rollbackHandler?.(tick);
+    },
+    setHashAtTick: (tick: number, hash: number) => hashAtTickMap.set(tick, hash),
+    setMemHash: (hash: number) => { memHash = hash; },
+    setVerifiedTick: (vt: number) => { verifiedTick = vt; },
+    setRPCsAtTick: (tick: number, rpcs: Array<{ meta: { playerSlot: number }; inputId: number }>) => {
+      rpcsByTick.set(tick, rpcs);
+    },
+    get tickHandler() { return tickHandler; },
+    get rollbackHandler() { return rollbackHandler; },
+  };
+}
+
+// ─── Tests ──────────────────────────────────────────────────
+
+describe('DiagnosticsCollector', () => {
+  it('should record tick data via tick handler', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setHashAtTick(1, 0xABCD);
+    setVerifiedTick(0);
+    fireTick(1);
+
+    expect(collector.count).toBe(1);
+
+    const timeline = collector.getTimeline();
+    expect(timeline).toHaveLength(1);
+    expect(timeline[0].tick).toBe(1);
+    expect(timeline[0].hash).toBe(0xABCD);
+    expect(timeline[0].verifiedTick).toBe(0);
+    expect(timeline[0].wasRollback).toBe(false);
+
+    collector.dispose();
+  });
+
+  it('should fall back to mem.getHash() when hashHistory misses', () => {
+    const { runner, fireTick, setMemHash, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setMemHash(0x1234);
+    setVerifiedTick(0);
+    fireTick(1);
+
+    const timeline = collector.getTimeline();
+    expect(timeline[0].hash).toBe(0x1234);
+
+    collector.dispose();
+  });
+
+  it('should record input counts per player slot', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick, setRPCsAtTick } = createMockRunner({ maxPlayers: 4 });
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setHashAtTick(5, 0);
+    setVerifiedTick(4);
+    setRPCsAtTick(5, [
+      { meta: { playerSlot: 0 }, inputId: 1 },
+      { meta: { playerSlot: 0 }, inputId: 2 },
+      { meta: { playerSlot: 1 }, inputId: 1 },
+    ]);
+    fireTick(5);
+
+    const timeline = collector.getTimeline();
+    expect(timeline[0].inputCountBySlot[0]).toBe(2);
+    expect(timeline[0].inputCountBySlot[1]).toBe(1);
+    expect(timeline[0].inputCountBySlot[2]).toBe(0);
+    expect(timeline[0].inputCountBySlot[3]).toBe(0);
+
+    collector.dispose();
+  });
+
+  it('should wrap ring buffer when full', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const bufferSize = 5;
+    const collector = new DiagnosticsCollector(runner, { bufferSize });
+
+    setVerifiedTick(0);
+    for (let t = 1; t <= 8; t++) {
+      setHashAtTick(t, t * 100);
+      fireTick(t);
+    }
+
+    // Buffer should contain ticks 4-8 (last 5)
+    expect(collector.count).toBe(5);
+    const timeline = collector.getTimeline();
+    expect(timeline.map(r => r.tick)).toEqual([4, 5, 6, 7, 8]);
+    expect(timeline.map(r => r.hash)).toEqual([400, 500, 600, 700, 800]);
+
+    collector.dispose();
+  });
+
+  it('should record rollback events', () => {
+    const { runner, fireTick, fireRollback, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setVerifiedTick(0);
+    // Simulate ticks 1-10
+    for (let t = 1; t <= 10; t++) {
+      setHashAtTick(t, t);
+      fireTick(t);
+    }
+
+    // Rollback to tick 5
+    fireRollback(5);
+
+    const rollbacks = collector.getRollbacks();
+    expect(rollbacks).toHaveLength(1);
+    expect(rollbacks[0].atSimTick).toBe(10);
+    expect(rollbacks[0].rollbackToTick).toBe(5);
+    expect(rollbacks[0].timestamp).toBeGreaterThan(0);
+
+    const stats = collector.getStats();
+    expect(stats.totalRollbacks).toBe(1);
+    expect(stats.lastRollbackTick).toBe(5);
+
+    collector.dispose();
+  });
+
+  it('should mark re-simulated ticks as wasRollback=true', () => {
+    const { runner, fireTick, fireRollback, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setVerifiedTick(0);
+    // Initial simulation: ticks 1-10
+    for (let t = 1; t <= 10; t++) {
+      setHashAtTick(t, t);
+      fireTick(t);
+    }
+
+    // Rollback to tick 8 (atSimTick=10)
+    fireRollback(8);
+
+    // Re-simulate ticks 8, 9, 10 (these should be marked as rollback)
+    for (let t = 8; t <= 10; t++) {
+      setHashAtTick(t, t + 1000); // different hash post-rollback
+      fireTick(t);
+    }
+
+    // Then simulate tick 11 (should NOT be marked as rollback)
+    setHashAtTick(11, 11);
+    fireTick(11);
+
+    const timeline = collector.getTimeline();
+    // Find tick 8, 9, 10, 11 entries (the latest ones)
+    const tick8 = timeline.find(r => r.tick === 8 && r.hash === 1008);
+    const tick9 = timeline.find(r => r.tick === 9 && r.hash === 1009);
+    const tick10 = timeline.find(r => r.tick === 10 && r.hash === 1010);
+    const tick11 = timeline.find(r => r.tick === 11);
+
+    expect(tick8?.wasRollback).toBe(true);
+    expect(tick9?.wasRollback).toBe(true);
+    expect(tick10?.wasRollback).toBe(true);
+    expect(tick11?.wasRollback).toBe(false);
+
+    collector.dispose();
+  });
+
+  it('should detect verifiedTick gaps', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setHashAtTick(1, 1);
+    setVerifiedTick(0);
+    fireTick(1);
+
+    setHashAtTick(2, 2);
+    setVerifiedTick(1); // +1, no gap
+    fireTick(2);
+
+    setHashAtTick(3, 3);
+    setVerifiedTick(5); // +4, gap!
+    fireTick(3);
+
+    setHashAtTick(4, 4);
+    setVerifiedTick(6); // +1, no gap
+    fireTick(4);
+
+    const stats = collector.getStats();
+    expect(stats.verifiedTickGapCount).toBe(1);
+
+    collector.dispose();
+  });
+
+  it('should provide correct stats', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setVerifiedTick(0);
+    for (let t = 1; t <= 5; t++) {
+      setHashAtTick(t, t * 10);
+      fireTick(t);
+    }
+
+    const stats = collector.getStats();
+    expect(stats.ticksRecorded).toBe(5);
+    expect(stats.totalRollbacks).toBe(0);
+    expect(stats.latestHash).toBe(50);
+    expect(stats.oldestTick).toBe(1);
+    expect(stats.newestTick).toBe(5);
+
+    collector.dispose();
+  });
+
+  it('should dispose and stop recording', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick, tickHandler } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setVerifiedTick(0);
+    setHashAtTick(1, 1);
+    fireTick(1);
+    expect(collector.count).toBe(1);
+
+    collector.dispose();
+
+    // Handler should be removed
+    expect(tickHandler).toBeNull();
+
+    // Double dispose should be safe
+    collector.dispose();
+  });
+
+  it('should cap rollback events at maxRollbackEvents', () => {
+    const { runner, fireTick, fireRollback, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100, maxRollbackEvents: 3 });
+
+    setVerifiedTick(0);
+    for (let t = 1; t <= 5; t++) {
+      setHashAtTick(t, t);
+      fireTick(t);
+    }
+
+    // Fire 4 rollbacks — only last 3 should remain
+    for (let i = 0; i < 4; i++) {
+      fireRollback(i + 1);
+    }
+
+    const rollbacks = collector.getRollbacks();
+    expect(rollbacks).toHaveLength(3);
+    expect(rollbacks[0].rollbackToTick).toBe(2);
+    expect(rollbacks[2].rollbackToTick).toBe(4);
+
+    collector.dispose();
+  });
+
+  it('should handle empty buffer stats gracefully', () => {
+    const { runner } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    const stats = collector.getStats();
+    expect(stats.ticksRecorded).toBe(0);
+    expect(stats.latestHash).toBe(0);
+    expect(stats.oldestTick).toBe(0);
+    expect(stats.newestTick).toBe(0);
+
+    const timeline = collector.getTimeline();
+    expect(timeline).toHaveLength(0);
+
+    collector.dispose();
+  });
+
+  it('should record physicsHash when physicsHashFn is provided', () => {
+    let callCount = 0;
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, {
+      bufferSize: 100,
+      physicsHashFn: () => {
+        callCount++;
+        return 0xDEAD;
+      },
+    });
+
+    setHashAtTick(1, 0xABCD);
+    setVerifiedTick(0);
+    fireTick(1);
+
+    const timeline = collector.getTimeline();
+    expect(timeline[0].physicsHash).toBe(0xDEAD);
+    expect(callCount).toBe(1);
+
+    const stats = collector.getStats();
+    expect(stats.latestPhysicsHash).toBe(0xDEAD);
+
+    collector.dispose();
+  });
+
+  it('should record physicsHash as 0 when physicsHashFn is not provided', () => {
+    const { runner, fireTick, setHashAtTick, setVerifiedTick } = createMockRunner();
+    const collector = new DiagnosticsCollector(runner, { bufferSize: 100 });
+
+    setHashAtTick(1, 0xABCD);
+    setVerifiedTick(0);
+    fireTick(1);
+
+    const timeline = collector.getTimeline();
+    expect(timeline[0].physicsHash).toBe(0);
+
+    const stats = collector.getStats();
+    expect(stats.latestPhysicsHash).toBe(0);
+
+    collector.dispose();
+  });
+});

package/src/lib/diagnostics-collector.ts

@@ -0,0 +1,210 @@
+import type { ECSRunner } from '@lagless/core';
+import type { DiagnosticsConfig, TickRecord, RollbackEvent, DiagnosticsStats } from './types.js';
+
+const DEFAULT_BUFFER_SIZE = 18000; // 5 min at 60fps
+const DEFAULT_MAX_ROLLBACK_EVENTS = 1000;
+
+export class DiagnosticsCollector {
+  private readonly _runner: ECSRunner;
+  private readonly _maxPlayers: number;
+  private readonly _bufferSize: number;
+
+  // Ring buffer — pre-allocated typed arrays
+  private readonly _ticks: Uint32Array;
+  private readonly _hashes: Uint32Array;
+  private readonly _physicsHashes: Uint32Array;
+  private readonly _velocityHashes: Uint32Array;
+  private readonly _verifiedTicks: Int32Array;
+  private readonly _wasRollback: Uint8Array;
+  private readonly _inputCounts: Uint8Array; // [bufferSize * maxPlayers]
+
+  private readonly _physicsHashFn: (() => number) | null;
+  private readonly _velocityHashFn: (() => number) | null;
+
+  private _head = 0;      // next write index
+  private _count = 0;     // number of valid entries
+
+  // Rollback events ring buffer
+  private readonly _maxRollbackEvents: number;
+  private readonly _rollbackEvents: RollbackEvent[] = [];
+  private _totalRollbacks = 0;
+  private _lastRollbackTick = 0;
+
+  // Rollback re-simulation tracking
+  private _isResimulating = false;
+  private _preRollbackTick = 0;
+  private _lastTickSeen = 0;
+
+  // VerifiedTick gap detection
+  private _prevVerifiedTick = -1;
+  private _verifiedTickGapCount = 0;
+
+  // Handler cleanup
+  private _removeTickHandler: (() => void) | null = null;
+  private _removeRollbackHandler: (() => void) | null = null;
+  private _disposed = false;
+
+  constructor(runner: ECSRunner, config?: DiagnosticsConfig) {
+    this._runner = runner;
+    this._maxPlayers = runner.Config.maxPlayers;
+    this._bufferSize = config?.bufferSize ?? DEFAULT_BUFFER_SIZE;
+    this._maxRollbackEvents = config?.maxRollbackEvents ?? DEFAULT_MAX_ROLLBACK_EVENTS;
+
+    this._physicsHashFn = config?.physicsHashFn ?? null;
+    this._velocityHashFn = config?.velocityHashFn ?? null;
+
+    this._ticks = new Uint32Array(this._bufferSize);
+    this._hashes = new Uint32Array(this._bufferSize);
+    this._physicsHashes = new Uint32Array(this._bufferSize);
+    this._velocityHashes = new Uint32Array(this._bufferSize);
+    this._verifiedTicks = new Int32Array(this._bufferSize);
+    this._wasRollback = new Uint8Array(this._bufferSize);
+    this._inputCounts = new Uint8Array(this._bufferSize * this._maxPlayers);
+
+    this._removeRollbackHandler = runner.Simulation.addRollbackHandler((tick) => {
+      this._onRollback(tick);
+    });
+
+    this._removeTickHandler = runner.Simulation.addTickHandler((tick) => {
+      this._onTick(tick);
+    });
+  }
+
+  // ─── Public API ──────────────────────────────────────────
+
+  public get runner(): ECSRunner {
+    return this._runner;
+  }
+
+  public get bufferSize(): number {
+    return this._bufferSize;
+  }
+
+  public get count(): number {
+    return this._count;
+  }
+
+  public getTimeline(): TickRecord[] {
+    const result: TickRecord[] = [];
+    const start = this._count < this._bufferSize ? 0 : this._head;
+
+    for (let i = 0; i < this._count; i++) {
+      const idx = (start + i) % this._bufferSize;
+      const slotOffset = idx * this._maxPlayers;
+      result.push({
+        tick: this._ticks[idx],
+        hash: this._hashes[idx],
+        physicsHash: this._physicsHashes[idx],
+        velocityHash: this._velocityHashes[idx],
+        verifiedTick: this._verifiedTicks[idx],
+        wasRollback: this._wasRollback[idx] !== 0,
+        inputCountBySlot: this._inputCounts.slice(slotOffset, slotOffset + this._maxPlayers),
+      });
+    }
+
+    return result;
+  }
+
+  public getRollbacks(): ReadonlyArray<RollbackEvent> {
+    return this._rollbackEvents;
+  }
+
+  public getStats(): DiagnosticsStats {
+    const oldestIdx = this._count < this._bufferSize ? 0 : this._head;
+    const newestIdx = this._count === 0 ? 0 : (this._head - 1 + this._bufferSize) % this._bufferSize;
+
+    return {
+      ticksRecorded: this._count,
+      totalRollbacks: this._totalRollbacks,
+      lastRollbackTick: this._lastRollbackTick,
+      verifiedTickGapCount: this._verifiedTickGapCount,
+      latestHash: this._count > 0 ? this._hashes[newestIdx] : 0,
+      latestPhysicsHash: this._count > 0 ? this._physicsHashes[newestIdx] : 0,
+      latestVelocityHash: this._count > 0 ? this._velocityHashes[newestIdx] : 0,
+      oldestTick: this._count > 0 ? this._ticks[oldestIdx] : 0,
+      newestTick: this._count > 0 ? this._ticks[newestIdx] : 0,
+    };
+  }
+
+  public dispose(): void {
+    if (this._disposed) return;
+    this._disposed = true;
+    this._removeTickHandler?.();
+    this._removeRollbackHandler?.();
+    this._removeTickHandler = null;
+    this._removeRollbackHandler = null;
+  }
+
+  // ─── Private handlers ────────────────────────────────────
+
+  private _onRollback(tick: number): void {
+    // Use _lastTickSeen (tracked in _onTick) because Simulation.tick is already
+    // restored to the rollback target when the rollback handler fires.
+    this._preRollbackTick = this._lastTickSeen;
+    this._isResimulating = true;
+    this._totalRollbacks++;
+    this._lastRollbackTick = tick;
+
+    const event: RollbackEvent = {
+      atSimTick: this._preRollbackTick,
+      rollbackToTick: tick,
+      timestamp: performance.now(),
+    };
+
+    if (this._rollbackEvents.length >= this._maxRollbackEvents) {
+      this._rollbackEvents.shift();
+    }
+    this._rollbackEvents.push(event);
+  }
+
+  private _onTick(tick: number): void {
+    if (this._isResimulating && tick > this._preRollbackTick) {
+      this._isResimulating = false;
+    }
+
+    const sim = this._runner.Simulation;
+    const provider = this._runner.InputProviderInstance;
+
+    // Get hash — prefer hashHistory (already computed), fall back to direct computation
+    let hash = sim.getHashAtTick(tick);
+    if (hash === undefined) {
+      hash = sim.mem.getHash();
+    }
+
+    // Get verifiedTick
+    const verifiedTick = provider.verifiedTick;
+
+    // Detect verifiedTick gaps (jumps of >1 between consecutive records)
+    if (this._prevVerifiedTick >= 0 && verifiedTick > this._prevVerifiedTick + 1) {
+      this._verifiedTickGapCount++;
+    }
+    this._prevVerifiedTick = verifiedTick;
+
+    // Count inputs per slot at this tick
+    const rpcs = provider.rpcHistory.getRPCsAtTick(tick);
+    const slotOffset = this._head * this._maxPlayers;
+
+    // Zero the slot region
+    this._inputCounts.fill(0, slotOffset, slotOffset + this._maxPlayers);
+    for (const rpc of rpcs) {
+      if (rpc.meta.playerSlot < this._maxPlayers) {
+        this._inputCounts[slotOffset + rpc.meta.playerSlot]++;
+      }
+    }
+
+    // Write to ring buffer
+    this._ticks[this._head] = tick;
+    this._hashes[this._head] = hash;
+    this._physicsHashes[this._head] = this._physicsHashFn ? this._physicsHashFn() : 0;
+    this._velocityHashes[this._head] = this._velocityHashFn ? this._velocityHashFn() : 0;
+    this._verifiedTicks[this._head] = verifiedTick;
+    this._wasRollback[this._head] = this._isResimulating ? 1 : 0;
+
+    this._head = (this._head + 1) % this._bufferSize;
+    if (this._count < this._bufferSize) {
+      this._count++;
+    }
+
+    this._lastTickSeen = tick;
+  }
+}

package/src/lib/diagnostics-protocol.ts

@@ -0,0 +1,44 @@
+import type { DiagnosticsReport } from './report-generator.js';
+
+// ─── Child → Parent (game iframe → dev-player) ──────────────
+
+export interface DiagnosticsSummaryMessage {
+  type: 'dev-bridge:diagnostics-summary';
+  instanceId: string;
+  rollbackCount: number;
+  lastRollbackTick: number;
+  verifiedTickGapCount: number;
+  ticksRecorded: number;
+  latestHash: number;
+  latestPhysicsHash: number;
+  latestVelocityHash: number;
+}
+
+export interface DiagnosticsReportMessage {
+  type: 'dev-bridge:diagnostics-report';
+  instanceId: string;
+  report: DiagnosticsReport;
+}
+
+export interface PerformanceStatsMessage {
+  type: 'dev-bridge:performance-stats';
+  instanceId: string;
+  tickTime: { latest: number; min: number; max: number; avg: number };
+  snapshotTime: { latest: number; min: number; max: number; avg: number };
+  overheadTime: { latest: number; min: number; max: number; avg: number };
+  systems: Array<{ name: string; latest: number; min: number; max: number; avg: number }>;
+}
+
+export type DiagnosticsChildMessage =
+  | DiagnosticsSummaryMessage
+  | DiagnosticsReportMessage
+  | PerformanceStatsMessage;
+
+// ─── Parent → Child (dev-player → game iframe) ──────────────
+
+export interface RequestDiagnosticsReportMessage {
+  type: 'dev-bridge:request-diagnostics-report';
+}
+
+export type DiagnosticsParentMessage =
+  | RequestDiagnosticsReportMessage;