feature: late spectator

[Fcornaire]

Hello! I'm working on EX (https://github.com/Fcornaire/TF.EX), a mod that attemtp to brings rollback netplay to TowerFall. I've used ggrs since the beginning of the project and stuck with it because I like how it's designed.

I thought it would be cool if a spectator could join a P2P session after it started, and after digging into the repo, it turned out to be easier than I expected.

How it works

The core idea: when enabled, the host retains every confirmed input since frame 0, so a late spectator can join at any time and replay the session from the very first frame, then catch up to live.

• SessionBuilder::with_late_spectators(true) : opt-in flag on the host session. With the flag off (by default), original behavior.
• P2PSession::add_spectator(addr) : registers a spectator on a running session. The spectator side needs no changes.
• History is streamed in ack-paced chunks of up to (SPECTATOR_SEND_WINDOW) 64 frames rather than all at once, so a far-behind spectator is throttled instead of disconnected.
• SpectatorSession::set_catchup_speed(), runtime version of the existing builder option, so a viewer can toggle between watching the buffered past and fast-forwarding to live.
• The spectator's input buffer is now a BTreeMap instead, it has to hold an arbitrarily large amount of input while catching up, and I chose BTreeMap because it releases memory as entries are consumed, which felt important for this feature.

Your opinion

• Retaining input_history from frame 0 , is that acceptable for the lib ?
• With the growable buffer, SpectatorTooFarBehind can no longer occur. I kept the variant for backward compatibility.

Existing tests all pass, and I added some.

Demo

Here's the feature running in TowerFall: three instances, the top two are the live players, the bottom one is a spectator who joins mid-match and catches up:

2026-08-23.late-spectate.mp4

[gschup]

Looks great! Let me sit on it for a night, but this looks good as-is! Thank you for the work :)

[gschup]

I have been hesitant to add late players joining a match for multiple reasons, but late spectators seem like a straightforward addition.

[gschup]

btw TowerFall and your mod are awesome <3