feat(stats): Generate match stats for headless replays

[bill-rich]

Stats Export for Replay Simulation

Adds a system to export detailed match statistics as gzip-compressed JSON alongside replay files. Designed to support post-game analytics, replay visualization tools, and automated stat collection pipelines.

What it does

When the -exportStats flag is passed on the command line (requires -headless and -replay), the engine records game events during replay simulation and writes a .gamestats.json.gz file next to the replay. An optional -statsUrl <url> flag uploads the compressed file to a server via HTTP POST after writing.

The exported JSON contains:

• Game metadata: map, mode, seed, frame count, player count
• Per-player summary: faction, side, color, final money/score, academy stats (supply centers built, upgrades purchased, generals points spent, etc.)
• Event streams: every build, kill, and capture event with frame number, player, position, and unit template names. Kill events include damage type.
• State change events: energy production/consumption, rank ups, skill point changes, science point changes, radar acquisition, player deaths, and battle plan activations. Emitted only when the value changes, not every frame.
• Time series: per-player money, money earned, and money spent sampled every 30 logic frames (~1 second).

How it hooks in

Event recording uses three hook points in existing game logic:

• Object::scoreTheKill records kills (after the same guards that gate score tracking. No self-kills, no civilian kills, no GUI-ignored objects)
• Player::onUnitCreated and Player::onStructureConstructionComplete record builds (respecting the isRebuild flag for structures)
• Object::onCapture records captures

Each call site is guarded by TheGlobalData->m_exportStats, so in normal (non-export) gameplay there is zero overhead The recording functions are never called. Inside the functions, a secondary exportingActive flag gates recording to the active window between StatsExporterBeginRecording and the end of ExportGameStatsJSON, preventing data accumulation between replays in a batch run.

The replay simulation loop in ReplaySimulation.cpp drives snapshot collection (called every frame, throttled internally to every 30 frames) and triggers export after each replay completes. Worker process mode forwards -exportStats and -statsUrl to child processes.

Flag validation

-exportStats is validated at startup in GameMain before any game logic runs. If -headless or -replay is missing, the process prints an error and exits immediately. This fail-fast approach avoids silent misconfiguration or flag mutation at runtime.

Design choices

Free functions with static state instead of a class: The exporter is intentionally not a subsystem or singleton. It's a leaf dependency. It reads from Player, ScoreKeeper, Energy, etc. but nothing depends on it. Free functions with file-scoped static state keep the coupling minimal and avoid touching the subsystem initialization order.

Two-layer gating (m_exportStats + exportingActive): m_exportStats is a command-line flag checked at call sites to eliminate function call overhead in normal gameplay. exportingActive is a runtime state flag managed by the exporter itself, active only between StatsExporterBeginRecording and export completion. The two serve different purposes: one answers "did the user opt in?" and the other answers "are we in the recording window right now?"

Raw player index remapping: The engine's player list includes observers, civilians, and other non-game slots. The exporter builds a mapping from raw engine indices to dense 1-based "game player" indices at first use, so the JSON output has player indices 1, 2, 3... regardless of how the engine internally numbers them. Events store raw indices during recording and remap at export time so the mapping only needs to be stable at the point of export, not during gameplay.

gzip compression: Stats files can be large for long games (many thousands of events). Writing gzip directly via zlib keeps file sizes manageable and avoids needing a separate compression step in the pipeline. The upload path sends the compressed file as-is with Content-Type: application/gzip.

nlohmann/json (ordered_json): Uses the existing json.hpp already vendored in the codebase under GameNetwork/GeneralsOnline/. ordered_json preserves insertion order so the output is human-readable without a separate formatting step.

WinInet for upload: The uploader uses WinInet (InternetOpenA/HttpSendRequestA) rather than pulling in a dependency like libcurl. WinInet is already available on all target platforms and handles HTTP/HTTPS with proxy support out of the box. The upload is synchronous and runs after the replay has finished simulating, so blocking is acceptable.

AcademyStats getters: Added const accessor methods to AcademyStats to expose the existing private counters (supply centers built, peons built, etc.) for export. These were previously only accessible through the calculateAcademyAdvice path.