Expand description
Tickwise: record, replay, and diff deterministic simulations.
Tickwise is an engine-agnostic recording, replay, and desync-debugging toolkit for deterministic multiplayer games. It is an observer: you drive your own game loop and call into the kit, and Tickwise never runs the simulation itself. That is what keeps it engine-agnostic, and it is why every API here is a callback into your code rather than a framework around it.
§The two-pass workflow
A desync is found in two passes, and the split exists because Tickwise cannot run your simulation for you.
Pass 1 is always on and cheap. Each client records its inputs and a
hash per tick with a Recorder. Given two recordings,
compare::first_divergence reports the first tick where the hashes
disagree. It works offline from the .rec files alone, in
milliseconds.
Pass 2 is targeted. You replay each recording through your own
simulation with a Replayer, asking it to capture a StateDump at
the divergent tick. diff::structural then reports the field-level
differences between the two dumps, classified as structural, exact, or
sub-epsilon float drift.
The tickwise command line tool in the tickwise-cli crate wraps
compare and diff, plus inspect for looking inside a recording.
§The probe
Everything hangs off one trait, DeterminismProbe, with three
methods: a cheap light_hash called
every tick, a full_hash called every N
ticks that covers all gameplay state, and a
state_dump called only during Pass 2.
Implement it by hand for full control over cost and coverage, or enable
the serde feature and let serde_probe::SerdeProbe derive all
three from any Serialize state.
§Recording
use tickwise::{DeterminismProbe, Recorder, RecorderConfig, StateDump};
struct Game { tick: u64, score: u64 }
impl DeterminismProbe for Game {
fn light_hash(&self) -> u64 { self.tick ^ self.score.rotate_left(17) }
fn full_hash(&self) -> u64 { self.light_hash() }
fn state_dump(&self) -> StateDump {
let mut dump = StateDump::empty();
dump.insert("tick", self.tick);
dump.insert("score", self.score);
dump
}
}
let mut game = Game { tick: 0, score: 0 };
let mut rec = Recorder::new(Vec::new(), RecorderConfig::default())?;
for tick in 0..600 {
let inputs = [0u8; 2]; // your own input encoding, opaque bytes
game.tick += 1; // your own simulation step
rec.record_tick(tick, &inputs, &game)?;
}
let recording = rec.finish()?; // the .rec bytesInputs are opaque bytes; Tickwise records them and hands them back at
replay without ever interpreting them. Declare an
input_format_id so the replayer
can refuse recordings made with an older encoding.
§Replaying
use tickwise::{ReplayConfig, Replayer};
let mut rep = Replayer::open("session.rec", ReplayConfig {
dump_at_ticks: vec![4021],
verify_hashes: true,
..ReplayConfig::default()
})?;
let mut game = Game { tick: 0 };
while let Some(step) = rep.next_step() {
game.apply(step.inputs()); // your loop applies the inputs and ticks
rep.after_tick(&game)?; // dumps and hash verification happen here
}
rep.finish("session.dump")?;With verify_hashes on, the replayer compares every live hash against
the recording and stops with ReplayError::HashMismatch the moment
your simulation stops reproducing the session. Snapshot resume follows
the same observer rule: Replayer::nearest_snapshot_before hands you
the bytes, you restore your own state, and Replayer::seek_to moves
the replay forward.
§Module map
probe: theDeterminismProbetrait.recorder: Pass 1 recording.compare: first-divergence search over two recordings.replayer: Pass 2 replay with dumps and verification.dump:StateDumpandValue, the structural state model.diff: the classified structural diff over two dumps.format: the versioned.recand.dumpcontainer. Malformed input never panics.serde_probe: the convenience layer behind theserdefeature, with the automatic probe and typed inputs.
§Features
The core has zero dependencies. Two optional features add them:
serde:serde_probe, typed inputs throughRecorder::record_tick_typedandreplayer::Step::inputs_typed, and xxh3 hashing.blake3: the blake3 hash as an alternative, for audit scenarios. Impliesserde.
§What Tickwise is not
Not a netcode or rollback library, not an engine plugin, not a determinism linter, and not async. It records, replays, and diffs, and it leaves the simulation to you.
Re-exports§
pub use dump::StateDump;pub use dump::Value;pub use format::SessionMeta;pub use format::SnapshotPolicy;pub use probe::DeterminismProbe;pub use recorder::RecordError;pub use recorder::Recorder;pub use recorder::RecorderConfig;pub use replayer::ReplayConfig;pub use replayer::ReplayError;pub use replayer::Replayer;
Modules§
- compare
- First-divergence search over two recordings, the offline half of Pass 1.
- diff
- Structural diff of state dumps, the offline half of Pass 2.
- dump
- Structural state dumps, decision #13.
- format
- The versioned
.reccontainer format. - probe
- The callback core of Tickwise.
- recorder
- The recording API, Pass 1 of the two-pass workflow.
- replayer
- The replay API, Pass 2 of the two-pass workflow.
- serde_
probe serde - The serde convenience layer, behind the
serdefeature.