multiplayer-state-machine-coverage

Overview

Networked games are state machines: each player connection, each replicated entity, and each authority handoff transitions through a documented set of states. Cert failures and on-the-wire bugs overwhelmingly happen at transition edges - connect, host migration, disconnect-mid-action, reconnect-after-network-loss - not in the steady-state gameplay loop.

This skill is a build-an-X workflow: produce a state-machine coverage matrix that enumerates every connection + ownership + replication state in your engine, crosses it with the network fault matrix (latency / loss / out-of-order / disconnect), and emits a fixture list + a go / no-go gate.

Composes with:

• game-test-categories-reference - multiplayer testing is a cross-axis over functional / compliance / compatibility / performance.
• platform-cert-overview-reference - the matrix maps onto Xbox XR-067 (MPSD session state), XR-064 (joinable sessions), XR-115 (controller / user add and remove), and XR-074 (loss of connectivity), all cited inline below from the Xbox Requirements page.
• unity-test-framework, unreal-automation-system, godot-gut-tests - the per-engine test frameworks the fixtures run in.

When to use

• Building the multiplayer test plan for a title that ships to Xbox / PlayStation / Switch - cert pass risk concentrates here.
• Triaging a recurring "host migration drops players" / "join fails after suspend" / "save corrupted on rejoin" bug class.
• Bringing up netcode-driven gameplay (Unity NGO, Unreal replication, Mirror) for the first time on a project - set the coverage floor before launch.

Microsoft's Certification step-by-step guide explicitly cites "Multiplayer does not work as expected" as one of the three most common reasons titles are placed on Hold. Holds are calendar-week delays - coverage authored ahead of cert is the cheapest mitigation.

Inputs

Before walking the workflow, gather:

Workflow

Step 1 - Enumerate connection states

Per engine docs, list the states the engine exposes. The matrix is fixed by the framework - you cannot add or remove states, only choose which to cover. The full per-engine connection-state tables (Unity NGO, Unreal replication, Mirror) - each state with its trigger and observability hook - are in references/engine-states.md.

Step 2 - Enumerate ownership states

Authority handoff is where most "ghost item" / "ability use after death" bugs live. The per-engine authority-state enumeration (NGO OwnerClientId / IsOwner; Unreal ROLE_*; Mirror isServer / isOwned) is in references/engine-states.md. Authority transitions to cover:

• Spawn → owner assignment - does the right OnStartAuthority / OnGainedOwnership callback fire?
• Authority handoff mid-action - player picks up an item that another player owns; does the prior owner stop sending RPCs?
• Authority loss on disconnect - does authority return to server or transfer to another client?
• Authority on host migration - see Step 4 below.

Step 3 - Enumerate replicated-property transitions

For every replicated property (NGO NetworkVariable<T>, Unreal UPROPERTY(Replicated) / RepNotify, Mirror [SyncVar]), identify:

1. The set of legal values it can hold.
2. The set of legal transitions between values (some pairs should never be observed).
3. The callback fired on remote when it changes (Unreal: OnRep_<PropName> per Networking Overview: "Replicated Using Properties: State that triggers a callback function upon replication"; Mirror: [SyncVar(hook=...)]; NGO: NetworkVariable<T>.OnValueChanged).

Each OnRep_ / hook handler is a transition edge that needs at least one fixture exercising it.

Step 4 - Cross with the network fault matrix

The engine state machines are deterministic on a perfect network. Real networks are not perfect. Cross-product each state from Step 1 with:

The full Cartesian product is too big - sample by risk-weighted buckets:

• High - every fault × every transition edge.
• Medium - steady-state gameplay × every fault.
• Low - steady-state gameplay × baseline (no fault).

Step 5 - Encode each combination as a fixture

For Unity NGO, the fixture is a UTF [UnityTest] PlayMode test (see unity-test-framework):

[UnityTest]
public IEnumerator HostMigration_TransfersAuthority_OnHostDisconnect()
{
    // Arrange - host + 2 clients
    var host = StartHost();
    yield return new WaitForSeconds(1f);
    var c1 = StartClient(); yield return new WaitForSeconds(0.5f);
    var c2 = StartClient(); yield return new WaitForSeconds(0.5f);

    // Spawn an authority-bearing object owned by host
    var npc = host.SpawnNpc();
    yield return new WaitForSeconds(0.5f);
    Assert.AreEqual(host.LocalClientId, npc.OwnerClientId);

    // Act - kill the host
    host.Shutdown();

    // Assert - surviving client becomes new host within
    // <= 5 s and reassigns NPC authority.
    yield return new WaitForSeconds(5f);
    Assert.IsTrue(c1.IsHost || c2.IsHost);
    Assert.IsNotNull(NetworkManager.Singleton.SpawnManager.SpawnedObjects[npc.NetworkObjectId]);
}

For Unreal, a unreal-automation-system spec wrapping IAutomationDriverModule doesn't drive netcode directly - instead, drive a multi-process test harness (UE 5.x's "Multi-User Editor" / Multi-Process PIE) and use specs to observe the resulting OnRep_ invocations.

For Mirror, the fixture is a Unity NGO-style UTF test plus Mirror's built-in network simulation transports.

Step 6 - Wire to platform-cert clauses

Map every fixture to a specific cert clause it covers - e.g. graceful disconnect on network loss → XR-074, MPSD session retained across host migration → XR-067, joinable via the Xbox shell → XR-064, privilege check before joining → XR-045. The full fixture→XR mapping table (and the Sony TRC / Nintendo Lotcheck NDA stable-ID convention) is in references/cert-clauses.md.

Step 7 - Emit the go / no-go gate

Aggregate the matrix into a coverage report:

Multiplayer state-machine coverage - MyGame v1.4.2
====================================================
Connection states enumerated:          7 / 7 ✓
Ownership transitions enumerated:      5 / 5 ✓
Replicated-property edges enumerated: 23 / 23 ✓
Fault-matrix coverage:
  High-risk bucket:  18 / 18 fixtures ✓
  Medium bucket:      9 / 12 fixtures (75 %) ⚠
  Low bucket:         3 /  4 fixtures (75 %)
Cert-clause coverage:
  XR-067 MPSD session state              ✓
  XR-074 Service connectivity loss        ✓
  XR-064 Joinable via shell               ✓
  XR-045 Privilege checks                 ✓
  XR-015 Comm-privacy                     ⚠ (CommunicateUsingVoice path uncovered)
  XR-115 Controller add/remove mid-MP     ✓
  XR-130 Save roams across SKUs           ✓

VERDICT: NO-GO (XR-015 voice-privacy path uncovered;
              medium-risk bucket below 80 % threshold)

The gate refuses to advance to platform-cert submission until every cert-mapped clause is covered and the high-risk bucket is at 100 %.

Worked example - Unity NGO host migration

Inputs:

• Engine + netcode: Unity 6.0, Netcode for GameObjects v2.11.
• Topology: Host (one client doubles as server).
• Max players: 8.
• Persistence: Session must survive host migration; saves per-client.
• Platform target: Xbox + PSN + Switch + Steam.

Step 1 - connection states from the NGO v2.11 manual: Disconnected, Connecting, Connected (Approved), Connected (Pending Spawn), Connected (Spawned), Disconnecting, Host.

Step 2 - ownership transitions: spawn → owner assigned; host quits → ownership re-elected; client picks up host-owned item.

Step 3 - replicated properties under coverage: currentHealth (NetworkVariable<float>), inventoryHash (NetworkVariable<int>), questFlags (NetworkVariable<NetworkSerializableQuestState>).

Step 4 - fault matrix selection: high-risk = Host → Connected (other client takes over) under each of {200 ms latency, 5 % loss, host-kill, host-suspend (Xbox)}.

Step 5 - encode each combination as a UTF PlayMode [UnityTest] (see code sample in Step 5 above).

Step 6 - map fixtures to cert clauses (per the XR list):

• Host-kill + reconvene → XR-067 (MPSD session retained).
• Host-suspend on Xbox → XR-074 (graceful service loss).
• New host accepts joins via shell → XR-064.
• Voice chat after host migration respects mute → XR-015.

Step 7 - emit gate. Failing fixture: voice mute is reapplied after host migration only 4 / 5 runs (flake). Verdict: NO-GO, flake on the XR-015 voice path; needs a deterministic re-application path before cert.

Anti-patterns

Limitations

• Multi-process test harnesses are flaky on CI. Spinning up multiple game instances (host + clients) in a single CI job often hits port-collision or timing-dependent flake. Run multiplayer fixtures on a dedicated multi-VM tier, not the same CI runner as unit tests.
• Engine-specific simulators differ. Unity's Network Simulator is config-driven; Mirror exposes a LatencySimulation component; Unreal uses Net PktLag / Net PktLoss console commands. The matrix must use whichever the engine ships - no generic abstraction works across all three.
• Cert clauses change. XR identifiers churn release-to-release (the XR v16.1 May 2026 release notes retired XR-134) - re-verify the mapping in Step 6 against the current XR document.
• NDA-only platform clauses. Sony TRC / Nintendo Lotcheck exact multiplayer clauses are NDA - cite by stable ID and tag fixtures with portal clause numbers.
• State-machine enumeration is engine-version-coupled. A NGO update may add states (e.g., a "Reconnecting" intermediate); re-enumerate when bumping the package version.
• Coverage matrix does not catch desync bugs by itself. It exercises transitions; for desync detection between authority and remote-mirrored state, add property-equality assertions inside fixtures (especially on the OnRep_ / hook paths).