Spectate catchup

[ryanbarlow97]

Description:

2026-01-24.12-34-52.mp4

Catchup mechanic for live games and changes replays to have a backlog for more "max" speed

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory
• I confirm I have thoroughly tested these changes and take full responsibility for any bugs introduced

Please put your Discord username so you can be contacted if a bug or regression is found:

w.o.n

[coderabbitai]

Walkthrough

The game runner's tick execution now returns a boolean and exposes pending turn count. The worker heartbeat was changed to throttle tick execution to at most 4 ticks per heartbeat. The local server replay queuing gained a backlog-based gating mechanism limiting queued replay turns.

Changes

Cohort / File(s)	Summary
Core game tick execution src/core/GameRunner.ts	executeNextTick() signature changed to return boolean (true on success, false on failure/early-exit); error paths reset isExecuting and return false. New public pendingTurns(): number reports remaining turns.
Worker heartbeat throttling src/core/worker/Worker.worker.ts	Added MAX_TICKS_PER_HEARTBEAT = 4. Heartbeat handler now runs up to min(gr.pendingTurns(), MAX_TICKS_PER_HEARTBEAT) ticks, looping and stopping when executeNextTick() returns false.
Local replay backlog gating src/client/LocalServer.ts	Replay queuing logic updated to compute a backlog and allow queuing when backlog < MAX_REPLAY_BACKLOG_TURNS (applies at fastest replay speed with a game record). Imports extended to use ReplaySpeedMultiplier.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~15 minutes

Poem

⏰ Heartbeats measured, four at a time,
Ticks return true when the game keeps in rhyme.
Backlogs kept small so replays don't race,
Pending turns counted, steady the pace. 🎮

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Spectate catchup' is vague and does not clearly convey what the main change is about; it lacks specificity about the feature being implemented.	Consider using a more descriptive title like 'Add catchup mechanic for live game spectation' to better summarize the feature being implemented.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	The PR description clearly relates to the changeset: implementing a catchup mechanic for live games and modifying replay speed handling, which matches the code changes in GameRunner, Worker.worker.ts, and LocalServer.ts.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}