feat(math): Route game logic math through WWMath with 3-mode deterministic support

[Okladnoj]

Merge by rebase

Rework of #2602, incorporating review feedback:

• GameMath via FetchContent (per @stephanmeesters, @OmniBlade recommendation)
• Trig.cpp preserved, redirected to WWMath instead of deleted (per @xezon request for standalone change)
• 3 math modes: VC6 (x87 inline asm), CRT (standard library), GameMath deterministic (per @Mauller recommendation)
• USE_DETERMINISTIC_MATH defaults on for non-VC6. BaseDefines.h turns it off automatically when gmath.h is not available or when RETAIL_COMPATIBLE_CRC is set, so a build without GameMath falls back to the CRT path rather than failing
• GameMath keeps its own intrinsics default — the earlier GM_ENABLE_INTRINSICS=OFF override was dropped after a Windows replay run showed byte-identical CRC logs with intrinsics on and off
• Linear history on top of current main, no merge commits

Open question: Replay checks pass both with and without USE_DETERMINISTIC_MATH, even though golden replays were recorded with an x87 build. The replays may not contain MSG_LOGIC_CRC messages, meaning the check only validates absence of crashes rather than game state CRC parity. If anyone has insight on this — please share.

Testing results

Cross-platform deterministic math parity verified with SimulationMathCrc::runBenchmark — computes CRC over 10 000 iterations of sin/cos/tan/atan2/sqrt/pow across a fixed input set.

System	Compiler	Math Library	CRC	Perf (10 000 iters)
Win32 x86	MSVC (modern)	fdlibm (deterministic)	🟩 76B53840	~6 ms
macOS ARM64	Apple Clang	fdlibm (deterministic)	🟩 76B53840	~11 ms
Win32 x86	MSVC (modern)	system math (native)	🟦 E8B6385A	~3 ms
macOS ARM64	Apple Clang	system math (native)	🟦 E8B6385A	~5 ms
Win32 x86	VC6 (legacy)	x87 CRT (no fdlibm)	🟧 B7B83850	~17 ms
Win32 x86	VC6 (legacy)	system math (native)	🟥 8BB5B841	~5 ms

• 🟩 cross-platform deterministic parity achieved (Win32 modern = macOS ARM64)
• 🟦 native system math match (Win32 modern = macOS ARM64)
• 🟧 VC6 deterministic (x87 CRT, separate group — fdlibm not supported)
• 🟥 VC6 native (x87 CRT, separate group)

Key fix: -ffp-contract=off in cmake/compilers.cmake — prevents Clang from emitting FMA instructions (fmadd) that skip intermediate rounding, breaking bit-exact parity with MSVC's /fp:precise default.

Note

Route game logic math through WWMath with 3-mode deterministic support

• Expands WWMath API in wwmath.h with explicit float, double, and legacy float overloads for all math operations. Deterministic builds dispatch to single-precision GameMath functions; non-deterministic builds use precision-matched C math functions.
• Adds USE_DETERMINISTIC_MATH and RETAIL_COMPATIBLE_CRC configuration macros in BaseDefines.h. Deterministic math enables only when GameMath is available and retail CRC compatibility is disabled. Adds GameMath as a CMake FetchContent dependency for non-VS6 builds via gamemath.cmake.
• Replaces direct C math calls (sqrt, sin, cos, atan2, fabs, ceil, etc.) with WWMath wrappers across the entire engine: Locomotor, Weapon, PartitionManager, PhysicsUpdate, AIUpdate, pathfinding, terrain, geometry, projectiles, and dozens of other systems.
• Introduces WWMath::Div_Safe to replace direct division in ~15 call sites (mine placement, scaffold count, health ratios, build progress, flight-path segments, turn-radius), clamping the divisor to a supplied epsilon in deterministic builds.
• Adds -ffp-contract=off for non-VS6 compilers in compilers.cmake to prevent fused multiply-add contraction, and adds a deterministic-vs-native math benchmark via SimulationMathCrc::runBenchmark.
• Risk: PartitionManager::calcMinRadius and calcRadiusVec now use Real intermediates instead of double outside RETAIL_COMPATIBLE_CRC builds, which may change radius results. Coord3D::length and several WWMath double overloads route through single-precision GameMath in deterministic builds, reducing precision. visualc.h no longer defines local math constants; consumers must use WWMATH_* equivalents. PolygonClass::Compute_Plane now casts squared length to float before WWMath::Sqrt, which may lose precision for large polygons.

📊 Macroscope summarized 32d3717. 188 files reviewed, 3 issues evaluated, 1 issue filtered, 2 comments posted

🗂️ Filtered Issues

GeneralsMD/Code/Libraries/Source/WWVegas/WW3D2/motchan.cpp — 0 comments posted, 1 evaluated, 1 filtered

• line 868: filtertable is used to decode the packed motion-channel data, but this changes its generated values from WWMath::Sin(float) (which used the double-precision sin path in non-deterministic builds) to Sinf_Legacy (which uses sinf on non-x86 builds). The table is not serialized with each motion channel, so existing assets decoded by a modern non-deterministic build can reconstruct different deltas/poses, and the change also makes the decoder's quantization behavior platform/configuration dependent rather than preserving the previous table generation. [ Out of scope (triage) ]

[greptile-apps]

Confidence Score: 5/5

[High risk] Routes game math through a new deterministic math wrapper.

The PR appears safe to merge based on the changes reviewed; no new actionable failure was established.

Summary

The PR routes game math through WWMath with configurable deterministic behavior. Changes since the previous review also:

• adjust terrain, docking, spawning, and particle-cannon logic in both game variants;
• revise archive tokenization and rename shared CMake dependency targets.

_{Reviews (31) · Last reviewed commit: "refactor(visualc): Remove excess math co..."}

[Okladnoj]

Here is what replay playback looks like at the moment.

I’m testing this on a separate branch:
https://github.com/Okladnoj/GeneralsGameCode/okji/test/deterministic-math-v2

I slightly adjusted the CI there so I can run Win32 and get access to the game resources.

[Skyaero42]

You did not review the changes you made with AI. It has issues that you should fix before asking it to be reviewed.

[Okladnoj]

reviwed all changes

[xezon]

This change does too many things. It is better to first consolidate trig and wwmath and maybe other sources of math, before going into gamemath territory.

[Okladnoj]

This change does too many things. It is better to first consolidate trig and wwmath and maybe other sources of math, before going into gamemath territory.

@xezon Hey! I understand your point, but the reason I didn't fully consolidate trig and wwmath in this PR is exactly to avoid doing too many things at once.

As we saw in PR #2602, fully removing trig.h and replacing it with WWMath across the codebase touches over 120 files. Mixing a massive 120+ file architectural refactoring with a core feature addition (GameMath) made the previous PR extremely difficult to review and broke compilation for some standalone utilities, because trig.h is used outside of just game math.

That's exactly why I chose this "routing" approach for this PR. By keeping the trig.h interface intact and just routing its internal implementation to WWMath, we achieve the deterministic math goals with a much smaller and safer footprint.

Perhaps the best option would be to test this PR first, and if everything is fine — merge it. And only after that, we can focus on a second PR dedicated purely to the architectural cleanup (removing trig.h across all 120+ files)?

[Okladnoj]

Hi @xezon! I have addressed all your review feedback points and updated the PR.

CI Status:
The CI is completely green. I ran the benchmarks on both Win32 and VC6 with the latest changes, and the CRC results perfectly match our previous deterministic baselines (76B53840 for deterministic, E8B6385A for native).

To save you from hunting through all the comment threads, here is a consolidated list of the answers and solutions to your review points:

• Function_Name convention / Naming inconsistencies
  Fixed. Renamed all math wrappers to use the _Origin and _Trig convention. The _Trig suffix also cleanly resolves conflicts with legacy EA names (e.g., ACos_Trig vs Acos).
• Move #define next to #include gmath
  Fixed.
• Redundant VC6 guard
  Fixed — removed the outer #if !(defined(_MSC_VER)...) guard, kept only __has_include. VC6 doesn't support __has_include, so the block is naturally skipped.
• "origin" terminology
  "Origin" means the original EA code called bare CRT functions (sqrt, acos, sinf...). The suffix explicitly marks which exact CRT function was used originally. These are not just type variants — they are different precision math paths.
• Missing gm math variants / CeilfOrigin identical to Ceil
Ceil(float) and Floor(float) are original EA code used only in rendering (visrasterizer.cpp). Determinism isn't needed there. However, CeilfOrigin(float) is a game logic wrapper that routes to gm_ceilf. Therefore, they are not identical.
• C++ overloads instead of f suffix
  Overloads are dangerous here. GameMath only provides float functions (the double version always narrows). With overloads, the compiler silently picks the version by argument type and could inadvertently change the precision path. Explicit names protect against this.
• No @fix prefix in CMake / What is ODR? / Line breaks / iters typo
  Fixed.
• Benchmark in GameLogic::update()
  Moved the auto-benchmark out of the replay loop. It is now a simple compile-time flag. (Did not prepare an ImGui stub since ImGui does not exist in the project).
• VS6 exclusion necessary in CMake?
  Yes, it is necessary. VC6 doesn't support <stdint.h> and long long required by GameMath. Removing the exclusion will break the build.
• Sqrt(double) intentional in BaseType.h?
  Yes, intentional. Coord3D::length() is used in game logic and participates in CRC — it must be strictly deterministic.

[Okladnoj]

Hi @xezon! Thanks for the detailed review. I agree with some of your points regarding code cleanliness (I will remove the Ceil/Floor wrappers for the renderer).

However, there are a couple of critical architectural points concerning the preservation of old replays (suffixes) and determinism (Trig.cpp) that I want to clarify before pushing changes.

1. C++ Overloads vs Explicit types (why suffixes are needed)

I want to explain why I had to come to an explicit separation of functions via suffixes instead of using C++ overloads. This is tied to the necessity of preserving 100% backwards compatibility for old builds (VC6 Retail Compatibility).

I introduced 3 types of functions because they reflect 3 completely different mathematical paths (math paths) in the original EA engine. Our codebase serves three build modes at once (VC6, Win32, and Deterministic), and if we don't strictly fix the paths, we will lose Retail compatibility on old compilers:

1. Without suffix (WWMath::Cos): This is the original Westwood Math implementation. In the original game on VC6/Win32, it compiles into inline x87 asm (fcos).
2. With _Trig suffix (WWMath::Cos_Trig): This is a replacement for the global Cos() function from Trig.cpp. In the original game on VC6, it called the CRT function cosf() (not fcos!). The difference in the lowest bits between fcos and cosf() is critical: if I merge them into a single function without a suffix, the retail build will start calling fcos instead of cosf(), and the original logic will break.
3. With _Origin and f_Origin suffixes (ACos_Origin vs ACosf_Origin): These replace direct system calls to acos(double) and acosf(float) in GameLogic. The deterministic library GameMath provides only float versions. My double version is forced to do a narrowing cast: (double)gm_acosf((float)x).
   The original EA code often passed variables of type float into system functions expecting double (e.g., acos()), relying on automatic type promotion by the compiler.
   If I switch to C++ overloads (just ACos), then when passing a float, the compiler will automatically pick the float overload. This will change the original math path (instead of calling the double version with narrowing, it will call the pure float version).

Explicit suffixes strictly lock the original execution path. They guarantee that the exact function intended in the original game is called, avoiding unpredictable compiler behavior during overload resolution.

Examples (The mechanics of overload conflicts)

Here is, with examples, how the overload mechanism breaks the original branches when compiling under VC6:

Example A: Conflicting identical signatures (_Trig)
In the original game, we had two different math paths that took the exact same type (float), but executed different instructions:

1. The original WWMath::Cos(float) → compiled into fcos (inline asm).
2. The original Trig::Cos(float) → compiled into cosf() (CRT).

C++ overloads only work with different argument types. How is the compiler supposed to know which of the two Cos(1.0f) calls should go to assembler, and which should go to the system CRT, if their signatures are absolutely identical? It can't.
If we remove _Trig and leave only WWMath::Cos(float), then in the VC6 build, all code from the former Trig.cpp will start invoking the fcos assembler instead of the original cosf(). The math is broken.

Example B: Path substitution via typing (_Origin)
On the calling code side in GameLogic, EA often wrote like this:

float myVal = 0.5f;
float result = acos(myVal); // In the original, this is a call to <math.h> double acos(double)

Since acos in C accepted a double, the compiler did an implicit cast: float -> double -> acos(double) -> float.

What happens if we introduce the overloads WWMath::ACos(float) and WWMath::ACos(double)?
The call to WWMath::ACos(myVal) will see the float type. The C++ overload mechanism will directly call the float overload, completely ignoring the original path with promotion to double. The VC6 logic is broken! The explicit suffix ACos_Origin(double) takes away the compiler's right to choose and strictly forces the original math path.

2. Sqrt(double) in BaseType.h:391

And (Real)sqrt( x*x + y*y + z*z ); was calling double sqrt(double) ?

Yes, in the original game it fell back to the system CRT double sqrt(double). But the problem is that Coord3D::length() is actively used in game logic (it participates in physics and CRC calculations). If I leave the system double, we will have discrepancies between Mac, Win32, and VC6. I have to forcibly cast it to deterministic float (at the cost of precision loss) to guarantee cross-platform sync.

3. "Trampolines" in Trig.cpp

What is the point of moving the function body to WWMath... No trampoline to WWMath.

The fact is that I was acting exactly according to your original task from the previous PR (#2602).
You wrote then: "Generally it is a bad sign if simplifying code would break something. If so, it needs to be fixed", and asked me to physically delete the old Trig.cpp files, migrating everything to WWMath.

I did exactly that. But stephanmeesters discovered that completely deleting trig.h breaks the VC6 / Win32 compilation (over 120 files are affected due to implicit includes).
To save the VC6 build, I had to restore the old Trig.h interface.

But I moved the implementation itself to wwmath.h to fulfill your requirement for math consolidation. If I write #if USE_DETERMINISTIC_MATH directly inside Trig.cpp, I will have to do it twice (since there are two Trig.cpp files in the engine — in Generals and GeneralsMD).
The trampoline is a transitional compromise that allowed us to not break the VC6 build and to gather the deterministic logic strictly in one place, as we planned. In the second phase, when there is already a working system with deterministic math in the main branch, we can start looking for the best way to delete trig.h and fully rely on wwmath.

4. Duplicates (Ceil / Floor)

Regarding Ceil and Floor — here I completely agree with you.
Since these functions (along with their original EA versions) are used exclusively in rendering (e.g., in visrasterizer.cpp) and do not participate in CRC calculations for network play, wrapping them in WWMath makes no sense.
I will completely remove these wrappers from wwmath.h and write direct calls to std::ceil / std::floor right at their call sites in the render code.

[xezon]

Hi @xezon! Thanks for the detailed review. I agree with some of your points regarding code cleanliness (I will remove the Ceil/Floor wrappers for the renderer).

However, there are a couple of critical architectural points concerning the preservation of old replays (suffixes) and determinism (Trig.cpp) that I want to clarify before pushing changes.

It is a bit tough to fight through this much AI generated text. Please push the last state of the code and then I can take a look at it in Visual Studio and try to polish it up if it needs polishing. I expect this is faster than chatting about where to go with this. Generally, try to not trust the AI generated code too much. It generates code that is for machines, not humans.

[Okladnoj]

It is a bit tough to fight through this much AI generated text. Please push the last state of the code and then I can take a look at it in Visual Studio and try to polish it up if it needs polishing. I expect this is faster than chatting about where to go with this. Generally, try to not trust the AI generated code too much. It generates code that is for machines, not humans.

I wrote every point personally — I only asked AI to format it properly, fix spelling, and translate it into English, exactly like I’m asking now, because my English is not very strong.

I personally worked through every point of that long text, so it would be better to read it carefully and understand the reasoning behind it — there is nothing unnecessary there.

The main point is that suffixes like _Trig and _Origin are physically necessary for us, because overloading cannot handle this task properly.

In the original project, before deterministic math was introduced, there were places with mixed math inside the game logic that affects the CRC. When USE_DETERMINISTIC_MATH is disabled, we need to support the old CRC calculation system, which means we need simultaneous _Trig and _Origin implementations.

If we could simply remove USE_DETERMINISTIC_MATH from the project, there would not be such a large-scale transformation and interweaving of math functions. But in the old mode, we support not only Win32, but also VC6 with its own assembly functions.

[Okladnoj]

Hi @xezon! Thanks for the detailed review. I agree with some of your points regarding code cleanliness (I will remove the Ceil/Floor wrappers for the renderer).

@xezon
In short, I don’t think it can be explained much shorter or simpler than in that message.

The project’s math was not always written with a clean and transparent architecture — or at least not all parts of it were. Maybe this was even done intentionally to make it harder to reverse-engineer the CRC logic.

At the moment, all workflows build successfully, and all replays also play successfully both with deterministic math enabled and disabled.

Above, I sent a screenshot of your job, plus one additional replay run that I configured specifically to verify Win32.

[xezon]

Ok fair comments. I was under the impression I was chatting with AI generated text because of all the polished formatting. Can you push the latest state to the branch that you have now? I would like to take a look at it in Visual Studio next.

Btw, Replay Check is currently broken. We need to wait until after that is fixed.

[Okladnoj]

Ok fair comments. I was under the impression I was chatting with AI generated text because of all the polished formatting. Can you push the latest state to the branch that you have now? I would like to take a look at it in Visual Studio next.

Btw, Replay Check is currently broken. We need to wait until after that is fixed.

The branch is already up to date — I haven't made any changes since the last push, I was waiting for your feedback. Feel free to take the current branch and work on it in VS. If you need my help — push your changes and I'll pick up from there.

Regarding the broken Replay Check — the CI runner has no way to obtain the game data. I solved this by extracting a minimal set of files from the Steam distribution (no textures, audio, or GUI — just enough for replay verification), uploaded them as a release to a private repository (Okladnoj/generals-gamedata), and connected it to the workflow via a PAT secret (GAMEDATA_PAT). The CI downloads the data using gh release download, verifies SHA256, and uses it for replay check. You can see the configuration on the test branch: okji/test/deterministic-math-v2 — file .github/workflows/check-replays.yml. Feel free to adopt this approach — or give me access to your organization, and I'll create a similar private repo with the data and wire it up to your CI.

[xezon]

The branch is already up to date

The last push in from 08 May

[xezon]

Next wave. I am not of fan of the Div_Safe usage. Is protects from division by zero, but it does so in an illogical way.

[xezon]

What is the current state of this review?

[Okladnoj]

@xezon

What is the current state of this review?

3 review points addressed:

• added an epsilon clamp to WWMath::Div_Safe; the fallback is kept, the reason is in the comment
• replaced the smiley
• reworded the comment in Coord3D::length(); Caball009's idea is left as a @todo for the next PR

[xezon]

• added an epsilon clamp to WWMath::Div_Safe; the fallback is kept, the reason is in the comment

I do not understand this reasoning. The fallback values were invented by this change. What this change needs to do instead is invent appropriate epsilons at the individual division sites.

Div_Safe should be removed. And callsites should clamp the divisor to a reasonable safe value, the default min value being WWMATH_EPSILON.

Example:

Real ratio = m_currentHealth / prevMaxHealth;

to

Real ratio = m_currentHealth / std::max(prevMaxHealth, WWMATH_EPSILON);

Div_Safe can be kept because we still need the 2 compile methods, but it does not carry a fallback.

Real ratio = m_currentHealth / prevMaxHealth;

to

Real ratio = WWMath::Div_Safe(m_currentHealth, prevMaxHealth, WWMATH_EPSILON);

Make the epsilon argument default to WWMATH_EPSILON

[Okladnoj]

@xezon
Done. fallback is gone; the third argument of Div_Safe is now an epsilon, defaulting to WWMATH_EPSILON.

[xezon]

Are the commit titles and descriptions properly up-to-date and accurate?

[Okladnoj]

@xezon
Commit titles and descriptions are updated: feat(crc) and feat(bezier) got accurate titles, and every commit now has a description.

[xezon]

Why does this need to run on a frame 400 ? Should this perhaps be part of a unit test instead?

[Okladnoj]

Frame 400 was picked by experiment: by then the game has settled into a steady load. The benchmark runs inside the game loop, so it measures on a CPU that is busy with the game rather than in a cold standalone process, which gives numbers closer to real play.

[xezon]

I dont understand. So the math benchmark results depend on which moment they run at and are not deterministic at random points in the lifetime of the process? In other words, if we run the benchmark at frame 399 or at the launch of the application, the results will be different? If yes, why?

[Okladnoj]

@xezon
What does determinism have to do with this? I’m talking about CPU load. I measured the execution speed of the math functions. And yes, the speed of calculations is affected not only by how heavily the PC is loaded with other processes, but even by the power delivered through the power cable. A real-life example: when I was testing the CTA functions, I couldn’t understand why they suddenly started showing negative results — and only later noticed that I was having fluctuations in the power grid.

[xezon]

Ok so it is a performance benchmark, not a correctness one.

Ok that is still odd however. The execution before the benchmark should not influence the result of the benchmark. It would make more sense if the benchmark was isolated from the game runtime.

[xezon]

We should add a proper benchmark target that does the CPU warmup and test. Then we do not need to hack it into the game like that.

[Okladnoj]

ok, in this PR?

[xezon]

Separate. We also need a unit test target. I wanted to take a look at this soon but you can also explore into that direction.

[Okladnoj]

Removed runBenchmarkOnFrame and its call in GameLogic. Only runBenchmark is left, to be called manually.

[xezon]

Google Benchmark has been added with #3405.

After it is merged you should be able to hook up your new benchmark there.

[macroscopeapp]

Macroscope has since reviewed this pull request. An earlier review was skipped by a cost limit; a review has now completed, so that notice no longer applies.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a broad math backend and build-mode change that rewires existing AI, physics, pathfinding, gameplay, and rendering behavior across 188 files, with additional external dependency and compiler floating-point changes. The benchmark/testing design remains a separate concern, so the scope and runtime blast radius require human review.

Not approved because:

• Per-review cost limit exceeded (workspace setting). Approvability relies on correctness review in order to determine eligibility

^{Review your spending limits in Billing settings, or comment @macroscope-app review this PR to bypass the limit and review now. You can add or adjust custom eligibility rules. Learn more.}

[Okladnoj]

@macroscope-app review

[macroscopeapp]

Sorry, I'm unable to act on this request because you do not have permissions within this repository.

[xezon]

@Okladnoj When you rebase, there will be some conflicts with aeac4c2

[Okladnoj]

@xezon how that PR going?

[xezon]

On it!