feat(sagepatch): casual QoL patch for macOS + Linux (Phase 1)

[ebellumat]

Summary

Introduces SagePatch — an optional, drop-in patch for GeneralsX that adds quality-of-life features for casual play, gated by the new CMake flag RTS_BUILD_OPTION_SAGE_PATCH (default OFF, ON in the macos-vulkan preset).

Inspired by the casual subset of the original GenTool, but independently implemented from the public GenTool changelog and SDL3/CoreGraphics/X11 documentation. No code reverse-engineered from the original closed-source d3d8.dll (which is VMProtect-protected anyway). No anti-cheat, no networking, no replay tools, no engine bug fixes — see the doc for the explicit non-goals.

The whole thing is outside the game source tree in Patches/SagePatch/. The only files touched in core are CMakeLists.txt, CMakePresets.json, and cmake/config-build.cmake to wire the option.

What's in

Feature	Trigger	macOS	Linux	Windows
Screenshot	F11	screencapture -l <id>	import (ImageMagick) / gnome-screenshot	stub
Cursor lock toggle	Scroll Lock	SDL3	SDL3	stub
Brightness up / down	Ctrl + PageUp / Ctrl + PageDown	CoreGraphics gamma	XF86VidMode (X11)	stub
Window snap (5 positions)	Ctrl + 1..5	SDL3	SDL3	stub
Camera height range	passive	INI override	INI override	INI override
Camera pitch	passive	INI override	INI override	INI override
Keyboard scroll speed	passive	INI override	INI override	INI override
FPS counter	passive	DXVK_HUD=fps default in run.sh	same	n/a

Architecture

Game process (GeneralsXZH)
    │
    ├── DYLD_INSERT_LIBRARIES (macOS) / LD_PRELOAD (Linux) → libsage_patch.{dylib,so}
    │       └── SDL_PollEvent gets replaced (interpose table on macOS,
    │           symbol override + dlsym RTLD_NEXT on Linux)
    │              └── F11 / Scroll Lock / Ctrl+PgUp/Dn / Ctrl+1..5 → SagePatch handlers
    │                      └── Per-platform: screencapture / ImageMagick,
    │                          CoreGraphics gamma / XF86VidMode, SDL_SetWindowPosition
    │
    └── Engine reads Data/INI/Default/GameData/SagePatch.ini → camera/scroll overrides

No D3D8 proxy, no Vulkan layer, no engine source modifications. Phase 1 patch source is ~600 lines C++ across common/, macos/, linux/, windows/ (stubs).

Layout

Patches/SagePatch/
    CMakeLists.txt
    include/SagePatch/{Hooks.h, Features.h, Logger.h}
    src/
      common/                          # SDL3 — every platform
        Init.cpp / KeyHandler.cpp / CursorLock.cpp / WindowPosition.cpp
      macos/                           # __DATA,__interpose, screencapture, CoreGraphics
        interposers_macos.cpp / Screenshot_macos.cpp / Brightness_macos.cpp
      linux/                           # LD_PRELOAD, ImageMagick, XF86VidMode (lazy dlopen)
        interposers_linux.cpp / Screenshot_linux.cpp / Brightness_linux.cpp
      windows/                         # stubs (Phase 2)
        Stubs_windows.cpp
    resources/Override.ini             # engine INI override
docs/PATCHES/SAGEPATCH.md              # user/dev documentation

What's intentionally not in scope

• Anti-cheat (MDS, Game File Validator, version check, ergc) — explicit user decision; out of scope.
• External-server features (CNC Online, GameRanger, Upload Mode, ticker, ladder, GenTool updater) — depend on third-party infrastructure SagePatch does not own.
• Replay tools and competitive features (Money Display, Player Table, Random Balance, fog-of-war replay, frame stepping, controls bar) — focus is casual play.
• Engine bug fixes (Scud bug, Tunnel bug, Building bug, multiplayer movement crash) — these are already handled upstream by TheSuperHackers/GeneralsGameCode, which is the parent of GeneralsX and is maintained by the same author who wrote GenTool. The codebase already carries 170+ @bugfix annotations including Tunnel System fixes by xezon. Duplicating them here would create merge conflicts on the next upstream sync.
• In-game text overlay (clock, match timer, in-game settings menu) — would need a graphics-pipeline hook (D3D8 proxy or Vulkan layer); Phase 2 if there's appetite. The existing DXVK_HUD provides a basic FPS counter as a substitute.
• Windows preload mechanism — Win32 has no LD_PRELOAD / __interpose equivalent; needs a proxy d3d8.dll like the original GenTool. Stubs are in place so the build still succeeds with RTS_BUILD_OPTION_SAGE_PATCH=ON on Windows, but the runtime is no-op until the proxy is implemented.

Already in the engine, no patch needed

These GenTool-era options are first-class engine flags in Common/CommandLine.cpp. Documented in the SAGEPATCH.md so users know they can call them directly via run.sh:

• -nologo
• -noShellAnim
• -noshellmap
• -quickstart
• -xres N -yres N (resolution unlock — engine no longer locks the list)
• -forcefullviewport
• -noaudio, -nomusic, -novideo

Test plan

• Builds on macOS arm64 (macos-vulkan preset, RTS_BUILD_OPTION_SAGE_PATCH=ON)
• libsage_patch.dylib produced — 55 KB, arm64 native, dynamic SDL3 lookup
• Deploy script copies the dylib + Override.ini into the game runtime dir
• Generated run.sh wrapper sets DYLD_INSERT_LIBRARIES correctly (no trailing :)
• Smoke launch shows the SagePatch banner with all 4 hot-key registrations and the engine loads Data/INI/Default/GameData/SagePatch.ini
• SAGE_PATCH_DISABLED=1 ./run.sh skips the preload as expected
• Linux build verification (no Linux host available in this session — config compiles, runtime path needs Linux tester)
• Each individual feature manually validated (F11 / Scroll Lock / Ctrl+PgUp/Dn / Ctrl+1..5)

Notes on naming

SagePatch is a placeholder picked at scaffolding time (the SAGE engine being what Generals runs on). Trivial to rename via:

git grep -l SagePatch | xargs sed -i '' 's/SagePatch/<NewName>/g; s/sage_patch/<new_name>/g; s/SAGE_PATCH/<NEW_NAME>/g'
mv Patches/SagePatch Patches/<NewName>
mv docs/PATCHES/SAGEPATCH.md docs/PATCHES/<NEWNAME>.md

Commits

• d42ef875c — initial Phase 1 (macOS-only, mistake)
• 3efaac65c — cross-platform refactor (macOS + Linux + Windows stubs), window snaps, FPS HUD default
• 3a87fa2cd — docs scope clarifications

[fbraz3]

Hey @ebellumat, thanks for your contribution!

I see there are several commits in this PR. Please let me know when it's ready for review.

Regarding the FPS counter feature, how is it different from the native FPS counter located at the top-left corner of the screen?

[ebellumat]

You're right, didn't realize the native one existed. The DXVK_HUD trick I had in the wrapper is broken on macOS anyway (MoltenVK can't compile the HUD shader, hangs the game at the EA logo), so I just dropped the FPS claim from the docs in 535c8a1.

Keeping it as draft for now, want to do another pass on macOS at 1440p with assets and get a Linux smoke test before flipping. Will ping when ready.

[ebellumat]

Camera distance overrides is working :D

[fbraz3]

Camera distance overrides is working :D

Cool! This kind of zoom remember me the older C&C games like RA2.

[fbraz3]

note: I pushed a bugfix for full screen mode on main branch, you may want to merge it on your fork to be sure it not broke anything.