Discord server
Guide

Players desync at the same moment every game

A desync drops players when their game state stops matching. It never shows in single player, so the cause is almost always code that runs differently on each machine.

What you see

  • Players are dropped from an online game, often at a repeatable moment.
  • The game writes a folder under Documents\Warcraft III\Errors with a Desync.txt and a replay.
  • Testing alone never shows it.

Why it happens

GetLocalPlayer() returns a different player on each machine, so code inside if GetLocalPlayer() == p then runs on one client only. If that code creates a handle (a unit, group, timer, effect or location) or changes game state (moves a unit, issues an order, rolls a random number), the clients drift apart. ForGroup and ForForce inside such a block desync reliably.

Some values differ between machines by nature, such as camera positions and others the documentation marks as asynchronous. Using them to change game state desyncs.

In Lua maps, pairs() can visit table keys in a different order on each client. A loop that damages units or hands out rewards in that order desyncs. So can tostring on game objects, and GetHandleId used in local code.

How to fix it

  1. Do every handle-creating and state-changing call on all clients. Branch on the local player only to choose a value: a model path, a text, a transparency, whether a frame is visible.
  2. Per-player effects: choose the model path inside the local branch (empty for everyone else) and create the effect outside it, so every client creates it.
  3. Create UI frames for all players, then show, hide or set their text locally.
  4. Lua: iterate arrays with a numeric for or ipairs. For sets, keep a separate array of keys or use a table type that remembers insertion order.
  5. If a desync still happens, note the game time and the Errors folder, then check what runs at that moment.

How WC3 Map Doctor detects it

Rules that look for this
  • Severe
    A handle is created or game state changes inside a GetLocalPlayer branch, which desyncs the other players.
    DESYNC-localplayer-handle
  • Severe
    A pairs() or next() loop changes game state, and the iteration order differs between clients, so the game desyncs.
    DESYNC-lua-pairs-state

Desync fixes need to know what the author meant, so they are reported with the line, not changed automatically. The example report leaves one in place and says why.

Sources

Written in our own words from our lab notes; these are the pages behind them.