feat: Simulation math CRC utility for mismatch prevention

[stephanmeesters]

This PR adds a diagnostic utility to compute a CRC of simulation-relevant math operations which may be useful for predicting and preventing mismatches in multiplayer games.

It's basically a cocktail of math functions that is tweaked to be able to differentiate compilers, known good/bad Linux config, processor architecture. In the case of a non-matching CRC then there would be a high chance of seeing a mismatch at some point.

This provides a similar function to calculating CRC's of a set of replays, with the benefit that it runs very quickly (sub 0.1 ms) and is more stable to changes in the codebase.

Testing results

System	Compiler	CRC value
windows x86	vc6	🟩 89B53879
linux x86 good¹	vc6	🟩 89B53879
linux x86 bad¹	vc6	🟥 DCB83820
windows arm	vc6	⬜ TBD
mac arm (parallels)⁴	vc6	🟨 2EB834D2
mac arm (rosetta)⁵	vc6	⬜ TBD
windows x86	win32	🟦 B5B838E0
linux x86 good²	win32	🟦 B5B838E0
linux x86 bad³	win32	⬜ TBD
windows arm	win32	⬜ TBD
mac arm (parallels)⁴	win32	🟪 D4B838D4
mac arm (rosetta)⁵	win32	⬜ TBD

¹ Good/bad is determined by replay CRC's see #1940
² Known good here based on extensive testing using replays from GeneralsOnline (not the same binary though)
³ I don't have a known bad Linux config for win32
⁴ Apple M1 Mac Mini, Parallels Desktop 26, Windows 11 ARM
⁵ Using Whisky or Crossover

Implementation

A command line argument is added that prints this simulation math CRC: -printSimMathCrc.

It's out of scope but a possible use case for this is to check CRC's between a lobby host and someone who joins so see if their systems are compatible, and perhaps warn or block if the CRC's don't match.

Help with testing

If you have an ARM machine and would like to help test and fill in the TBD items it would be much appreciated.

Instructions

Download and install this version with the CRC print flag (must be logged into GitHub):
vc6: https://github.com/TheSuperHackers/GeneralsGameCode/suites/54311017349/artifacts/5120052850
win32: https://github.com/TheSuperHackers/GeneralsGameCode/suites/54311017349/artifacts/5120052850

Run this command using PowerShell, first dir into the directory with the game files:

$out = Join-Path $env:TEMP ("stdout_{0}.log" -f ([guid]::NewGuid())); $p = Start-Process -FilePath "generalszh.exe" -ArgumentList "-printSimMathCrc" -RedirectStandardOutput $out -PassThru; $p.WaitForExit() | Out-Null; Get-Content $out; Remove-Item $out -ErrorAction SilentlyContinue

If everything went well this should print the simulation CRC value.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds a diagnostic utility class SimulationMathCrc that computes a CRC checksum of simulation-relevant floating-point math operations. The utility is designed to detect potential multiplayer mismatches by identifying differences in:

• Compiler implementations (vc6 vs win32)
• Processor architectures (x86 vs ARM)
• Platform configurations (Windows vs Linux vs macOS)
• Floating-point rounding modes and precision

The implementation performs matrix operations using a cocktail of math functions from both WWMath (custom Sin/Cos) and standard C library (tanf, asinf, acosf, atanf, atan2f, sinhf, coshf, tanhf, sqrtf, expf, log10f, logf), intentionally mixing sources to maximize sensitivity to platform differences.

Key changes:

• New utility class with single static calculate() method
• Sets FPU control word to match game's rounding mode (vc6 only)
• Performs matrix multiplication and inversion with carefully chosen values
• Returns 32-bit CRC that can be compared between systems

The code is clean, well-commented, and follows existing codebase patterns for FPU control and CRC generation.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The changes are isolated to a new utility class with no dependencies on game logic. The implementation follows established patterns for FPU control and CRC calculation. The code is thoroughly tested across multiple platforms per the PR description. No breaking changes or side effects.
• No files require special attention

Important Files Changed

Filename	Overview
Core/GameEngine/CMakeLists.txt	Added new SimulationMathCrc header and source files to build system
Core/GameEngine/Include/Common/SimulationMathCrc.h	Simple utility class header with single static method to calculate simulation math CRC
Core/GameEngine/Source/Common/SimulationMathCrc.cpp	Implements CRC computation using matrix operations and various math functions to detect platform/compiler differences

Sequence Diagram

sequenceDiagram
    participant Client as Client Code
    participant SMC as SimulationMathCrc
    participant XferCRC as XferCRC
    participant Matrix as Matrix3D
    participant Math as Math Libraries

    Client->>SMC: calculate()
    SMC->>SMC: _fpreset()
    SMC->>SMC: _controlfp(0x000A001F, _MCW_RC | _MCW_PC | _MCW_EM)
    Note over SMC: Set FPU rounding mode<br/>for vc6 compatibility
    
    SMC->>XferCRC: open("SimulationMathCrc")
    XferCRC-->>SMC: Ready to accumulate CRC
    
    SMC->>SMC: appendMatrixCrc(xfer)
    Note over SMC: Create matrices with<br/>hard-coded values
    
    SMC->>Matrix: matrix.Set(12 float values)
    SMC->>Math: WWMath::Sin/Cos + std math functions
    Math-->>SMC: Computed values
    SMC->>Matrix: factors_matrix.Set(computed values)
    
    SMC->>Matrix: Multiply(matrix, factors_matrix, &matrix)
    SMC->>Matrix: matrix.Get_Inverse(matrix)
    
    SMC->>XferCRC: xferMatrix3D(&matrix)
    Note over XferCRC: Accumulate matrix data<br/>into CRC checksum
    
    SMC->>SMC: _fpreset()
    Note over SMC: Reset FPU state
    
    SMC->>XferCRC: close()
    SMC->>XferCRC: getCRC()
    XferCRC-->>SMC: 32-bit CRC value
    SMC-->>Client: CRC checksum

Loading

[greptile-apps]

Greptile found no issues!

From now on, if a review finishes and we haven't found any issues, we will not post anything, but you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}

[Skyaero42]

While I think the concept is great, I don't think we should pollute the user-facing command-line options even more.
I think there are other ways to perform these tests rather than embedding it in the main application.

[stephanmeesters]

I can agree with that, the command line was useful for testing but maybe not so user friendly, and sharing a CRC with users is not necessarily a goal as the meaning can be misunderstood (a matching CRC does not guarantee no mismatch).

We could hold off merging until there is some kind of plan to use it

[helmutbuhler]

I like this! I don't mind the commandline option, there are so many already anyway.
But we cannot expect users to run this manually, maybe we check this once the player enters the network lobby automatically? If the value doesn't match the common value, we can warn the user.

[bobtista]

I like it :) Agreed maybe we remove the command line option, and use this in the game lobby to warn people of potential compat issues. Also, looking forward, when we eventually go 64 bit + cross platform, this will presumably be removable, just something to plan for.

[Caball009]

I'm not sure whether I see the value of the command line option, but perhaps I could use the CRC value for #1404

[greptile-apps]

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[xezon]

I'm not sure whether I see the value of the command line option, but perhaps I could use the CRC value for #1404

I agree. The idea for the CRC precheck is great. It would combine well for joining rooms and is another layer of safety to detect mismatch early.

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}