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

Core/GameEngine/Include/Common/RandomValue.h

@@ -36,4 +36,10 @@ extern void InitGameLogicRandom( UnsignedInt seed ); ///< Set the GameLogic seed
 extern UnsignedInt GetGameLogicRandomSeed( void );   ///< Get the seed (used for replays)
 extern UnsignedInt GetGameLogicRandomSeedCRC( void );///< Get the seed (used for CRCs)
 
+// TheSuperHackers @info bobtista 19/01/2026
+// Functions to save/restore the full RNG state for checkpoints.
+// The state array must have room for 6 UnsignedInts.
+extern void GetGameLogicRandomState( UnsignedInt* state, UnsignedInt* baseSeed );
+extern void SetGameLogicRandomState( const UnsignedInt* state, UnsignedInt baseSeed );
+
 //--------------------------------------------------------------------------------------------------------------

Core/GameEngine/Include/Common/ReplaySimulation.h

@@ -28,6 +28,9 @@ class ReplaySimulation
 	// Returns exit code 0 if all replays were successfully simulated without mismatches
 	static int simulateReplays(const std::vector<AsciiString> &filenames, int maxProcesses);
 
+	// Continue a replay from a checkpoint file in headless mode
+	static int continueReplayFromCheckpoint(const AsciiString &checkpointFile);
+
 	static void stop() { s_isRunning = false; }
 
 	static Bool isRunning() { return s_isRunning; }

Core/GameEngine/Source/Common/RandomValue.cpp

@@ -148,6 +148,28 @@ UnsignedInt GetGameLogicRandomSeedCRC( void )
 	return c.get();
 }
 
+// TheSuperHackers @info bobtista 19/01/2026
+// Get the full RNG state for serialization in checkpoints.
+void GetGameLogicRandomState( UnsignedInt* state, UnsignedInt* baseSeed )
+{
+	for (int i = 0; i < 6; ++i)
+	{
+		state[i] = theGameLogicSeed[i];
+	}
+	*baseSeed = theGameLogicBaseSeed;
+}
+
+// TheSuperHackers @info bobtista 19/01/2026
+// Restore the full RNG state after loading a checkpoint.
+void SetGameLogicRandomState( const UnsignedInt* state, UnsignedInt baseSeed )
+{
+	for (int i = 0; i < 6; ++i)
+	{
+		theGameLogicSeed[i] = state[i];
+	}
+	theGameLogicBaseSeed = baseSeed;
+}
+
 void InitRandom( void )
 {
 #ifdef DETERMINISTIC

Core/GameEngine/Source/Common/ReplaySimulation.cpp

@@ -21,6 +21,7 @@
 #include "Common/ReplaySimulation.h"
 
 #include "Common/GameEngine.h"
+#include "Common/GameState.h"
 #include "Common/LocalFileSystem.h"
 #include "Common/Recorder.h"
 #include "Common/WorkerProcess.h"
@@ -99,8 +100,27 @@
 					fflush(stdout);
 				}
 				TheGameLogic->UPDATE();
+
+				// Check for checkpoint save BEFORE checking for CRC mismatch
+				// so we can save checkpoints even if the replay will eventually fail
+				if (TheGlobalData->m_replaySaveAtFrame != 0 &&
+					TheGameLogic->getFrame() == TheGlobalData->m_replaySaveAtFrame &&
+					!TheGlobalData->m_replaySaveTo.isEmpty())
+				{
+					// TheSuperHackers @info bobtista 19/01/2026
+					// Pass just the filename to saveGame() - it will be saved to the Save directory.
+					SaveCode result = TheGameState->saveGame(TheGlobalData->m_replaySaveTo, UnicodeString::TheEmptyString, SAVE_FILE_TYPE_NORMAL);
+					if (result != SC_OK)
+					{
+						numErrors++;
+					}
+					TheRecorder->stopPlayback();
+					break;
+				}
+
 				if (TheRecorder->sawCRCMismatch())
 				{
+					DEBUG_LOG(("CRC mismatch at frame %d", TheGameLogic->getFrame()));
 					numErrors++;
 					break;
 				}
@@ -253,3 +273,95 @@
 	else
 		return simulateReplaysInWorkerProcesses(filenamesResolved, maxProcesses);
 }
+
+int ReplaySimulation::continueReplayFromCheckpoint(const AsciiString &checkpointFile)
+{
+	int numErrors = 0;
+
+	// TheSuperHackers @info bobtista 19/01/2026
+	// We need to initialize the replay BEFORE loading the checkpoint because:
+	// 1. loadGame() calls startNewGame() which creates team prototypes based on the map
+	// 2. During replay playback, startNewGame() uses TheRecorder->getGameInfo() to get the correct team setup
+	// 3. But CHUNK_Recorder is loaded AFTER startNewGame() runs
+	// So we must initialize the replay first to provide the correct game info.
+	if (TheGlobalData->m_simulateReplays.empty())
+	{
+		DEBUG_LOG(("No replay file specified for checkpoint loading"));
+		return 1;
+	}
+
+	AsciiString replayFile = TheGlobalData->m_simulateReplays[0];
+	DEBUG_LOG(("Initializing replay from %s before loading checkpoint", replayFile.str()));
+
+	// Initialize the recorder from the replay file so that when loadGame() calls
+	// startNewGame(), it will have the correct game info from the replay header.
+	if (!TheRecorder->initializeReplayForCheckpointLoad(replayFile))
+	{
+		DEBUG_LOG(("Failed to initialize replay from %s", replayFile.str()));
+		return 1;
+	}
+
+	DEBUG_LOG(("Loading checkpoint from %s", checkpointFile.str()));
+
+	AvailableGameInfo gameInfo;
+	gameInfo.filename = checkpointFile;
+	TheGameState->getSaveGameInfoFromFile(checkpointFile, &gameInfo.saveGameInfo);
+
+	SaveCode result = TheGameState->loadGame(gameInfo);
+	if (result != SC_OK)
+	{
+		DEBUG_LOG(("Failed to load checkpoint (error %d)", result));
+		return 1;
+	}
+
+	if (!TheRecorder->isPlaybackMode())
+	{
+		DEBUG_LOG(("Checkpoint was not saved during replay playback"));
+		return 1;
+	}
+
+	DEBUG_LOG(("Resuming replay from frame %d", TheGameLogic->getFrame()));
+
+#ifdef _DEBUG
+	DWORD startTimeMillis = GetTickCount();
+	UnsignedInt totalTimeSec = TheRecorder->getPlaybackFrameCount() / LOGICFRAMES_PER_SECOND;
+#endif
+
+	while (TheRecorder->isPlaybackInProgress())
+	{
+		TheGameClient->updateHeadless();
+
+#ifdef _DEBUG
+		const int progressFrameInterval = 10*60*LOGICFRAMES_PER_SECOND;
+		if (TheGameLogic->getFrame() != 0 && TheGameLogic->getFrame() % progressFrameInterval == 0)
+		{
+			UnsignedInt gameTimeSec = TheGameLogic->getFrame() / LOGICFRAMES_PER_SECOND;
+			UnsignedInt realTimeSec = (GetTickCount()-startTimeMillis) / 1000;
+			DEBUG_LOG(("Elapsed Time: %02d:%02d Game Time: %02d:%02d/%02d:%02d",
+					realTimeSec/60, realTimeSec%60, gameTimeSec/60, gameTimeSec%60, totalTimeSec/60, totalTimeSec%60));
+		}
+#endif
+		TheGameLogic->UPDATE();
+		if (TheRecorder->sawCRCMismatch())
+		{
+			numErrors++;
+			break;
+		}
+	}
+
+#ifdef _DEBUG
+	{
+		UnsignedInt gameTimeSec = TheGameLogic->getFrame() / LOGICFRAMES_PER_SECOND;
+		UnsignedInt realTimeSec = (GetTickCount()-startTimeMillis) / 1000;
+		DEBUG_LOG(("Elapsed Time: %02d:%02d Game Time: %02d:%02d/%02d:%02d",
+				realTimeSec/60, realTimeSec%60, gameTimeSec/60, gameTimeSec%60, totalTimeSec/60, totalTimeSec%60));
+
+		if (TheRecorder->sawCRCMismatch())
+			DEBUG_LOG(("CRC Mismatch detected!"));
+		else
+			DEBUG_LOG(("Replay completed successfully"));
+	}
+#endif
+
+	return numErrors != 0 ? 1 : 0;
+}

Core/GameEngineDevice/Source/W3DDevice/GameClient/BaseHeightMap.cpp

@@ -2984,18 +2984,53 @@ void BaseHeightMapRenderObjClass::crc( Xfer *xfer )
 // ------------------------------------------------------------------------------------------------
 /** Xfer
 	* Version Info:
-	* 1: Initial version */
+	* 1: Initial version
+	* 2: Added support for headless mode where tree/prop buffers may be null */
 // ------------------------------------------------------------------------------------------------
 void BaseHeightMapRenderObjClass::xfer( Xfer *xfer )
 {
 
 	// version
-	XferVersion currentVersion = 1;
+	XferVersion currentVersion = 2;
 	XferVersion version = currentVersion;
 	xfer->xferVersion( &version, currentVersion );
 
-	xfer->xferSnapshot( m_treeBuffer );
-	xfer->xferSnapshot( m_propBuffer );
+	if (version >= 2)
+	{
+		// TheSuperHackers @info bobtista 26/01/2026
+		// In headless mode, m_treeBuffer and m_propBuffer are not allocated.
+		// We need to track whether they were present when saved so we can properly
+		// skip the data when loading in headless mode (or vice versa).
+		Bool hasTreeBuffer = (m_treeBuffer != nullptr);
+		xfer->xferBool(&hasTreeBuffer);
+		if (hasTreeBuffer)
+		{
+			if (xfer->getXferMode() == XFER_LOAD && m_treeBuffer == nullptr)
+			{
+				DEBUG_CRASH(("BaseHeightMapRenderObjClass::xfer - Cannot load tree buffer in headless mode"));
+				throw XFER_INVALID_PARAMETERS;
+			}
+			xfer->xferSnapshot(m_treeBuffer);
+		}
+
+		Bool hasPropBuffer = (m_propBuffer != nullptr);
+		xfer->xferBool(&hasPropBuffer);
+		if (hasPropBuffer)
+		{
+			if (xfer->getXferMode() == XFER_LOAD && m_propBuffer == nullptr)
+			{
+				DEBUG_CRASH(("BaseHeightMapRenderObjClass::xfer - Cannot load prop buffer in headless mode"));
+				throw XFER_INVALID_PARAMETERS;
+			}
+			xfer->xferSnapshot(m_propBuffer);
+		}
+	}
+	else
+	{
+		// Version 1: unconditional serialization (legacy - requires both buffers)
+		xfer->xferSnapshot( m_treeBuffer );
+		xfer->xferSnapshot( m_propBuffer );
+	}
 
 
 }

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DTerrainVisual.cpp

@@ -1150,6 +1150,9 @@ void W3DTerrainVisual::crc( Xfer *xfer )
 // ------------------------------------------------------------------------------------------------
 void W3DTerrainVisual::xfer( Xfer *xfer )
 {
+	// In headless mode, terrain may not be fully initialized
+	// Only proceed if we have the height map data (which is the critical logic data)
+	Bool hasHeightMap = (m_logicHeightMap != nullptr);
 
 	// version
 #if RTS_GENERALS && RETAIL_COMPATIBLE_XFER_SAVE
@@ -1164,9 +1167,9 @@ void W3DTerrainVisual::xfer( Xfer *xfer )
 	TerrainVisual::xfer( xfer );
 
 	// flag for whether or not the water grid is enabled
-	Bool gridEnabled = m_isWaterGridRenderingEnabled;
+	Bool gridEnabled = hasHeightMap ? m_isWaterGridRenderingEnabled : FALSE;
 	xfer->xferBool( &gridEnabled );
-	if( gridEnabled != m_isWaterGridRenderingEnabled )
+	if( hasHeightMap && gridEnabled != m_isWaterGridRenderingEnabled )
 	{
 
 		DEBUG_CRASH(( "W3DTerrainVisual::xfer - m_isWaterGridRenderingEnabled mismatch" ));
@@ -1175,7 +1178,7 @@ void W3DTerrainVisual::xfer( Xfer *xfer )
 	}
 
 	// xfer grid data if enabled
-	if( gridEnabled )
+	if( gridEnabled && m_waterRenderObject != nullptr )
 		xfer->xferSnapshot( m_waterRenderObject );
 
 /*
@@ -1210,25 +1213,31 @@ void W3DTerrainVisual::xfer( Xfer *xfer )
 
 	// Write out the terrain height data.
 	if (version >= 2) {
-		UnsignedByte *data = m_logicHeightMap->getDataPtr();
-		Int len = m_logicHeightMap->getXExtent()*m_logicHeightMap->getYExtent();
-		Int xferLen = len;
-		xfer->xferInt(&xferLen);
-		if (len!=xferLen) {
-			DEBUG_CRASH(("Bad height map length."));
-			if (len>xferLen) {
-				len = xferLen;
+		// In headless mode, m_logicHeightMap may be nullptr if terrain wasn't loaded
+		if (m_logicHeightMap == nullptr) {
+			Int xferLen = 0;
+			xfer->xferInt(&xferLen);
+		} else {
+			UnsignedByte *data = m_logicHeightMap->getDataPtr();
+			Int len = m_logicHeightMap->getXExtent()*m_logicHeightMap->getYExtent();
+			Int xferLen = len;
+			xfer->xferInt(&xferLen);
+			if (len!=xferLen) {
+				DEBUG_CRASH(("Bad height map length."));
+				if (len>xferLen) {
+					len = xferLen;
+				}
+			}
+			xfer->xferUser(data, len);
+			if (xfer->getXferMode() == XFER_LOAD && m_terrainRenderObject != nullptr)
+			{
+				// Update the display height map.
+				m_terrainRenderObject->staticLightingChanged();
 			}
-		}
-		xfer->xferUser(data, len);
-		if (xfer->getXferMode() == XFER_LOAD)
-    {
-			// Update the display height map.
-			m_terrainRenderObject->staticLightingChanged();
 		}
 	}
 
-	if (version >= 3) {
+	if (version >= 3 && m_terrainRenderObject != nullptr) {
 		xfer->xferSnapshot(m_terrainRenderObject);
 	}
 

GeneralsMD/Code/GameEngine/Include/Common/GlobalData.h

@@ -352,6 +352,10 @@ class GlobalData : public SubsystemInterface
 	std::vector<AsciiString> m_simulateReplays; ///< If not empty, simulate this list of replays and exit.
 	Int m_simulateReplayJobs; ///< Maximum number of processes to use for simulation, or SIMULATE_REPLAYS_SEQUENTIAL for sequential simulation
 
+	UnsignedInt m_replaySaveAtFrame; ///< If non-zero, auto-save when this frame is reached during replay
+	AsciiString m_replaySaveTo; ///< Filename for auto-save during replay
+	AsciiString m_loadReplayCheckpoint; ///< If set, load this checkpoint and continue replay
+
 	Int m_maxParticleCount;						///< maximum number of particles that can exist
 	Int m_maxFieldParticleCount;			///< maximum number of field-type particles that can exist (roughly)
 	WeaponBonusSet* m_weaponBonusSet;