[sync] TheSuperHackers upstream sync 06-05-2026

[fbraz3]

merge(thesuperhackers): sync upstream with cross-platform integrity (6 commits, 06-05-2026)

Imports 6 commits from thesuperhackers/main (tip f334383) while preserving
GeneralsX's cross-platform architecture (SDL3 + DXVK + OpenAL + FFmpeg) and
the GeneralsX-specific input/audio behaviors.

Upstream commits imported:
f334383 bugfix(contain): Prevent riders from being added to destroyed
container object when Reinforcement Pad is destroyed before
Troop Crawler drop (TheSuperHackers#2746)
7c78a5e refactor(metaevent): Split MetaEventTranslator::translateGameMessage()
into smaller functions (TheSuperHackers#2758)
a7fad3b fix(milesaudiomanager): Prevent multithread crashing in
MilesAudioManager (TheSuperHackers#2718)
b0becc4 refactor(milesaudiomanager): Clean up and simplify MilesAudioManager
(TheSuperHackers#2718)
df2224b bugfix(object): Avoid crash with dangling contain module in
Object::onDestroy() when Reinforcement Pad is destroyed before
Troop Crawler drop (TheSuperHackers#2747)
20f4254 fix(memory): Fix various memory leaks (2) (TheSuperHackers#2710)

Conflict resolution (see docs/WORKDIR/planning/SYNC_2026-06-05_TSUPERHACKERS_PLAN.md):

1. MetaEvent.cpp (Generals/ + GeneralsMD/) - refactor refactor(metaevent): Split MetaEventTranslator::translateGameMessage() into smaller functions TheSuperHackers/GeneralsGameCode#2758 splits
   translateGameMessage() into onMouseEvent/onKeyEvent helpers, replacing
   the per-key m_keyDownInfos bit-array with the GeneralsX-local
   m_lastKeyDown/m_lastModState members. GeneralsX semantics (mods-only-
   changed detection + normal key-transition branch) are preserved inside
   onKeyEvent(). We do NOT adopt upstream's KeyDownInfo/m_keyDownInfos
   because that would silently change input behavior beyond the sync's
   intent.

2. MetaEvent.h (Generals/ + GeneralsMD/) - kept GeneralsX's m_lastKeyDown
   and m_lastModState members and adopted only the onMouseEvent /
   onKeyEvent helper declarations. Removed upstream's onKeyModStateRemoved,
   onKeyPressed, getActionKeyType, getKeyModState declarations since they
   are not defined in the GeneralsX .cpp.

3. OpenAL audio manager (Core + GeneralsMD stub) - upstream's GameAudio.h
   API change makes nextMusicTrack/prevMusicTrack return AsciiString
   (instead of void) and removes getMusicTrackName. The auto-merged
   CommandXlat.cpp call sites use the new return value. GeneralsX's
   OpenAL implementations were updated to match the new signature and
   return the new track name. getMusicTrackName was removed from the
   header and implementation since it has no callers anymore.

4. AGENTS.md - pre-existing merge conflict markers in HEAD from a prior
   sync attempt were properly resolved by keeping the comprehensive
   "Updated upstream" version of the Must-Load Context section.

Auto-merged files (all reviewed for correctness):

• Generals{,MD}/Code/GameEngine/Include/GameLogic/Object.h
• Generals{,MD}/Code/GameEngine/Source/GameLogic/Object/Contain/{Open,Transport}Contain.cpp
• Generals{,MD}/Code/GameEngine/Source/GameLogic/Object/Object.cpp
• Generals{,MD}/Code/GameEngine/Source/Common/GameEngine.cpp
• Generals{,MD}/Code/GameEngine/Source/Common/RTS/Player.cpp
• Generals{,MD}/Code/GameEngine/Source/Common/System/SaveGame/GameStateMap.cpp
• Generals{,MD}/Code/GameEngine/Source/GameClient/MessageStream/CommandXlat.cpp
• Generals{,MD}/Code/GameEngine/Source/GameClient/Drawable.cpp
• Generals{,MD}/Code/GameEngine/Source/GameLogic/Map/SidesList.cpp
• Generals{,MD}/Code/GameEngine/Source/GameLogic/Object/Update/BattlePlanUpdate.cpp
• Generals{,MD}/Code/Libraries/Source/WWVegas/WW3D2/{hcanim,hrawanim,seglinerenderer}.cpp
• Generals{,MD}/Code/Tools/WorldBuilder/src/ScriptDialog.cpp
• Core/GameEngine/Include/Common/GameAudio.h
• Core/GameEngine/Source/GameLogic/System/GameLogicDispatch.cpp
• Core/GameEngineDevice/Include/MilesAudioDevice/MilesAudioManager.h
• Core/GameEngineDevice/Source/MilesAudioDevice/MilesAudioManager.cpp
• Core/GameEngineDevice/Source/W3DDevice/GameClient/Drawable/Draw/W3DModelDraw.cpp
• Dependencies/Utility/CMakeLists.txt
• Dependencies/Utility/Utility/interlocked_adapter.h (new)

Validation:

• macOS-vulkan configure: passed (179.3s)
• macOS-vulkan build (z_generals + g_generals): passed
• macOS smoke test (GeneralsXZH -win -noFullScreen, 40s): clean
  "exited main loop" with GameMain() returning code 0
• Linux validation deferred to CI (per user direction)

No conflict markers remain in the working tree. All GeneralsX CI
infrastructure (.github/workflows/, .github/ISSUE_TEMPLATE/,
.github/copilot-instructions.md) is untouched by the sync.

---

User Verification Checklist

Test the following items on at least one supported platform before approving:

• cmake --preset macos-vulkan (or linux64-deploy) succeeds
• cmake --build build/<preset> --target z_generals (Zero Hour) builds
• cmake --build build/<preset> --target g_generals (base Generals) builds
• Game launches and reaches the main menu
• Main menu navigates (mouse + keyboard)
• Skirmish gameplay starts and runs (1v1 AI)
• Campaign flow: at least one campaign map loads
• Audio playback (UI sounds, in-game music, unit voices)
• Video playback (intros/cutscenes)
• Renderer stability (no crashes/hangs on camera movement, alt-tab)
• Input handling (mouse, keyboard, hotkeys)
• Mod loading (default INI files load correctly)

Feature Areas Touched by Resolved Conflicts

• Input / MetaEvent — verify keyboard shortcuts (CTRL+key combos, modifier-only hotkeys) work as before
• Music controls — verify "next track" / "prev track" debug commands still print the new track name in the message log (used by upstream PR fix(milesaudiomanager): Prevent multithread crashing in MilesAudioManager TheSuperHackers/GeneralsGameCode#2718 API change)
• Contain / Reinforcement Pad — verify Troop Crawler drop / Reinforcement Pad destruction paths don't crash
• Memory leaks — play a long session and verify memory usage stays bounded
• Dangling m_containedBy — verify the RETAIL_COMPATIBLE_CRC=OFF (default) path; the ON path is retail-binary compatibility and not used by GeneralsX
• MilesAudioManager — these source files are not compiled by GeneralsX presets (commented out in CMakeLists); verify only that the OpenAL manager still works

Risky Areas for Extra Review

The following subsystems are flagged for additional scrutiny:

• Generals{,MD}/Code/GameEngine/Source/GameClient/MessageStream/MetaEvent.cpp — GeneralsX's mods-only-changed input behavior is preserved but the structure follows upstream's refactor; please verify keyboard hotkeys still work (especially modifier-only transitions like CTRL+SHIFT combinations).
• Generals{,MD}/Code/GameEngine/Source/GameLogic/Object/Object.cpp and Object.h — the auto-merge added m_containedByID and RETAIL_COMPATIBLE_CRC guards. GeneralsX uses RETAIL_COMPATIBLE_CRC=OFF by default; verify no assertion failures.
• Core/GameEngineDevice/Include/OpenALAudioDevice/OpenALAudioManager.h and Source/OpenALAudioDevice/OpenALAudioManager.cpp — adapted to the new nextMusicTrack/prevMusicTrack return value semantics. Verify music track advance still works.
• GeneralsMD/Code/GameEngineDevice/Source/OpenALAudioManager.cpp (stub used when SAGE_USE_OPENAL=OFF) — updated to match the new return types so it doesn't go out of sync with the Core/ implementation.
• Core/GameEngineDevice/Source/MilesAudioDevice/MilesAudioManager.cpp — large upstream refactor; not built by GeneralsX presets, but present in the tree. No impact expected.

Plan Document

The full conflict-resolution plan and per-commit analysis is in:
docs/WORKDIR/planning/SYNC_2026-06-05_TSUPERHACKERS_PLAN.md