Spectator mode — development status & next steps

[Vmarcelo49]

Status: Code complete, pending runtime validation

All 5 phases of the spectator mode plan () are implemented and wired end-to-end, but never validated at runtime (requires Wine + MBAACC.exe).

What's done (code-level)

Phase	Description	Status
1	Protocol — message added to protocol	✅ Complete
2	Host-side — ported from CCCaster, integrated into NetworkThread	✅ Complete
2.5	NetworkThread integration — CONNECT/DISCONNECT handlers, re-enabled	✅ Re-enabled ()
3	Client-side — receives + + and replays	✅ Complete
4	Launcher/GUI — and GUI Spectate button working	✅ Complete
5	Relay spectate — via relay server	✅ Complete

Where we stopped

The spectator code was fully implemented in commits and (2026-07-14/15), including re-enabling the two DISABLERS that were blocking it in the network thread. Build is clean (MinGW cross-compile, zero warnings/errors).

What's missing is runtime validation — the feature has never been tested with actual Wine + MBAACC.exe.

Runtime validation matrix (pending)

1. Regression test: host + join via localhost — must still work end-to-end (critical: previously caused a Wine regression)
2. Direct spectate: host + join + 3rd instance as spectator via — spectator should receive SpectateConfig + InitialGameState + BothInputs stream and replay the match
3. Relay spectate: — spectator connects via relay, host identifies as spectator, replay works
4. Spectator disconnect mid-match — host's SpectatorManager removes spectator via , no crash, no impact on ongoing match
5. Opponent disconnect mid-match with spectator connected — spectator should also be disconnected or notified

Known minor pendings (non-blocking for basic spectate)

• SpectatorManager::step() detects pending spectator timeout but only does _pending.erase(peer) — no enet_peer_disconnect_later call. Relies on spectator's own client-side timeout.
• frameStepRerun not adapted for spectator — may work as-is (spectator has no local inputs to predict), but needs runtime confirmation.
• getInput() dispatcher has no explicit SpectateNetplay path — returns 0 by default (correct for spectator), but unverified at runtime.
• SyncHash received by spectator is intentionally discarded — no desync detection for spectators by design.

Next steps

• Set up Wine + MBAACC.exe environment for runtime testing
• Run the 5-point validation matrix above
• Fix any regressions or issues found
• Test with weak-opponent scenario (see Poor rollback netplay experience — hiccups during online matches #4 — poor rollback experience may interact with spectator)

References

• Full plan: docs/spectator-plan.md
• Threading prerequisite: docs/threading-migration.md (Layer 4 — complete)
• Key commits: 027d9ee (initial implementation), 3fd525e (re-enablement)

[Vmarcelo49]

Status update: working locally end-to-end (multi-round + rematch)

Spectator mode now works in local testing: a third instance joining mid-session replays from the start of the session, follows every round transition (including the RetryMenu rematch), and trails live play by a native ~2-4s delay. Validated repeatedly with a new integration harness (scripts/spectest.sh: host + joiner auto-mash + late spectator on localhost, headless-capable).

What was wrong

The original port streamed spectators from the host's LIVE rollback containers with only transient protection, applied RngState/MenuIndex messages instantly on arrival, and let future-era inputs reach the spectator's game. Combined effects: mid-round joins desynced permanently, retry menus stalled or rematched prematurely, and boundary scenes froze.

What changed (656c136)

1. Session archive ('proven truth') — SpectatorManager now keeps its own append-only history of BothInputs batches, pulled only after they cross a 120-frame safety lag behind the live edge (getBothInputs(pos, minLag)), with preserveStartIndex pinned at the archive cursor so GC cannot eat unarchived frames.
2. Replay-from-start promotion — new spectators get SpectateConfig + archived per-index RngStates/MenuIndexes + every batch from cursor 0; serving is burst-paced during catch-up and throttled near live.
3. Deferred control application — RngState and MenuIndex are buffered by index client-side and applied exactly when playback crosses their transition (fixes premature rematches + mid-round RNG corruption).
4. Lockstep throttle — spectators never simulate frames lacking proven inputs; holds keep the last frame visible (skip forced off) and release when the stream advances past our index (fixes boundary deadlocks).
5. Catch-up fast-forward — engages beyond ~6s of backlog, auto-disengages near live; SPACE toggles manually. Threshold must exceed the safety lag or ff never disengages.
6. Receive-only spectators — setInput/saveState/rollback/spin-lock/send paths all exclude them (spectator PlayerInputs were being echoed back to the host, polluting joiner containers).
7. Retry-menu navigation from the archive — CCCaster-parity branch reads the per-index MenuIndex choice instead of raw replayed input; host AND joiner choices are both archived.
8. SyncHash desync detection for spectators — host forwards hashes; spectator compares its replayed state and logs mismatches without stopping (0 detected across validation runs).

Validation

scripts/spectest.sh --duration=120 headless: 3/3 instances through multiple rounds incl. rematch; zero stream holes; zero SyncHash mismatches; deferred RNG/menu applied at each crossing. Visible-mode runs confirmed identical behavior plus clean disconnect teardown.

Remaining (why this stays open)

• Real-network (two-NAT) spectate session untested; relay-room spectate path reworked but unvalidated online.
• Win-pose cinematic pauses proven-data production for its duration — spectator holds visibly for those seconds by design; may feel like a hiccup.
• Diagnostic logging still chatty during catch-up bursts; worth gating behind env.
• Native delay is currently implicit (~2-4.5s depending on pacing); consider exposing it as a configurable value.

[Vmarcelo49]

Behavior update per spec clarification: spectators now join at CHARACTER SELECT at normal speed, watching the archived inputs land input-by-input (the full session history replays — no more jump-to-live). SPACE toggles fast-forward for skipping backlog; catch-up auto-disengages near live. Default matches the original CCCaster feel; CASTER_SPECTATE_FASTFWD=1 restores join-at-speed.

Also landed in bdd8024:

• Boundary jumps: when the host's frame counter rolls into a new index (world-timer freeze during win-pose), playback snaps forward instead of simulating nonexistent frames — fixes the visible freeze at every round end.
• Receive-only spectators: setInput/saveState/rollback/spin-lock/send paths all exclude them. This also fixed a hidden corruption: with kFlagNetplay always set, spectators were running the spin-lock AND echoing PlayerInputs back to the host, polluting joiner containers.
• Retry-menu navigation from archived choices (SpectateNetplay branch, player-filtered so both players can't double-step the nav FSM).
• Stream gap detector now tolerates intentional cross-index overlap batches.

Validation (scripts/spectest.sh): default mode replays from chara select frame-exact vs proven edge; FASTFWD mode catches up to live and locks there; zero SyncHash mismatches across multi-round runs; rematch traversal confirmed headless.

Still open for this issue: online/relay-room spectate validation, win-pose hold UX polish, catch-up log gating, configurable native delay.