Docs/Client Reconnection
Guides

Unity Client Reconnection

TurnKit handles temporary socket drops automatically and supports restart-safe resume when you save a small reconnect snapshot. Pair this page with the Unity Client API and WebSocket reconnect behavior.

Socket Drop (App stays running)

TurnKit handles reconnection automatically. The client sends an automatic RECONNECT message with the last acknowledged move number. The server replays any missed moves via OnMoveMade and signals the end with OnSyncComplete.

What you need to do

  • Wait until Relay.IsReady is true before sending any actions.
  • If you need move history, store OnMoveMade events yourself.
  • If you're using TurnKit server lists, replayed moves automatically rebuild list state. Refresh your UI from Relay.GetList(...) or Relay.AllLists after sync completes.
  • If your game logic depends on the message.json payload, apply replayed moves without animations or wait times.

Game Crash or Restart

Automatic reconnection will not work because in-memory data is lost. To resume a match, save these values locally:

  • relayToken
  • lastMoveNumber
  • playerId and slug for identity and metadata
  • If the game uses AUTH_REQUIRED, persist or refresh the player JWT you need before calling the queue or resume flow again.
bool resumed = await Relay.Resume(playerId, slug, savedRelayToken, savedLastMoveNumber);

if (resumed)
{
    // Missed moves replay through OnMoveMade, then OnSyncComplete fires.
}
else
{
    // Fall back to normal matchmaking or join flow.
}

After a successful resume, the server replays missed moves followed by OnSyncComplete the same way as a normal reconnect.

If the server returns RECONNECT_EXPIRED, the match can no longer be resumed. Clear saved data and fall back to normal matchmaking or join flow.

Other Client Reconnection

The rules are the same for any client using the WebSocket protocol.

Temporary Socket Drop

  • Reconnect to the same relay WebSocket using the valid relay token.
  • Send RECONNECT { lastMoveNumber }.
  • Block outgoing actions until you receive OnSyncComplete.
  • Replayed moves rebuild server list state automatically.
  • If using custom payloads, apply every replayed move in order to your local game state.

Crash / Restart

  • Save at minimum relayToken and lastMoveNumber plus playerId and slug if needed.
  • If player auth is required, make sure a valid player JWT is available again before rejoining normal client APIs.
  • On restart, reconnect with the token and resume from the saved last move number.
  • If resume succeeds, process missed moves normally.
  • If you get RECONNECT_EXPIRED, the match cannot be resumed. Clear saved data and start a fresh join.
Unity Client Reconnection - TurnKit Docs