feat(replay): Add checkpoint save and resume functionality for replays

[bobtista]

Summary

• Adds ability to save game state checkpoints during replay playback and resume from them
• Implements command line options for automated checkpoint save/load (-saveAtFrame, -saveTo, -loadCheckpoint)

New Features:

• Save checkpoints at any frame during replay playback
• Resume replay from a saved checkpoint with full state restoration
• Headless mode support for automated testing

CRC Consistency Fixes:

• Serialize AI, Pathfinder, AIGroup, and PartitionCell state for checkpoint CRC matching
• Preload CRC from replay file after checkpoint load for verification
• Restore RNG state at start of update to ensure deterministic behavior
• Fix shroud state, weapon timing, and path state corruption after checkpoint load

Testing
-[x] Save checkpoint during replay, load it, verify replay continues without desync
-[x]Test headless mode checkpoint save/load via command line
-[x] Verify CRC matches between original replay and checkpoint-resumed replay

TODO

• Replicate to Generals

Notes

• Since game state is saved at the checkpoint moment, any changes that would meaningfully affect game state BEFORE that frame will require a new checkpoint being made. Ideally, fixes are about something that happens after the checkpoint and before the mismatch/crash being fixed.

[greptile-apps]

Greptile Summary

This PR adds checkpoint save/resume functionality for replay debugging, allowing developers to create save points at specific frames during replay playback and resume from those points in headless mode.

Key changes:

• Extends RecorderClass to implement Snapshot interface for serialization of replay state (filename, file position, CRC queue)
• Adds CLI options -saveAtFrame, -saveTo, and -loadCheckpoint for checkpoint management
• Implements continueReplayFromCheckpoint() to load checkpoint and resume replay from saved position
• Adds headless mode checks in GameState to prevent UI calls and skip visual-only blocks during checkpoint saves
• Properly handles CRC state restoration by serializing the CRC queue and associated flags

Implementation notes:

• When loading a checkpoint, the replay filename is restored from the checkpoint itself (not from -replay CLI arg)
• Visual blocks (CHUNK_TerrainVisual, CHUNK_TacticalView, CHUNK_ParticleSystem, CHUNK_GhostObject) are skipped in headless saves
• The save/load system handles missing blocks gracefully, making headless checkpoints compatible with the existing save system
• CRC queue is properly serialized/restored to maintain sync detection after checkpoint resume

Confidence Score: 5/5

• This PR is safe to merge with proper testing of checkpoint save/load workflow
• The implementation is well-designed with proper error handling, memory management (CRCInfo cleanup in reset()), and defensive coding. The serialization logic correctly handles all replay state, and the headless mode guards prevent UI crashes. The save/load system's existing tolerance for missing blocks ensures compatibility.
• No files require special attention. The core implementation in Recorder.cpp and ReplaySimulation.cpp is solid.

Important Files Changed

Filename	Overview
Core/GameEngine/Source/Common/ReplaySimulation.cpp	Implemented checkpoint save at specified frame and resume functionality with proper error handling
GeneralsMD/Code/GameEngine/Source/Common/Recorder.cpp	Implemented serialization methods for replay state, added file reopening logic, and proper CRCInfo cleanup in reset()
GeneralsMD/Code/GameEngine/Source/Common/System/SaveGame/GameState.cpp	Added CHUNK_Recorder snapshot block, headless mode checks for UI calls, and logic to skip visual blocks in headless saves

Sequence Diagram

sequenceDiagram
participant CLI as Command Line
participant GM as GameMain
participant RS as ReplaySimulation
participant GS as GameState
participant RC as RecorderClass
participant GL as GameLogic
participant FS as FileSystem
Note over CLI,FS: Checkpoint Save Flow
CLI->>GM: -replay file.rep -saveAtFrame 49000 -saveTo checkpoint.sav
GM->>RS: simulateReplays([file.rep])
RS->>RC: playbackFile(file.rep)
RC->>FS: Open replay file
FS-->>RC: File handle
loop Until target frame or end
RS->>GL: UPDATE()
GL-->>RS: Current frame
alt Frame == saveAtFrame
RS->>GS: saveGame(checkpoint.sav)
GS->>RC: xfer(XFER_SAVE)
Note over RC: Saves replay filename,<br/>file position, CRC state
GS->>FS: Write checkpoint file
FS-->>GS: Success
RS->>RC: stopPlayback()
RC->>FS: Close replay file
end
end
Note over CLI,FS: Checkpoint Resume Flow
CLI->>GM: -loadCheckpoint checkpoint.sav
GM->>RS: continueReplayFromCheckpoint(checkpoint.sav)
RS->>GS: loadGame(checkpoint.sav)
GS->>FS: Read checkpoint file
FS-->>GS: Checkpoint data
GS->>RC: xfer(XFER_LOAD)
Note over RC: Restores replay filename,<br/>file position, CRC state
GS->>RC: loadPostProcess()
RC->>FS: reopenReplayFileAtPosition(position)
FS-->>RC: File handle at saved position
loop Until replay end or CRC mismatch
RS->>GL: UPDATE()
GL-->>RS: Current frame
RC->>FS: Read next commands from position
alt CRC mismatch detected
RS-->>GM: Exit with error
end
end
RS-->>GM: Exit code

Loading

[Caball009]

There are some issues with the CRC computation for the replay from save game.

[helmutbuhler]

Looks nice! Will -loadCheckpoint also work with savegames that the player generated? If so we could check that savegames from retail can still be loaded.

[github-actions]

⚠️ Title/Commit Validation Failed

Invalid commit messages:

• Fix TurretStateMachine not serializing base StateMachine state
• Fix DozerActionStateMachine not serializing base StateMachine state
• cleanup(replay): Remove debug logging added during checkpoint investigation
• cleanup(replay): Remove obsolete resetTransientStateForCheckpoint workaround
  PR titles and commit messages must follow conventional commits format:

type: Description
type(scope): Description

Allowed types:bugfix, build, chore, ci, docs, fix, feat, perf, refactor, revert, style, test, tweak, unify

See CONTRIBUTING.md for details.

[bobtista]

Closing this for now - the whackamole process was a grind. There's a fix found along the way though that I'll split out into its own PR.