How to Build a Session Replay System for Game Debugging

A good session replay system is the single most powerful debugging tool you can add to a game. Instead of chasing a vague “my character fell through the floor” report, you load the replay, scrub to the moment before the fall, and watch it happen. This guide walks through a design that has held up across several shipped titles — from a 2D puzzle platformer to a co-op survival game with physics-driven vehicles — and the tradeoffs you’ll make along the way.

Inputs Are Cheap. Record Everything.

The input stream is the backbone of your replay. It’s tiny, trivially compressible, and it’s the thing players actually did. Record every button press, stick deflection, mouse delta, and touch event with a monotonic frame number or a fixed-step simulation tick. Don’t try to be clever with delta encoding in the first version — raw tuples compress well enough with zstd to stay under a kilobyte per minute.

Also record the session-level seed used by your deterministic RNG. If any system uses a non-deterministic source — wall-clock time, system entropy, OS thread scheduling — either replace it with the seeded RNG or capture its outputs alongside inputs. A single unrecorded Random.value call in an AI behavior tree will cause your replay to diverge within seconds.

Snapshots Bound the Damage From Non-Determinism

Full determinism is a lovely goal and rarely achievable in a commercial engine. Physics, multithreaded job systems, and floating-point order-of-operations variations all introduce tiny divergences that compound frame-over-frame. Periodic snapshots give you a mechanism to reset the simulation to a known-good state before small drift turns into a replay that bears no resemblance to what actually happened.

A snapshot is not a save file. It only needs to capture the state that your simulation cannot reconstruct from inputs and seeds: rigid body transforms and velocities, AI blackboards, active timers, current scripted sequence index, inventory contents, and health. Cosmetic particles, audio emitters, and UI animation state are all derivable and should be excluded. For a typical indie game, a snapshot should be 50–300 KB.

public struct Snapshot {
    public int tick;
    public ulong rngState;
    public EntitySnapshot[] entities;
    public GlobalFlags flags;
}

// Capture every N fixed-step ticks (120 ticks @ 60Hz = 2s)
public void FixedUpdate() {
    currentTick++;
    if (currentTick % snapshotInterval == 0) {
        Snapshot snap = Capture();
        replayBuffer.Push(snap);
    }
    RecordInputs(currentTick);
    StepSimulation();
}

Choose your snapshot interval based on how long the simulation can drift before it’s useless. Two to five seconds works for most action games. Slower-paced games can go to ten. Faster-paced multiplayer shooters sometimes snapshot every 250ms but piggyback on their existing network replication layer instead of building a second system.

Playback: Seek, Step, and Scrub

The replay viewer is where your investment pays off. At minimum it needs three controls: a seek bar that jumps to the nearest snapshot and re-simulates forward, variable playback speed (0.25x to 8x), and single-frame step. Add a toggle to visualize input state — a floating overlay of the virtual controller — so you can see exactly what the player pressed when the bug fired.

When the user scrubs backward, you can’t reverse the simulation; you restore the most recent earlier snapshot and re-run inputs forward to the requested tick. On a modern machine this is fast enough to feel instant for reasonable snapshot intervals. Cache the last few resolved states so rapid scrubbing doesn’t thrash.

The best debugging session I’ve had in five years was watching a desync bug replay at 0.1x speed with the physics debug overlay on. The bug took ninety minutes to trigger live. In replay, I isolated it in eight minutes.

Make the Capture Path Opt-In and Cheap

Always-on session recording is a tempting default, but it has real costs. Disk writes can stall the main thread, the ring buffer costs memory, and serializing snapshots pulls data out of CPU cache. Run the ring buffer in memory only and only flush to disk when a crash, assertion, or explicit bug-report action fires. A five-minute ring buffer of snapshots plus inputs is usually under 20 MB — cheap to keep in RAM.

When the player submits a bug report, upload the last N seconds of the buffer along with a screenshot and log. When your crash handler fires, dump the buffer synchronously before process death using a pre-allocated scratch arena so you’re not calling the allocator from a signal handler.

Privacy and Consent

Replays are recordings of real people playing. Treat them that way. Never record text chat, voice, or real names in the replay stream itself — strip those to separate, optional attachments. For multiplayer games, never record the opponent’s raw inputs; record the reconciled server state the local client saw. When a player triggers an upload, show them a one-line summary of what’s included and let them opt out.

Give players a way to delete their own replays. Link the replay ID to a player account (hashed if possible) so a deletion request can find all of them. This matters for GDPR and CCPA compliance, and it matters because it’s the right way to treat your players.

Related Issues

For crash-side capture that pairs well with replay buffers, see best practices for error logging in game code. For a broader look at structured diagnostics, read how to set up tracing for game events.

If I can watch the bug happen, I can fix it. Session replay is the shortest path between a report and a reproduction.