Skip to content

Determinism replay

import { Aside } from ‘@astrojs/starlight/components’;

Problem

Your game has a “share replay” button. The user records 5 minutes of gameplay; you want any other player on any machine to reproduce that 5 minutes exactly — same world layout, same NPC paths, same combat outcomes — by loading just the seed + the input script.

Snippet

import { createGameboardRuntimeFromScenario } from 'declarative-hex-worlds/runtime';
import { runGameboardScenarioSimulationScript } from 'declarative-hex-worlds/simulation';

const runtime = createGameboardRuntimeFromScenario(scenario);
const result = runGameboardScenarioSimulationScript(scenario, replayScript, {
  rounds: 300,
});

// Same scenario + same script always produces the same `result.events`.
// `result.events` is byte-identical to what the recorder produced.

What the library handles

Seed threading. Every random decision routes through seedrandom; same seed → same outputs.
Script replay. runGameboardScenarioSimulationScript executes recorded commands in order; the event records become a fingerprint.
Cross-process gate. PRD E1’s tests/unit/determinism.test.ts spawns N subprocesses + asserts byte-identity. The gate runs in default pnpm test — regressions can’t sneak in.

API cross-links