@irtio/bots

Run scripted clients against a live irtio room. Collect wire traces and reports for synchronization, bandwidth, handler errors, and prediction behavior.

npm install --save-dev @irtio/bots tsx

Run five clients

Start your project's room with npx irtio dev. This script uses its shared schema. Create simulate.ts at the project root and use the endpoint printed by the dev server:

import { randomScript, spawnBots } from '@irtio/bots';
import { schema } from './irtio/schema.js';

const runner = await spawnBots(5, {
  schema,
  url: 'ws://localhost:7070',
  role: 'player',
  script: randomScript(schema),
  durationMs: 10_000,
});

try {
  await runner.done();
} finally {
  const report = await runner.stop();
  console.log(report);
  await runner.trace.save('trace.json');
  if (!report.ok) process.exitCode = 1;
}

npx tsx simulate.ts

The bots share a room when no room code is supplied. The duration is in milliseconds. stop() leaves the room and returns the final report; trace.save() writes the recorded traffic as JSON. Use Node.js 22 for scripts.

Choose a test

| API | Use | | --- | --- | | randomScript(schema) | Exercise writes and RPCs using generated values | | spawnBots(count, options) | Run clients and inspect their report and trace | | defineScenario(...) | Describe a repeatable sequence with assertions | | conditionedTransport(...) | Apply controlled latency, loss, duplication, and reordering |

Random calls do not follow game rules. Use a scenario for turn-based play, setup sequences, and specific outcomes. Expected ctx.deny refusals are separate from handler errors, but a high refusal rate can fail the denial-rate invariant. Inspect report.invariants, scriptErrors, and endedBy when a run fails.

For command-line runs, use npx irtio simulate. See built-in invariants and scenarios for thresholds, reports, and scripted tests.