How I Debug Multiplayer Desyncs in Unity

Desyncs are the hardest class of multiplayer bug because they hide. The game runs fine on your machine, fine in the editor, and then two players in different states report that "something went wrong" with no clear steps to reproduce. Here's the process I use to make them tractable.

1. Make it reproducible before anything else

A desync you can't reproduce is a desync you can't fix. My first move is always to build tooling: a way to force a specific game state, replay a recorded sequence of inputs, and snapshot the simulation at each frame. Once you can trigger the divergence on demand, you've turned an impossible bug into an ordinary one.

2. Compare, don't guess

With deterministic netcode, two clients that started from the same state and received the same inputs must match. So I capture the simulation state on both clients frame by frame and compare them. The first frame that differs points straight at the system that broke determinism.

3. Hunt the usual suspects

Most desyncs trace back to a short list of causes:

• Unseeded randomness — any Random call that isn't driven by a shared, deterministic seed.
• Floating-point drift — non-deterministic math or engine physics leaking into gameplay logic.
• Frame-order dependence — logic that depends on Update ordering or wall-clock time instead of the simulation tick.
• State outside the simulation — gameplay-affecting values living in MonoBehaviours or static fields the netcode doesn't roll back.

4. Fix the cause, then re-verify

Once the divergent system is found, the fix is usually to move that logic back inside the deterministic simulation or remove the source of non-determinism. Then I re-run the same recorded input sequence and confirm both clients now match all the way through. If they do, the bug is genuinely gone — not just hidden again.

This is the same approach I used on shipped Photon Quantum titles like Soul Fighters, and it's why project-rescue work on broken multiplayer is some of the most valuable work I do.