multiplayer-reconnect-runbook

name	multiplayer-reconnect-runbook
description	Operational reconnect workflow for restoring clients to authoritative multiplayer state without duplicate or out-of-order mutation.
tier	operational
godot_version	4.6+
doc_anchors	["godot-docs/tutorials/networking/high_level_multiplayer.rst","godot-docs/tutorials/networking/websocket.rst","godot-docs/classes/class_multiplayerapi.rst","godot-docs/tutorials/editor/command_line_tutorial.rst"]
tags	["multiplayer","reconnect","reliability"]
depends_on	["godot-skills/godot-tertiary/networking-reliability-reconciliation-contract/SKILL.md","godot-skills/godot-operational/qa-validation-loop/SKILL.md"]

Multiplayer Reconnect Runbook

Use When

• Client disconnect/reconnect behavior is being implemented or debugged.
• Mid-match recovery and state resync logic changes.
• Reliability regressions appear under packet loss or transient dropouts.

Outcomes

• Reconnected clients resume from a validated authoritative boundary.
• Duplicate player intents are not re-applied during reconnect retries.
• UI state transitions back to match flow without desync side effects.

Required Rules

• Reconnect handshake must include session identity and ordering boundary metadata.
• Authoritative snapshot/commit boundary must be applied before local input unlock.
• Pending local intents are reconciled by request identity, not blindly replayed.
• Every reconnect rejection path returns stable reason codes for diagnostics.

Workflow

1. Trigger reconnect scenario at defined boundary (idle, pending intent, post-commit).
2. Re-authenticate session and request authoritative snapshot plus last commit/tick index.
3. Apply snapshot, then reconcile pending local intents by idempotent request IDs.
4. Resume UI at safe gate (await_commit or equivalent) and unlock input once synced.
5. Record envelope metadata and reason codes for all reconnect outcomes.

Validation

• Induced dropout test: reconnect from mid-match and verify identical authoritative state.
• Duplicate intent test: retry same request ID during reconnect and confirm single apply.
• Out-of-order replay test: deliver stale commit after newer commit and verify safe reject.

Failure Modes

• Client resumes input before authoritative state is applied.
• Reconnect path regenerates request IDs and double-applies actions.
• UI recovers visually while simulation remains unsynced.

Local Doc Anchors

• godot-docs/tutorials/networking/high_level_multiplayer.rst
• godot-docs/tutorials/networking/websocket.rst
• godot-docs/classes/class_multiplayerapi.rst
• godot-docs/tutorials/editor/command_line_tutorial.rst