Tickwise in Unity

Tickwise introduces a lightweight Unity bridge that lets developers record deterministic simulations and compare them across runs. The package wraps a Rust native library, provides simple interfaces for hashing state, and includes a sample that demonstrates how to detect desyncs at a specific tick.

Mon, 14 Sep 2026 20:11:05 GMT

Tickwise is a new tool that brings deterministic recording to Unity projects. It does not replace your game loop; instead, it sits on top of your existing fixed‑step simulation and lets you capture the state of every tick, hash it, and later compare two recordings to find the exact tick where they diverge.

What the Bridge Provides

The core of Tickwise is a native Rust library that exposes a C ABI. The Unity package is a thin C# wrapper that implements two small interfaces:

• IDeterminismProbe – exposes LightHash() (cheap, per tick) and FullHash() (expensive, every N ticks).
• ITickwiseStateWriter – optional, writes a full state dump for field‑level diffs.

These interfaces are all that your game code needs to touch. The rest of the system, including recording and comparison, is handled by the Tickwise CLI tool.

Getting Started in Unity

Adding the package is straightforward. In the Package Manager, add the Git URL:

"com.cosgunhalil.tickwise":"https://github.com/cosgunhalil/Tickwise.git#unity/v0.1.0"

Alternatively, edit Packages/manifest.json directly. The release branch contains pre‑built binaries for Windows, macOS, Linux, Android, and iOS. For iOS you must link the static library, which changes the import name to __Internal.

Once installed, import the bundled sample scene “Deterministic Mini Game.” The scene contains eight balls that bounce in a box using integer math and no Unity physics. This pure‑logic simulation is ideal for demonstrating deterministic recording.

Recording a Run

In the sample, a Recorder object is created in Start() with a configuration that includes a build hash, platform, tick rate, and hash intervals. The FixedUpdate() method steps the simulation, feeds it scripted input, and records each tick:

_recorder.RecordTick(_tick, _input, _sim);

Two important points: the build hash and platform are stored in the recording header, so comparing recordings from different builds is flagged as invalid; and the full hash interval is set to 50 ticks in the sample to keep the recording short, but the default 300 ticks is a better starting point for real games.

Detecting a Desync

The sample includes a “chaos” toggle that injects a value derived from the real wall clock into the simulation after tick 421. Running the scene twice—once with chaos off and once with it on—produces two recordings that differ from tick 421 onward. Using the CLI tool:

tickwise compare clean.rec chaotic.rec

The output reports: “first divergence at tick 421, last agreement at tick 420.” The tool pinpoints the exact tick where the two runs stopped agreeing, which is invaluable for debugging non‑deterministic bugs that only surface when comparing runs.

Validation and Testing

Tickwise includes a Unity play‑mode test that automatically runs the sample twice, calls the CLI tool, and asserts that the output contains the expected divergence message. The C# wrapper is also compiled in a plain .NET project and tested on Windows, macOS, and Linux, ensuring that the core logic works independently of Unity.

Using Tickwise in Your Project

To integrate Tickwise:

1. Identify the deterministic simulation in your game—ideally a fixed‑step system that owns its state.
2. Implement IDeterminismProbe on a class that can hash its state cheaply (light hash) and fully (full hash).
3. Record two runs, then run the CLI comparison. If the simulation reproduces itself, the comparison will confirm no divergence; otherwise, it will report the first tick of mismatch.

Because the bridge is language‑agnostic, the same Rust library powers other engine wrappers (Unreal, Godot, Bevy, etc.). Tickwise is still in early versions, so users are encouraged to report any issues.

Why It Matters

Deterministic multiplayer games rely on perfect sync between clients. Tickwise gives developers a precise, automated way to verify that their simulation behaves identically across runs, making it easier to catch subtle bugs that only appear in production.

Why it matters

Deterministic multiplayer requires that every client’s simulation stay in lockstep. Tickwise gives developers a reliable, automated way to confirm that their game logic is truly deterministic, helping to catch elusive bugs before they affect players.

Key points

• Tickwise is a thin Unity wrapper over a Rust native library that records deterministic simulation state.
• It exposes two interfaces: a cheap per‑tick hash and an expensive full‑tick hash.
• The sample scene demonstrates how to record, inject a non‑deterministic bug, and pinpoint the exact tick of divergence using the CLI tool.
• The package includes automated tests that validate the bridge, recording format, and comparison tool across platforms.
• Integration requires implementing the probe interfaces on your own simulation class and recording two runs for comparison.
• The tool works offline, making it suitable for CI pipelines and cross‑machine debugging.

Frequently asked questions

Do I need to rewrite my game loop to use Tickwise?

No. Tickwise works with your existing fixed‑step loop; you simply call the recorder once per tick and provide the input bytes and a probe object.

Can I use Tickwise with Unity physics?

Tickwise itself does not enforce physics; you can use Unity physics as long as you can provide deterministic input and hash the resulting state.

Is the native library cross‑platform?

Yes. Binaries are included for Windows, macOS, Linux, Android (three ABIs), and iOS (static library).

Reporting drawn from

• dev.to